regvelo.tools.markov_density_screening

regvelo.tools.markov_density_screening(adata, adata_perturb_dict, TERMINAL_STATES, STARTING_POINTS, tf_ko_list, cluster_key, method='stepwise', n_step_to_use=500, n_simulations=1000, seed=0, output_dir='.', plot=False, save=False)[source]

Run Markov simulations to score TF perturbation effects on cell fate density.

For each TF, simulates random walks from STARTING_POINTS to TERMINAL_STATES in both the baseline and perturbed transition matrices, computes a density difference (dd) score and its significance, then collects per-cell visit statistics. After all TFs are processed, the result tables are stored in adata.uns['markov_density_screening'] and, when save=True, also written to CSV in output_dir. Per-TF density-difference figures are drawn only when plot=True.

Parameters:

  • adata (AnnData) – Baseline AnnData with velocity outputs and terminal state annotations in adata.obs['term_states_fwd'].

  • adata_perturb_dict (dict[str, AnnData]) – Perturbed AnnData objects keyed by TF name, as returned by rgv.tl.in_silico_block_simulation().

  • TERMINAL_STATES (list[str]) – Terminal state labels used to define absorption boundaries for the Markov simulation.

  • STARTING_POINTS (list[str]) – Cell-type labels (from adata.obs[cluster_key]) used to seed random walks.

  • tf_ko_list (list[str] | None) – TFs to simulate. If None, all TFs in adata.var['TF'] are used.

  • cluster_key (str) – .obs column name for cell-type annotation, used to identify starting cells.

  • method (str) – Markov simulation method passed to rgv.tl.markov_density_simulation(), either 'stepwise' or 'one-step'.

  • n_step_to_use (int) – Number of steps for the Markov random walk.

  • n_simulations (int) – Number of simulations per starting cell, passed to rgv.tl.markov_density_simulation().

  • seed (int) – Random seed passed to rgv.tl.markov_density_simulation().

  • output_dir (str) – Directory to write the result CSVs into when save=True. Default "." (current working directory).

  • plot (bool) – Whether to draw the density-difference figures. Default False.

  • save (bool) – Whether to also write the result tables to CSV in output_dir. Default False.

Return type:

None

Returns:

: Nothing. Results are stored in adata.uns['markov_density_screening'] as a dict with keys:

  • 'dd_score_by_TF': per-TF density difference scores, significance values, and baseline/perturbed absorption rates.

  • 'visits_by_TF': per-cell visit counts, densities, and differences for each TF.

  • 'screen_perturbation_rate': long-form per-terminal-state visit differences with significance annotation for every TF.

When save=True, writes the tables above to output_dir as:

  • markov_dd_score_by_TF.csv

  • markov_visits_by_TF.csv

  • markov_screen_perturbation_rate.csv