Metadata-Version: 2.4
Name: cytogater
Version: 0.1.1
Summary: Python implementation of cytoGateR marker-aware cell annotation
Author-email: Matthew Li <mali0328@uni.sydney.edu.au>, Nikhil Karthik <nkar0221@uni.sydney.edu.au>, Harry Robertson <harry.robertson@sydney.edu.au>, Jean Yang <jean.yang@sydney.edu.au>, Lijia Yu <yulj2010@gmail.com>
Maintainer-email: Lijia Yu <yulj2010@gmail.com>
License-Expression: GPL-2.0-only
Project-URL: Homepage, https://github.com/SydneyBioX/cytoGateR
Project-URL: Repository, https://github.com/SydneyBioX/cytoGateR
Project-URL: Issues, https://github.com/SydneyBioX/cytoGateR/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anndata>=0.10
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.10
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == "plot"
Requires-Dist: seaborn>=0.13; extra == "plot"
Provides-Extra: torch
Requires-Dist: torch>=2.1; extra == "torch"
Provides-Extra: notebook
Requires-Dist: ipykernel>=6; extra == "notebook"
Requires-Dist: jupyterlab>=4; extra == "notebook"
Requires-Dist: nbclient>=0.10; extra == "notebook"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# cytoGateR Python

This is the Python implementation of `cytoGateR`. It uses an `AnnData` object
and keeps the R function names, parameter names, and defaults where Python
syntax permits.

Implemented modules include:

- marker GMMs, soft gating, and tree gating;
- hierarchical reference construction and recursive hierarchical kNN;
- weighted kNN consensus cleaning and prediction;
- random-forest consensus cleaning and prediction;
- optional PyTorch training and prediction;
- confidence labels, cutoffs, F1, confusion, and agreement metrics;
- probability and spatial uncertainty;
- Matplotlib spatial, marker, label, metric, and tree plots.

## Installation

Install the latest release from PyPI:

```bash
pip install cytogater
```

Plotting, neural-network, and notebook support are available as optional extras:

```bash
pip install 'cytogater[plot]'
pip install 'cytogater[torch]'
pip install 'cytogater[notebook]'
```

To install from source for development, clone the repository and create the
provided Conda environment:

```bash
git clone https://github.com/SydneyBioX/cytoGateR.git
cd cytoGateR/python
conda env create -f environment.yml
conda activate cytogater-python
pytest
```

## Data layout

Python `AnnData` stores cells in rows and markers in columns. Put the expression
matrix used by the R `assay_name = "exprs"` default in:

```python
adata.layers["exprs"]
```

The lineage table is a pandas data frame with `cell_type`, `pos_markers`, and
`neg_markers` columns. The marker columns contain Python lists.

## Example

```python
import pandas as pd
import cytogater

lineage_table = pd.DataFrame({
    "cell_type": ["Tcell", "Bcell"],
    "pos_markers": [["CD3e"], ["CD20"]],
    "neg_markers": [["CD20"], ["CD3e"]],
})

result = cytogater.run_tree_gating(
    adata,
    lineage_table,
    assay_name="exprs",
    max_depth=1,
    min_cells=100,
    min_score=0.1,
    workers=1,
)

result["hard_label"]
result["prob_mat"]
```

Results are returned with the same main keys as R. Labels and `P_*` columns are
also stored in `adata.obs`; probability matrices are stored in `adata.obsm`.

The package is intentionally flat at its public surface:

```python
cytogater.run_soft_gating(...)
cytogater.run_tree_gating(...)
cytogater.train_custom_knn(...)
cytogater.train_custom_randomforest(...)
cytogater.calculate_uncertainty(...)
```

The implementations are also grouped under `cytogater.gating`,
`cytogater.models`, `cytogater.metrics`, `cytogater.uncertainty`, and
`cytogater.plotting`.

## R compatibility note

The Python implementation uses a deterministic two-component Gaussian-mixture
fit. R uses `mclust`, so fitted cutoffs can differ slightly even though the
pipeline, parameters, defaults, scoring, and output structure are aligned.
The Python `lambda_` argument corresponds to the R `lambda` argument because
`lambda` is reserved syntax in Python. `num_trees` corresponds to R's
`num.trees`; `train_custom_randomforest()` also accepts `**{"num.trees": 200}`.

Run tests with:

```bash
cd cytoGateR/python
pytest
```
