Metadata-Version: 2.4
Name: cellitac
Version: 2.0.0
Summary: Cell type Identification using Transcription factor Analysis and Chromatin accessibility
Author-email: "Rana H. Abu-Zeid" <ranahamed2111@gmail.com>, Olaitan Awe <laitanawe@gmail.com>, Syrus Semawule <semawulesyrus@gmail.com>, Emmanuel Aroma <emmatitusaroma@gmail.com>, Toheeb Jumah <jumahtoheeb@gmail.com>, Derek Reiman <dreiman@ttic.edu>
License: MIT
Project-URL: Homepage, https://github.com/omicscodeathon/cellitac/
Project-URL: Issues, https://github.com/omicscodeathon/cellitac/issues
Keywords: single-cell,scATAC-seq,scRNA-seq,multiome,cell-type-identification,transcription-factor,chromatin-accessibility,machine-learning
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: xgboost>=2.0
Requires-Dist: imbalanced-learn>=0.11
Requires-Dist: matplotlib>=3.7
Requires-Dist: seaborn>=0.12
Requires-Dist: networkx>=3.1
Provides-Extra: r
Requires-Dist: rpy2>=3.5; extra == "r"
Provides-Extra: umap
Requires-Dist: umap-learn>=0.5; extra == "umap"
Provides-Extra: all
Requires-Dist: rpy2>=3.5; extra == "all"
Requires-Dist: umap-learn>=0.5; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# cellitac

**Cell type Identification using Transcription factor Analysis and Chromatin accessibility**

A pipeline for single-cell multiome (scATAC + scRNA) data that identifies cell
types from **transcription-factor motif activity**. RNA is used only to derive
labels; the classifier itself is trained purely on TF activity, so the model
learns chromatin-level regulatory signal.

---
## Pipeline

| Stage | Steps | Tools |
|-------|-------|-------|
| **1. Preprocessing** (R) | multiome H5 → joint RNA+ATAC QC on shared barcodes | Seurat, Signac |
| | SingleR labels from the Monaco immune reference | SingleR, celldex |
| | JASPAR motif scan → chromVAR per-cell TF activity | JASPAR2020, motifmatchr, chromVAR |
| **2. Machine learning** (Python) | class composition, unsupervised feature cleaning | pandas, scikit-learn |
| | Logistic Regression, Random Forest, SVM, XGBoost | scikit-learn, xgboost, imbalanced-learn |
| | TF ↔ cell-type association (Mann-Whitney + BH-FDR + effect size) | scipy |
| | figures, tables and a JSON report | matplotlib, seaborn, networkx |

**Scope.** cellitac has been developed and tested on human **PBMC** multiome
data, using the Monaco immune reference for SingleR labels. It works on any
human tissue whose cell types are covered by that reference (blood, bone
marrow, immune infiltrates).

**Genome builds:** hg38 (default) and hg19.

---

## Requirements

- Linux or macOS (Windows via WSL)
- Python 3.9 – 3.12
- Conda / Miniconda
- R ≥ 4.3 with the Bioconductor packages listed below (for the preprocessing
  stage). The ML stage runs on Python alone.

---

## Installation

Take the R packages from conda as pre-built binaries — do not let
`BiocManager` compile them from source (recent GCC versions fail on some of
the older Bioconductor C code, which then cascades through every downstream
package).

```bash
conda create -n cellitac -c conda-forge -c bioconda -y \
  python=3.11 rpy2 r-base=4.4 \
  r-seurat r-signac r-data.table \
  bioconductor-jaspar2020 bioconductor-tfbstools \
  bioconductor-motifmatchr bioconductor-chromvar \
  bioconductor-singler bioconductor-celldex \
  bioconductor-biovizbase bioconductor-rtracklayer \
  bioconductor-summarizedexperiment bioconductor-biocparallel \
  bioconductor-bsgenome.hsapiens.ucsc.hg38 \
  bioconductor-ensdb.hsapiens.v86

conda activate cellitac
pip install cellitac
```




For hg19 data, swap the last two conda packages for
`bioconductor-bsgenome.hsapiens.ucsc.hg19` and `bioconductor-ensdb.hsapiens.v75`.

Verify:

```bash
cellitac --version
cellitac-install-r --check-only   # must say: all N R packages present
```

If you only need the ML stage (you already have preprocessed CSVs), install
with pip alone — no R required:

```bash
pip install cellitac
```

---

## Input files

## Files required by the pipeline

cellitac detects files by extension, so **file names do not matter**. From
the 10x page above, download the three files with these extensions into one
folder:

### Required Files

| File | Extension |
| --- | --- |
| [Filtered feature-barcode matrix](https://cf.10xgenomics.com/samples/cell-arc/2.0.0/pbmc_unsorted_10k/pbmc_unsorted_10k_filtered_feature_bc_matrix.h5) | `.h5` |
| [ATAC fragments](https://cf.10xgenomics.com/samples/cell-arc/2.0.0/pbmc_unsorted_10k/pbmc_unsorted_10k_atac_fragments.tsv.gz) | `.tsv.gz` |
| [Fragments tabix index](https://cf.10xgenomics.com/samples/cell-arc/2.0.0/pbmc_unsorted_10k/pbmc_unsorted_10k_atac_fragments.tsv.gz.tbi) | `.tsv.gz.tbi` |

### Download via CLI

Alternatively, you can download these files directly from the command line:

```bash
wget https://cf.10xgenomics.com/samples/cell-arc/2.0.0/pbmc_unsorted_10k/pbmc_unsorted_10k_filtered_feature_bc_matrix.h5
wget https://cf.10xgenomics.com/samples/cell-arc/2.0.0/pbmc_unsorted_10k/pbmc_unsorted_10k_atac_fragments.tsv.gz
wget https://cf.10xgenomics.com/samples/cell-arc/2.0.0/pbmc_unsorted_10k/pbmc_unsorted_10k_atac_fragments.tsv.gz.tbi

```

Missing the tabix index? Create it with `tabix -p bed <fragments>.tsv.gz`.

---

## Usage

### Command line

The package installs four commands. Every command supports `--help` for the
full flag list.

```bash
# full pipeline (preprocessing + ML)
cellitac --input /path/to/data --output /path/to/results

# preprocessing already finished — go straight to the ML stage
cellitac --input /path/to/data --output /path/to/results --skip-preprocessing

# force re-running the R stage even if its outputs exist
cellitac --input /path/to/data --output /path/to/results --force-preprocessing

# data aligned to hg19
cellitac --input /path/to/data --output /path/to/results --genome hg19

# the two stages separately
cellitac-preprocess --input /path/to/data --output /path/to/results
cellitac-model      --data /path/to/results/preprocessing --output /path/to/results/ml_results

# one-off: install the R/Bioconductor dependencies
cellitac-install-r [--genome hg19] [--check-only]
```

`cellitac` is **resumable**: if `<output>/preprocessing/` already contains
`cellitac_TF_activity.csv` and `cell_labels.csv`, the R stage is skipped and
only the ML stage runs. Use `--force-preprocessing` to override.

### Python API

```python
from cellitac import run_full_pipeline, run_preprocessing, run_model

run_full_pipeline(input_dir="/path/to/data", output_dir="/path/to/results")

# skip R when preprocessing is already done
run_full_pipeline(input_dir="/path/to/data",
                  output_dir="/path/to/results",
                  skip_preprocessing=True)

# stages separately
run_preprocessing(input_dir="/path/to/data",
                  output_dir="/path/to/results/preprocessing")
run_model(data_dir="/path/to/results/preprocessing",
          output_dir="/path/to/results/ml_results")

# direct access to the ML class
from cellitac.mainModel import CellitacPipeline
pipe = CellitacPipeline(data_dir="/path/to/results/preprocessing",
                        out_dir="/path/to/results/ml_results")
pipe.run()
print(pipe.metrics_df)
```

---

## Output layout

```
<output>/
├── preprocessing/                    # stage 1 (R)
│   ├── cellitac_TF_activity.csv      # X — cells × TF motifs (chromVAR z-scores)
│   ├── cell_labels.csv               # y — cell_id, cell_type
│   ├── motif_to_TF_map.csv           # JASPAR motif ID → TF symbol
│   └── multiome_processed.rds        # full Seurat object
└── ml_results/                       # stage 2 (Python)
    ├── cellitac_ml_report.json
    ├── fig01_umap_TFactivity_before_training.png
    ├── fig02_class_composition_pies.png
    ├── fig03_class_imbalance_handling.png
    ├── fig04_model_comparison.png
    ├── fig05_confusion_matrices.png
    ├── fig06_importance_<model>.png
    ├── fig07_TF_network_<model>.png
    ├── fig08_learning_curves.png
    ├── fig09_umap_tsne_after_training.png
    ├── table01_class_composition.csv
    ├── table02_model_performance.csv
    ├── table03_accuracy_and_overfitting.csv
    ├── table04_per_class_metrics.csv
    ├── table05_per_class_recall.csv
    ├── table06_top20_TF_all_models.csv
    ├── table07_TF_celltype_associations_full.csv
    ├── table08_network_edges_<model>.csv
    └── table09_learning_curve.csv
```

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `rpy2 is not available` | `conda install -c conda-forge r-base rpy2` — only the preprocessing stage needs it |
| `Missing R packages: ...` | install them from conda (see Installation), not from source |
| `Could not find the H5 matrix file` | check that `--input` points at the folder holding the raw files |
| `tabix index ... missing` | `tabix -p bed <fragments>.tsv.gz` |
| `compilation failed for package 'rtracklayer'` | GCC 14 vs old UCSC C code. Use the conda binaries; or add `CFLAGS = -std=gnu17 -O2` to `~/.R/Makevars` |
| Preprocessing appears to re-run every time | it doesn't — outputs are detected and skipped. Use `--force-preprocessing` if you actually want to re-run it |

---

## Contributors

- Rana H. Abu-Zeid — ranahamed2111@gmail.com
- Syrus Semawule — semawulesyrus@gmail.com
- Emmanuel Aroma — emmatitusaroma@gmail.com
- Toheeb Jumah — jumahtoheeb@gmail.com
- Derek Reiman, Ph.D. — dreiman@ttic.edu
- Olaitan I. Awe, Ph.D. — laitanawe@gmail.com

## License

MIT
