cellitac 1.0.0__tar.gz

cellitac-1.0.0/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2025 Rana Hamed, Syrus, Emmanuel
+
+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.

cellitac-1.0.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: cellitac
+Version: 1.0.0
+Summary: Cell type identification using Transcription factor Analysis and Chromatin accessibility
+Author-email: Rana H Abuzeid <ranahamed2111@gmail.com>, Olaitan Awe <laitanawe@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/omicscodeathon/cellitac/
+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: 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: openpyxl>=3.1
+Requires-Dist: rpy2>=3.5
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: xgboost>=2.0
+Requires-Dist: imbalanced-learn>=0.11
+Requires-Dist: sklearn-compat>=0.1.5
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: seaborn>=0.12
+Requires-Dist: plotly>=5.18
+Requires-Dist: networkx>=3.1
+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"
+Dynamic: license-file
+
+# scatactf
+
+Single-Cell ATAC + RNA Multiome Processing & ML Classification Pipeline
+
+---
+
+## What It Does
+
+| Stage | Steps | Tools |
+|-------|-------|-------|
+| **Preprocessing** | RNA QC → normalization → cell-type annotation | Seurat + SingleR (R via rpy2) |
+| **Preprocessing** | ATAC QC → TF-IDF → LSI | Signac (R via rpy2) |
+| **Preprocessing** | RNA + ATAC integration → ML-ready CSVs | Pure Python |
+| **ML** | Imbalance analysis → SMOTE → feature selection | scikit-learn, imbalanced-learn |
+| **ML** | RF + XGBoost + SVM training & evaluation | scikit-learn, xgboost |
+| **ML** | 19 plots + JSON report + XLSX | matplotlib, seaborn, networkx |
+
+---
+
+## Installation
+
+### Option A – Local / Team (pip install -e)
+
+```bash
+git clone https://github.com/your-org/scatactf.git
+cd scatactf
+
+# Install R packages (run once inside R)
+Rscript -e "
+  install.packages('BiocManager')
+  BiocManager::install(c(
+    'Seurat', 'Signac', 'SingleR', 'celldex',
+    'SingleCellExperiment', 'GenomicRanges',
+    'EnsDb.Hsapiens.v75', 'biovizBase', 'hdf5r'
+  ))
+"
+
+# Install Python package
+pip install -e ".[dev]"
+```
+
+### Option B – PyPI
+
+```bash
+pip install scatactf
+# R must be installed separately
+```
+
+### Option C – Docker (recommended for full reproducibility)
+
+```bash
+docker build -t scatactf:1.0.0 -f docker/Dockerfile .
+
+docker run --rm \
+  -v /your/data:/data \
+  -v $(pwd)/results:/results \
+  scatactf:1.0.0 \
+  --input /data --output /results
+```
+
+---
+
+## Data Download
+
+https://www.10xgenomics.com/datasets/pbmc-from-a-healthy-donor-no-cell-sorting-10-k-1-standard-1-0-0
+
+Required files (place in your `--input` directory):
+```
+pbmc_unsorted_10k_filtered_feature_bc_matrix.h5
+pbmc_unsorted_10k_per_barcode_metrics.csv
+pbmc_unsorted_10k_atac_fragments.tsv.gz
+pbmc_unsorted_10k_atac_fragments.tsv.gz.tbi
+pbmc_unsorted_10k_atac_peaks.bed
+```
+
+---
+
+## Usage
+
+### Command Line
+
+```bash
+# Full pipeline (preprocessing + ML)
+scatactf --input ~/singlecell/ATAC --output my_results
+
+# Preprocessing only (generates python_ready_data/)
+scatactf-preprocess --input ~/singlecell/ATAC --output my_results
+
+# ML only (if you already have python_ready_data/)
+scatactf-model --data my_results/python_ready_data --output my_results/ml
+```
+
+### Python API
+
+```python
+from scatactf import run_full_pipeline, run_preprocessing, run_model
+
+# Full pipeline
+run_full_pipeline(input_dir="~/singlecell/ATAC", output_dir="my_results")
+
+# Preprocessing only
+run_preprocessing(input_dir="~/singlecell/ATAC", output_dir_python="python_ready_data")
+
+# ML only
+run_model(data_dir="python_ready_data", output_dir="ml_results")
+
+# Use the ML class directly for more control
+from scatactf.mainModel import scATACMLPipeline
+pipeline = scATACMLPipeline(data_dir="python_ready_data", output_dir="ml_results")
+pipeline.run_complete_pipeline()
+```
+
+### Environment Variables
+
+```bash
+export SCATAC_INPUT_DIR=~/singlecell/ATAC
+export SCATAC_OUT_ML=ml_results
+scatactf
+```
+
+---
+
+## Output Files
+
+### ml_results/
+| File | Description |
+|------|-------------|
+| `ml_pipeline_report.json` | Full JSON report |
+| `model_performance_summary.csv` | Accuracy/F1/AUC per model |
+| `detailed_model_results.xlsx` | Per-class metrics, CV results |
+| `model_performance_comparison.png` | Bar chart comparison |
+| `confusion_matrices.png` | Confusion matrices |
+| `class_distribution_analysis.png` | Cell type distribution |
+| `class_balancing_comparison.png` | Before/after SMOTE |
+| `feature_importance.png` | RF + XGBoost top 20 features |
+| `simple_feature_heatmap.png` | Feature importance heatmap |
+| `overfitting_analysis.png` | CV train vs validation |
+| `learning_curves.png` | Learning curves per model |
+| `performance_radar.png` | Radar chart |
+| `feature_distributions.png` | Violin plots |
+| `class_separation_pca.png` | PCA scatter |
+| `basic_tf_network.png` | Feature–cell-type network |
+
+---
+
+## Package Structure
+
+```
+scatactf/
+├── src/scatactf/
+│   ├── __init__.py          # Public API
+│   ├── _version.py
+│   ├── config.py            # All parameters (paths, QC thresholds, ML hyperparams)
+│   ├── pipeline.py          # run_preprocessing, run_model, run_full_pipeline
+│   ├── preprocessing.py     # R preprocessing via rpy2
+│   ├── mainModel.py         # scATACMLPipeline class (19-step ML pipeline)
+│   ├── cli.py               # scatactf / scatactf-preprocess / scatactf-model
+│   └── rscripts/
+│       ├── team1_rna.R      # Exact Seurat + SingleR code
+│       └── team2_atac.R     # Exact Signac code
+├── tests/
+│   └── test_model.py
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT

cellitac-1.0.0/README.md

@@ -0,0 +1,180 @@
+# scatactf
+
+Single-Cell ATAC + RNA Multiome Processing & ML Classification Pipeline
+
+---
+
+## What It Does
+
+| Stage | Steps | Tools |
+|-------|-------|-------|
+| **Preprocessing** | RNA QC → normalization → cell-type annotation | Seurat + SingleR (R via rpy2) |
+| **Preprocessing** | ATAC QC → TF-IDF → LSI | Signac (R via rpy2) |
+| **Preprocessing** | RNA + ATAC integration → ML-ready CSVs | Pure Python |
+| **ML** | Imbalance analysis → SMOTE → feature selection | scikit-learn, imbalanced-learn |
+| **ML** | RF + XGBoost + SVM training & evaluation | scikit-learn, xgboost |
+| **ML** | 19 plots + JSON report + XLSX | matplotlib, seaborn, networkx |
+
+---
+
+## Installation
+
+### Option A – Local / Team (pip install -e)
+
+```bash
+git clone https://github.com/your-org/scatactf.git
+cd scatactf
+
+# Install R packages (run once inside R)
+Rscript -e "
+  install.packages('BiocManager')
+  BiocManager::install(c(
+    'Seurat', 'Signac', 'SingleR', 'celldex',
+    'SingleCellExperiment', 'GenomicRanges',
+    'EnsDb.Hsapiens.v75', 'biovizBase', 'hdf5r'
+  ))
+"
+
+# Install Python package
+pip install -e ".[dev]"
+```
+
+### Option B – PyPI
+
+```bash
+pip install scatactf
+# R must be installed separately
+```
+
+### Option C – Docker (recommended for full reproducibility)
+
+```bash
+docker build -t scatactf:1.0.0 -f docker/Dockerfile .
+
+docker run --rm \
+  -v /your/data:/data \
+  -v $(pwd)/results:/results \
+  scatactf:1.0.0 \
+  --input /data --output /results
+```
+
+---
+
+## Data Download
+
+https://www.10xgenomics.com/datasets/pbmc-from-a-healthy-donor-no-cell-sorting-10-k-1-standard-1-0-0
+
+Required files (place in your `--input` directory):
+```
+pbmc_unsorted_10k_filtered_feature_bc_matrix.h5
+pbmc_unsorted_10k_per_barcode_metrics.csv
+pbmc_unsorted_10k_atac_fragments.tsv.gz
+pbmc_unsorted_10k_atac_fragments.tsv.gz.tbi
+pbmc_unsorted_10k_atac_peaks.bed
+```
+
+---
+
+## Usage
+
+### Command Line
+
+```bash
+# Full pipeline (preprocessing + ML)
+scatactf --input ~/singlecell/ATAC --output my_results
+
+# Preprocessing only (generates python_ready_data/)
+scatactf-preprocess --input ~/singlecell/ATAC --output my_results
+
+# ML only (if you already have python_ready_data/)
+scatactf-model --data my_results/python_ready_data --output my_results/ml
+```
+
+### Python API
+
+```python
+from scatactf import run_full_pipeline, run_preprocessing, run_model
+
+# Full pipeline
+run_full_pipeline(input_dir="~/singlecell/ATAC", output_dir="my_results")
+
+# Preprocessing only
+run_preprocessing(input_dir="~/singlecell/ATAC", output_dir_python="python_ready_data")
+
+# ML only
+run_model(data_dir="python_ready_data", output_dir="ml_results")
+
+# Use the ML class directly for more control
+from scatactf.mainModel import scATACMLPipeline
+pipeline = scATACMLPipeline(data_dir="python_ready_data", output_dir="ml_results")
+pipeline.run_complete_pipeline()
+```
+
+### Environment Variables
+
+```bash
+export SCATAC_INPUT_DIR=~/singlecell/ATAC
+export SCATAC_OUT_ML=ml_results
+scatactf
+```
+
+---
+
+## Output Files
+
+### ml_results/
+| File | Description |
+|------|-------------|
+| `ml_pipeline_report.json` | Full JSON report |
+| `model_performance_summary.csv` | Accuracy/F1/AUC per model |
+| `detailed_model_results.xlsx` | Per-class metrics, CV results |
+| `model_performance_comparison.png` | Bar chart comparison |
+| `confusion_matrices.png` | Confusion matrices |
+| `class_distribution_analysis.png` | Cell type distribution |
+| `class_balancing_comparison.png` | Before/after SMOTE |
+| `feature_importance.png` | RF + XGBoost top 20 features |
+| `simple_feature_heatmap.png` | Feature importance heatmap |
+| `overfitting_analysis.png` | CV train vs validation |
+| `learning_curves.png` | Learning curves per model |
+| `performance_radar.png` | Radar chart |
+| `feature_distributions.png` | Violin plots |
+| `class_separation_pca.png` | PCA scatter |
+| `basic_tf_network.png` | Feature–cell-type network |
+
+---
+
+## Package Structure
+
+```
+scatactf/
+├── src/scatactf/
+│   ├── __init__.py          # Public API
+│   ├── _version.py
+│   ├── config.py            # All parameters (paths, QC thresholds, ML hyperparams)
+│   ├── pipeline.py          # run_preprocessing, run_model, run_full_pipeline
+│   ├── preprocessing.py     # R preprocessing via rpy2
+│   ├── mainModel.py         # scATACMLPipeline class (19-step ML pipeline)
+│   ├── cli.py               # scatactf / scatactf-preprocess / scatactf-model
+│   └── rscripts/
+│       ├── team1_rna.R      # Exact Seurat + SingleR code
+│       └── team2_atac.R     # Exact Signac code
+├── tests/
+│   └── test_model.py
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT

cellitac-1.0.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cellitac"
+version = "1.0.0"
+description = "Cell type identification using Transcription factor Analysis and Chromatin accessibility"
+readme = "README.md"
+license = {text = "MIT"}
+
+authors = [
+    {name = "Rana H Abuzeid", email = "ranahamed2111@gmail.com"},
+    {name = "Olaitan Awe", email = "laitanawe@gmail.com"}
+]
+keywords = [
+  "single-cell", "scATAC-seq", "scRNA-seq", "multiome",
+  "cell-type-identification", "transcription-factor",
+  "chromatin-accessibility", "machine-learning"
+]
+
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.9"
+
+dependencies = [
+  # Data
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "openpyxl>=3.1",
+  # rpy2 bridge
+  "rpy2>=3.5",
+  # ML
+  "scikit-learn>=1.3",
+  "xgboost>=2.0",
+  "imbalanced-learn>=0.11",
+  "sklearn-compat>=0.1.5",
+  # Visualization
+  "matplotlib>=3.7",
+  "seaborn>=0.12",
+  "plotly>=5.18",
+  "networkx>=3.1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-cov",
+  "black",
+  "ruff",
+]
+
+[project.scripts]
+cellitac            = "cellitac.cli:main"
+cellitac-preprocess = "cellitac.cli:run_preprocess"
+cellitac-model      = "cellitac.cli:run_model"
+
+[project.urls]
+Homepage = "https://github.com/omicscodeathon/cellitac/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+cellitac = ["rscripts/*.R"]

cellitac-1.0.0/setup.cfg

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

cellitac-1.0.0/src/cellitac/__init__.py

@@ -0,0 +1,41 @@
+"""
+cellitac
+========
+Single-Cell ATAC + RNA Multiome Processing & ML Classification Pipeline.
+
+This package runs two stages end-to-end:
+
+  Stage 1 – Preprocessing (R via rpy2)
+      • Team 1: RNA processing, QC, normalization, cell-type annotation
+                (Seurat + SingleR + celldex)
+      • Team 2: ATAC processing, QC, TF-IDF, LSI
+                (Signac + EnsDb)
+      • Integration: combine RNA + ATAC → ML-ready CSVs
+
+  Stage 2 – ML Classification (pure Python)
+      • Class imbalance analysis & SMOTE balancing
+      • Feature engineering & selection
+      • Random Forest, XGBoost, SVM training
+      • Evaluation, visualizations, reports
+
+Quick start
+-----------
+>>> from cellitac import run_preprocessing, run_model, run_full_pipeline
+>>> run_full_pipeline(input_dir="~/singlecell/ATAC", output_dir="results")
+
+Or from the command line::
+
+    cellitac --input ~/singlecell/ATAC --output results
+    cellitac-preprocess --input ~/singlecell/ATAC
+    cellitac-model --data python_ready_data --output ml_results
+"""
+
+from cellitac._version import __version__
+from cellitac.pipeline import run_preprocessing, run_model, run_full_pipeline
+
+__all__ = [
+    "run_preprocessing",
+    "run_model",
+    "run_full_pipeline",
+    "__version__",
+]

cellitac-1.0.0/src/cellitac/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

cellitac-1.0.0/src/cellitac/cli.py

@@ -0,0 +1,147 @@
+"""
+cellitac.cli
+============
+Command-line interface for the cellitac package.
+
+Installed entry points (pyproject.toml):
+  cellitac            → run full pipeline (preprocessing + ML)
+  cellitac-preprocess → run preprocessing only (R steps)
+  cellitac-model      → run ML model only (on existing python_ready_data)
+
+Examples
+--------
+  # Full pipeline
+  cellitac --input ~/singlecell/ATAC --output results/
+
+  # Preprocessing only
+  cellitac-preprocess --input ~/singlecell/ATAC --output results/
+
+  # ML only (after preprocessing)
+  cellitac-model --data results/python_ready_data --output results/ml_results
+"""
+
+import argparse
+import sys
+
+from cellitac import config as cfg
+from cellitac.pipeline import run_full_pipeline, run_preprocessing, run_model
+
+
+# ============================================================================
+# Full pipeline CLI
+# ============================================================================
+def main():
+    parser = argparse.ArgumentParser(
+        prog="cellitac",
+        description="scATAC + RNA Multiome Processing & ML Classification Pipeline",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  cellitac --input ~/singlecell/ATAC --output my_results
+  cellitac --input /data/pbmc10k
+        """,
+    )
+    parser.add_argument(
+        "--input", "-i",
+        default=cfg.INPUT_DIR,
+        metavar="DIR",
+        help=f"Raw 10x data directory  (default: {cfg.INPUT_DIR})",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        default="cellitac_results",
+        metavar="DIR",
+        help="Base output directory  (default: cellitac_results)",
+    )
+    parser.add_argument(
+        "--version", "-v",
+        action="version",
+        version="cellitac 1.0.0",
+    )
+
+    args = parser.parse_args()
+    try:
+        success = run_full_pipeline(input_dir=args.input, output_dir=args.output)
+        sys.exit(0 if success else 1)
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        sys.exit(1)
+    except Exception as exc:
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+# ============================================================================
+# Preprocessing-only CLI
+# ============================================================================
+def run_preprocess():
+    parser = argparse.ArgumentParser(
+        prog="cellitac-preprocess",
+        description="Run preprocessing only: RNA (Seurat) + ATAC (Signac) + Integration",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  cellitac-preprocess --input ~/singlecell/ATAC
+  cellitac-preprocess --input /data --output custom_results/
+        """,
+    )
+    parser.add_argument("--input",  "-i", default=cfg.INPUT_DIR,
+                        metavar="DIR", help="Raw data directory")
+    parser.add_argument("--output", "-o", default="cellitac_results",
+                        metavar="DIR", help="Base output directory")
+    parser.add_argument("--version", action="version", version="cellitac 1.0.0")
+
+    args = parser.parse_args()
+
+    import os
+    team1_dir  = os.path.join(args.output, "team1_rna_output")
+    team2_dir  = os.path.join(args.output, "team2_atac_output")
+    python_dir = os.path.join(args.output, "python_ready_data")
+
+    try:
+        run_preprocessing(
+            input_dir=args.input,
+            output_dir_team1=team1_dir,
+            output_dir_team2=team2_dir,
+            output_dir_python=python_dir,
+        )
+        print(f"\nPreprocessing complete. ML-ready data in: {python_dir}")
+        sys.exit(0)
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        sys.exit(1)
+    except Exception as exc:
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+# ============================================================================
+# ML-only CLI
+# ============================================================================
+def run_model_cli():
+    parser = argparse.ArgumentParser(
+        prog="cellitac-model",
+        description="Run ML classification on existing python_ready_data",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  cellitac-model --data python_ready_data --output ml_results
+  cellitac-model --data cellitac_results/python_ready_data
+        """,
+    )
+    parser.add_argument("--data",   "-d", default=cfg.OUTPUT_DIR_PYTHON,
+                        metavar="DIR", help="python_ready_data directory")
+    parser.add_argument("--output", "-o", default=cfg.OUTPUT_DIR_ML,
+                        metavar="DIR", help="ML results output directory")
+    parser.add_argument("--version", action="version", version="cellitac 1.0.0")
+
+    args = parser.parse_args()
+    try:
+        success = run_model(data_dir=args.data, output_dir=args.output)
+        sys.exit(0 if success else 1)
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        sys.exit(1)
+    except Exception as exc:
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        sys.exit(1)