causarray 0.0.5__tar.gz → 0.0.7__tar.gz

{causarray-0.0.5 → causarray-0.0.7}/.gitignore

@@ -1,3 +1,9 @@
+# Planning documents
+plan/
+
+# Local Codex project guidance
+/AGENTS.md
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -160,5 +166,24 @@ cython_debug/
 #.idea/
 
 
-test*
+# Generic module tests under tests/ ARE tracked (regression coverage for
+# the causarray API).  Exclude only benchmark / scratch files that are
+# not part of the unit-test suite — add new exclusions here when
+# benchmark or tutorial-coupled test files appear.
+tests/benchmark_adamson.py
+
 causarray/___*.py
+
+# Adamson tutorial is currently a local analysis and is not part of the
+# committed documentation.
+/docs/source/tutorial/adamson/
+
+# Replogle tutorial: large data files (regenerate with prep_tutorial_data.py or
+# download from the project data repository; replogle_subset.h5ad is ~2 GB)
+docs/source/tutorial/replogle/replogle_subset.h5ad
+docs/source/tutorial/replogle/replogle_subset_norm*.h5ad
+docs/source/tutorial/replogle/replogle_normed.h5ad
+docs/source/tutorial/replogle/replogle_results.h5
+
+# Unrelated tutorial directory (not part of causarray package docs)
+docs/source/tutorial/scp/

{causarray-0.0.5 → causarray-0.0.7}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: causarray
-Version: 0.0.5
+Version: 0.0.7
 Summary: causarray is a Python module for simultaneous causal inference with an array of outcomes.
-Author-email: Jin-Hong Du <jinhongd@andrew.cmu.com>, Maya Shen <myshen@andrew.cmu.edu>, Hansruedi Mathys <mathysh@pitt.edu>, Kathryn Roeder <jinhongd@andrew.cmu.com>
-Maintainer-email: Jin-Hong Du <jinhongd@andrew.cmu.com>
+Author-email: Jin-Hong Du <jinhongd@hku.hk>, Maya Shen <myshen@andrew.cmu.edu>, Hansruedi Mathys <mathysh@pitt.edu>, Kathryn Roeder <jinhongd@hku.hk>
+Maintainer-email: Jin-Hong Du <jinhongd@hku.hk>
 License: MIT License
 License-File: LICENSE
 Classifier: Intended Audience :: Developers
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
 
 # causarray
 
-Advances in single-cell sequencing and CRISPR technologies have enabled detailed case-control comparisons and experimental perturbations at single-cell resolution. However, uncovering causal relationships in observational genomic data remains challenging due to selection bias and inadequate adjustment for unmeasured confounders, particularly in heterogeneous datasets. To address these challenges, we introduce `causarray` [Du25], a doubly robust causal inference framework for analyzing array-based genomic data at both bulk-cell and single-cell levels. `causarray` integrates a generalized confounder adjustment method to account for unmeasured confounders and employs semiparametric inference with flexible machine learning techniques to ensure robust statistical estimation of treatment effects.
+Advances in single-cell sequencing and CRISPR technologies have enabled detailed case-control comparisons and experimental perturbations at single-cell resolution. However, uncovering causal relationships in observational genomic data remains challenging due to selection bias and inadequate adjustment for unmeasured confounders, particularly in heterogeneous datasets. To address these challenges, we introduce `causarray` [Du26], a doubly robust causal inference framework for analyzing array-based genomic data at both bulk-cell and single-cell levels. `causarray` integrates a generalized confounder adjustment method to account for unmeasured confounders and employs semiparametric inference with flexible machine learning techniques to ensure robust statistical estimation of treatment effects.
 
 
 ## Usage
@@ -49,17 +49,49 @@ The module can be installed via PyPI:
 pip install causarray
 ```
 
+For optimal parallel performance, we recommend installing `llvm-openmp` if using conda:
+```cmd
+conda install -c conda-forge llvm-openmp
+```
+
 For `R` users, `reticulate` can be used to call `causarray` from `R`.
 The documentation and tutorials using both `Python` and `R` are available at [causarray.readthedocs.io](https://causarray.readthedocs.io/en/latest/).
 
 
 
-## Logs
+## Tutorials
+
+| Tutorial | Language | Description | Link |
+|----------|----------|-------------|------|
+| Perturb-seq [Jin20] | Python | CRISPR screen analysis on excitatory neurons | [Notebook](https://causarray.readthedocs.io/en/latest/tutorial/perturbseq/perturbseq-py.html) |
+| Perturb-seq [Jin20] | R | Same analysis using `reticulate` | [Notebook](https://causarray.readthedocs.io/en/latest/tutorial/perturbseq/perturbseq-r.html) |
+| Genome-wide CRISPRi screen [Replogle22] | Python | Batch fitting on 200 perturbations from a K562 genome-wide CRISPRi screen | [Notebook](https://causarray.readthedocs.io/en/latest/tutorial/replogle/replogle-py.html) |
+| Case-control: SEA-AD [Gabitto24] | Python | Causal inference on observational single-cell data (Alzheimer's disease) | [Notebook](https://causarray.readthedocs.io/en/latest/tutorial/case_control/sea_ad_case_control.html) |
+
+### Batch fitting API
+
+For screens with hundreds to thousands of perturbations, use `gcate_lfc_batch` so
+that peak memory is bounded by one batch at a time:
+
+```python
+from causarray import gcate_lfc_batch
 
-- [x] (2025-01-30) Python package released on PyPI
-- [x] (2025-02-01) code for reproducing figures in paper
-- [x] (2025-02-02) Tutorial for Python and R
-- [ ] Documentation
+df_res = gcate_lfc_batch(
+    Y, X, A, r,
+    batch_size=10,    # perturbations per batch (or use n_batches= for a fixed count)
+    max_cells=2000,   # max pert cells per batch (ctrl added on top)
+    n_ctrl=2000,      # fixed ctrl subsample shared across batches
+    cache_path='results.h5',   # resume if interrupted
+    verbose=True,
+)
+```
+
+See the [Replogle-E-K562 tutorial](https://causarray.readthedocs.io/en/latest/tutorial/replogle/replogle-py.html)
+for a demonstration on 200 perturbations from a genome-wide CRISPRi screen.
+
+## Changelog
+
+See [CHANGELOG](https://causarray.readthedocs.io/en/latest/changelog.html) for a full version history.
 
 
 <!-- 
@@ -101,4 +133,10 @@ rmarkdown::render("perturbseq.Rmd", rmarkdown::md_document(variant = "markdown_g
 
 
 ## References
-[Du25] Jin-Hong Du, Maya Shen, Hansruedi Mathys, and Kathryn Roeder (2025). Causal differential expression analysis under unmeasured confounders with causarray. bioRxiv, 2025-01.
+[Du26] Jin-Hong Du, Maya Shen, Hansruedi Mathys, and Kathryn Roeder. "Uncovering causal relationships in single cell omic studies with causarray". In: Briefings in Bioinformatics (2026).
+
+[Gabitto24] Mariano I. Gabitto et al. "Integrated multimodal cell atlas of Alzheimer's disease". In: Nature Neuroscience (2024).
+
+[Jin20] Xin Jin et al. "In vivo Perturb-seq reveals neuronal and glial abnormalities associated with autism risk genes". In: Nature Neuroscience (2020).
+
+[Replogle22] Joseph M. Replogle et al. "Mapping information-rich genotype-phenotype landscapes with genome-scale Perturb-seq". In: Cell (2022).

causarray-0.0.7/README.md

@@ -0,0 +1,117 @@
+[![Documentation Status](https://readthedocs.org/projects/causarray/badge/?version=latest)](https://causarray.readthedocs.io/en/latest/?badge=latest)
+[![PyPI](https://img.shields.io/pypi/v/causarray?label=pypi)](https://pypi.org/project/causarray)
+[![PyPI-Downloads](https://img.shields.io/pepy/dt/causarray)](https://pepy.tech/project/causarray)
+
+
+# causarray
+
+Advances in single-cell sequencing and CRISPR technologies have enabled detailed case-control comparisons and experimental perturbations at single-cell resolution. However, uncovering causal relationships in observational genomic data remains challenging due to selection bias and inadequate adjustment for unmeasured confounders, particularly in heterogeneous datasets. To address these challenges, we introduce `causarray` [Du26], a doubly robust causal inference framework for analyzing array-based genomic data at both bulk-cell and single-cell levels. `causarray` integrates a generalized confounder adjustment method to account for unmeasured confounders and employs semiparametric inference with flexible machine learning techniques to ensure robust statistical estimation of treatment effects.
+
+
+## Usage
+
+We recommend using `causarray` in a conda environment:
+```cmd
+# create a new conda environment and install the necessary packages
+conda create -n causarray python=3.12 -y
+
+# activate the environment
+conda activate causarray
+```
+
+The module can be installed via PyPI:
+```cmd
+pip install causarray
+```
+
+For optimal parallel performance, we recommend installing `llvm-openmp` if using conda:
+```cmd
+conda install -c conda-forge llvm-openmp
+```
+
+For `R` users, `reticulate` can be used to call `causarray` from `R`.
+The documentation and tutorials using both `Python` and `R` are available at [causarray.readthedocs.io](https://causarray.readthedocs.io/en/latest/).
+
+
+
+## Tutorials
+
+| Tutorial | Language | Description | Link |
+|----------|----------|-------------|------|
+| Perturb-seq [Jin20] | Python | CRISPR screen analysis on excitatory neurons | [Notebook](https://causarray.readthedocs.io/en/latest/tutorial/perturbseq/perturbseq-py.html) |
+| Perturb-seq [Jin20] | R | Same analysis using `reticulate` | [Notebook](https://causarray.readthedocs.io/en/latest/tutorial/perturbseq/perturbseq-r.html) |
+| Genome-wide CRISPRi screen [Replogle22] | Python | Batch fitting on 200 perturbations from a K562 genome-wide CRISPRi screen | [Notebook](https://causarray.readthedocs.io/en/latest/tutorial/replogle/replogle-py.html) |
+| Case-control: SEA-AD [Gabitto24] | Python | Causal inference on observational single-cell data (Alzheimer's disease) | [Notebook](https://causarray.readthedocs.io/en/latest/tutorial/case_control/sea_ad_case_control.html) |
+
+### Batch fitting API
+
+For screens with hundreds to thousands of perturbations, use `gcate_lfc_batch` so
+that peak memory is bounded by one batch at a time:
+
+```python
+from causarray import gcate_lfc_batch
+
+df_res = gcate_lfc_batch(
+    Y, X, A, r,
+    batch_size=10,    # perturbations per batch (or use n_batches= for a fixed count)
+    max_cells=2000,   # max pert cells per batch (ctrl added on top)
+    n_ctrl=2000,      # fixed ctrl subsample shared across batches
+    cache_path='results.h5',   # resume if interrupted
+    verbose=True,
+)
+```
+
+See the [Replogle-E-K562 tutorial](https://causarray.readthedocs.io/en/latest/tutorial/replogle/replogle-py.html)
+for a demonstration on 200 perturbations from a genome-wide CRISPRi screen.
+
+## Changelog
+
+See [CHANGELOG](https://causarray.readthedocs.io/en/latest/changelog.html) for a full version history.
+
+
+<!-- 
+# Development
+
+The dependencies for running `causarray` method are listed in `environment.yml` and can be installed by running
+
+```cmd
+PIP_NO_DEPS=1 conda env create -f environment.yml
+```
+
+
+## Build
+```cmd
+git tag 0.0.0
+git tag --delete 1.0.0
+python -m pip install .
+```
+
+## Testing
+```cmd
+python -m pytest tests/test_gcate.py
+python -m pytest tests/test_DR_learner.py
+```
+
+## Documentation
+
+```cmd
+mkdir docs
+cd docs
+sphinx-quickstart
+
+make html # sphinx-build source build
+
+
+rmarkdown::render("perturbseq.Rmd", rmarkdown::md_document(variant = "markdown_github"))
+```
+-->
+
+
+## References
+[Du26] Jin-Hong Du, Maya Shen, Hansruedi Mathys, and Kathryn Roeder. "Uncovering causal relationships in single cell omic studies with causarray". In: Briefings in Bioinformatics (2026).
+
+[Gabitto24] Mariano I. Gabitto et al. "Integrated multimodal cell atlas of Alzheimer's disease". In: Nature Neuroscience (2024).
+
+[Jin20] Xin Jin et al. "In vivo Perturb-seq reveals neuronal and glial abnormalities associated with autism risk genes". In: Nature Neuroscience (2020).
+
+[Replogle22] Joseph M. Replogle et al. "Mapping information-rich genotype-phenotype landscapes with genome-scale Perturb-seq". In: Cell (2022).