drvi.utils.tools.traverse_latent

drvi.utils.tools.traverse_latent#

drvi.utils.tools.traverse_latent(model, embed, n_steps=20, n_samples=100, copy_adata_var_info=True, **kwargs)[source]#

Perform latent space traversal and enrich with metadata.

This function generates systematic traversals through the latent space and decodes them to observe the effects on gene expression. It creates both control (baseline) and effect (traversal) conditions. Additionally, it enriches the data with dimension-specific metadata like titles, vanished status, and ordering.

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.

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

  • copy_adata_var_info (bool (default: True)) – Whether to copy variable information from the original model’s AnnData.

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

Return type:

AnnData

Returns:

AnnData AnnData object containing the traversal results with enriched metadata. In addition to the structure returned by make_traverse_adata, the .obs also contains: - title: Dimension titles from embed.var['title'] - vanished: Vanished status from embed.var['vanished'] - order: Dimension ordering from embed.var['order']

Raises:

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

Notes

The function performs the following steps: 1. Generates systematic traversal vectors using iterate_dimensions 2. Creates baseline noise for each sample based on dimension std values 3. Generates random categorical covariates for individual samples if the model uses them 4. Decodes both control (noise only) and effect (noise + traversal) conditions 5. Returns the difference between effect and control as the main data 6. Enriches the traversal data with dimension-specific information like titles, vanished status, and ordering.

The function expects the following columns in embed.var: - original_dim_id: Original dimension indices - min, max, std: Dimension statistics - title: Human-readable dimension titles - vanished: Boolean indicating vanished dimensions - order: Dimension ordering

Examples

>>> # Basic traversal
>>> traverse_data = traverse_latent(model, embed)
>>> # Traversal with custom parameters
>>> traverse_data = traverse_latent(model, embed, n_steps=30, n_samples=50)