Skip to content

0 Getting ready

Jump to bottom
Johanna G.R.L edited this page Oct 15, 2026 · 3 revisions

0. Getting ready for SpacePath usage

This documentation assumes that SpacePath and its dependencies has been installed as explained in its README.

We provide example datasets for running SpacePath and rapidly get familiar with the expected input of Spatial Lipidomics or Spatial Metabolomics datasets.

SpacePath currently supports two usage modalities:

  • 💻 Through the Bash command line (client accession) on Linux and MacOS operative systems, or alternatively,

  • 📦 As a Python library (SpacePath.core) callable in user-defined scripts, Jupyter notebooks, Google Colab, etc.

For any of the two modalities the input data remains identical, except for the dataset-specific parameters (.tsv), which is required only for command-line usage.

The input data that is expected by SpacePath comprises:

  • Intensities in .h5ad file (Anndata object)
  • Annotations as comma-delimited .csv files
  • Reference tables of mappings (of compound identifiers) as tab-delimited .tsv files
  • Pathways and their compounds as tab-delimited files

Before digging into the specifics of the input data formats, we recommend to download and rapidly inspect the provided datasets examples which follow an standardized input data structure.

Provided example spatial metabolomics/lipidomics datasets

Instructions to download the example datasets of spatial metabolomics/lipidomics acquisitions are provided in this link. The registry in Zenodo is https://zenodo.org/records/19113236.

With your downloaded and unzipped datasets, the expected folder structure is:

$working_dir     # working directory
├── examples-sm-data      #   the data folder where the datasets subfolders are stored
│    ├── example-corn-root      # the example dataset N 1 (a subfolder)
│    ├── metabolites-mappings      # the provided reference pathways (a subfolder)
│    ├── example-cerebellum      # the example dataset N 2 (a subfolder)
│   
├── SpacePath    #  DO NOT modify anything inhere

The input data structure is the same whether the user chooses to use the command line, or the Python library.

Important : this structure assumes that SpacePath is used in its local clone version, but when installing from PyPI, the clones SpacePath folder does not exist in the working directory.

Details about input data formats are provided in the section Expected-data-formats.

Proceeding to Execution ⚙️

For running SpacePath in the command line on the downloaded example data the user must go to the section 1-SpacePath-in-the-command-line


Expected Data Formats

Annotation CSV files

Your annotation CSV files (e.g., SAMPLE-HMDB.csv, SAMPLE-LipidMaps.csv) must contain these columns:

Column Type Description Example
mz float Mass-to-charge ratio 720.553782
formula string Molecular formula C39H78NO8P
moleculeIds string Database identifier(s), comma-separated if multiple HMDB0001259 or LMGP02011252, LMGP01010532
moleculeNames string Compound name(s), comma-separated if multiple PE(13:0/21:0)

Optional quality columns (recommended for QC filtering):

Column Type Description Range
fdr float False discovery rate 0-1
msm float MSM score 0-1
rawOffSampleProb float Off-sample probability 0-1
totalIntensity float Total ion intensity >0

h5ad intensity matrix

Your .h5ad file should contain:

Attribute Description
X Sparse matrix of intensities (spots × m/z features)
var DataFrame with mz column (float values)
obs DataFrame with spot identifiers as index
obsm['spatial'] NumPy array of (x, y) coordinates, shape (n_spots, 2)

Example structure:

AnnData object with n_obs × n_vars = 5000 × 200
    obs: 'obs'
    var: 'mz'
    obsm: 'spatial'

Spot naming convention

Spot names should follow the pattern x{X}_y{Y} where X and Y are integer coordinates:

  • x0_y0, x0_y1, x1_y0, etc.

This convention is used internally for coordinate extraction.

Pathways files

Pathways must be provided within tab-delimited files, with any extension, but complying with the following format:

WP654   Beta oxydation      HMDB456462342   HMDB45243445    HMDB787456456
WP027   Lypooxygenase activity  HMDB78967976786 HMDB86465   HMDB678575675   HMDB9769000

each row specifies, in this strict order, one pathway identifier, its corresponding pathway name and the molecule identifiers associated to it, each element of the row must be separated by tabulations, and the file must not contain a header. This format is typically used by sspa for KEGG pathways, obeying to The Broad Institute rules for pathway enrichment.

Mapping tables for associating HMDB, LipidMaps and CoreMetabolome identifiers to KEGG compounds

We provide the tables that allow for mapping the identifiers, e.g. from HMDB, or LipidMaps, to KEGG compound identifiers. For details, expand the subsection below.

Provided compound identifiers mapping to KEGG compounds (click to show/hide)

When performing a pathway enrichment using KEGG pathways, SpacePath must map non KEGG identifiers (e.g. HMDB) to KEGG nomenclature. The user may provide his own tables, but we include three alongside our example data. The format is specified at the end of this subsection.

The type of annotation (e.g. LipidMaps) must be written identically across three specific locations:

  1. the suffix of the annotation filename.
  2. the value of the column annotations_to_use in the parameters .tsv file (command-line only). Multiple values (e.g. HMDB, LipidMaps) must be separated by an space .
  3. the first column of the corresponding mapping table.

Illustrative example:

  1. The annotation of the dataset my_dataset is provided in a file whose name ends with LipidMaps as shown below:
data
├── my_dataset   <-  dataset (a subfolder of data)
│   ├── my_dataset.h5ad
│   ├── my_dataset-LipidMaps.csv   <- annotation file with suffix 'LipidMaps'
  1. therefore, the mapping table .tsv file in this location:
data
├── metabolites-mappings   <-  dataset (a subfolder of data)
│   ├── LipidMaps-to-KEGG-<date>.tsv

must have these two columns:

LipidMaps	KEGG
LMFA08030003	C11839
LMFA08030004	C11841
LMFA08030005	C11842

where the first column is identical to the annotation filename suffix.

  1. finally, in the parameters file (command-line only):
... annotations_to_use ...
... HMDB LipidMaps ...

Clone this wiki locally