API

The main user-facing API is exposed at the top level of the terra package. The typical workflow is to harmonize an AnnData, tokenize it against a trained model, and embed it:

from terra import download_pretrained, harmonize_tokenize_embed_pipeline

Inference

harmonize_tokenize_embed_pipeline(adata, ...)	Harmonize, tokenize and embed an AnnData object.
harmonize_adata(adata[, ...])	Harmonize an AnnData object prior to tokenization.
tokenize_adata(adata, model_folder_path, ...)	Tokenize an AnnData object based on the parameters in the model config and return the tokenized Hugging Face dataset.
embed_dataset(dataset, model_folder_path[, ...])	Embed a tokenized dataset, returning cell-, neighborhood- and gene-level embeddings.
gene_embed_dataset(dataset, model_folder_path)	Compute per-gene embeddings or co-occurrence statistics over a tokenized dataset.
infer(args, dataset, load_folder_path[, ...])	Use a trained model for inference, returning cell, neighborhood and optionally gene embeddings.
get_gene_embed(dataset, model_folder_path[, ...])	Retrieve gene embeddings for specified cell and neighborhood gene IDs.
get_average_gene_embed(dataset, ...[, ...])	Retrieve average gene embeddings for each gene per dataset.
perturb_dataset(dataset, perturb_df, ...[, ...])	Perturb a tokenized Hugging Face dataset according to a perturbation dataframe.
get_emd_distance(dataset, model_folder_path)	Compute and return distance between cosine similarity of cell_neb and cell_cell matrix.
get_spatial_score(dataset, model_folder_path)	Compute and return cosine similarity matrix for specified gene IDs.

Hugging Face Hub

download_pretrained(repo_id, *[, revision, ...])	Download a published TERRA model bundle.
push_model_to_hub(model_folder, repo_id, *)	Create (if needed) a Hugging Face model repo and upload a TERRA model bundle.

Data

Convenience reader used by the tutorials to load public 10x Genomics Xenium samples.

read_xenium_10x(base_url, out_dir)

Download a 10x Genomics Xenium sample and load it as an AnnData.