How linnalab/qclus works
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.py Quickstart API · splicing_from_bam.ipynb BAM notebook · splicing_from_loompy.ipynb Loom notebook · gene_lists.py Gene lists
Components 25
Core library
Primary QClus analysis code and shared helpers.
- Package init · Exports the public qclus module interface.
qclus/__init__.py - Quickstart API · Main user-facing function for filtering and annotation.
qclus/qclus.py - Filter pipeline · Computes QC features, clusters droplets, and applies filtering logic.
qclus/qclus.py - Tissue mode · Switches between heart-specific and generic filtering behavior.
qclus/qclus.py - Metrics · Derives droplet-level metrics used by the filter.
qclus/qclus.py - Clustering · Groups droplets or nuclei for downstream filtering decisions.
qclus/qclus.py - QC filter · Marks empty or contaminated droplets for removal.
qclus/qclus.py - Annotated output · Returns filtered data with retention annotations.
qclus/qclus.py - Gene lists · Curated marker sets and tissue-specific gene priors.
qclus/gene_lists.py - Utilities · Shared data handling and transformation helpers.
qclus/utils.py
Tutorials
Notebook workflows showing end-to-end usage and upstream splicing extraction.
- Heart notebook · End-to-end cardiac filtering workflow.
tutorials/qclus_tutorial_heart.ipynb - Brain notebook · Generic non-cardiac QClus workflow example.
tutorials/qclus_tutorial_brain.ipynb - BAM notebook · Extracts splicing fractions from BAM inputs.
tutorials/splicing_from_bam.ipynb - Loom notebook · Extracts splicing fractions from Velocyto loom inputs.
tutorials/splicing_from_loompy.ipynb
Packaging
Source install and runtime environment definition.
- setup.py · Installable Python package definition.
setup.py - Requirements · Pinned Python dependencies for the library.
requirements.txt - Environment · Reproducible runtime setup script.
environment.sh
External ecosystem
File formats and single-cell tools QClus integrates with.
- Counts file · Count matrix in h5 or h5ad format.
- Fraction table · Barcode-indexed unspliced fraction CSV.
- AnnData · In-memory matrix container used by QClus and downstream analysis.
- Scanpy · Typical downstream analysis workflow after QClus filtering.
- Velocyto · Source of unspliced fraction from loom-based workflows.
- Quantifiers · Upstream generators such as STARsolo and alevin-fry.
- 10x BAM · Source BAM files used for custom splicing extraction.
Other components
- README · Project overview and usage entrypoints.
README.md
Connections 27
- 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.