CLI Usage Guide

spMetaTME is designed around a powerful Command Line Interface (CLI) that simplifies common tasks like metabolic inference and model pretraining. This guide explains how to use these commands.

Getting Help

The spmetatme command provides help information for all its subcommands.

spmetatme --help

For help on a specific subcommand, use:

spmetatme infer --help
spmetatme pretrain --help

---

1. Metabolic Inference (spmetatme infer)

Predict metabolic reaction fluxes and identify spatial domains. This is the main tool used for analyzing new datasets.

Basic Usage

spmetatme infer --input data/my_sample.h5ad --model-species human --metabolic-model breast_cancer

Key Parameters

Parameter	Short	Required	Default	Description
--input	-i	Yes	-	Path to input .h5ad file.
--metabolic-model	-	Yes	-	Name of the metabolic model (e.g., breast_cancer, human_gem).
--model-species	-s	No	human	Species context for the pretrained model (human or mouse).
--preprocess / --no-preprocess	-	No	True	Whether to run MAGIC preprocessing.
--finetune / --no-finetune	-	No	False	Whether to finetune the model on your input data first.
--epochs	-	No	10	Number of finetuning epochs.
--num-clusters	-	No	7	Number of clusters for spatial domain identification. (Alias: --n-clusters)
--method	-	No	kmeans	Clustering method (options: mclust, leiden, louvain, spectral, kmeans).
--output-name	-	No	adata.h5ad	Suffix for the generated result file.

Advanced Examples

Finetune + Inference with custom cluster count:

spmetatme infer -i sample.h5ad --model-species human --metabolic-model breast_cancer --finetune --epochs 20 --n-clusters 5

Using a custom method for clustering:

spmetatme infer -i sample.h5ad --metabolic-model breast_cancer --method leiden

List available metabolic models directly from infer:

spmetatme infer --list-models

---

2. Base Model Pretraining (spmetatme pretrain)

Train a new base model from scratch using multiple spatial transcriptomics datasets.

Basic Usage

spmetatme pretrain --training-list data/*.h5ad --metabolic-model human_gem --repo-id MyRepo/my-model

Key Parameters

Parameter	Short	Required	Default	Description
--training-list	-t	Yes	-	Path or glob pattern to training .h5ad files.
--metabolic-model	-m	Yes	-	Name of the metabolic model to use for training.
--repo-id	-	Yes	-	The ID of the repository/folder to save the results.
--preprocess / --no-preprocess	-	No	True	Whether to preprocess the training data.
--push-to-hub / --no-push-to-hub	-	No	False	Whether to push the final model to Hugging Face Hub.
--epochs	-	No	20	Number of training epochs.
--save-dir	-	No	output/...	Local directory to save model checkpoints.

---

Tip: Available Metabolic Models

You can always list the available metabolic models that spMetaTME supports for inference with:

spmetatme list-metabolic-models