drvi.utils.tools.calculate_differential_vars

drvi.utils.tools.calculate_differential_vars#

drvi.utils.tools.calculate_differential_vars(traverse_adata, **kwargs)[source]#

Calculate differential variables based on a combination of max_possible and min_possible effects.

This function performs a comprehensive differential variable analysis by calculating effects using both “max_possible” and “min_possible” methods, then combining them into a unified score that considers both approaches.

Parameters:

  • traverse_adata (AnnData) – AnnData object created by traverse_latent or make_traverse_adata. Must contain .layers['control'] and .layers['effect'].

  • **kwargs – Additional keyword arguments passed to find_differential_effects.

Return type:

None

Returns:

None Results are stored in traverse_adata: - .uns["max_possible_traverse_effect_stepwise"]: Max possible stepwise effects - .uns["min_possible_traverse_effect_stepwise"]: Min possible stepwise effects - .uns["combined_score_traverse_effect_stepwise"]: Combined stepwise effects - .varm["max_possible_traverse_effect_pos/neg"]: Max possible direction effects - .varm["min_possible_traverse_effect_pos/neg"]: Min possible direction effects - .varm["combined_score_traverse_effect_pos/neg"]: Combined direction effects

Notes

The function performs the following steps: 1. Calculates differential effects using “max_possible” method 2. Calculates differential effects using “min_possible” method 3. Combines the results using a custom scoring function

Scoring Logic:

The combined score is designed to identify genes that show consistent differential effects across both calculation methods. The filtering criteria are:

  1. Base threshold: max_possible >= 1.0 (ensures substantial effect)

  2. Relative thresholds: Either: - max_possible > 50% of its maximum across all dimensions and steps, OR - min_possible > 10% of its maximum across all dimensions and steps

  3. Final score: For genes passing the filters, score = max_possible × min_possible

This approach provides a robust way to identify genes that show consistent differential effects across both calculation methods, reducing false positives while maintaining sensitivity to real biological effects.

Biological Interpretation:

  • High combined scores: Genes with strong specific effects

  • High max_possible, low min_possible: These genes are usually shared with another program, with the other program having a larger effect.

  • Low max_possible, high min_possible: Not possible.

  • Low scores in both: Genes with weak or inconsistent effects

Examples

>>> # Basic differential variable calculation
>>> calculate_differential_vars(traverse_adata)
>>> # With custom parameters
>>> calculate_differential_vars(traverse_adata, add_to_counts=0.05, relax_max_by=0.1)
>>> # Access results
>>> max_effects = traverse_adata.varm["max_possible_traverse_effect_pos"]
>>> min_effects = traverse_adata.varm["min_possible_traverse_effect_pos"]
>>> combined_effects = traverse_adata.varm["combined_score_traverse_effect_pos"]