fm-foundation-models_skill

Overview

This skill provides a unified API to run 22 foundation models for bulk, single-cell, and spatial RNA-seq analysis. It streamlines common workflows: generating cell embeddings, annotating cell types, integrating batches, and predicting perturbation or drug responses. The API uses a consistent 6-step pipeline so the same calls work across models and hardware constraints.

How this skill works

The skill inspects your input AnnData or h5ad file and auto-detects species, gene ID scheme (symbol vs Ensembl), modality, and batch/label columns. It lists compatible models, recommends the best model given task and hardware, validates preprocessing requirements, runs the selected model (embedding/annotation/integration/perturbation), and writes outputs and provenance into the AnnData object. Device selection, checkpoint resolution, and output key naming are handled automatically with clear diagnostics and auto-fix suggestions.

When to use it

• You need high-quality cell embeddings for downstream clustering or visualization.
• You want automated cell-type annotation using a foundation model.
• You must integrate multiple batches or modalities with minimal manual tuning.
• You want to predict perturbation or drug-response effects at single-cell resolution.
• You need cross-species embedding or analysis for non-human samples.

Best practices

• Run profile_data() first to detect gene ID scheme and species before selecting a model.
• Match gene IDs to model expectations (symbols vs Ensembl) or choose Geneformer for Ensembl IDs.
• Check device and min VRAM reported by model descriptions; reduce batch_size if encountering OOM.
• Keep provenance: every run writes metadata to adata.uns['fm'] for reproducibility.
• Filter low-quality genes/cells (e.g., filter genes seen in <10 cells) to avoid empty embeddings.

Example use cases

• Generate scGPT or CellPLM embeddings for PBMC scRNA-seq and visualize on UMAP.
• Profile an h5ad and automatically recommend a model that fits a CPU-only environment (e.g., Geneformer).
• Integrate multiple batches from a multi-center study using scGPT or UCE and validate silhouette scores.
• Predict single-cell response to a perturbation with scFoundation when a matching adapter is available.
• Embed cross-species single-cell data (zebrafish, macaque, pig) using UCE for comparative analysis.