ocelli.pp.generate_modalities

ocelli.pp.generate_modalities#

ocelli.pp.generate_modalities(adata: AnnData, topics: str = 'X_lda', n_features: int = 100, log_norm: bool = True, weights: str = 'weights', verbose: bool = False, copy: bool = False)#

Generate topic-based modalities from unimodal data.

This function creates topic-based modalities using the topic-feature distribution from Latent Dirichlet Allocation (LDA). Features (e.g., genes) are grouped based on their highest topic assignment, and the top n_features per group are retained to form new modalities. Modalities are saved as numpy.ndarray arrays in adata.obsm[modality*], where * denotes the topic ID.

Parameters:

  • adata (anndata.AnnData) – The annotated data matrix.

  • topics (str) – Key in adata.varm storing the topic-feature distribution matrix (numpy.ndarray of shape (n_vars, n_topics)). (default: X_lda)

  • n_features (int) – Maximum number of features to retain for each topic-based modality. (default: 100)

  • log_norm (bool) – Whether to log-normalize the generated modalities. (default: True)

  • weights (str) – Key in adata.obsm where the topic-based weights matrix will be saved. This matrix is row-normalized so each row sums to 1. (default: weights)

  • verbose (bool) – Whether to print progress notifications. (default: False)

  • copy (bool) – Whether to return a copy of anndata.AnnData. If False, modifies the input object in-place. (default: False)

Returns:

  • If copy=False: Updates the input adata with:

    • adata.uns[“modalities”]: List of generated modalities.

    • adata.obsm[modality*]: Arrays of generated modalities, where * denotes the topic ID.

    • adata.uns[vars_*]: Feature names used for each modality, where * denotes the topic ID.

    • adata.obsm[weights]: Topic-based weights matrix.

  • If copy=True: Returns a modified copy of adata with the above updates.

Return type:

anndata.AnnData or None

Example:
import ocelli as oci
from anndata import AnnData
import numpy as np

# Example AnnData object
adata = AnnData(X=np.random.random((100, 50)))
adata.varm["X_lda"] = np.random.random((50, 5))  # Mock LDA output

# Generate modalities
oci.pp.generate_modalities(adata, topics="X_lda", n_features=50, verbose=True)