Quick Start¶

This page gives the fastest path to run SpaceTracer on your data.

1) Prepare environment¶

Complete Installation first.

Make sure you have installed the package into your environment (for CLI usage):

pip install .
spacetracer --help

2) Prepare inputs and references¶

At minimum you need:

• aligned BAM file from spatial transcriptomics
• tissue position file (for Visium)
• reference genome FASTA and required resources from Resources
• writable output directory

3) Edit config file¶

Create config.yaml from the template in Configuration, then update all sample-specific paths and run parameters.

Pretrained mutation-prediction models are already provided under SpaceTracer_new_github/models:

• spatial_free_model
• spatial_feature_preserved_model

Set these via model_dir and model_name in your config. For full parameter/input meaning, use Config Reference.

4) Run full workflow¶

SpaceTracer run --config config.yaml

Fallback command:

python -m SpaceTracer.cli.run --config config.yaml

5) Resume or rerun when needed¶

SpaceTracer run --config config.yaml --start-from genotyping
SpaceTracer run --config config.yaml --stop-at merge_feature
SpaceTracer run --config config.yaml --only-steps "RNA_feature,phasing,merge_feature" --force
SpaceTracer run --config config.yaml --force

Notes:

• --start-from <step> skips earlier completed steps and resumes from the specified step.
• --stop-at <step> runs up to that step and then exits.
• --force reruns requested steps even if checkpoint metadata says they are complete.
• --only-steps runs exactly the listed steps (topologically ordered within that subset) and does not auto-include external dependencies.
• If required upstream outputs are missing, --only-steps will fail with missing-key or missing-file errors.

6) Check outputs and step details¶

Use these pages for interpretation and debugging:

• Outputs
• Step-by-step guide (code-aligned with SpaceTracer/steps)
• Single-Step Debug Cookbook

Common output files from downstream feature and prediction stages include:

• output_dir/all_feature.txt
• output_dir/all_feature.parquet
• output_dir/mutation_prediction/results/Sample_total_pred_truesites.vcf
• output_dir/mutation_prediction/results/Sample_total_pred_truesites_PASS.vcf