Overview

This project is based on the version python pygoslin of the tool Goslin « Grammar on succinct lipid nomenclature » developed by Dominik Kopczynsk and Nils Hoffmann. This API-REST was developed in order to be use in a microservice architecture.

It’s a tool which translates lipid names into a standardized name according to the lipid shorthand nomenclature. It also generates related information such as :

  • The category and the class of the lipid

  • The nomenclature level of the standardized lipid name

  • The mass of the lipid

  • The sum formula of the lipid

This API-REST also stores in its memory a local database built from the LipidMaps Structure Database. From this local database, it retrieves, from the standardized name obtained with pygoslin, the LipidMaps ID and the InCHI-key corresponding. When it is filled in the database, it also retrieves the SwissLipids ID.

Installation

You can install this API by different ways.

Locally

You can install the API on your machine to use it locally.

First, clone the git repository and move into it :

$ git clone https://git.mesocentre.uca.fr/unh-metabocloud/goslin-api.git
$ cd goslin-api

Then, create a Python virtual environment and activate it with the following command :

$ python3 -m venv .venv
$ source .venv/bin/activate

Now, install the required dependencies for the application using the requirements.txt file :

$ pip install -r requirements.txt

Note

pygoslin is installed with the other needed dependencies in the requirements.txt file, but it can also be installed alone via the setup.py file :

  • First move into the goslin-api repository and download the .zip file from the pygoslin GitHub repository :

$ wget https://github.com/lifs-tools/pygoslin/archive/refs/heads/master.zip

  • Then extract it to the directory of your virtual environment :

$ unzip master.zip && rm master.zip

You should now have a pygoslin-master directory inside your virtual environment directory.

  • Install pygoslin with the setup.py file with the following command :

$ cd pygoslin-master
$ python3 setup.py install

pygoslin is now installed in your virtual environment. You can now delete the pygoslin-master directory if you want.

You can now launch the application with the following command :

$ python3 -m main.goslin_rest

Note

By default, the application is launched on port 8080 with the log level set to info. But you can configure both parameters.

  • Use the option -p to choose the port on which you want the application to listen :

    For example :

    $ python3 -m main.goslin_rest -p 8000

    OR

    $ python3 -m main.goslin_rest --port 8000

  • Use the option --log_level to choose the log level you want for the application :

    For example :

    $ python3 -m main.goslin_rest --log_level debug

    Hint

    The application can be launched with the info level, debug level or error level. The option does not take into account the case of the string. It will also work with a value such as DEBUG or Info.

  • You can of course use both options in the same time :

    $ python3 -m main.goslin_rest --log_level debug -p 8000

    The application will then be launched in debug mode on the port 8000.

With Docker

You can also launch the application by building a Docker image from the Dockerfile. This method enables to build a container with the application and all the required dependencies in a single command.

First, clone the git repository :

$ git clone https://git.mesocentre.uca.fr/unh-metabocloud/goslin-api.git

Move into the repository and build the docker image :

$ cd goslin
$ docker build -t goslin .

The option -t enables to tag the docker image. You can then for example also specify a version (e.g goslin:2.0.2).

Note

The . in this command indicates that the Dockerfile is present in the current repository (usually the root of the project). This command can therefore be executed without being in the application repository but in this case the . must be replace by the path to the Dockerfile.

You can now launched the application from the docker image :

$ docker run -p 8080:8080 goslin

This command runs the application using the default values for the --log_level and --port parameters but you can also configure them as seen above

$ docker run -p 8000:8000 goslin --log_level debug -p 8000

This command will launched the application on the port 8000 in debug mode.

Note

The two -p options are two different options. The first is an option of the docker run command connecting the container to the host while the second is an option of the Goslin API to choose which port the application should listen on.

Important

The ports specified for each -p option must match for the application to work.

Web usage

You can use this API locally as explained in the installation section above, but you can also use it directly from your browser from the MetaboCloud website.

A query example for one lipid :

https://metabocloud.mesocentre.uca.fr/goslin/validate?lipids_names=Cholesterol

A query example with several lipids :

https://metabocloud.mesocentre.uca.fr/goslin/validate?lipids_names=Cholesterol&lipids_names=Cer%2018%3A1%3B2%2F16%3A0

Caution

The lipid names put in the query parameters must be percent-encoded to avoid issues that can be caused by the special characters and spaces.

The lipid name Cer 18:1;2/16:0 thus becomes : Cer%2018%3A1%3B2%2F16%3A0

Documentation

You can find information on the use of this API :

  • Here on this documentation, for the technical information about the API (Installation, Functions, Variables) and some examples of use.

  • On the Swagger documentation for the different requests accepted by the application, their required parameters and their different possible responses along with examples.

References

  1. Goslin 2.0 implements the recent lipid shorthand nomenclature for MS-derived lipid structures. Dominik Kopczynski, Nils Hoffmann, Bing Peng, Gerhard Liebisch, Friedrich Spener, Robert Ahrends. Preprint 2021 https://doi.org/10.1021/acs.analchem.1c05430

  2. Goslin - A Grammar of Succinct Lipid Nomenclature. Dominik Kopczynski, Nils Hoffmann, Bing Peng, Robert Ahrends. Analytical Chemistry 2020 92 (16), 10957-10960 https://doi.org/10.1021/acs.analchem.0c01690