Single-cell CNV and malignant cells

Infer chromosome-scale copy-number evidence from tumor single-cell RNA-seq and turn it into reviewable malignant-cell, event, and subclone annotations.

Research question

Which cells, clusters, or samples show broad expression-derived CNV signal consistent with malignant tumor populations, and what inferred events or subclones explain those calls?

Who this is for

Tumor single-cell analysts who need malignant vs. non-malignant labels before downstream TME analysis
Oncology researchers who want CNV-derived tumor subclone labels for communication, immune, spatial, or response workflows
Computational biology teams that need an auditable Python-native alternative to wrapping inferCNV-style R code

Data requirements

Data	Required	Purpose
`.h5ad` single-cell expression dataset	Yes	Input matrix and metadata
Gene order columns in `var` or uploaded gene-order table	Yes	Chromosome-ordered smoothing and event annotation
Reference-cell labels	Strongly recommended	Defines normal/reference cells for expression-centering
Group, sample, cell type, or cluster metadata	Recommended	Aggregates evidence by biologically meaningful populations
UMAP coordinates in `obsm["X_umap"]`	Optional	Enables malignant-score overlay in the result review

Workflow

Data → Analyze → Single-Cell CNV → Review CNV evidence → Export labels / oncology handoff

Step 1 — Prepare tumor single-cell data

Upload or select an AnnData dataset with gene symbols and chromosome coordinates. Define a reference group using non-malignant immune, stromal, endothelial, or normal epithelial labels when those labels are available.

Step 2 — Run Single-Cell CNV

Run the single_cell_cnv pipeline from the analysis workspace. The pipeline computes reference-centered expression signal, smooths genes in chromosome order, scores CNV burden, calls broad gain/loss evidence, assigns malignant confidence, and identifies CNV-defined subclones.

Step 3 — Review evidence

Open the Single-Cell CNV result view to inspect:

chromosome-ordered heatmap preview
reference-cell QC and contamination warnings
malignant score and classification reason by cell group
chromosome summaries and inferred segment/event tables
optional deletion/neutral/gain state calls
CNV subclones and defining features
UMAP malignant-score overlay when coordinates are present

The CNV signal heatmap always computes on the full dataset — every score, event, subclone, and state call is derived from all cells and all ordered genes. The heatmap chart itself is a downsampled preview only (default caps: 400 genes, 600 cells/groups) so it renders quickly in the browser. The panel states exactly how many of the total genes/cells are shown, and its own caveats appear as a footnote directly under the chart, not as a separate section.

The downsampling is a plain even stride across the index range — it is not content-aware and does not rank or select by CNV signal strength, malignant status, or driver-gene position. Genes still tend to read clearly because chromosome-order smoothing runs on the full gene set before this sampling, so a driver gene's signal already echoes into its chromosome-order neighbors even if that exact gene is skipped by the stride. Cells have no equivalent smoothing step, so a small subclone could in principle be under-represented in the chart even though it remains fully captured in the per-cell exports. For full-resolution, per-gene, per-cell values, use the TSV/artifact exports in Step 4, not the chart.

Step 4 — Export downstream artifacts

Use TSV exports for group evidence, events, state calls, chromosome summaries, and subclones. No path needs to be copied to feed Oncology Malignant Cell Detection — pick this experiment and its completed Single-Cell CNV run directly from the dropdowns on Oncology's Malignant Cell Detection panel; the run is looked up by ID.

Expected outputs

cell_cnv_scores.parquet with cnv_malignant_status, cnv_malignant_score, cnv_burden, classification reason, and cnv_subclone_id
group_cnv_scores.parquet and sample_cnv_scores.parquet
cnv_segments.parquet and chromosome_cnv_summary.parquet
copy_state_calls.parquet and state posterior payload when state calling is enabled
heatmap_payload.json for browser review
oncology_handoff.json for downstream oncology interpretation

Typical analyses

Analysis	Question
Malignant label review	Which clusters are likely malignant and why?
Tumor subclone review	Are there CNV-defined malignant subpopulations?
Event interpretation	Which chromosome gains/losses and cancer-gene overlaps support the calls?
Reference QC	Are reference cells clean enough to support the classification?
Oncology handoff	Which labels, subclones, and events should feed TME communication or response modeling?

Important caveats

Expression-derived CNV is research evidence, not a DNA copy-number assay. Use mutation, CNA, histology, or prior labels when available to confirm important findings. Weak or contaminated reference labels can create false malignant calls, so always review reference QC before using downstream labels.

A "Fewer than 25 genes survived filtering on: chr*" caveat names specific chromosomes (by chromosome, not a count) where too few genes remained after gene-detection filtering to support a reliable chromosome-level summary — typically small, gene-sparse chromosomes such as chr21 or chrY. It only affects confidence in that chromosome's aggregate call; gene-level and whole-genome results are unaffected.