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

Step 4 — Export downstream artifacts

Use TSV exports for group evidence, events, state calls, chromosome summaries, and subclones. Copy the oncology handoff path when the result should feed Oncology Malignant Cell Detection.

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.