Single-Step Debug Cookbook¶

Use this page when you want to rerun only a part of the pipeline during debugging or parameter tuning.

Core command patterns¶

Run from a specific step:

SpaceTracer run --config config.yaml --start-from <step_name>

Stop at a specific step:

SpaceTracer run --config config.yaml --stop-at <step_name>

Force recompute (ignore completed checkpoints):

SpaceTracer run --config config.yaml --start-from <step_name> --force

Recommended debug workflows¶

A) Genotyping parameter tuning¶

When adjusting steps.genotyping thresholds:

SpaceTracer run --config config.yaml --start-from genotyping --stop-at merge_feature --force

Why: this reruns genotype and all downstream feature integration without redoing BAM/pileup work.

B) RNA-only feature tuning¶

When adjusting steps.RNA_feature parameters:

SpaceTracer run --config config.yaml --start-from RNA_feature --stop-at merge_feature --force

Why: only reruns the relevant branch and final merge.

C) Spatial feature tuning¶

When adjusting steps.spatial_feature thresholds:

SpaceTracer run --config config.yaml --start-from spatial_feature --stop-at merge_feature --force

D) Rebuild chunk-related evidence¶

When changing mpileup/chunk parameters:

SpaceTracer run --config config.yaml --start-from mpileup --force

Why: this refreshes filter_mpileup_file, chunk DB, UMI combine, and all downstream outputs.

Quick checklist before partial reruns¶

• confirm edited parameters are in the correct config section
• ensure input/resource paths still exist
• use --force when old checkpoints may mask changes
• verify expected output files were regenerated by timestamp/size

Common pitfalls¶

• No visible changes after rerun: likely due to checkpoint skip; add --force.
• Missing input key/file error: start step is too late for required upstream outputs.
• Unexpected branch output missing: verify step dependencies in Step Reference Overview.