Skip to main content
Products Technology Company Resources
Support Suite Home

Understanding the AnnData (Scanpy) object that is downloadable from Trailmaker Insights module

  • First Published:
  • Updated:

How to download an AnnData object from TrailmakerTM Insights module

Downloading an AnnData object from the Trailmaker Insights module is a simple process that allows you to further analyze your Scanpy projects using Python. Here's how you can do it:

1. Log in to your Trailmaker account, navigate to the Insights module.

2. From the Projects list, select the project from which you want to download the object.

This initiates the download of the AnnData object in a format that is compatible with Python. Once downloaded, you can load this object into your Python environment for advanced analysis and visualization.

Note that Projects that use Seurat have the 'Processed Seurat object (.rds)' option which allows the download of the Seurat object. Seurat objects cannot be downloaded from Scanpy Projects and vice versa.

What is a .h5ad file and how do you use it?

A .h5ad file is a file format used mostly in Scanpy. It is based on the standard HDF5 format (Hierarchical Data Formats), which is mainly used to store well-organized scientific data. Specifically, the H5AD format is employed to store AnnData objects, a data structure used by Scanpy for single-cell analysis in Python. This format stores the expression matrix together with annotations, embeddings, and analysis results in a single efficient HDF5-based container.

See the AnnData documentation and the “Getting started with AnnData” tutorial for further details.

In the context of Trailmaker, the .h5ad file you download contains a processed AnnData object, which is a comprehensive representation of your single-cell RNA sequencing data. This file encapsulates all the processed data and analyses you've performed on the dataset within Trailmaker. This includes normalized, variable features, dimensionality reductions, clustering results, cell type annotations and more. Note that projects processed before 28 of April 2026 will contain an additional scaled layer whereas projects processed after that date won’t. This layer can be recomputed using the following code:

import scanpy as sc
adata = sc.read_h5ad("your_AnnData_object.h5ad")
adata.layers["scaled"] = adata.layers["normalized"].copy()
sc.pp.scale(adata, max_value=10, layer="scaled")

 

By loading this file into Scanpy, you can pick up right where you left off, allowing for further customization, additional analyses, or integration with other datasets. 


To work with your AnnData object in Python, you can load the .h5ad file using the read_h5ad() function. For example:

import scanpy as sc
adata = sc.read_h5ad("your_AnnData_object.h5ad")

 

What does the AnnData object downloaded from Trailmaker contain?

The AnnData object downloaded from Trailmaker is a processed dataset that contains only the cells retained after all filtering steps have been applied during Data Processing. Additionally, cells with fewer than 10 transcripts are removed from the AnnData object. This ensures that the data you're working with is clean, high-quality, and ready for downstream analysis. The cells that were filtered out during Data Processing in Trailmaker are not contained within the object.

Structure of the AnnData object

An AnnData object is a specialized data structure in Scanpy designed for matrix-like data, including single-cell RNA sequencing data. It efficiently organizes data and results, allowing you to perform complex analyses and visualizations. The AnnData object comprises several key components, each serving a specific role in storing data, metadata, or analysis results:

  • X: the raw count matrix (cells x genes). X is left untouched by normalization or scaling and serves as the source of original counts.
  • obs: a dataframe with cell-level metadata, such as cell identifiers and experimental conditions. 
  • var: a dataframe with gene-level metadata
  • uns: unstructured annotations, often dictionaries containing parameters and results of analyses
  • obsm: multi-dimensional embeddings (e.g. PCA, UMAP, t-SNE)
  • varm: per-gene information such as principal components
  • layers: alternative representations of the count matrix derived from X (e.g. normalized, scaled). The scaled layer is only available for projects processed before 28 of April 2026. 
  • obsp: square matrices representing graphs

The AnnData object from Trailmaker contains specific metadata columns within the obs slot, providing detailed information about each cell:

  • barcode: The unique identifier for each cell detected in the dataset.
  • orig.ident: Indicates the original identity or source of each cell. This is particularly useful when data from multiple samples, conditions, or experimental groups are combined, as it helps trace each cell back to its origin.
  • nCount_RNA: The total number of RNA molecules (counts) detected in each cell. This reflects the cellular RNA content and can be used for quality control.
  • nFeature_RNA: The number of genes with non-zero counts observed in each cell. This metric indicates the complexity of the transcriptome captured in each cell.
  • percent.mt: The proportion of transcripts mapping to mitochondrial genes. High percentages may indicate cell stress or damage, serving as a quality control metric.
  • doublet_scores: Quantifies the likelihood that a cell is a doublet (i.e., contains RNA from two or more cells). See Understanding the Seurat object that is downloadable from Trailmaker Insights module for more details.
  • doublet_class: Categorizes each cell as "singlet" or "doublet" based on the doublet score. See Understanding the Seurat object that is downloadable from Trailmaker Insights module for more details.
  • cell_ids: An internal identifier assigned to each cell within Trailmaker for tracking purposes.
  • Samples/sample-id: Indicates the sample to which each cell belongs.
  • Leiden (or louvain) clusters: The cluster assignments for each cell, calculated using the Leiden or Louvain algorithms during the Configure Embedding step of Data Processing in Trailmaker.
  • Custom cell sets: If any custom cell sets were created in Trailmaker, they will be present in the obs annotation of the AnnData object as columns named with the name you defined in Trailmaker (e.g., MyCellSet)
  • CellTypist-*: If cell type annotation was performed in Trailmaker using CellTypist, the annotations will be present in the obs annotation of the AnnData object as columns named “CellTypist-Model” (e.g., CellTypist-Healthy_COVID19_PBMC). 
  • Decoupler-*:  If cell type annotation was performed in Trailmaker using Decoupler, the annotations will be present in the obs annotation of the AnnData object as columns named “Decoupler-ORA-Species-Tissue” (e.g., Decoupler-ORA-human-Immune system). 

The var slot contains information about genes. The columns are:

  • gene_symbols: Gene names corresponding to Ensembl IDs
  • feature_types: Feature category (e.g., “Gene Expression”)
  • highly_variable: Boolean indicating if the gene was identified as highly variable
  • highly_variable_rank, means, variances, variances_norm: Statistics used in variable gene selection
  • mean, std: Expression-level statistics across cells.

The uns slot contains unstructured results, including:

  • clusters_rank_genes_groups: Differential expression results
  • experimentId: Unique experiment identifier from Trailmaker
  • integration_method: Method used for batch correction (e.g., Harmony).
  • pca, umap, tsne: Parameters used to compute dimensionality reductions
  • neighbors: Parameters and graph information used for clustering
  • leiden: Parameters used for Leiden clustering
  • hvg: Details of the highly variable gene selection

Multi-dimensional embeddings stored in obsm include:

  • pca_raw: a snapshot of the original PCA results before Harmony integration is applied. It contains the full PCA embeddings (X_pca_raw) and the variance explained across components. This information is mainly used internally for:
    • Elbow plot (to visualize variance explained per PC)
    • Automatic estimation of the number of PCs to retain
  • pca_harmony: Harmony-corrected PCA. Trailmaker replaces X_pca with X_pca_harmony so that all downstream steps (neighbors graph, Leiden clustering, UMAP, t-SNE) use the integrated representation
  • X_umap: UMAP embedding
  • X_tsne: t-SNE embedding

In short, pca_raw preserves the pre-integration PCA results so that you still have access to the uncorrected variance structure of the dataset, while pca / pca_harmony represents the integrated data that Trailmaker uses for clustering and visualization.

 

Immune AnnData object (.h5ad)

For projects generated with Evercode BCR or TCR kits, Trailmaker provides an additional AnnData object containing immune repertoire information. This immune AnnData object is available to download from the Project Details page:

The immune AnnData object:

  • Contains the same cells as the main WT AnnData object (after Data Processing filtering).
  • Stores BCR/TCR V(D)J and clonotype information instead of transcriptomic features.

This object is designed for downstream immune repertoire analysis and can be integrated with the main WT AnnData object using the shared cell identifiers.

 

Structure of the immune AnnData object

Unlike the expression AnnData object, the immune object does not contain a count matrix. Instead, it stores immune-specific annotations across three main components (obs, uns and obsm). The immune annotations are generated from the immune files produced by the Pipeline module (barcode_report.tsv, clonotype_frequency.tsv, (tcr/bcr)_annotation_airr.tsv). For more details, see this article for BCR data and this article for TCR data. The three main components of immune AnnData are:

1. obs: per-cell immune annotations. 

The obs slot contains BCR/TCR metadata for each cell. 

Some columns are shared between BCR and TCR analysis:

  • Clonotype and sample metadata:
    • clonotype_id: clonotype identifier
    • clonokey: combined TRA/TRB CDR3 identifier for internal use
    • sample-id: sample identifier
    • samples: sample name
    • cell_ids: cell identifiers for internal use
    • barcode: cell identifiers
    • isMultiplet: whether a cell is considered a potential multiplet/doublet
    • Barcode well and window identifiers (bc1_well, bc2_well, bc3_well, bc1_wind, etc.)

Some columns are specific to BCR data:

  • IGK chain:
    • IGK_V, IGK_D, IGK_J, IGK_C
    • IGK_cdr3_aa
    • IGK_read_count
    • IGK_transcript_count
  • IGL chain:
    • IGL_V, IGL_D, IGL_J, IGL_C
    • IGL_cdr3_aa
    • IGL_read_count
    • IGL_transcript_count
  • IGH chain:
    • IGH_V, IGH_D, IGH_J, IGH_C
    • IGH_cdr3_aa
    • IGH_read_count
    • IGH_transcript_count
  • Secondary chains (if detected):
    • secondary_IGK_*
    • secondary_IGL_*
    • secondary_IGH_*

Some columns are specific to TCR data:

  • TCR α 
  • chain (TRA):
    • TRA_V, TRA_D, TRA_J, TRA_C
    • TRA_cdr3_aa
    • TRA_read_count
    • TRA_transcript_count
  • TCR β chain (TRB):
    • TRB_V, TRB_D, TRB_J, TRB_C
    • TRB_cdr3_aa
    • TRB_read_count
    • TRB_transcript_count
  • Secondary chains (if detected):
    • secondary_TRA_*
    • secondary_TRB_*

Cells without detected BCR/TCR chains will have NaN values in the corresponding fields.

2. uns[“clonotype_frequency”]: clonotype frequency table

The uns slot contains a clonotype-level summary table derived from the clonotype_frequency output generated by the Pipeline module and subsequently filtered by Trailmaker. It includes:

  • IGK/L and IGH CDR3 amino acid sequences for BCR data; TRA and TRB CDR3 amino acid sequences for TCR data
  • clonotype_id
  • count (number of cells assigned to the clonotype)
  • frequency
  • clonokey
     

3. obsm["airr"]: full AIRR-formatted annotations

It stores the full AIRR-formatted immune receptor annotations for each cell. These originate from the AIRR file produced by the Pipeline module and include detailed V(D)J alignment and sequence-level information.

This structure preserves the full immune receptor annotation in a standardized format suitable for advanced repertoire analysis.
 

Relationship to the main AnnData object

  • The immune AnnData object and the expression AnnData object contain the same filtered cells.
  • They can be joined or cross-referenced using shared identifiers (barcode, cell_ids, sample-id).
  • The immune object contains only immune repertoire data, while the main AnnData object contains gene expression, clustering, embeddings, and annotations.

Together, these objects enable integrated transcriptomic and immune repertoire analysis within the Python/Scanpy ecosystem.

You can combine the expression AnnData object and the immune AnnData object into a single MuData object (from the mudata package) as follows:

import scanpy as sc
import mudata as mu

# Load objects
adata = sc.read_h5ad("expression_adata.h5ad")
immune = sc.read_h5ad("immune_adata.h5ad")

# Create MuData container
mdata = mu.MuData({
   "rna": adata,
   "immune": immune
})

 

This creates a multimodal object where:

  • mdata["rna"] contains the gene expression (WT) data
  • mdata["immune"] contains the immune data

Both modalities share the same cells and can be analyzed jointly within the MuData framework.

 

Summary

In this article, we've guided you through the process of downloading and using an AnnData object from the Trailmaker Insights module. We explained how to obtain the AnnData .h5ad file and load it into Scanpy, and provided a detailed explanation of the AnnData object structure. 

By following these steps, you can leverage the rich data contained in the AnnData object and perform advanced downstream analysis outside of Trailmaker.


 

 

Was this article helpful?
0 out of 0 found this helpful

Have more questions? Please contact support.

Return to top

Related articles