drvi.utils.tools.get_split_effects

drvi.utils.tools.get_split_effects#

drvi.utils.tools.get_split_effects(model, embed, n_steps=20, n_samples=100, traverse_kwargs=None, de_kwargs=None)[source]#

Get split effects by performing latent traversal and differential analysis.

This is a high-level function that combines latent space traversal with differential variable analysis. It performs the complete pipeline from generating traversal data to calculating differential effects.

Parameters:

  • model (DRVI) – Trained DRVI model for decoding latent representations.

  • embed (AnnData) – AnnData object containing latent dimension statistics in .var. Must have columns: original_dim_id, min, max, std, title, vanished, order.

  • n_steps (int (default: 20)) – Number of steps in the traversal. Must be even (half negative, half positive).

  • n_samples (int (default: 100)) – Number of samples to generate for each step.

  • traverse_kwargs (dict | None (default: None)) – Additional arguments passed to traverse_latent. Common options include: - copy_adata_var_info: Whether to copy variable information - noise_formula: Custom noise generation function - max_noise_std: Maximum noise standard deviation.

  • de_kwargs (dict | None (default: None)) – Additional arguments passed to calculate_differential_vars. Common options include: - add_to_counts: Pseudo-count for log calculations - relax_max_by: Relaxation factor for min_possible method.

Return type:

AnnData

Returns:

AnnData AnnData object containing both traversal data and differential analysis results. Includes all outputs from traverse_latent and calculate_differential_vars:

Traversal Data: - .X: Difference between effect and control conditions - .layers['control']: Control condition gene expression - .layers['effect']: Effect condition gene expression - .obs: Metadata including dim_id, sample_id, step_id, span_value, title, vanished, order

Differential Analysis Results: - .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["*_traverse_effect_pos/neg"]: Direction-specific effects for all methods

Raises:

  • ValueError – If required columns are missing from embed.var.

  • KeyError – If required data is missing from the model or embed objects.

Notes

This function is a convenience wrapper that performs the complete analysis pipeline in one call. It’s equivalent to:

`python traverse_adata = traverse_latent(model, embed, n_steps, n_samples, **traverse_kwargs) calculate_differential_vars(traverse_adata, **de_kwargs) return traverse_adata `

Functionality:

  1. Traversal Generation: Creates systematic traversals through latent space

  2. Decoding: Converts latent traversals to gene expression predictions

  3. Differential Analysis: Calculates effects using max_possible and min_possible methods

  4. Combination: Creates unified scores for robust gene identification

Use Cases:

  • Gene Discovery: Identify genes associated with specific latent dimensions

  • Pathway Analysis: Understand biological processes captured by latent factors

  • Model Validation: Verify that latent dimensions have interpretable biological meaning

  • Comparative Analysis: Compare effects across different models or conditions

Examples

>>> # Basic split effects analysis
>>> split_effects = get_split_effects(model, embed)
>>> # With custom parameters
>>> split_effects = get_split_effects(model, embed, n_steps=30, n_samples=50)
>>> # Access results
>>> combined_effects = split_effects.varm["combined_score_traverse_effect_pos"]
>>> stepwise_effects = split_effects.uns["combined_score_traverse_effect_stepwise"]