Quick start

This page shows the minimum future-fate workflow. Read Introduction for conceptual orientation and Mathematical framework for the equations.

Prepare the data

The AnnData object must contain annotations, a continuous ordering, and a velocity graph. Inspect the native embedding and velocity field before fitting scCS.

Fit Discounted Future-Fate Propagation

import scCS

scorer = scCS.SingleScorer(
    adata,
    root=("Ngn3 high EP", "Pre-endocrine"),
    branches=["Alpha", "Beta", "Delta", "Epsilon"],
    obs_key="clusters",
)

report = scorer.preflight(ordering_metric="latent_time")
print(report.to_frame())

scorer.build_embedding(ordering_metric="latent_time")
scorer.fit(
    scoring_mode="future_fate",
    future_fate_options={
        "effective_horizon": 64,
        "anchor_quantile": 0.90,
        "min_anchor_cells": 10,
        "progression_scale": "rank",
    },
)
result = scorer.score()
print(result.summary())

Read the result

scorer.plot_star(result, color_by="future_fate_affinity:Beta")
scorer.plot_star(result, color_by="future_fate_reach")
scorer.plot_star(result, color_by="future_fate_specificity")
scorer.plot_star(result, color_by="reach_supported_specificity")
scorer.plot_star(result, color_by="signed_progression")

CFA answers which future is favored. DFR answers how much probability reaches a supplied fate. FFS answers how decisive the distribution is. SOF independently reports forward or retrograde motion.

Check sensitivity

Repeat the fit across plausible effective horizons and anchor quantiles. Inspect result.anchor_diagnostics_frame() and compare per-cell CFA rather than only population averages.

Instantaneous mode

scorer.fit(scoring_mode="instantaneous")
instantaneous = scorer.score()
scorer.plot_direction_strength_map(instantaneous)
scorer.plot_rose(instantaneous)

Instantaneous mode measures local direction in the supervised geometry. It is not a substitute for DFFP future probabilities.