Single-cell RNA-seq Analysis Pipeline

This repository contains an end-to-end Python pipeline for single-cell RNA-seq analysis on a real public dataset.

The workflow uses the 10x Genomics PBMC 3k dataset, starting from the raw 10x count matrix and proceeding through quality control, filtering, normalization, dimensionality reduction, clustering, marker gene analysis, and broad cell type annotation. The pipeline generates figures, summary tables, and a short report automatically.

What This Pipeline Does & Why It Matters

Single-cell RNA-seq generates expression profiles for thousands of individual cells simultaneously — but raw data alone tells you nothing. The biological signal is buried under technical noise, batch effects, and the sheer scale of the data.

This pipeline takes a raw 10x Genomics count matrix and produces something interpretable: distinct cell populations, their marker genes, and annotated cell type identities — automatically, reproducibly, and with full QC documentation at every step.

Why this matters in practice:

• Drug discovery teams need to know which cell types are present in a tissue and how their transcriptional state changes under treatment
• A pipeline that goes from raw counts to annotated UMAP in a single run removes the manual bottleneck that slows that work down
• Every output — figures, tables, reports — is versioned and reproducible, so results can be trusted and shared

Built on the standard 10x PBMC 3k benchmark dataset so results are fully verifiable against the field.

Pipeline Architecture

Raw 10x Matrix (PBMC 3k)
        │
        ▼
┌─────────────────────┐
│   Quality Control   │  → qc_histograms.png
│  filter cells · mito│
└─────────────────────┘
        │
        ▼
┌─────────────────────┐
│   Normalization     │
│  scran · log1p      │
└─────────────────────┘
        │
        ▼
┌─────────────────────┐
│  Feature Selection  │
│  HVGs · PCA         │
└─────────────────────┘
        │
        ▼
┌─────────────────────┐
│  Graph + Embedding  │  → umap_clusters.png
│  KNN graph · UMAP   │
└─────────────────────┘
        │
        ▼
┌─────────────────────┐
│  Leiden Clustering  │  → marker_heatmap.png
│  8 clusters         │
└─────────────────────┘
        │
        ▼
┌─────────────────────┐
│ Cell Type Annotation│  → umap_cell_types.png
│  6 immune populations│
└─────────────────────┘
        │
        ▼
 Analysis Report + .h5ad

Dataset

The analysis uses the public PBMC 3k dataset from 10x Genomics:

• PBMC 3k filtered gene-barcode matrices

This dataset is widely used as a reference example for single-cell RNA-seq workflows and is well suited for demonstrating core preprocessing, clustering, and interpretation steps in a reproducible local analysis pipeline.

Workflow

The pipeline performs the following steps:

1. downloads and extracts the 10x matrix files
2. calculates standard cell-level QC metrics
3. filters low-quality cells and low-detection genes
4. removes cells with elevated mitochondrial transcript content
5. normalizes counts and log-transforms expression
6. selects highly variable genes
7. runs PCA and constructs a nearest-neighbor graph
8. generates a UMAP embedding
9. performs Leiden clustering
10. identifies cluster-level marker genes
11. assigns broad immune cell type labels using canonical marker panels

Results at a Glance

UMAP — Cell Type Annotation

2,698 cells across 6 immune populations identified using canonical marker panels

UMAP — Leiden Clusters

8 unsupervised clusters resolved by graph-based Leiden algorithm

Marker Gene Heatmap

Top differentially expressed genes per cell type — confirms biological plausibility of annotations

QC Distributions

Genes per cell, UMI counts, and mitochondrial percentage before filtering

Output Files

After a successful run, the pipeline writes:

• output/processed/cluster_summary.tsv
• output/processed/marker_genes.tsv
• output/reports/analysis_summary.md
• output/figures/qc_histograms.png
• output/figures/umap_clusters.png
• output/figures/umap_cell_types.png
• output/figures/marker_heatmap.png

The full per-cell metadata table and .h5ad object are also generated locally for downstream analysis, but are typically not committed to Git because they are larger intermediate files.

Repository Structure

.
├── run_pipeline.py
├── requirements.txt
├── pyproject.toml
├── src/single_cell_pipeline/
│   ├── analysis.py
│   ├── data.py
│   └── pipeline.py
└── tests/

Running the Pipeline

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 run_pipeline.py

Implementation Notes

This project is intended to demonstrate practical familiarity with standard single-cell RNA-seq analysis steps in Python. The cluster labels are heuristic and based on canonical immune markers, so they should be interpreted as broad cell type assignments rather than definitive annotations.

Testing

python3 -m unittest discover -s tests -v

License

MIT License. See LICENSE.