OmicVerse Single-Cell LDA Topic Clustering
Goal
Turn the notebook's MIRA-backed topic modeling section into a reusable job: fit an LDA topic model on count-like single-cell data, predict topic usage, and optionally derive hard cluster labels or RFC-based labels.
Quick Workflow
- Inspect whether the data still has a count layer and a highly-variable-feature flag.
- Choose
feature_type, learning_rate, and whether to run ondisk=False or ondisk=True.
- Construct
LDA_topic(...), then decide how many topics to fit.
- Run
predicted(num_topics=...) to create LDA_cluster.
- If the user wants harder classification on an embedding, run
get_results_rfc(...) with explicit use_rep and LDA_threshold.
Interface Summary
ov.utils.LDA_topic(adata, feature_type='expression', highly_variable_key='highly_variable_features', layers='counts', batch_key=None, learning_rate=0.001,> constructs the wrapper.- The documented
feature_type branch is modality-sensitive; current docs describe at least expression and accessibility.
ondisk=False keeps training data in memory. ondisk=True writes local training and test datasets before tuning and fitting.predicted(num_topics=6) fits the model with the chosen topic count, predicts topic usage, and writes LDA_cluster.get_results_rfc(adata, use_rep='X_pca', LDA_threshold=0.5, num_topics=6) trains tree-based classifiers on high-confidence topic assignments and writes LDA_cluster_rfc and LDA_cluster_clf.
Stage Selection
- Use the plain
predicted(...) path when the user wants one topic-to-cluster projection without extra classifiers.
- Use the RFC path only when the user explicitly wants classifier-derived hard labels from the topic representation.
- Use
ondisk=True only when dataset size makes in-memory execution impractical.
- Treat the notebook's embedding panels as optional reporting, not the reusable contract.
Input Contract
- Start from
AnnData.
- Keep a count-like layer available under the selected
layers key.
- Ensure the selected highly-variable flag exists in
adata.var.
- Ensure the embedding named by
use_rep exists before the RFC path.
Minimal Execution Patterns
import omicverse as ov
lda = ov.utils.LDA_topic(
adata,
feature_type="expression",
highly_variable_key="highly_variable_features",
layers="counts",
batch_key=None,
learning_rate=1e-3,
)
lda.predicted(num_topics=13)
lda.get_results_rfc(
adata,
use_rep="scaled|original|X_pca",
LDA_threshold=0.4,
num_topics=13,
)
Constraints
- Do not use this skill on data that no longer has a usable count-like layer for the selected
layers key.
- Do not treat the notebook's topic count as a universal default.
- Do not use the RFC path without a real embedding in
obsm.
ondisk=True creates local training/test datasets and is a runtime mode choice, not part of the reusable semantic contract.- Keep smoke and acceptance commands shell-agnostic.
Validation
- Check that the wrapper constructed successfully with the intended
feature_type, layers, and ondisk mode.
- After
predicted(...), check that topic columns and LDA_cluster exist.
- After the RFC path, check that
LDA_cluster_rfc and LDA_cluster_clf exist.
- If only a bounded smoke path was run, state whether model fitting was skipped or reduced.
Resource Map
- Use the branch selection notes when choosing
feature_type, ondisk, or the RFC path.
- Use the source grounding notes for current signatures, PyTorch compatibility behavior, and output labels.
- Use the notebook mapping notes to trace the notebook's topic-modeling section into this reusable skill.
- Use the compatibility notes for dependency, GPU, and filesystem-sensitive behavior.
1---2name: omicverse-single-cell-lda-topic-clustering3description: Run OmicVerse single-cell LDA topic clustering with the MIRA backend as a reusable, triggerable skill. Use when fitting topic models on count-like AnnData, choosing between in-memory and on-disk execution, or converting topic assignments into hard cluster labels and RFC-based labels.4---56# OmicVerse Single-Cell LDA Topic Clustering78## Goal910Turn the notebook's MIRA-backed topic modeling section into a reusable job: fit an LDA topic model on count-like single-cell data, predict topic usage, and optionally derive hard cluster labels or RFC-based labels.1112## Quick Workflow13141. Inspect whether the data still has a count layer and a highly-variable-feature flag.152. Choose `feature_type`, `learning_rate`, and whether to run `ondisk=False` or `ondisk=True`.163. Construct `LDA_topic(...)`, then decide how many topics to fit.174. Run `predicted(num_topics=...)` to create `LDA_cluster`.185. If the user wants harder classification on an embedding, run `get_results_rfc(...)` with explicit `use_rep` and `LDA_threshold`.1920## Interface Summary2122- `ov.utils.LDA_topic(adata, feature_type='expression', highly_variable_key='highly_variable_features', layers='counts', batch_key=None, learning_rate=0.001, ondisk=False)` constructs the wrapper.23- The documented `feature_type` branch is modality-sensitive; current docs describe at least `expression` and `accessibility`.24- `ondisk=False` keeps training data in memory. `ondisk=True` writes local training and test datasets before tuning and fitting.25- `predicted(num_topics=6)` fits the model with the chosen topic count, predicts topic usage, and writes `LDA_cluster`.26- `get_results_rfc(adata, use_rep='X_pca', LDA_threshold=0.5, num_topics=6)` trains tree-based classifiers on high-confidence topic assignments and writes `LDA_cluster_rfc` and `LDA_cluster_clf`.2728## Stage Selection2930- Use the plain `predicted(...)` path when the user wants one topic-to-cluster projection without extra classifiers.31- Use the RFC path only when the user explicitly wants classifier-derived hard labels from the topic representation.32- Use `ondisk=True` only when dataset size makes in-memory execution impractical.33- Treat the notebook's embedding panels as optional reporting, not the reusable contract.3435## Input Contract3637- Start from `AnnData`.38- Keep a count-like layer available under the selected `layers` key.39- Ensure the selected highly-variable flag exists in `adata.var`.40- Ensure the embedding named by `use_rep` exists before the RFC path.4142## Minimal Execution Patterns4344```python45import omicverse as ov4647lda = ov.utils.LDA_topic(48 adata,49 feature_type="expression",50 highly_variable_key="highly_variable_features",51 layers="counts",52 batch_key=None,53 learning_rate=1e-3,54 ondisk=False,55)56lda.predicted(num_topics=13)57```5859```python60lda.get_results_rfc(61 adata,62 use_rep="scaled|original|X_pca",63 LDA_threshold=0.4,64 num_topics=13,65)66```6768## Constraints6970- Do not use this skill on data that no longer has a usable count-like layer for the selected `layers` key.71- Do not treat the notebook's topic count as a universal default.72- Do not use the RFC path without a real embedding in `obsm`.73- `ondisk=True` creates local training/test datasets and is a runtime mode choice, not part of the reusable semantic contract.74- Keep smoke and acceptance commands shell-agnostic.7576## Validation7778- Check that the wrapper constructed successfully with the intended `feature_type`, `layers`, and `ondisk` mode.79- After `predicted(...)`, check that topic columns and `LDA_cluster` exist.80- After the RFC path, check that `LDA_cluster_rfc` and `LDA_cluster_clf` exist.81- If only a bounded smoke path was run, state whether model fitting was skipped or reduced.8283## Resource Map8485- Use the branch selection notes when choosing `feature_type`, `ondisk`, or the RFC path.86- Use the source grounding notes for current signatures, PyTorch compatibility behavior, and output labels.87- Use the notebook mapping notes to trace the notebook's topic-modeling section into this reusable skill.88- Use the compatibility notes for dependency, GPU, and filesystem-sensitive behavior.
omicverse