Package: pymantra
Metabolomics-centred graph-based multi-omics integrationmantrais a conceptual approach to compute estimates for the change of
metabolic reaction activity between two groups of samples. It relies on linear
relationships between substrate and product metabolites of a reaction and how
the coefficients of these relationships change between conditions. In addition
to analyzing metabolomics data, mantra also provides a correlation-based
approach formulti-omics integration.As an approach to provide smaller, mechanistically interpretable results based
on both the reaction estimates (and multi-omics associations) and the metabolic
network structure, network enrichment on the basis of a simulated-annealing
assisted local search is used.Thepymantrapackage provides all functionalities for computing changes in
reaction activity, multi-omics associations and performing the network
enrichment as well as reporting and plotting their results. Additionally, it
contains utilities to perform metabolite ID mapping.flowchart LR


subgraph in[Required Input]
    met(Metabolome Data)
end

subgraph opt[Optional Multi-Omics Data]
    direction LR
    subgraph opti[Input]
        direction LR
        org(Organism/Microbiome Data)
        cat(Genome/Transcriptome Data)
    end
    subgraph optc[Associations]
        associ[compute_multiomics_associations]
    end
end

subgraph db["Databases (online and/or offline)"]
    neo4j[(neo4j Graph)]
    sql[(SQL ID maps)]
end

namemap[NameMapper<br><i>Metabolite ID Mapping</i>]
netgen[NetworkGenerator]
metnet(((Metabolic Network)))


estimates[Reaction Estimates]
lso[Local Search Enrichment]
res[Enrichment Results]
reac[ ]

sql -.-> namemap
met --> namemap --> netgen
neo4j -.-> netgen

opti --> netgen --> metnet

metnet & opti & estimates --> optc
metnet & met --- reac ----> estimates


estimates & optc --> lso --> res

style reac width:0px,height:0pxManuscriptIf you would like to learn more about the details of the methodology and see
some real-world results please check out ourmanuscript.Getting StartedTo get started we recommend going through somecode examplesprovided
in pymantra's documentation and the installation guide below.InstallationUsingpipThe recommended installation is viapip.
It has pre-compiled wheels available for all major operating systems.Generally using python version 3.10 or newer is recommended, but backwards
compatability is ensured down to 3.8.If you would like to run the experiments presented in the paper (code in
theexperiments folder), please use the second option to install
the additional dependencies and mind the different version requirements (seeREADME).Additionally, dependencies required for package development and generation of
sphinx documentation can be obtained.# install with package dependenciespipinstallpymantra# for including the dependencies to run the paper experimentspipinstallpymantra[experiments]# for including the development dependenciespipinstallpymantra[dev]# for including the documentation dependenciespipinstallpymantra[docs]Installation from sourceTo install from source first clone the github repository including submodulesgitclonehttps://github.com/lipitum/pymantra.git--recursiveAdditionally, you need to download required database files for name mapping
fromhereOn macOS and Linux we recommend to use the following from within the pymantra
directorypipinstallgdown
gdown--folderhttps://drive.google.com/drive/folders/1sWTHWRqzglWOjTMwNa_aqkKT__Y7Snmq?usp=sharing
mvpackage/chebi.dbpymantra/namemapping/ChEBI/
mvpackage/hmdb.dbpymantra/namemapping/HMDB/
mvpackage/mantra.dbpymantra/namemapping/mantra_db/
mvpackage/reactome.dbpymantra/namemapping/Reactome/
rm-rpackageOn Windows the syntax would change to (untested)pip install gdown
gdown --folder https://drive.google.com/drive/folders/1sWTHWRqzglWOjTMwNa_aqkKT__Y7Snmq?usp=sharing
move package\chebi.db pymantra\namemapping\ChEBI\
move package\hmdb.db pymantra\namemapping\HMDB\
move package\mantra.db pymantra\namemapping\mantra_db\
move package\reactome.db pymantra\namemapping\Reactome\
rmdir /s /q packageMake sure you have a C++ compiler installed (recommended are gcc for
Linux and OS X and Visual C++ for Windows). Please make sure the
compiler matches the one, with which your python distribution was installed.The only c++ dependency for compilation is
theboost library.
In case it is already installed on your system (with version >= 1.77) you can
also drop the--recursiveflag in thegit clonecall. In addition to
installing boost from source you can also useconda.In addition to boost, we use OpenMP for parallel processing. It is usually
installed with your compiler, although macOS users might have to run additional
installation steps. Windows has currently no support for new OpenMP standards.
If it is not possible to compile with OpenMP, parallelized options will be
unavailable in the python package, but all other functionalities are not
affected.On macOS installation can be done on different ways, e.g. through MacPorts or
homebrew (recommended -brew install libomp).Once the c++ dependencies are installed, the package installation can be
invoked by callingpip installpipinstall.To verify installation run the unit testspython-mpytestSimilar to the regularpipinstallation you can also install the optional
dependencies.DatabasePer default the setup script installs all code, butnotthe neo4j database.
Instead, an online version of the database will be used. Since this is slower
than having a local database, we provide two options to run the neo4j database
locally.DockerWe provide a docker script to run the neo4j database on your computer in aseparate repository.
Please follow the instructions there to run the container.When calling theNetworkGeneratormake sure your provide the correct URI
and the user and password given in your .env file int pymantra-db-api folder.
If you use the default setting this leads toAPINetworkGenerator("127.0.0.1:8084")In this case onlyAPINetworkGenerator.get_subgraphandAPINetworkGenerator.as_networkxare available instead of the wholeNewtorkGeneratorfunction repertoire. Yet, for most use cases these functions
are all you need.Manual InstallationIf you want to generate the networks outside docker, you will  have to install
neo4j on your systems (community version is sufficient).
For instructions see theinstallation page.Having installed neo4j, download the mantra database dump fromhereand move theTheNetworkGeneratorcan now be initialized withNetworkGenerator("bolt://127.0.0.1:7687",("<user>","<password>"))Manuscript ExperimentsAll code used to generate the results presented in ourmanuscriptis located in theexamplesfolder. Please mind the higher version
requirements indicated in theREADMEwhen reproducing
the experiments.CitationIf you usepymantrafor your own work, please cite our manuscript@article{koehler2023,title={Identification and Integration of Key-Metabolic Reactions from Untargeted Metabolomics Data},author={K\"ohler, Nikolai and W\"urf, Vivian and Rose, Tim D and Pauling, Josch K},journal={bioRxiv},year={2023},publisher={Cold Spring Harbor Laboratory},doi={https://doi.org/10.1101/2023.05.15.540613}}