Merge branch 'develop'

.github/workflows/pythonapp.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-20.04, ubuntu-latest, macos-latest, windows-latest]
-        python-version: [3.7]
+        python-version: [3.8]
 
     name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
     steps:

.travis.yml

@@ -1,25 +1,19 @@
 language: python
+python: 3.8.5
 jobs:
   include:
-    - name: "Python 3.7 on Linux"
-      python: 3.7.7
+    - name: "Python 3.8 on Linux"
+      python: 3.8.5
       before_install:
         - pip3 install -r requirements.txt
-    - name: "Python 3.7 on macOS"
-      os: osx
-      osx_image: xcode11.2
-      language: shell
-      before_install:
-        - python -m pip install --upgrade pip
-        - pip3 install --user -r requirements.txt
-    - name: "Python 3.7 on Windows"
+    - name: "Python 3.8 on Windows"
       os: windows
       language: shell
       before_install:
-        - choco install python --version 3.7
+        - choco install python --version 3.8.5
         - python -m pip install --upgrade pip
         - pip3 install -r requirements.txt
-      env: PATH=/c/Python37:/c/Python37/Scripts:$PATH
+      env: PATH=/c/Python38:/c/Python38/Scripts:$PATH
 install:
   - pip3 install codecov==2.1.7 coverage==5.1 pytest==5.4.3 pytest-cov==2.10.0
 script:

LipidLynxX.py

@@ -16,15 +16,37 @@
 import webbrowser
 import uvicorn
 
-from lynx.app import app, app_url, app_port
+from lynx.app import app
+from lynx.daemon import daemon_lynx
+from lynx.utils.cfg_reader import app_prefix, app_cfg_info
+from lynx.utils.ports import check_port
 
 
-def start_lynx():
+def start_lynx(app_url: str, app_port: int):
+
     print("Start Browser: ")
-    webbrowser.open(f"http://{app_url}:{app_port}", new=1, autoraise=True)
-    print("Start LipidLynxX Server: ")
+    app_link = f"http://{app_url}:{app_port}{app_prefix}"
+    webbrowser.open(app_link, new=1, autoraise=True)  # launch default web browser
+    # Start message queue powered by ZeroMQ.
+    # check ports
+    checked_zmq_client_port = check_port(
+        int(app_cfg_info.get("zmq_client_port", 2409)), task_name="ZMQ client"
+    )
+    checked_zmq_worker_port = check_port(
+        int(app_cfg_info.get("zmq_worker_port", 2410)), task_name="ZMQ worker"
+    )
+    # run zmq daemon
+    daemon_lynx(checked_zmq_client_port, checked_zmq_worker_port)
+    print("Start LipidLynxX Application...")
     uvicorn.run(app, host=app_url, port=app_port)
 
 
 if __name__ == "__main__":
-    start_lynx()
+    # check port
+    checked_app_url = app_cfg_info.get("app_url", "127.0.0.1")
+    app_port = int(app_cfg_info.get("app_port", 1399))
+    checked_app_port = check_port(app_port, task_name="LipidLynxX main app")
+    if app_port != checked_app_port:
+        print(f"Port: [{app_port}] in config.ini is already in use.")
+        print(f"[INFO] LipidLynxX is now running on port [{checked_app_port}].")
+    start_lynx(checked_app_url, checked_app_port)

README.md

@@ -1,5 +1,4 @@
-![LipidLynx_icon_Logo](doc/images/LipidLynxX_icon_128.jpg) 
-![LipidLynx_text_Logo](lynx/static/images/LipidLynxX_logo_color.png)
+![LipidLynx_Logo](doc/images/LipidLynxX_Logo_merged.png) 
 
 ![Platforms](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-blue.svg?color=orange)
 ![total downloads](https://img.shields.io/github/downloads/SysMedOs/LipidLynxX/total.svg?color=green)
@@ -10,7 +9,7 @@
 The LipidLynxX project is aimed to provide a unified identifier for major lipids, especially oxidized lipids
 in the epilipidome.
 
-![LipidLynx_01_Home](doc/images/LipidLynxX_Start_Chromium.png)
+![LipidLynx_01_Home](doc/images/LipidLynxX_Start_Firefox.png)
 
 ## Main Modules
 
@@ -117,7 +116,7 @@ And wait a bit ☕ Binder and Jupyter Notebook will prepare LipidLynxX demo for
 ### Screenshots
 
 - **GUI**
-    ![LipidLynx_02_Converter](doc/images/LipidLynxX_01_Converter_text_output.png)
+    ![LipidLynx_01_Converter](doc/images/LipidLynxX_01_Converter_text_input.png)
 - **API**
     - LipidLynxX provides API documentation using both OpenAI (left) and ReDoc (right)
     ![LipidLynxX_API](doc/images/LipidLynxX_API.png)
@@ -188,7 +187,7 @@ And wait a bit ☕ Binder and Jupyter Notebook will prepare LipidLynxX demo for
 
   - Example
 
-    ![LipidLynx_01_Home](lynx/static/images/levels_mod_full.png)
+    ![LipidLynx_levels](lynx/static/images/levels_mod_full.png)
 
 - Currently supported modification controlled vocabularies
     ![LipidLynx_01_Home](doc/images/nomenclature_cv.png)

daemon_lynx.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2016-2020  SysMedOs_team @ AG Bioanalytik, University of Leipzig:
+#
+# LipidLynxX is using GPL V3 License
+#
+# Please cite our publication in an appropriate form.
+#   LipidLynxX preprint on bioRxiv.org
+#   Zhixu Ni, Maria Fedorova.
+#   "LipidLynxX: a data transfer hub to support integration of large scale lipidomics datasets"
+#   DOI: 10.1101/2020.04.09.033894
+#
+# For more info please contact:
+#     Developer Zhixu Ni [email protected]
+
+from lynx.daemon import daemon_lynx
+
+if __name__ == "__main__":
+    daemon_lynx()

doc/LipidLynxX_UserGuide.md

@@ -6,8 +6,8 @@
 ![LipidLynxX_Start_Chromium](images/LipidLynxX_Start_Chromium.png)
 ## This user guide is designed for:
 
--   LipidLynxX version: v0.4.12
--   API version: v0.1
+-   LipidLynxX version: v0.8.24
+-   API version: 1.0
 
 ## Table of Contents
 1. [How to install](#How_to_install_LipidLynxX)
@@ -32,29 +32,42 @@ In each release, there is always an `Assets` section. Please download the Window
 
 When the file is successfully downloaded, you can unzip it to any folder .e.g `D:/Apps/LipidLynxX`.
 Open the folder of LipidLynxX and you can find the `LipidLynxX.exe` by using `right click -> Group by -> Type`
+
 ![Guide_install_02](images/Guide_install_exe_02.png)
+
 You can double click on `LipidLynxX.exe` to start LipidLynxX
+
 ![Guide_install_03](images/Guide_install_exe_03.png)
+
 Your antivirus may block it first and shows a blue frame. 
 After virus checking finished, it may have some error message. Close all warnings and this command prompt window.
+
 ![Guide_install_03](images/Guide_install_exe_04.png)
+
 Now click on `LipidLynxX.exe` again and the following command prompt window will show up without any error message.
+
 ![Guide_install_03](images/Guide_install_exe_04.png)
+
 A web browser window will start automatically and load the LipidLynxX local web service at:
-[http://127.0.0.1:5000/lynx/](http://127.0.0.1:5000/lynx/)
+
+[http://127.0.0.1:1399](http://127.0.0.1:1399)
+
 Please make sure you have Chrome or Firefox installed.
-![LipidLynxX_Start_fox](images/LipidLynxX_Start_fox.png)
+
+![LipidLynxX_Start_fox](images/LipidLynxX_Start_Firefox.png)
+
 If windows internet explorer or Microsoft Edge browser started by default, 
-please start Chrome or Firefox manually and visit [http://127.0.0.1:5000/lynx/](http://127.0.0.1:5000/lynx/)
+please start Chrome or Firefox manually and visit [http://127.0.0.1:1399](http://127.0.0.1:1399)
+
 
 Now you have LipidLynxX installed successfully.
 
 Please leave the LipidLynxX command prompt window on during the run. 
 If you accidentally close the web page of LipidLynxX, you can always visit 
-[http://127.0.0.1:5000/lynx/](http://127.0.0.1:5000/lynx/) to get back to LipidLynxX.
+[http://127.0.0.1:1399](http://127.0.0.1:1399) to get back to LipidLynxX.
 
 If you want to quit LipidLynxX, just close the LipidLynxX command prompt window, 
-and then the LipidLynxX at [http://127.0.0.1:5000/lynx/](http://127.0.0.1:5000/lynx/) will be switched off.
+and then the LipidLynxX at [http://127.0.0.1:1399](http://127.0.0.1:1399) will be switched off.
 Please make sure you saved all your output files before closing the LipidLynxX command prompt window.
 
 ### Install from source code
@@ -128,7 +141,7 @@ After some debug information, you will see following information:
 
 And a browser window will pop up with LipidLynxX interface using link:
 
-[http://127.0.0.1:5000/lynx/](http://127.0.0.1:5000/lynx/)
+[http://127.0.0.1:1399](http://127.0.0.1:1399)
 
 ![Guide_install_source_08](images/LipidLynxX_Start_Chromium.png)
 
@@ -221,15 +234,15 @@ python LynxEqualizer.py -l "B0,D0,D1" -i doc/sample_data/input/LipidLynxX_test.c
 - **LipidLynxX Converter API Examples**
 
 ```bash
-curl http://127.0.0.1:5000/lynx/api/0.1/converter/str/ -d 'data="PLPC"' -X GET
-curl http://127.0.0.1:5000/lynx/api/0.1/converter/list/ -d 'data=["PAPE", "PE 36:4"]' -X GET
-curl http://127.0.0.1:5000/lynx/api/0.1/converter/dict/ -d 'data={"Sample1":["PAPC","PS 16:0/18:2(9Z,12Z)"],"SAMPLE2":["PC 16:0_20:4","PS 16:0_18:2"]}' -X GET
+curl http://127.0.0.1:1399api/0.1/converter/str/ -d 'data="PLPC"' -X GET
+curl http://127.0.0.1:1399api/0.1/converter/list/ -d 'data=["PAPE", "PE 36:4"]' -X GET
+curl http://127.0.0.1:1399api/0.1/converter/dict/ -d 'data={"Sample1":["PAPC","PS 16:0/18:2(9Z,12Z)"],"SAMPLE2":["PC 16:0_20:4","PS 16:0_18:2"]}' -X GET
 ```
 
 - **LipidLynxX Equalizer API Examples**
 
 ```bash
-curl http://127.0.0.1:5000/lynx/api/0.1/equalizer/ -d 'data={"Sample1":["PAPC","PS 16:0/18:2(9Z,12Z)", "DPPE"],"SAMPLE2":["PC 16:0_20:4","PS 16:0_18:2", "PG 18:0_18:3"]}&level=D0' -X GET
+curl http://127.0.0.1:1399api/0.1/equalizer/ -d 'data={"Sample1":["PAPC","PS 16:0/18:2(9Z,12Z)", "DPPE"],"SAMPLE2":["PC 16:0_20:4","PS 16:0_18:2", "PG 18:0_18:3"]}&level=D0' -X GET
 ```
 - **Screenshot**
 ![LipidLynxX_API](images/LipidLynxX_API.png)

doc/LipidLynxX_deploy_guide.md

@@ -0,0 +1,132 @@
+# Deploy LipidLynxX
+
+## Requirement
+
+LipidLynxX is based on FastAPI, thus tool chains using `nginx`, `supervisor`,`gunicorn`, and `uvicorn` is recommended.
+
++ **System installation**
+
+  + `sudo apt install nginx supervisor`
+
++ **Python installation**
+
+  + Install `anaconda`/`miniconda` and create a virtual enviroment e.g. `envlynx`
+
+    + `conda create -n envlynx python=3.7`
+
+    + `conda activate envlynx`
+
+    + `pip install -r requirement.txt`  # do this under LipidLynxX folder
+
+  + Install `gunicorn`, and `uvicorn`
+
+    + `pip install gunicorn uvicorn gevent`
+
+
+
+Restart linux server before going to following setps.
+
+
+
+## Setup nginx
+
+- Check if you have `nginx` installed and go to its config folder
+
+  - `cd /etc/nginx/conf.d`
+
+- Create a new config file named `lynx.conf`
+
+  - `sudo nano lynx.conf`
+
+- Edit following content accordingly especially content inside`{}` and save the file.
+
+  - ```json
+    server {
+        listen 80;
+        server_name {example.com};
+        access_log  /var/log/nginx/example.log;
+
+        location / {
+            proxy_pass http://127.0.0.1:8000;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        }
+    }
+
+    ```
+
+    - `http://127.0.0.1:8000` is default by `gunicorn`
+- Restart `nginx`
+  - `sudo service nginx restart`
+
+## Setup supervisor
+
++ Check if you have `supervisor` installed and go to its config folder
+
+  + `cd /etc/supervisor/conf.d`
+
++ Create a new config file named `lynx.conf`
+
+  + `sudo nano lynx.conf`
+
++ Edit following content accordingly especially content inside`{}` and save the file.
+
+  + ```ini
+    [program:daemon_lynx]
+    directory=/home/{USER_NAME}/{PATH_TO_LipidLynxX_FOLDER}
+    environment=PATH=/home/anaconda3/envs/envlynx38/bin  # or your env path
+    command=/home/{USER_NAME}/anaconda3/envs/envlynx38/bin/python daemon_lynx.py
+    autorestart=true
+    redirect_stderr=true
+    stdout_logfile=/home/{USER_NAME}/{PATH_TO_LipidLynxX_FOLDER}/daemon_lynx_stdout.log
+    stderr_logfile=/home/{USER_NAME}/{PATH_TO_LipidLynxX_FOLDER}/daemon_lynx_error.log
+
+    [program:lynx_app]
+    directory=/home/{USER_NAME}/{PATH_TO_LipidLynxX_FOLDER}
+    environment=PATH=/home/anaconda3/envs/envlynx38/bin  # or your env path
+    command=/home/{USER_NAME}/anaconda3/envs/envlynx38/bin/gunicorn lynx.app:app -w 4 -k uvicorn.workers.UvicornWorker
+    autorestart=true
+    redirect_stderr=true
+    stdout_logfile=/home/{USER_NAME}/{PATH_TO_LipidLynxX_FOLDER}/lynx_app_stdout.log
+    stderr_logfile=/home/{USER_NAME}/{PATH_TO_LipidLynxX_FOLDER}/lynx_app_error.log
+
+    [supervisord]
+    logfile=/home/{USER_NAME}/{PATH_TO_LipidLynxX_FOLDER}/supervisord.log
+    logfile_maxbytes=50MB
+
+    ```
+
+    + if you use miniconda, then replace anaconda3 by miniconda/miniconda3
+
+    + `-w 4` means set up 4 workers, you can adjust number of workers based on your server configuration. 
+
++ Refresh configs for `supervisor`
+
+  + `sudo supervisorctl reread`
+
++ Restart `supervisor`
+
+  + `sudo service supervisor restart`
+
+
+
+## Test LipidLynxX
+
+Now you can visit `127.0.0.1` on the PC/server running LipidLynxX and other PCs in the same local network can access LipidLynxX web GUI using the IP of LipidLynxX computer e.g. `192.168.100.101`
+
+
+
+## Update LipidLynxX
+
+After updating LipidLynxX, you have to restart the web service.
+
+You can reboot the server or run following two commands to restart `supervisor` and `nginx` service.
+
++ stop supervisor `sudo supervisorctl stop lynx_app lynx_daemon`
++ check supervisor status `sudo supervisorctl status`
++ kill rest of daemon `sudo pkill -f daemon_lynx`
++ start supervisor `sudo supervisorctl start lynx_app lynx_daemon`
++ check supervisor status `sudo supervisorctl status`
++ restart nginx `sudo service nginx restart`
+
+LipidLynxX should then run with the new version.

doc/sample_data/input/LipidLynxX_Linker_Template.csv

@@ -0,0 +1,4 @@
+Sample1,Reference1,Reference2
+PC(16:0_18:2),PLPC,PC O-16:0_18:2
+PE(16:0_20:4),PLPE,C18 Sphingomyelin
+PC(16:0_22:5),,Cer(d14:0/26:0)