Skip to content

3 Supplementary information: library usage

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

Supplementary information: library usage

This section showcases code snippets for handling special cases using our SpacePath.core library.

Special case 1: using Wikipathways for computing pathway scores

Our SpacePath.core library also allows for using Wikipathways and we provide all the required files.

Reminder of the dictionary containing the location of the pathways of reference

pathways_files_location_info = {
        "KEGG" : {'file': "KEGG_hsa_pathways_compounds_R110.gmt",
                      'subfolder': "metabolites-mappings",
                      'id_type': 'KEGG'},
        "WIKI" : {'file': "WIKIPATHWAYS_human_multi_id_redundant.mmt",
                          'subfolder': "metabolites-mappings",
                          'id_type': 'moleculeIds'}}

We do not need to translate our dataset's HMDB, CoreMetabolome and LipidMaps molecules identifiers, because our provided "WIKI" reference file (.mmt) comprises all these types of identifiers. Simply, a disambiguation step will be applied and is included in the following snippet:

# Create thsis time a copy to be used with Wikipathways only
annots_copy = annots_obj.model_copy()
# then do the verification and cleaning-up: 
annots_copy.usable_id = "moleculeIds"
annots_copy.verify()    # pay attention to this (required)
annots_copy.keep_best_mz_id_pairs(adata_mz.var.copy())
annots_copy.remove_redundant_aliases()    # disambiguation
annots_copy.df.head()

As you observed, the majority of the code lines are the same as seen in the previous section, being the exception the use of .verify() for the annotations object when preparing it for Wikipathways mapping. Also, to avoid confusion with the previous section, the names of the objects are modified in this section.

Now load the pathways object:

sets_WIKI =   spd.MetabolicPathways(
    data_dir=data_centralized_folder,
    subfolder=pathways_files_location_info['WIKI']['subfolder'],
    file=pathways_files_location_info['WIKI']['file'])

sets_WIKI.molecule_id_type = "moleculeIds"  # pay attention to this
sets_WIKI.load()
sets_WIKI.piled.head(3)   # have a glance on the loaded pathways

Finally, run the per-spot scoring of the spatial data using Wikipathways

sets_WIKI,annots_copy.df = spm.SyncPathwaysAndAnnots.run(
            sets_WIKI.model_copy(),
            annots_copy.df,
            usable_id=pathways_files_location_info['WIKI']['id_type'],
            min_set_size=2)

# metabolites weights matrix :
wiki_suitable_metabolites_computed_df, coords = spm.ComputeAssignmentsWeights.run(
            adata_mz, annots_copy.df,
            usable_id=pathways_files_location_info['WIKI']['id_type'])

# scores computation: configure and run
config_run_scores_wiki = spm.ComputePathwaysScoresConfig(
    type_abbr="WIKI", min_entity=2)

wiki_scores_df = spm.ComputePathwaysScores.run(
    sets_WIKI.to_dict(),
    wiki_suitable_metabolites_computed_df,
    config=config_run_scores_wiki
)

Special case 2: expanding the functional coverage with chemical families

It has been reported that the pathways coverage is low. Our library can help to extend functional annotation of spatial metabolomics/lipidomics data through chemical families.

For demonstration purposes, we will pick here the first 50 $m/z$'s ranked by their Moran's I values. For a given $m/z$, the closer the I value to 1.0, the more the spatial distribution is clustered in the space.

from SpacePath.core.processing.measures_methods import compute_moran_i

adata_mz = compute_moran_i(adata_mz, n_perms=50)
top_chosen_mz = adata_mz.var.sort_values(by='I', ascending=False).head(50)['mz'].astype(str).tolist()
adata_part = adata_mz[:, top_chosen_mz]

annots_tmp = annots_copy.model_copy()    # molecules IDs in same format as used for 'WIKI' mapping
annots_tmp, adata_part = measures_methods.match_adata_mz_and_annots(annots_tmp, adata_part)
annots_tmp.df.head(1)

Compute first the families; they are automatically saved as a .mmt file per dataset (Click to show)

mol_similarities_result = spm.ComputeMoleculesSimilarityMatrix.run(
        molecules_ids_list=annots_tmp.df['moleculeIds'].unique().tolist())
updated_config = spm.ComputeMoleculesFamiliesConfig(
    cutoff_tree=0.6)
computed_fam_results = spm.ComputeMoleculesFamilies.run(
    mol_similarities_result,
    annots_tmp.df,
    SAMPLE,
    subfolder,
    data_centralized_folder,
    plot_folder,
    config=updated_config)

Load the families in a similar way as pathways are loaded (Click to show)

families_obj = spd.MetabolicPathways(
        data_dir=data_centralized_folder,
        subfolder=subfolder,
        file=f"{SAMPLE}-molecules_families.mmt",
        molecule_id_type = "moleculeIds"
)
families_obj.load()
families_obj, annots_copy.df = spm.SyncPathwaysAndAnnots.run(
    families_obj.model_copy(),
    annots_copy.df,
    usable_id='moleculeIds',
    min_set_size=2)

Finally configure and run families scores per-spot (Click to show)

fam_suit_metabolites_computed_df, coords = spm.ComputeAssignmentsWeights.run(
    adata_part, annots_copy.df, usable_id='moleculeIds')

updated_config = spm.ComputePathwaysScoresConfig(type_abbr="FAMILIES",
                                                min_entity=2)
families_scores_df = spm.ComputePathwaysScores.run(
    families_obj.to_dict(),
    fam_suit_metabolites_computed_df, config=updated_config
)

Clone this wiki locally