StateTrace

A backend-independent framework for donor- and cohort-aware validation of cellular-state transportability and downstream inference.

StateTrace does not map cells. Mapping tools (scPoli, scANVI/scArches, Symphony, Azimuth, CellTypist, a user classifier, or StateTrace’s own kNN baseline) answer which state is this cell? StateTrace answers a different question: is a cellular state defined in one human cohort reproducible and transportable enough to support inference in another?

For every state it asks, in order: is it reproducible across the reference’s donors, or does it depend on particular donors? Does it recover in unseen donors, and in an independent cohort? Is the conclusion the same across mapping backends? Is the query version shifted, uncertain or partly out of reference? Only then is the state supported for group-level differential abundance, pseudobulk expression or genetic analyses.

Getting started

• Installation
  • Extras
  • From source
• Quickstart
  • 1. Build and validate the reference by donor
  • 2. Freeze
  • 3. Validate transport into an independent cohort
  • 4. Gate downstream inference
• Concepts
  • Donors, not cells, are the replication unit
  • StateTrace consumes mapping; it does not perform it
  • Seven questions, one route
  • Two coordinate systems: identity from the mapper, shift from the frozen reference
  • Three layers of shift evidence, never conflated
  • Abstention is a result
  • Freeze before you look at the query
  • What StateTrace is not

Tutorials

• Validate a reference by donor
• Freeze and reload a reference
• Validate transport into a new cohort
• From two h5ad files to a transport report

Guides

• Grouped validation
  • Leave-one-group-out
  • External backends
  • Abstention
  • Random split
  • Known optimism of a fixed latent
• Transport validation and inference gating
  • Two coordinate systems
  • Per cell
  • Per donor x state
  • Per state
  • Status rules (evaluated in order)
  • Backend robustness
  • Downstream
  • Per donor x state in expression space
  • Two-sample engines (reported, not decisive)
  • Cohort offset
  • Held-out novelty calibration
• The frozen reference format
• Roadmap
  • Planned: StateTrace-Spatial
  • Cell-level frozen-expression evidence
  • Release criteria for v1.0
• StateTrace staged roadmap
  • Summary
  • Promotion rule
  • Development policy
  • Current status
  • Stage 1: two coordinate systems and G0
  • Stage 2: backend coverage and G1
  • Stage 3: real-data robustness, G2 and G3
  • Stage 4: inference validity and G4
  • Stage 5: generalisation and G5
  • Stage 6: StateTrace-Spatial (0.5.0) — distinguish mapping failure from segmentation failure
  • Stage 7: usability and stable release (1.0.0)
  • Schedule
  • Milestone log
• StateTrace-Spatial: boundary stability
  • 1. Biological Claim
  • 2. Primary Hypothesis
  • 3. Statistical Unit and Design
  • 4. Primary Comparison
  • 5. Covariates and Exclusions
  • 6. Expected Effect Direction
  • 7. Minimal Primary Analysis
  • 8. Sensitivity Analyses
  • 9. Orthogonal Validation
  • 10. Main Figure-Worthy Result
  • 11. Reviewer Objections and Responses
  • 12. Implementation Notes

Reference

• API reference
  • statetrace.reference
  • statetrace.predictions, features, calibration
  • statetrace.transport, robustness, aggregation
  • statetrace.expression
  • statetrace.twosample
  • statetrace.validation
  • statetrace.metrics
  • statetrace.backends
  • statetrace.datasets
  • statetrace.io
  • statetrace.schema