Overview

This project is based on the version python pygoslin of the tool Goslin « Grammar on succinct lipid nomenclature » developped by Dominik Kopczynsk and Nils Hoffmann. This API-REST was developped 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, create a Python virtual environment with the following command by specifying a name for your environment :

$ python3 -m venv <name>

Then, move into the newly created repository containing your virtual environment and activate it :

$ cd <name>
$ source bin/activate

Clone the git repository :

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

Move into the repository and install the required dependencies for the application :

  • Installation for pygoslin :

    • pygoslin can be installed in two different ways :

      • Via the pip command :

      $ pip install pygoslin

      • Via the setup.py file :

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

        $ cd goslin
$ 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 shoud 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.

  • Installation of other dependencies :

    • This REST-API requires other dependencies to work correctly. They can be installed with the following command from the root of the goslin repository:

    $ cd path/to/goslin
$ pip install -r requirements.txt

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