# annsel

<div align="center">

|             |                                                                                                                                                                                                              |
| :---------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| **Status**  | [![Build][badge-build]][link-build] [![Tests][badge-test]][link-test] [![Documentation][badge-docs]][link-docs] [![codecov][badge-codecov]][link-codecov] [![pre-commit][badge-pre-commit]][link-pre-commit] |
|  **Meta**   |         [![Hatch project][badge-hatch]][link-hatch] [![Ruff][badge-ruff]][link-ruff] [![uv][badge-uv]][link-uv] [![License][badge-license]][link-license] [![gitmoji][badge-gitmoji]][link-gitmoji]          |
| **Package** |                                                                 [![PyPI][badge-pypi]][link-pypi] [![PyPI][badge-python-versions]][link-pypi]                                                                 |
|             |                                                                                                                                                                                                              |

</div>

[badge-build]: https://github.com/srivarra/annsel/actions/workflows/build.yaml/badge.svg
[badge-test]: https://github.com/srivarra/annsel/actions/workflows/test.yaml/badge.svg
[badge-docs]: https://img.shields.io/readthedocs/annsel?logo=readthedocs
[badge-codecov]: https://codecov.io/gh/srivarra/annsel/graph/badge.svg?token=ST0ST1BTWU
[badge-ruff]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
[badge-uv]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json
[badge-license]: https://img.shields.io/badge/License-MIT-yellow.svg
[badge-hatch]: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg
[badge-pypi]: https://img.shields.io/pypi/v/annsel.svg?logo=pypi&label=PyPI&logoColor=gold
[badge-python-versions]: https://img.shields.io/pypi/pyversions/annsel.svg?logo=python&label=Python&logoColor=gold
[badge-pre-commit]: https://results.pre-commit.ci/badge/github/srivarra/annsel/main.svg
[badge-gitmoji]: https://img.shields.io/badge/gitmoji-😜😍-FFDD67.svg

Annsel is a user-friendly library that brings familiar dataframe-style operations to [`AnnData`](https://anndata.readthedocs.io/en/latest/) objects.

It's built on the [narwhals][link-narwhals] compatibility layer for dataframes.

Take a look at the GitHub Projects board for features and future plans: [Annsel Features][link-gh-project]

<!-- done -->

## Getting started

Please refer to the [documentation][link-docs], in particular, the [API documentation][link-api].

## Installation

You need to have Python 3.10 or newer installed on your system. If you don't have
Python installed, we recommend installing [uv][link-uv].
There are several ways to install `annsel`:

1. Install the most recent release:

    With `uv`:

    ```zsh
    uv add annsel
    ```

    With `pip`:

    ```zsh
    pip install annsel
    ```

2. Install the latest development version:

    With `uv`:

    ```zsh
    uv add git+https://github.com/srivarra/annsel
    ```

    With `pip`:

    ```zsh
    pip install git+https://github.com/srivarra/annsel.git@main
    ```

## Examples

```python
import annsel as an

adata=an.datasets.leukemic_bone_marrow_dataset()
```

### Filter

```python
adata.an.filter(
    obs=(
        an.col(["Cell_label"]).is_in(["Classical Monocytes", "CD8+CD103+ tissue resident memory T cells"]),
        an.col(["sex"]) == "male",
    ),
    var=an.col(["vst.mean"]) >= 3,
)
```

### Select

```python
adata.an.select(
    obs=an.col(["Cell_label"]),
    var=an.col(["vst.mean", "vst.std"]),
)
```

### Group By

```python
adata.an.group_by(
    obs=an.col(["Cell_label"]),
    var=an.col(["feature_type"]),
    return_group_names=True,
)
```

## Release notes

See the [changelog][changelog].

## Contact

For questions and help requests, you can reach out in the [scverse discourse][scverse-discourse] or the [discussions][link-disucssions] tab.
If you found a bug, please use the [issue tracker][issue-tracker].

## Citation

> Varra, S. R. annsel [Computer software]. <https://github.com/srivarra/annsel>

<!-- done3 -->

[scverse-discourse]: https://discourse.scverse.org/
[issue-tracker]: https://github.com/srivarra/annsel/issues
[changelog]: https://annsel.readthedocs.io/en/latest/changelog.html
[link-docs]: https://annsel.readthedocs.io
[link-api]: https://annsel.readthedocs.io/en/latest/api/index.html
[link-pypi]: https://pypi.org/project/annsel
[link-codecov]: https://codecov.io/gh/srivarra/annsel
[link-test]: https://github.com/srivarra/annsel/actions/workflows/test.yml
[link-build]: https://github.com/srivarra/annsel/actions/workflows/build.yaml
[link-ruff]: https://github.com/astral-sh/ruff
[link-uv]: https://github.com/astral-sh/uv
[link-license]: https://opensource.org/licenses/MIT
[link-hatch]: https://github.com/pypa/hatch
[link-narwhals]: https://github.com/narwhals-dev/narwhals
[link-disucssions]: https://github.com/srivarra/annsel/discussions
[link-pre-commit]: https://results.pre-commit.ci/latest/github/srivarra/annsel/main
[link-gitmoji]: https://gitmoji.dev/
[link-gh-project]: https://github.com/users/srivarra/projects/9
