Foundation Model Analysis

Foundation Model Analysis

Use this skill when a user wants to generate cell embeddings, annotate cell types, integrate batches, or predict perturbation effects using single-cell foundation models. The ov.fm module provides a unified 6-step API that works identically across all 22 supported models.

Model Selection Guide

Pick a model based on your task, species, and hardware. The 5 skill-ready models have full adapter support:

12 additional partial models (scBERT, GeneCompass, Nicheformer, scMulan, tGPT, CellFM, scCello, scPrint, AiDocell, Pulsar, Atacformer, scPlantLLM) and 5+ experimental models are also registered.

Quick decision tree

• Cross-species → UCE
• Ensembl gene IDs or CPU-only → Geneformer
• ATAC-seq data → Atacformer (partial) or scGPT
• Multi-omics (RNA+ATAC+Protein) → scMulan (partial)
• Spatial transcriptomics → Nicheformer (partial) or scGPT
• Fastest throughput on large datasets → CellPLM
• General RNA, no special needs → scGPT

6-Step Unified Workflow

Every FM analysis follows the same pipeline regardless of model choice:

Step 1: Discover available models

import omicverse as ov
models = ov.fm.list_models(task="embed", skill_ready_only=True)
# Returns: {"count": int, "models": [{name, version, tasks, species, ...}]}

Step 2: Profile your data

profile = ov.fm.profile_data("pbmc3k.h5ad")
# Auto-detects: species, gene_scheme (symbol/ensembl), modality, batch/celltype columns
# Returns model_compatibility per model (compatible: bool, issues: [], recommendations: [])

Step 3: Select best model

selection = ov.fm.select_model(
    "pbmc3k.h5ad",
    task="embed",
    prefer_zero_shot=True,   # No labeled data needed
    max_vram_gb=8,            # Hardware constraint
)
model_name = selection['recommended']['name']
# Returns: recommended model with rationale, fallbacks list, preprocessing_notes

Step 4: Validate compatibility

validation = ov.fm.preprocess_validate("pbmc3k.h5ad", model_name, "embed")
# Returns: status ("ready"/"needs_preprocessing"), diagnostics, auto_fixes suggestions

Step 5: Execute

result = ov.fm.run(
    task="embed",
    model_name=model_name,
    adata_path="pbmc3k.h5ad",
    output_path="pbmc3k_embedded.h5ad",
    device="auto",          # auto-detects cuda/mps/cpu
    batch_size=64,          # CellPLM can use 128
    batch_key=None,         # For integration tasks
    label_key=None,         # For annotation tasks
    checkpoint_dir=None,    # Auto-resolved from env vars or cache
)
# Returns: {output_path, output_keys, statistics} or {error: str}

Step 6: Interpret results

metrics = ov.fm.interpret_results(
    "pbmc3k_embedded.h5ad",
    task="embed",
    generate_umap=True,
    color_by=["cell_type"],
)
# Returns: metrics (silhouette scores), visualizations, embedding_keys

Gene ID Resolution

Gene ID mismatch is the most common failure mode. The profile_data() function detects your data's gene scheme automatically.

If profile_data() reports gene_scheme: "ensembl" but you selected scGPT (which needs symbols), either convert gene IDs first or switch to Geneformer.

Hardware Requirements

Device auto-detection priority: CUDA → MPS (Apple Silicon) → CPU.

Checkpoint resolution priority:

1. checkpoint_dir parameter in ov.fm.run()
2. Model-specific env var: OV_FM_CHECKPOINT_DIR_SCGPT
3. Base env var + subfolder: OV_FM_CHECKPOINT_DIR/scgpt/
4. OmicVerse model cache (auto-download if available)

Critical API Reference

TaskType values

"embed", "annotate", "integrate", "perturb", "spatial", "drug_response"

Output keys are model-specific

# After running, embeddings are stored in adata.obsm with model-specific keys:
# scGPT → adata.obsm['X_scGPT']
# Geneformer → adata.obsm['X_geneformer']
# UCE → adata.obsm['X_uce']
# Check result['output_keys'] for the exact keys written

Provenance tracking

# Every run writes provenance to adata.uns['fm']:
# {"runs_json": [...], "latest_json": "..."}
# Contains: model_name, version, task, timestamp, output_keys

Defensive Validation Patterns

import os

# Before any FM workflow: verify input file exists
assert os.path.isfile(adata_path), f"Input file not found: {adata_path}"

# After profile_data: check species was detected
profile = ov.fm.profile_data(adata_path)
assert 'unknown' not in profile.get('species', 'unknown').lower(), \
    f"Species not detected. Check gene names — use HGNC symbols (human) or standard names (mouse)."

# After select_model: verify a model was recommended
selection = ov.fm.select_model(adata_path, task="embed")
assert 'recommended' in selection and selection['recommended'], \
    "No compatible model found. Check species, gene IDs, and hardware constraints."

# Before run: verify checkpoint exists (for models requiring local weights)
desc = ov.fm.describe_model(model_name)
if desc.get('resources', {}).get('checkpoint_url'):
    print(f"Model may need checkpoint download. Check OV_FM_CHECKPOINT_DIR env var.")

Troubleshooting

• Gene ID mismatch warning in profile: Your data uses Ensembl IDs but the selected model expects symbols (or vice versa). Convert with adata.var_names = adata.var['gene_symbols'] or switch to a compatible model.
• CUDA out of memory: Reduce batch_size (try 32 or 16). For UCE/scFoundation (16GB VRAM), ensure no other GPU processes are running.
• Model not installed or ImportError: Some models need separate packages. Install via pip install scgpt / pip install geneformer or use conda isolation (OV_FM_DISABLE_CONDA_SUBPROCESS=0).
• Species unsupported: Most models only support human. For mouse, use scGPT or UCE. For zebrafish/pig/frog, only UCE works.
• Empty embeddings (all zeros): Input data may have constant or near-zero expression. Filter genes with sc.pp.filter_genes(adata, min_cells=10) before running.
• Checkpoint not found: Set the environment variable OV_FM_CHECKPOINT_DIR_<MODEL>=/path/to/weights or pass checkpoint_dir directly to ov.fm.run().
• device='auto' picks CPU despite GPU available: Check torch.cuda.is_available(). If False, verify CUDA drivers and PyTorch CUDA build.

Examples

• "Generate scGPT embeddings for my PBMC dataset and visualize on UMAP."
• "Which foundation model works best for my mouse brain scRNA-seq data?"
• "Embed my ATAC-seq data using a foundation model — I only have 8GB VRAM."
• "Profile my h5ad file and tell me which models are compatible."

References

• Quick copy/paste commands: reference.md
• FM API source: omicverse/fm/api.py
• Model registry: omicverse/fm/registry.py