hcr_data_qc

About

Quality control analysis for AIND HCR data processing. Provides tools for validating tile alignment, camera alignment, segmentation, spectral unmixing, and spot detection.

Use Cases:

1. Interactive analysis - Within a CodeOcean capsule/cloud workstation (or local machine):

   • Make sure processed HCR data asset is attached to capsule

   // run just tile_alignment
   python launch_qc.py --dataset HCR_788639-25_2025-06-06_13-00-00_processed_2025-06-17_07-08-14 --output-dir /root/capsule/scratch/qc-test --tile-alignment --pyramid-level 4

   // run all qc 
   python launch_qc.py --dataset HCR_788639-25_2025-06-06_13-00-00_processed_2025-06-17_07-08-14 --output-dir /root/capsule/scratch/qc-test --all --pyramid-level 0 

2. Reproducible runs - With CodeOcean app panel

   • See HCR QC Kickoff capsule

3. Pipeline integration - As automated QC steps (not implemented yet)

Intergration will AIND QC portal will happen when team identifies and evaluates essential plots.

Change log

v0.4.0 (10/16/2025)

• new metadata parsing and accessors in HCRRound/HCRDataset
• improved loading spot functions, cleaned up returned dataframe
• added get_spot_channel_gene_map()
• added simple soma classifier (logistic regression)
• added HCR cell filters, to remove non-somas (classifier of choice) and overlap cells

v0.3.9 (8/11/2025)

• Add spot detection visualization function to plot top 10 cells per gene based on spot count
• Implement segmentation overview plotting with single and multi-view options
• Create comprehensive cell expression plotting functions for multi-round HCR analysis
• Extract and modularize zarr data processing utilities for cell data and masks
• Example notebook for single cell plots

v0.3.8 (8/08/2025)

• refactor file tree to use "viz" api for simplified access to plotting functions

v0.3.7 (8/01/2025)

• Adds a new plot_spot_metric_dist function for analyzing spot quality distributions with correlation and distance thresholds
• Introduces cluster-based centroid plotting capabilities and cell x gene analysis for coregistered spots
• Updates channel color mapping and improves plot layout consistency

Installation

To use the software, in the root directory, run

pip install -e .

To develop the code, run

pip install -e .[dev]

Contributing

Linters and testing

Run pre_commit_checks.py, which includes coverage, black, isort, flake8, & interrogate

Pull requests

• Internal members please create a branch.
• External members please fork the repository and open a pull request from the fork.

Commits

We'll primarily use Angular style for commit messages. Roughly, they should follow the pattern:

<type>: <short summary>

type is one of:

• build: Changes that affect build tools or external dependencies (example scopes: pyproject.toml, setup.py)
• ci: Changes to our CI configuration files and scripts (examples: .github/workflows/ci.yml)
• docs: Documentation only changes
• feat: A new feature
• fix: A bugfix
• perf: A code change that improves performance
• refactor: A code change that neither fixes a bug nor adds a feature
• test: Adding missing tests or correcting existing tests