recursieve 1.0.0__tar.gz

recursieve-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The recursieve authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

recursieve-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE README.md
+recursive-include tests *.py
+prune manuscript
+prune data
+prune env
+global-exclude __pycache__ *.py[cod] *.h5ad

recursieve-1.0.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: recursieve
+Version: 1.0.0
+Summary: Iterative gene selection algorithm for single-cell group comparisons
+Author: Kenny Pavan
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ArpiarSaundersLab/RecurSieve
+Project-URL: Source, https://github.com/ArpiarSaundersLab/RecurSieve
+Project-URL: Issues, https://github.com/ArpiarSaundersLab/RecurSieve/issues
+Keywords: single-cell,scRNA-seq,feature selection,gene selection,random forest,anndata,scanpy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: AnnSQL>=1.0.3
+Requires-Dist: anndata>=0.10
+Requires-Dist: joblib>=1.3
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scanpy>=1.10
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.10
+Requires-Dist: seaborn>=0.13
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ArpiarSaundersLab/RecurSieve/main/manuscript/logo_dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ArpiarSaundersLab/RecurSieve/main/manuscript/logo_light.png">
+    <img src="https://raw.githubusercontent.com/ArpiarSaundersLab/RecurSieve/main/manuscript/logo_light.png" alt="Recursieve logo" width="360">
+  </picture>
+</p>
+
+
+**RecurSieve** is an iterative gene selection algorithm that identifies discriminative genes between two biological groups in single-cell datasets. It uses an ensemble learning approach with a blend of random forest classifiers and gaussian mixture models to progressively select genes that best separate the groups, collapsing selected genes into a lower dimensional representational axis at each iteration.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install recursieve
+```
+
+RecurSieve requires Python 3.12 or newer.
+
+To install the development version from GitHub:
+
+```bash
+pip install git+https://github.com/ArpiarSaundersLab/RecurSieve.git
+```
+
+## Usage
+
+```python
+import anndata as ad
+from recursieve import recursieve
+
+adata = ad.read_h5ad("data/alz.h5ad")
+model = recursieve(
+    adata=adata,
+    group1="control",
+    group2="disease",
+    field_name="condition",
+    max_iterations=100,
+)
+
+# all genes found
+panel = model.genes
+
+# genes unique to RecurSieve
+non_de_genes = model.unique_gene_panel 
+ ```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| adata | AnnData | required | Annotated data matrix |
+| group1 | str | required | First group label |
+| group2 | str | required | Second group label |
+| field_name | str | "sample" | Column in obs containing group labels |
+| plots | bool | False | Generate visualization plots |
+| print_to_console | bool | False | Print selected genes during iteration |
+| max_iterations | int | 100 | Maximum iterations to run |
+| additive | bool | True | Add new genes to panel or replace |
+| flip_rate_percentage | float | 0.01 | Stop when the label flip rate falls below this value |
+| patience | int or None | 10 | Stop after this many iterations without a new flip-rate minimum (None disables) |
+| pval_cutoff | float | 0.05 | P-value threshold for differential expression |
+| logfc_cutoff | float | 0.1 | Absolute log2 fold-change threshold for differential expression |
+| seed | int | 42 | Random seed for reproducibility |
+| summary_method | str | "mean" | Method to collapse genes: "mean" or "pca" |
+| n_estimators | int | 300 | Number of random forest trees |
+| n_jobs | int | -1 | Number of parallel jobs (-1 uses all cores) |
+| max_depth | int or None | 10 | Maximum random forest tree depth |
+| n_seeds | int | 10 | Seeds used by `seed_stability()` |
+| preprocess | bool | True | Run QC, normalization, and HVG selection |
+| run | bool | True | Run the pipeline on construction; if False, call `fit()` later |
+| annsql_db | str or None | None | AnnSQL database to load instead of `adata` |
+
+## Robustness checks
+
+`seed_stability` checks whether the same genes are selected with different random seeds. `coexpression_null` checks whether the selected genes are found more often than by chance, by rerunning on randomized data.
+
+Each seed and each shuffle is a full RecurSieve run, so these checks take much longer than a single run. On a 10-core laptop, 25 shuffles took about 1.5 hours for 25,000 cells and about 3.5 hours for 50,000 cells.
+
+Both methods return a dictionary of pandas DataFrames and do not write files. The example below runs both checks and saves the main tables as CSV files.
+
+```python
+seeds = model.seed_stability(n_seeds=10)
+null = model.coexpression_null(n_shuffles=25)
+
+seeds["gene_frequency"].to_csv("seed_gene_frequency.csv", index=False)
+null["pvalues"].to_csv("null_pvalues.csv", index=False)
+null["gene_frequency"].to_csv("null_gene_frequency.csv", index=False)
+```
+
+<br>
+
+## License
+
+The RecurSieve software is released under the [MIT License](https://github.com/ArpiarSaundersLab/RecurSieve/blob/main/LICENSE). The data, figures, and tables in [`manuscript/`](https://github.com/ArpiarSaundersLab/RecurSieve/tree/main/manuscript) are dedicated to the public domain under [CC0 1.0](https://github.com/ArpiarSaundersLab/RecurSieve/blob/main/manuscript/LICENSE).
+
+## Citation
+
+RecurSieve: An Ensemble Learning Algorithm for Single-Cell Feature Selection Captures Subtle Gene Expression Patterns<br>
+<i>bioRxiv link coming soon</i>

recursieve-1.0.0/README.md

@@ -0,0 +1,102 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ArpiarSaundersLab/RecurSieve/main/manuscript/logo_dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ArpiarSaundersLab/RecurSieve/main/manuscript/logo_light.png">
+    <img src="https://raw.githubusercontent.com/ArpiarSaundersLab/RecurSieve/main/manuscript/logo_light.png" alt="Recursieve logo" width="360">
+  </picture>
+</p>
+
+
+**RecurSieve** is an iterative gene selection algorithm that identifies discriminative genes between two biological groups in single-cell datasets. It uses an ensemble learning approach with a blend of random forest classifiers and gaussian mixture models to progressively select genes that best separate the groups, collapsing selected genes into a lower dimensional representational axis at each iteration.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install recursieve
+```
+
+RecurSieve requires Python 3.12 or newer.
+
+To install the development version from GitHub:
+
+```bash
+pip install git+https://github.com/ArpiarSaundersLab/RecurSieve.git
+```
+
+## Usage
+
+```python
+import anndata as ad
+from recursieve import recursieve
+
+adata = ad.read_h5ad("data/alz.h5ad")
+model = recursieve(
+    adata=adata,
+    group1="control",
+    group2="disease",
+    field_name="condition",
+    max_iterations=100,
+)
+
+# all genes found
+panel = model.genes
+
+# genes unique to RecurSieve
+non_de_genes = model.unique_gene_panel 
+ ```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| adata | AnnData | required | Annotated data matrix |
+| group1 | str | required | First group label |
+| group2 | str | required | Second group label |
+| field_name | str | "sample" | Column in obs containing group labels |
+| plots | bool | False | Generate visualization plots |
+| print_to_console | bool | False | Print selected genes during iteration |
+| max_iterations | int | 100 | Maximum iterations to run |
+| additive | bool | True | Add new genes to panel or replace |
+| flip_rate_percentage | float | 0.01 | Stop when the label flip rate falls below this value |
+| patience | int or None | 10 | Stop after this many iterations without a new flip-rate minimum (None disables) |
+| pval_cutoff | float | 0.05 | P-value threshold for differential expression |
+| logfc_cutoff | float | 0.1 | Absolute log2 fold-change threshold for differential expression |
+| seed | int | 42 | Random seed for reproducibility |
+| summary_method | str | "mean" | Method to collapse genes: "mean" or "pca" |
+| n_estimators | int | 300 | Number of random forest trees |
+| n_jobs | int | -1 | Number of parallel jobs (-1 uses all cores) |
+| max_depth | int or None | 10 | Maximum random forest tree depth |
+| n_seeds | int | 10 | Seeds used by `seed_stability()` |
+| preprocess | bool | True | Run QC, normalization, and HVG selection |
+| run | bool | True | Run the pipeline on construction; if False, call `fit()` later |
+| annsql_db | str or None | None | AnnSQL database to load instead of `adata` |
+
+## Robustness checks
+
+`seed_stability` checks whether the same genes are selected with different random seeds. `coexpression_null` checks whether the selected genes are found more often than by chance, by rerunning on randomized data.
+
+Each seed and each shuffle is a full RecurSieve run, so these checks take much longer than a single run. On a 10-core laptop, 25 shuffles took about 1.5 hours for 25,000 cells and about 3.5 hours for 50,000 cells.
+
+Both methods return a dictionary of pandas DataFrames and do not write files. The example below runs both checks and saves the main tables as CSV files.
+
+```python
+seeds = model.seed_stability(n_seeds=10)
+null = model.coexpression_null(n_shuffles=25)
+
+seeds["gene_frequency"].to_csv("seed_gene_frequency.csv", index=False)
+null["pvalues"].to_csv("null_pvalues.csv", index=False)
+null["gene_frequency"].to_csv("null_gene_frequency.csv", index=False)
+```
+
+<br>
+
+## License
+
+The RecurSieve software is released under the [MIT License](https://github.com/ArpiarSaundersLab/RecurSieve/blob/main/LICENSE). The data, figures, and tables in [`manuscript/`](https://github.com/ArpiarSaundersLab/RecurSieve/tree/main/manuscript) are dedicated to the public domain under [CC0 1.0](https://github.com/ArpiarSaundersLab/RecurSieve/blob/main/manuscript/LICENSE).
+
+## Citation
+
+RecurSieve: An Ensemble Learning Algorithm for Single-Cell Feature Selection Captures Subtle Gene Expression Patterns<br>
+<i>bioRxiv link coming soon</i>

recursieve-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "recursieve"
+version = "1.0.0"
+description = "Iterative gene selection algorithm for single-cell group comparisons"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [
+  { name = "Kenny Pavan" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["single-cell", "scRNA-seq", "feature selection", "gene selection", "random forest", "anndata", "scanpy"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+  "AnnSQL>=1.0.3",
+  "anndata>=0.10",
+  "joblib>=1.3",
+  "matplotlib>=3.7",
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "scanpy>=1.10",
+  "scikit-learn>=1.3",
+  "scipy>=1.10",
+  "seaborn>=0.13",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/ArpiarSaundersLab/RecurSieve"
+Source = "https://github.com/ArpiarSaundersLab/RecurSieve"
+Issues = "https://github.com/ArpiarSaundersLab/RecurSieve/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

recursieve-1.0.0/setup.cfg

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

recursieve-1.0.0/src/recursieve/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from .recursieve import recursieve
+
+try:
+    __version__ = version("recursieve")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__all__ = ["recursieve", "__version__"]