cytogater 0.1.1__tar.gz

cytogater-0.1.1/LICENSE

@@ -0,0 +1,9 @@
+This package is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License version 2 as published by the Free
+Software Foundation.
+
+This package is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+for the complete license text.
+

cytogater-0.1.1/PKG-INFO

@@ -0,0 +1,153 @@
+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
+```

cytogater-0.1.1/README.md

@@ -0,0 +1,114 @@
+# 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
+```

cytogater-0.1.1/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cytogater"
+version = "0.1.1"
+description = "Python implementation of cytoGateR marker-aware cell annotation"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "GPL-2.0-only"
+license-files = ["LICENSE"]
+authors = [
+  {name = "Matthew Li", email = "mali0328@uni.sydney.edu.au"},
+  {name = "Nikhil Karthik", email = "nkar0221@uni.sydney.edu.au"},
+  {name = "Harry Robertson", email = "harry.robertson@sydney.edu.au"},
+  {name = "Jean Yang", email = "jean.yang@sydney.edu.au"},
+  {name = "Lijia Yu", email = "yulj2010@gmail.com"},
+]
+maintainers = [
+  {name = "Lijia Yu", email = "yulj2010@gmail.com"},
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+  "anndata>=0.10",
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "scikit-learn>=1.3",
+  "scipy>=1.10",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.7", "seaborn>=0.13"]
+torch = ["torch>=2.1"]
+notebook = ["ipykernel>=6", "jupyterlab>=4", "nbclient>=0.10"]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/SydneyBioX/cytoGateR"
+Repository = "https://github.com/SydneyBioX/cytoGateR"
+Issues = "https://github.com/SydneyBioX/cytoGateR/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "slow: needs the shared PRJ-cytogater data and runs for ~1 minute per dataset",
+]

cytogater-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cytogater-0.1.1/src/cytogater/__init__.py

@@ -0,0 +1,110 @@
+"""Marker-aware cell annotation for Python."""
+
+from .core import (
+    assign_soft_labels,
+    build_fullcoverage_tree,
+    calculate_soft_scores,
+    collect_path_scores,
+    fit_gmm_2,
+    fit_marker_stats,
+    gmm_equal_posterior_cutoff,
+    marker_separability,
+    neg_penalty,
+    run_soft_gating,
+    run_tree_gating,
+    score_marker_logistic,
+    score_marker_rank,
+    tree_prob,
+)
+from .gating.hierarchical import (
+    build_hierarchical_reference,
+    build_lineage_hierarchy,
+)
+from .metrics import (
+    apply_cutoff_labels,
+    assign_confident_labels,
+    calculate_f1,
+    class_metrics_from_fit,
+    compute_custom_labels,
+    custom_labels,
+    label_agreement_rates,
+    label_confusion_matrix,
+    prob_mad_cutoff,
+    prob_quantile_cutoff,
+    probability_label_matrix,
+)
+from .models.neural_network import predict_unknown_with_dl, train_custom_dl
+from .plotting import (
+    plot_celltype_tree,
+    plot_class_metrics,
+    plot_confusion_matrix,
+    plot_ct_marker_intensity,
+    plot_label_agreement,
+    plot_label_cardinality,
+    plot_label_confusion_matrix,
+    plot_label_counts,
+    plot_label_dotplot,
+    plot_labelled_cells,
+    plot_marker_density,
+    plot_marker_priority_tree,
+    plot_probability_map,
+    plot_pseudobulk_heatmap,
+    plot_rand_cell_probs,
+    plot_score_hist,
+    print_celltype_tree,
+    tree_to_df,
+)
+
+try:
+    from .models.knn import (
+        predict_hierarchical_knn_recursive,
+        predict_unknown_with_knn,
+        predict_wknn_multi,
+        train_custom_knn,
+    )
+    from .models.random_forest import (
+        predict_unknown_with_randomforest,
+        rf_metric_table,
+        rf_metric_text,
+        train_custom_randomforest,
+    )
+    from .uncertainty import calculate_spatial_prior_labels, calculate_uncertainty
+except ImportError:
+    # Gating remains importable in lightweight environments. A normal package
+    # installation installs scikit-learn and exposes these functions.
+    pass
+
+__all__ = [
+    "assign_soft_labels",
+    "build_fullcoverage_tree",
+    "calculate_soft_scores",
+    "collect_path_scores",
+    "fit_gmm_2",
+    "fit_marker_stats",
+    "gmm_equal_posterior_cutoff",
+    "marker_separability",
+    "neg_penalty",
+    "run_soft_gating",
+    "run_tree_gating",
+    "score_marker_logistic",
+    "score_marker_rank",
+    "tree_prob",
+    "apply_cutoff_labels", "assign_confident_labels",
+    "build_hierarchical_reference", "build_lineage_hierarchy",
+    "calculate_f1", "calculate_spatial_prior_labels", "calculate_uncertainty",
+    "class_metrics_from_fit", "compute_custom_labels", "custom_labels",
+    "label_agreement_rates", "label_confusion_matrix",
+    "predict_hierarchical_knn_recursive", "predict_unknown_with_dl",
+    "predict_unknown_with_knn", "predict_unknown_with_randomforest",
+    "predict_wknn_multi", "prob_mad_cutoff", "prob_quantile_cutoff",
+    "probability_label_matrix", "rf_metric_table", "rf_metric_text",
+    "train_custom_dl", "train_custom_knn", "train_custom_randomforest",
+    "plot_celltype_tree", "plot_class_metrics", "plot_confusion_matrix",
+    "plot_ct_marker_intensity", "plot_label_agreement",
+    "plot_label_cardinality", "plot_label_confusion_matrix",
+    "plot_label_counts", "plot_label_dotplot", "plot_labelled_cells",
+    "plot_marker_density", "plot_marker_priority_tree",
+    "plot_probability_map", "plot_pseudobulk_heatmap",
+    "plot_rand_cell_probs", "plot_score_hist", "print_celltype_tree",
+    "tree_to_df",
+]