Skip to content

feat(report): decouple the feature distributions from the PCA and regroup the sections - #48

Merged
CarlosBlancoGo merged 1 commit into
mainfrom
feat/feature-distribution-sections
Aug 27, 2026
Merged

feat(report): decouple the feature distributions from the PCA and regroup the sections#48
CarlosBlancoGo merged 1 commit into
mainfrom
feat/feature-distribution-sections

Conversation

@CarlosBlancoGo

Copy link
Copy Markdown
Collaborator

Replaces the PCA-selected violin panels with a per-feature distribution for every curated feature, placed in the report section its metric belongs to, and regroups the surrounding sections so nothing is shown twice.

Summary

  • Every curated feature now has a violin panel. They were previously the union of the top-10 |loading| on PC1 and PC2, so the PCA decided which distributions the reader was shown. Because the logic for the PCA will change in future issues, this has been refactored.
  • Panels go to the section their metric belongs to, not into one block. Twelve of the curated features already had a violin elsewhere in the report from the identical column, and those figures are richer (per-category colour, zoom insets), so they are not duplicated. Two new sections cover what had no figure at all: Samples Splice Junction Composition, and Samples Quality Features (good/bad as tabs). A third section appears only under --pca_features, so a user whitelist does not silently lose its distributions.
  • The QC overview heatmap moved to the top of the report, right after the summary table, so the reader can decide which features are worth opening before scrolling the distributions.
  • Section membership realigned with the per-sample report. Unique junction chains / isoforms per cell are library size there; genes, annotated genes and mitochondrial content are gene characterisation. The multisample report had drifted in three places and now matches.
  • Each count is followed by its per-unit rate. A raw count tracks how deeply a cell was sequenced and cannot be compared across samples of different depth; the rate is what survives that. Isoforms mode also gains the per-cell isoform violin it has lacked since feat(cell_metrics): add per-cell isoform diversity for isoforms mode #45, which added the column, the per-sample violin and the summary-table row but no multisample figure.
  • Removed the combined structural-category figure, which was built and assigned but only ever rendered in the PDF, together with its sole dependency (ggdist).
  • "Unique Isoforms" is now "Isoforms" in both reports. Transcripts_in_cell is the FL sum and Isoforms_in_cell is the distinct-model count, so the two names already read correctly as a pair. Unique junction chains keep their full name, which is part of the established term.

Details

Panel titles come from the curated registry label rather than from the column name.

Registry block names became constants shared by the registry and the report layout. The layout decides which blocks still need a section by name, so a literal string in both places would let a rename silently duplicate or drop a whole section of figures.

Fixes three per-unit rates rendering as percentages. infer_feature_metadata() promotes any count-like feature whose maximum is at most 1.5 to a percentage and multiplies it by 100, and genes-per-read, UJCs-per-read and isoforms-per-transcript are ratios bounded by 1 by construction, so all three drew on a 0–100 axis labelled "Genes, %" / "Reads, %" / "Transcripts, %". The rate suffix is now detected and stripped before the domain rules run, so the numerator names the domain, and rates get their own unit so they are neither rescaled nor drawn on a log axis.

Validated by regenerating the multisample report in both reads and isoforms modes and inspecting the rendered figures, including a run with a --pca_features whitelist to exercise the fallback section. The per-sample report was run directly in both modes as well, since the multisample regeneration does not exercise it — that check caught a rename that would have silently orphaned the JavaScript selector hiding a mode-specific tab, which is keyed on the section heading's generated anchor.

…roup the sections

Every curated feature now gets a violin panel, placed in the section its
block belongs to, instead of the union of the top-10 |loading| on PC1/PC2
choosing which distributions the reader is shown.
@CarlosBlancoGo
CarlosBlancoGo merged commit bdb9165 into main Aug 27, 2026
2 checks passed
@CarlosBlancoGo
CarlosBlancoGo deleted the feat/feature-distribution-sections branch August 27, 2026 16:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant