METASPACE docs

Appearance

Your METASPACE Journey ​

This page maps the full path through METASPACE — from raw data to published results. Each stage is collapsible so you can jump to wherever you are in your workflow.

Stage 1 — Getting Organized  ·  Account, groups, and projects

Before uploading any data, it helps to understand how METASPACE organizes users and data.

  • Account Settings — create an account, update your profile, and find your API key for programmatic access.
  • Groups & Members — a group represents a lab or team. Members share access to private datasets. The group admin controls membership.
  • Projects — a project collects related datasets together, typically corresponding to a publication or study. Create a project before uploading so your datasets are organized from the start.

Tip: The recommended order is: create a group → create a project → upload datasets linked to that project.

Stage 2 — Preparing Your Data  ·  Getting into the right format

METASPACE accepts imaging MS data as centroided imzML + ibd files. Both files must be present for upload.

Don't have imzML yet? ​

See Exporting to imzML Format for instructions on converting from common vendor formats. Make sure your data is centroided before proceeding — profile-mode data is not supported.

Want to know what's detectable before you run? ​

The Detectability App lets you explore which metabolites and adducts are likely to be detected under your specific imaging MS protocol and technology. Useful for choosing databases and setting expectations before annotation.

Stage 3 — Uploading Your Dataset  ·  Submission, metadata, and annotation settings

Upload ​

The Upload Page guide covers the full submission form: linking to a project, selecting your instrument and ion source, choosing databases, and setting annotation parameters.

Metadata ​

Read Metadata Recommendations alongside the upload guide — good metadata makes your dataset discoverable and reproducible. Fill it in while the context is fresh.

Custom databases ​

If the molecules you care about aren't in any standard database, you can upload your own list. See Custom Databases — the database must be attached to a group before it appears in the upload selector.

Uploading programmatically? ​

The Python Client supports automated dataset submission as part of a larger pipeline.

Annotation runs automatically after submission. Processing time depends on dataset size.

Stage 4 — Interpreting Your Results  ·  Understanding what was computed

Once annotation is complete, start here before exploring individual features.

Start here ​

Understanding the Annotation Page explains what METASPACE computed, how to read the annotation table, what the FDR and scores mean, and where to go next.

Go deeper (optional) ​

METASPACE runs two analyses automatically alongside annotation. These guides explain them in detail:

  • Co-localization — which ion images share similar spatial patterns across your dataset, and how to use this to assess annotation quality.
  • Off-Sample Filtering — how METASPACE identifies annotations that fall outside the tissue and suppresses them from results.
Stage 5 — Exploring Your Results  ·  Visualization and spectral inspection

Ion image visualization ​

  • Ion Image Visualization — the core viewer for exploring annotated ion images, applying color maps, and adjusting intensity.
  • Multi-Channel Ion Image Viewer — overlay multiple ion images in separate color channels to compare spatial distributions side by side.
  • Optical Image Overlay — align an H&E or fluorescence image with ion images to correlate molecular distributions with histology.

Per-pixel spectra and normalization ​

If you want to inspect the raw spectral data behind annotations, or explore intensity normalization options:

Stage 6 — Downstream Analysis  ·  Spatial analysis, cross-dataset comparison, and export

Spatial pattern analysis ​

Draw regions of interest directly on your ion images and use them for focused exploration or comparison:

  • ROI Selection — define regions based on histology, anatomy, or any visible spatial structure.
  • Spatial Segmentation — automatically partition a dataset into chemically coherent tissue regions, without drawing ROIs by hand.
  • ROI Differential Analysis — identify metabolites enriched or depleted in one ROI relative to all others.

Cross-dataset comparison ​

Bring regions from several datasets in a project together for side-by-side or statistical comparison:

  • Multi-Dataset Comparison — compare ion images for the same metabolite across multiple datasets.
  • Cross-Dataset Statistical Analysis — test which ions differ significantly between experimental conditions spread across multiple datasets, using a moderated statistical model built for small replicate counts.

Export for external tools ​

To take your annotation results into external analysis environments:

  • METASPACE Converter — download and convert annotation results into AnnData or SpatialData format for use with Python-based spatial omics tools like scanpy and squidpy.
  • Python Client — retrieve annotation tables, ion images, and metadata programmatically for custom pipelines.
Stage 7 — Sharing & Publishing  ·  Making your data available

Share with collaborators ​

Sharing Annotations & Datasets — control visibility and access for your datasets, and share specific annotation views with collaborators.

Publish alongside a paper ​

Publishing Projects — link a project to a publication DOI and make your datasets publicly available. This is the standard route for data availability statements in imaging MS papers.