# linnalab/qclus architecture

> Architecture diagram of the GitHub repository linnalab/qclus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/linnalab/qclus
- Repository: https://github.com/linnalab/qclus

## Overview

QClus is a local Python analysis package for snRNA-seq droplet/nuclei filtering, not a web service or distributed system. The repository is organized around a small core library plus tutorial notebooks that demonstrate end-to-end preprocessing workflows.

1. **Primary user entrypoint**
   - The main API is exposed from `qclus/qclus.py` and imported as `qclus`.
   - The README highlights `quickstart_qclus(counts_path, fraction_unspliced, tissue=...)` as the standard entrypoint.
   - This function is the architectural center: it takes a count matrix plus per-droplet unspliced fraction, runs the filtering logic, and returns an annotated `AnnData` object.

2. **Input data boundary**
   - QClus expects two main inputs:
     - a count matrix in `.h5` or `.h5ad` format,
     - a `fraction_unspliced.csv` table indexed by droplet/cell barcode.
   - This makes the package a downstream QC/filtering layer that sits after raw count generation and before downstream analysis such as Scanpy workflows.

3. **Upstream splicing-fraction preparation**
   - The repository treats “fraction of unspliced reads” as a separate preprocessing concern.
   - The README describes three upstream sources:
     - direct output from tools like **alevin-fry** or **STARsolo**,
     - **Velocyto** `.loom` files,
     - 10x **BAM** files via custom notebook-based extraction.
   - The notebooks in `tutorials/` encode these alternative data-ingestion paths.

4. **Core filtering pipeline**
   - The algorithm is described as clustering nuclei/droplets using multiple metrics, then filtering empty and highly contaminated droplets.
   - Architecturally, this implies a pipeline with:
     - feature/metric calculation,
     - clustering or grouping,
     - rule-based or score-based filtering,
     - output annotation of retained vs removed droplets.
   - The package is tuned for robustness across variable quality and contamination levels.

5. **Tissue-specific branching**
   - The API has a tissue parameter with at least two modes: `heart` and `other`.
   - `heart` corresponds to the original publication’s cardiac-specific settings.
   - `other` disables cell-type-specific metrics and represents the more generic path for non-cardiac data.
   - This is an important architectural boundary: the pipeline is configurable by tissue, and the feature set used for filtering changes accordingly.

6. **Gene-list subsystem**
   - `qclus/gene_lists.py` likely holds curated marker/gene sets used by the tissue-specific logic.
   - This module is the main place where biological prior knowledge enters the algorithm.
   - For architecture diagrams, treat it as a configuration/data layer feeding the core analysis logic rather than as a standalone algorithmic component.

7. **Utilities and shared helpers**
   - `qclus/utils.py` is the shared support layer for common operations such as data handling, transformations, and helper routines used by the core pipeline.
   - In the architecture, this is a cross-cutting support module rather than a top-level subsystem.

8. **Tutorials as workflow examples**
   - The `tutorials/` directory contains Jupyter notebooks for:
     - heart data,
     - brain data,
     - splicing extraction from BAM,
     - splicing extraction from Loom.
   - These notebooks are not just documentation; they show the intended orchestration of QClus inside a broader Scanpy-style preprocessing workflow.

9. **Execution model**
   - The repository is designed for interactive or batch execution in Python, typically inside a notebook or script.
   - There is no server, queue, or database layer.
   - Inputs are file-based; outputs are in-memory annotated objects and likely downstream-saved tables/figures from the notebooks.

10. **Packaging and environment**
   - `setup.py` packages the library for installation from source.
   - `requirements.txt` and `environment.sh` define the Python/conda runtime setup.
   - This is a source-installed scientific Python project, with the environment script being part of the operational boundary for reproducibility.

11. **External ecosystem**
   - The architecture is tightly coupled to common single-cell tooling:
     - **AnnData / Scanpy** for matrix representation and downstream workflow,
     - upstream count/splicing generators such as **10x**, **STARsolo**, **alevin-fry**, **Velocyto**.
   - These are important integration points because QClus assumes their file formats and data conventions.

12. **Likely end-to-end data flow**
   - Raw sequencing is processed by an upstream aligner/quantifier.
   - Splicing fractions are extracted or computed into a barcode-indexed table.
   - Counts and splicing fractions are passed into `quickstart_qclus`.
   - QClus computes QC features, clusters droplets, applies tissue-aware filtering, and returns a filtered/annotated dataset for downstream analysis.

Overall, the architecture is a compact scientific Python library centered on a single filtering pipeline, with tissue-specific configuration data, helper utilities, and notebooks that demonstrate how to feed it from common snRNA-seq preprocessing outputs.

Main entry points: [`qclus/qclus.py`](https://github.com/linnalab/qclus/blob/main/qclus/qclus.py) (Quickstart API), [`tutorials/splicing_from_bam.ipynb`](https://github.com/linnalab/qclus/blob/main/tutorials/splicing_from_bam.ipynb) (BAM notebook), [`tutorials/splicing_from_loompy.ipynb`](https://github.com/linnalab/qclus/blob/main/tutorials/splicing_from_loompy.ipynb) (Loom notebook), [`qclus/gene_lists.py`](https://github.com/linnalab/qclus/blob/main/qclus/gene_lists.py) (Gene lists)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_init["Package init<br/>api export<br/>[__init__.py]"]
  node_qclus_api["Quickstart API<br/>entrypoint<br/>[qclus.py]"]
  node_filter_pipeline{{"Filter pipeline<br/>analysis pipeline<br/>[qclus.py]"}}
  node_tissue_branch(("Tissue mode<br/>config branch<br/>[qclus.py]"))
  node_feature_calc["Metrics<br/>feature extraction<br/>[qclus.py]"]
  node_cluster_step{{"Clustering<br/>grouping<br/>[qclus.py]"}}
  node_contam_filter{{"QC filter<br/>filtering<br/>[qclus.py]"}}
  node_annotate_out[("Annotated output<br/>AnnData result<br/>[qclus.py]")]
  node_gene_lists["Gene lists<br/>biological config<br/>[gene_lists.py]"]
  node_utils["Utilities<br/>helpers<br/>[utils.py]"]
end

subgraph group_tutorials["Tutorials"]
  node_heart_nb["Heart notebook<br/>workflow notebook"]
  node_brain_nb["Brain notebook<br/>workflow notebook"]
  node_bam_nb["BAM notebook<br/>ingestion notebook"]
  node_loom_nb["Loom notebook<br/>ingestion notebook"]
end

subgraph group_packaging["Packaging"]
  node_setup["setup.py<br/>packaging<br/>[setup.py]"]
  node_requirements["Requirements<br/>runtime deps<br/>[requirements.txt]"]
  node_env_script["Environment<br/>conda/script<br/>[environment.sh]"]
end

subgraph group_external["External ecosystem"]
  node_counts_h5ad[("Counts file<br/>input data")]
  node_fraction_csv["Fraction table<br/>input data"]
  node_anndata[("AnnData<br/>single-cell object")]
  node_scanpy["Scanpy<br/>downstream ecosystem"]
  node_velocyto["Velocyto<br/>upstream tool"]
  node_starsolo_alevin["Quantifiers<br/>upstream tools"]
  node_bam_source[("10x BAM<br/>raw input")]
end

node_readme["README<br/>docs<br/>[README.md]"]

node_readme -->|"documents"| node_qclus_api
node_init -->|"exports"| node_qclus_api
node_qclus_api -->|"invokes"| node_filter_pipeline
node_qclus_api -->|"consumes"| node_counts_h5ad
node_qclus_api -->|"consumes"| node_fraction_csv
node_filter_pipeline -->|"computes"| node_feature_calc
node_feature_calc -->|"feeds"| node_cluster_step
node_cluster_step -->|"drives"| node_contam_filter
node_tissue_branch -->|"selects"| node_gene_lists
node_gene_lists -->|"provides"| node_feature_calc
node_tissue_branch -->|"configures"| node_filter_pipeline
node_utils -.->|"supports"| node_filter_pipeline
node_contam_filter -->|"produces"| node_annotate_out
node_qclus_api -->|"returns"| node_annotate_out
node_annotate_out -->|"handoff"| node_scanpy
node_heart_nb -->|"demonstrates"| node_qclus_api
node_brain_nb -->|"demonstrates"| node_qclus_api
node_bam_nb -->|"reads"| node_bam_source
node_bam_nb -->|"builds"| node_fraction_csv
node_loom_nb -->|"reads"| node_velocyto
node_loom_nb -->|"builds"| node_fraction_csv
node_starsolo_alevin -->|"source"| node_fraction_csv
node_counts_h5ad -->|"loads"| node_anndata
node_fraction_csv -->|"joins"| node_anndata
node_setup -->|"packages"| node_qclus_api
node_requirements -.->|"pins"| node_setup
node_env_script -.->|"defines"| node_requirements

click node_readme "https://github.com/linnalab/qclus/blob/main/README.md"
click node_init "https://github.com/linnalab/qclus/blob/main/qclus/__init__.py"
click node_qclus_api "https://github.com/linnalab/qclus/blob/main/qclus/qclus.py"
click node_filter_pipeline "https://github.com/linnalab/qclus/blob/main/qclus/qclus.py"
click node_tissue_branch "https://github.com/linnalab/qclus/blob/main/qclus/qclus.py"
click node_feature_calc "https://github.com/linnalab/qclus/blob/main/qclus/qclus.py"
click node_cluster_step "https://github.com/linnalab/qclus/blob/main/qclus/qclus.py"
click node_contam_filter "https://github.com/linnalab/qclus/blob/main/qclus/qclus.py"
click node_annotate_out "https://github.com/linnalab/qclus/blob/main/qclus/qclus.py"
click node_gene_lists "https://github.com/linnalab/qclus/blob/main/qclus/gene_lists.py"
click node_utils "https://github.com/linnalab/qclus/blob/main/qclus/utils.py"
click node_heart_nb "https://github.com/linnalab/qclus/blob/main/tutorials/qclus_tutorial_heart.ipynb"
click node_brain_nb "https://github.com/linnalab/qclus/blob/main/tutorials/qclus_tutorial_brain.ipynb"
click node_bam_nb "https://github.com/linnalab/qclus/blob/main/tutorials/splicing_from_bam.ipynb"
click node_loom_nb "https://github.com/linnalab/qclus/blob/main/tutorials/splicing_from_loompy.ipynb"
click node_setup "https://github.com/linnalab/qclus/blob/main/setup.py"
click node_requirements "https://github.com/linnalab/qclus/blob/main/requirements.txt"
click node_env_script "https://github.com/linnalab/qclus/blob/main/environment.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_init,node_qclus_api,node_filter_pipeline,node_tissue_branch,node_feature_calc,node_cluster_step,node_contam_filter,node_annotate_out,node_gene_lists,node_utils toneBlue
class node_heart_nb,node_brain_nb,node_bam_nb,node_loom_nb toneAmber
class node_setup,node_requirements,node_env_script toneMint
class node_counts_h5ad,node_fraction_csv,node_anndata,node_scanpy,node_velocyto,node_starsolo_alevin,node_bam_source toneRose
class node_readme toneNeutral
```

## Components

### Core library

Primary QClus analysis code and shared helpers.

- [Package init](https://github.com/linnalab/qclus/blob/main/qclus/__init__.py): api export · Exports the public qclus module interface. · `qclus/__init__.py`
- [Quickstart API](https://github.com/linnalab/qclus/blob/main/qclus/qclus.py): entrypoint · Main user-facing function for filtering and annotation. · `qclus/qclus.py`
- [Filter pipeline](https://github.com/linnalab/qclus/blob/main/qclus/qclus.py): analysis pipeline · Computes QC features, clusters droplets, and applies filtering logic. · `qclus/qclus.py`
- [Tissue mode](https://github.com/linnalab/qclus/blob/main/qclus/qclus.py): config branch · Switches between heart-specific and generic filtering behavior. · `qclus/qclus.py`
- [Metrics](https://github.com/linnalab/qclus/blob/main/qclus/qclus.py): feature extraction · Derives droplet-level metrics used by the filter. · `qclus/qclus.py`
- [Clustering](https://github.com/linnalab/qclus/blob/main/qclus/qclus.py): grouping · Groups droplets or nuclei for downstream filtering decisions. · `qclus/qclus.py`
- [QC filter](https://github.com/linnalab/qclus/blob/main/qclus/qclus.py): filtering · Marks empty or contaminated droplets for removal. · `qclus/qclus.py`
- [Annotated output](https://github.com/linnalab/qclus/blob/main/qclus/qclus.py): AnnData result · Returns filtered data with retention annotations. · `qclus/qclus.py`
- [Gene lists](https://github.com/linnalab/qclus/blob/main/qclus/gene_lists.py): biological config · Curated marker sets and tissue-specific gene priors. · `qclus/gene_lists.py`
- [Utilities](https://github.com/linnalab/qclus/blob/main/qclus/utils.py): helpers · Shared data handling and transformation helpers. · `qclus/utils.py`

### Tutorials

Notebook workflows showing end-to-end usage and upstream splicing extraction.

- [Heart notebook](https://github.com/linnalab/qclus/blob/main/tutorials/qclus_tutorial_heart.ipynb): workflow notebook · End-to-end cardiac filtering workflow. · `tutorials/qclus_tutorial_heart.ipynb`
- [Brain notebook](https://github.com/linnalab/qclus/blob/main/tutorials/qclus_tutorial_brain.ipynb): workflow notebook · Generic non-cardiac QClus workflow example. · `tutorials/qclus_tutorial_brain.ipynb`
- [BAM notebook](https://github.com/linnalab/qclus/blob/main/tutorials/splicing_from_bam.ipynb): ingestion notebook · Extracts splicing fractions from BAM inputs. · `tutorials/splicing_from_bam.ipynb`
- [Loom notebook](https://github.com/linnalab/qclus/blob/main/tutorials/splicing_from_loompy.ipynb): ingestion notebook · Extracts splicing fractions from Velocyto loom inputs. · `tutorials/splicing_from_loompy.ipynb`

### Packaging

Source install and runtime environment definition.

- [setup.py](https://github.com/linnalab/qclus/blob/main/setup.py): packaging · Installable Python package definition. · `setup.py`
- [Requirements](https://github.com/linnalab/qclus/blob/main/requirements.txt): runtime deps · Pinned Python dependencies for the library. · `requirements.txt`
- [Environment](https://github.com/linnalab/qclus/blob/main/environment.sh): conda/script · Reproducible runtime setup script. · `environment.sh`

### External ecosystem

File formats and single-cell tools QClus integrates with.

- **Counts file**: input data · Count matrix in h5 or h5ad format.
- **Fraction table**: input data · Barcode-indexed unspliced fraction CSV.
- **AnnData**: single-cell object · In-memory matrix container used by QClus and downstream analysis.
- **Scanpy**: downstream ecosystem · Typical downstream analysis workflow after QClus filtering.
- **Velocyto**: upstream tool · Source of unspliced fraction from loom-based workflows.
- **Quantifiers**: upstream tools · Upstream generators such as STARsolo and alevin-fry.
- **10x BAM**: raw input · Source BAM files used for custom splicing extraction.

### Other components

- [README](https://github.com/linnalab/qclus/blob/main/README.md): docs · Project overview and usage entrypoints. · `README.md`

## Connections

- README → Quickstart API: documents · README presents the main entrypoint and expected inputs.
- Package init → Quickstart API: exports · Package init exposes the public API.
- Quickstart API → Filter pipeline: invokes · quickstart_qclus runs the core filtering workflow.
- Quickstart API → Counts file: consumes · Takes a count matrix as primary input.
- Quickstart API → Fraction table: consumes · Uses barcode-indexed unspliced fractions.
- Filter pipeline → Metrics: computes · Derives QC metrics from input data.
- Metrics → Clustering: feeds · Metrics are used for clustering/grouping.
- Clustering → QC filter: drives · Cluster structure informs filtering decisions.
- Tissue mode → Gene lists: selects · Tissue mode chooses different biological priors.
- Gene lists → Metrics: provides · Marker sets influence feature computation.
- Tissue mode → Filter pipeline: configures · Heart and other modes alter the filtering path.
- Utilities → Filter pipeline: supports · Shared helpers are used across the pipeline.
- QC filter → Annotated output: produces · Filtering results are written back to AnnData annotations.
- Quickstart API → Annotated output: returns · Public API returns the annotated filtered dataset.
- Annotated output → Scanpy: handoff · Output is intended for downstream Scanpy analysis.
- Heart notebook → Quickstart API: demonstrates · Notebook shows cardiac workflow usage.
- Brain notebook → Quickstart API: demonstrates · Notebook shows generic non-cardiac workflow usage.
- BAM notebook → 10x BAM: reads · Notebook extracts splicing from BAM inputs.
- BAM notebook → Fraction table: builds · Produces the fraction table consumed by QClus.
- Loom notebook → Velocyto: reads · Notebook uses Velocyto loom inputs.
- Loom notebook → Fraction table: builds · Produces the fraction table consumed by QClus.
- Quantifiers → Fraction table: source · Upstream quantifiers can provide the unspliced fraction table.
- Counts file → AnnData: loads · Count files are converted into AnnData objects.
- Fraction table → AnnData: joins · Fraction table is aligned to the cell barcode index.
- setup.py → Quickstart API: packages · Source packaging installs the library code.
- Requirements → setup.py: pins · Dependencies constrain installation and runtime.
- Environment → Requirements: defines · Environment script captures the reproducible runtime.
