ocelli.pp.lda

Contents

ocelli.pp.lda#

ocelli.pp.lda(adata: AnnData, x: str | None = None, out: str = 'X_lda', n_components: int = 10, max_iter: int = 30, doc_topic_prior=None, topic_word_prior: float = 0.1, learning_method: str = 'batch', learning_decay: float = 0.7, learning_offset: float = 10.0, batch_size: int = 128, evaluate_every: int = -1, total_samples: int = 1000000, perp_tol: float = 0.1, mean_change_tol: float = 0.001, max_doc_update_iter: int = 100, verbose: int = 0, random_state=None, n_jobs: int = -1, copy: bool = False)#

Latent Dirichlet Allocation

This function performs Latent Dirichlet Allocation (LDA) using the sklearn.decomposition.LatentDirichletAllocation implementation. LDA is a generative probabilistic model used for topic modeling and dimensionality reduction in single-cell data analysis.

Parameters:

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

  • x (str or None) – The key in adata.obsm storing the input data matrix with non-negative values. If None, adata.X is used as input. (default: None)

  • out (str) – The key to store the LDA output in adata.obsm and adata.varm. (default: X_lda)

  • n_components (int) – Number of topics to model. (default: 10)

  • max_iter (int) – Maximum number of iterations over the dataset. (default: 30)

  • doc_topic_prior (float or None) – Prior of the document-topic distribution. Defaults to 1 / n_components if None. (default: None)

  • topic_word_prior (float) – Prior of the topic-word distribution. (default: 0.1)

  • learning_method (str) – Method used for LDA updates. Options: batch or online. (default: batch)

  • learning_decay (float) – Learning rate for the online method. Must be in (0.5, 1.0]. (default: 0.7)

  • learning_offset (float) – Downweighting parameter for early iterations in online learning. Must be >1.0. (default: 10.0)

  • batch_size (int) – Number of documents per EM update in online learning. (default: 128)

  • evaluate_every (int) – Frequency of perplexity evaluation. Set to <=0 to disable. (default: -1)

  • total_samples (int) – Total number of documents. Used only in the partial_fit method. (default: 1,000,000)

  • perp_tol (float) – Perplexity tolerance for batch learning. Used only if evaluate_every > 0. (default: 0.1)

  • mean_change_tol (float) – Stopping tolerance for updating document-topic distribution. (default: 0.001)

  • max_doc_update_iter (int) – Maximum iterations for document-topic updates during the E-step. (default: 100)

  • verbose (int) – Verbosity level for logging. Options: 0, 1, 2. (default: 0)

  • random_state (int or None) – Random seed for reproducibility. (default: None)

  • n_jobs (int) – Number of parallel jobs. -1 uses all CPUs. (default: -1)

  • copy (bool) – If True, returns a copy of the AnnData object with LDA results. If False, modifies the input object in-place. (default: False)

Returns:

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

    • adata.obsm[out]: LDA observation-topic distribution.

    • adata.varm[out]: LDA feature-topic distribution.

    • adata.uns[f”{out}_params”]: Dictionary of LDA parameters.

  • 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

# Create example data
adata = AnnData(X=np.random.rand(100, 50))

# Apply LDA
oci.pp.LDA(adata, n_components=20)
Contents