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 REST API was developed in order to be use in a microservice architecture.

It’s a tool which translate a lipid name 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 REST API 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.

Once all dependencies are installed, some code source must be generated with OpenAPI Generator CLI. It can be done using the following command :

$ openapi-generator-cli generate -i resources/metabocloud-goslin.yaml -g python-flask --additional-properties=packageName=generated_code --global-property models,supportingFiles="base_model.py:util.py:typing_utils.py:"

Note

This command enables to generates object models directly from the object describe in the OpenAPI specification.

You can now launch the application with the following command :

$ fastapi run src/main.py

Note

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

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

    For example :

    $ fastapi run src/main.py --port 8080

  • Set up the environment variable LOG_LEVEL to choose the log level you want for the application :

    For example :

    $ LOG_LEVEL=DEBUG fastapi run src/main.py

    Hint

    The environment variable 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 :

    $ LOG_LEVEL=DEBUG fastapi run src/main.py --port 8080

    The application will then be launched in DEBUG mode on the port 8080.

Important

This application has been developed to be run in different environments (local, dev, prod). By default, when it is launch locally, it uses the environment local.

However, you can choose which environment to use to launch the application using the APP_ENV environment variable with the following command :

$ APP_ENV=dev fastapi run src/main.py --port 8080

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

Then move into the repository and run the bash script build_docker_image.sh :

$ cd goslin-api
$ ./build_docker_image.sh

Note

This Bash script ensures that the source code to be produced with OpenAPI Generator has been generated. If not, it generates it before building the Docker image.

You can now launched the application from the Docker image :

$ docker run -p 8080:8080 goslin

Note

You can also parameter the port and the log level :

$ docker run -e LOG_LEVEL=DEBUG -p 8000:8080 goslin

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

Important

This application has been developed to be run in different environments (local, dev, prod). By default, when it is launch with Docker, it uses the environment made for the MetaboCloud production server (prod) from which the application is publicly available.

However, you can choose which environment to use to launch the application using the APP_ENV environment variable with the following command :

$ docker run -e APP_ENV=dev -p 8080:8080 goslin

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?lipid_names=Cholesterol

A query example with several lipids :

https://metabocloud.mesocentre.uca.fr/goslin/validate?lipid_names=Cholesterol&lipid_names=Cer 18:1;2/16:0

Caution

The lipid names put in the query parameters may need to 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, Code documentation) and some examples of use.

  • On the OpenAPI 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