Repository navigation
1 SpacePath in the command line
SpacePath can be used through the generic command line:
SpacePath $INPUT_FILE $DATA_FOLDER $FIGURES_FOLDER
The explanation of the positional arguments is obtained by invoking the SpacePath --help, which shows the required arguments:
-
INPUT_FILE: the path to the .tsv file containing the parameters which are dataset-specific -
DATA_FOLDER: the path to the folder where the all the datasets subfolders are stored -
FIGURES_FOLDER: the path to the folder where the output figures, per dataset, will be saved
The example provided data, after download (as explained in 0-getting-ready), comes already structured:
$working_dir # working directory
├── examples-sm-data # the "data" folder where the datasets subfolders are stored
│ ├── example-corn-root # the example dataset N 1 (subfolder of "data")
│ ├── metabolites-mappings # the provided reference pathways (subfolder of "data")
│ ├── example-cerebellum # the example dataset N 2 (subfolder of "data")
│
├── SpacePath # local clone (optional) DO NOT modify anything inhere
│
SpacePath will run from any location, by simply loading the virtual environment used for install (conda, micromamba, etc), whether if using pip or poetry. Also, it will run from any location whether using a local clone or the installed package via PyPI.
SpacePath will run from any location by simply loading the virtual environment used for installation (Conda, Micromamba, etc.), whether using a local clone, or the package installed via PyPI.
If you use a local clone of SpacePath, the parameters file SpacePath/datasets_parameters/example-datasets-parameters.tsv is included and defines the per-dataset parameters of the example data.
The command for running SpacePath is shown in this snippet below the comment # run :
micromamba activate spacepath # adapt to your virtual environment
cd $working_dir # adapt to your working directory
mkdir example-figures # create empty folder for visualization outputs
# run:
SpacePath SpacePath/datasets_parameters/example-datasets-parameters.tsv examples-sm-data \
examples-sm-data \
example-figures this command will run the full analysis in ~5 minutes of runtime.
If the user installed SpacePath from PyPI, the file of parameters (.tsv) can be downloaded from here.
Place the example-datasets-parameters.tsv within the folder of your choice, e.g.my_parameters/:
$working_dir # working directory
├── examples-sm-data # the "data" folder where the datasets subfolders are stored
│ ├── ... # same as seen before
├── my_parameters # or any name by the user
│ ├── example-datasets-parameters.tsv
├── ...
and run:
micromamba activate spacepath # adapt to your virtual environment
cd $working_dir # adapt to your working directory
mkdir example-figures # create empty folder for visualization outputs
# run:
SpacePath my_parameters/example-datasets-parameters.tsv examples-sm-data example-figures Details about the expected columns of the parameters .tsv file are provided in the section The parameters file
The first positional argument of SpacePath in the command line is the parameters file.
For the example data, we provide this file ready to use: SpacePath/datasets_parameters/example-datasets-parameters.tsv. This file contains, per row, the parameters defined for each individual dataset, respecting a standardized format.
The example-datasets-parameters.tsv file contains dataset-specific configuration parameters used to control data processing, metabolite annotation filtering, spatial analysis, clustering, and pathway analysis.
A total of 12 columns are compulsory within the parameters file (unless optional is specified, the columns are compulsory):
| Column name | Description |
|---|---|
dataset_name |
Name or identifier of the dataset to be processed. |
metaspace_registry |
(optional) Identifier of the METASPACE dataset registration or analysis to use . |
annotations_to_use |
Metabolite annotation types to consider during the analysis (e.g., HMDB and LipidMaps), provided as a string with one space left between each type. |
in/out intensities for spot class |
(optional) Intensity threshold or parameter used to distinguish in-tissue from out-tissue to classify the spots to be kept or discarded. |
perform_spots_selection |
(optional) Indicates whether spot selection should be performed (YES or NO) |
offSample_cutoff |
Threshold used to filter metabolite annotations according to the offSample metric. |
msm_cutoff |
Minimum threshold for the METASPACE Molecular Signal Matching (MSM) score used to filter metabolite annotations. |
fdr_cutoff |
Maximum accepted false discovery rate (FDR) for metabolite annotations. |
Moran_I_cutoff |
Minimum Moran's I statistic required to retain features based on their spatial autocorrelation. |
Moran_padj_cutoff |
Maximum adjusted p-value accepted when filtering features based on spatial autocorrelation using Moran's I. |
cluster_params |
Clustering algorithm and its associated parameter(s), specified as a string (e.g., leiden_sg:0.5 or kmeans:4). |
pathways_types |
Pathway databases or pathway types to include in the analysis (e.g., KEGG and WikiPathways), provided as a string with one space left between each type. |
min_pathway_size |
Minimum number of elements required for a pathway to be considered in the analysis. |
cut_tree_mol_families |
Parameter controlling where the molecular-family clustering tree is cut to define molecular families. |
min_family_size |
Minimum number of elements required for a molecular family to be retained. |
Specific values ranges explanation:
-
offSample_cutoffis comprised between 0 and 1, the closer to 0 the more stringent -
msm_cutoffis comprised between 0 and 1, the closer to 1 the more stringent -
cut_tree_mol_familiesis comprised between 0 and 1, the closer to 0 the smaller the size of the families and the higher the number of families (0 is at the level of the leaves of the tree)
The optional column metaspace_registry is only taken into account by the auxiliary scripts (SpacePath/aux_scripts) for data download using an in-house implementation of the metaspace-converter.
The two remaining optional columns ( in/out intensities for spot class, perform_spots_selection) are only taken into account by the auxiliary scripts for spots filtering, which constitutes an appendiceal proposal, and can be replaced by any other user-defined method for spots filtering, or even skipped.
The full analysis, invoked by the generic command line, is indeed a series of different sequential steps that are automatically executed: from quality control, to pathways and molecular families differential analysis. A total of eight steps is performed, and as --mode all is selected by default, the default behaviour of SpacePath is to run them all without further user intervention.
The user can alternatively run, separately, each one of the eight steps of the workflow, which are numbered from 1 to 8.
For instance, the first step, which comprises ions quality control and data normalization, is performed by launching:
SpacePath $data_dir $figures_dir $parameters_file --mode 1
The table below explains the correspondences between the numeric call of each mode (step) and the specific processing that is performed:
| Mode | Name | Description |
|---|---|---|
| 1 | Load and Preprocess | Loads annotations, normalizes intensities (TIC), and quality-filters the m/z values. |
| 2 | Clean Annotations | Cleans annotations: resolves identifier aliases, selects best (m/z, identifier) pairs for repeats, and saves cleaned annotations with corresponding m/z values. |
| 3 | Clustering | Computes clustering of spots (the user chooses between Leiden or |
| 4 | Differential Analysis (m/z) | Performs differential analysis on m/z values. |
| 5 | Pathway Scoring | Computes pathway scores for the specified pathways. |
| 6 | Molecule Families | Computes molecule families and generates visualizations. |
| 7 | Family Scoring | Computes family scores for the computed families. |
| 8 | Differential Analysis (Families/Pathways) | Performs differential analysis on families and pathways. |