StarTrak

StarTrak (v1) builds cell-lineage trees and calls somatic RNA variants from single-cell and spatial transcriptomics data.

• Quick start: commands for BAM, 10x, ASTRO, and existing matrices.
• Visualization: plot variants and inspect gene assignments.

Installation

Use Python >= 3.10. The supplied Conda environment includes the Python packages, SAMtools, BCFtools, HTSlib, and GNU Parallel. Bash, Perl, and standard Unix utilities (including awk, sort, gzip, zcat, and shuf) must be available.

Run from the repository root:

conda env create -f docs/environment.yml
conda activate startrak2
bash StarTrak.sh --help

Workflow

dealbam -> varmat -> varanno -> encode -> build -> call

Stage	Purpose
dealbam	Curate the input BAM.
varmat	Count ALT/depth per variant and cell.
varanno	Annotate variants and calculate variant metrics.
encode	Select and QC variants; learn a cell embedding.
build	Build the lineage tree and final variant weights.
call	Call somatic variants using tumor labels, the tree, and read QC.

The default encoder, multiview_mut, combines expression, available spatial/image features, and selected mutation profiles. fusion and multiview are alternatives selected with --encoder4encode.

Runs resume automatically using <out-dir>/.spvar_state. Use --from-stage encode to rerun encode and later stages, or --no-resume to restart all selected stages. See the quick start for examples.

Inputs

Option	Input
--input-bam	Aligned RNA BAM.
--ref-fasta	Reference FASTA matching the BAM.
--spot-meta-tsv	Tab-separated cell/spot metadata.
--exp-mat / --exp-folder	Expression matrix / 10x matrix folder; expression is required for single-cell encode.
--snp-vcf / --rnaedit-vcf	Optional population SNP / RNA-editing annotation VCFs.
--patho-img	Optional pathology image for spatial features and overlays.

Use --tenx-input, --astroin, or --stpipelinein to discover inputs from a supported output folder. Use only one adapter at a time. Omitted annotation sources are not used for annotation or variant exclusion.

Metadata must start with a spot or pixel column. A spatial example:

spot	X	Y	imageX	imageY	tumor
AAACAAGTATCTCCCA-1	12	45	1200	980	1
AAACAGCTTTCAGAAG-1	13	44	1240	960	0

For non-spatial data, omit the coordinate columns. Use tumor=1 for tumor and tumor=0 for normal cells. Without a tumor column, the call stage is skipped. Cell IDs should match across metadata and matrices.

For 10x input, the adapter can combine a minimal spot_meta.tsv (one ID column, optionally followed by tumor) with tissue positions and scale factors. Always pass full spatial metadata explicitly with --spot-meta-tsv, even when the file is inside the 10x bundle.

Common Options

Option	Use
--sample-id SAMPLE --out-dir result --threads 8	Set the output prefix, directory, and threads.
--sample-desc ffpe,dbit	Enable FFPE and/or DBiT artifact filtering; either value can be used alone.
--disable-rna-variant-qc	Disable default read QC, except when sample-specific filtering requires it.
--no-tumor	Skip somatic calling.
--solid-germline-list variants.txt	Exclude listed variants from encode/build.
--solid-somatic-list variants.txt	Force listed variants into the tree; usable counts must exist in the RNA matrix.
--embedregion cells.txt	Restrict cells during encode; rerun from encode when changing the list.
--multi_mapping4lineage	Include multi-mapping variants in lineage tracing; these variants skip RNA read QC.

Variant lists use one CHROM:POS:REF:ALT per line (plain text or gzip). If a variant is in both lists, the germline exclusion takes precedence. Read QC is enabled by default and uses the curated BAM; reusing a variant matrix does not remove that requirement.

Use bash StarTrak.sh --help for more options. Shared defaults are in spVarpy/defaults.py.

Main Outputs

Paths below are relative to --out-dir; replace SAMPLE with --sample-id.

Path	Contents
SAMPLE_RNA_var_mat.txt.gz	Variant-by-cell ALT/depth matrix.
SAMPLE_variant_metric.tsv	Variant annotations and metrics.
encode/SAMPLE_RNA_embedding.tsv	Cell embedding.
encode/SAMPLE_variant_quality_candidates.tsv	Candidate QC results.
figure/spatialdiff/, figure/vafdiff/	Top-ranked variant plots.
final/SAMPLE_predict_tree.nwk	Final lineage tree.
final/SAMPLE_predict_variant_weights.tsv	Final variant weights and admission status.
final/SAMPLE_predict_result.ipynb	Interactive tree/clone notebook for spatial data.
final/somatic_call.txt	Final somatic calls when calling is enabled.

The somatic_call.merged_QC.tsv table classifies candidates; its somatic rows are not all final calls. Use somatic_call.txt for the mutation list.

Open the generated notebook to adjust CUT_HEIGHT, MIN_CLONE_SIZE, and MAX_CLONES. A pathology image is optional. If execution fails, check final/SAMPLE_predict_result.execute.log.