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

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).

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:

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:

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

Download via CLI

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

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.

# 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

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

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