Skip to content

Latest commit

 

History

History
253 lines (166 loc) · 10.2 KB

LipidLynxX_UserGuide.md

File metadata and controls

253 lines (166 loc) · 10.2 KB
Raw

LipidLynx_icon_Logo LipidLynx_text_Logo

LipidLynxX User Guide

LipidLynxX_Start_Chromium

This user guide is designed for:

  • LipidLynxX version: v0.8.24
  • API version: 1.0

Table of Contents

  1. How to install
  2. Step by step tutorial

How to install LipidLynxX

Install from exe version for Windows 10

Please get the latest version from LipidLynxX repository on GitHub using the link below:

https://github.com/SysMedOs/LipidLynxX/releases

In each release, there is always an Assets section. Please download the Windows version in .zip format (usually around 350 MB).

Guide_install_01

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

You can double click on LipidLynxX.exe to start LipidLynxX

Guide_install_03

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

Now click on LipidLynxX.exe again and the following command prompt window will show up without any error message.

Guide_install_03

A web browser window will start automatically and load the LipidLynxX local web service at:

http://127.0.0.1:1399

Please make sure you have Chrome or Firefox installed.

LipidLynxX_Start_fox

If windows internet explorer or Microsoft Edge browser started by default, please start Chrome or Firefox manually and visit 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: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: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

Please make sure you have git installed.

You can use python 3.7.6 directly, using virtual environment is strongly recommenced. In this tutorial, conda from anaconda or miniconda is used. Please find the installation guide of conda for your system on the following link: https://docs.anaconda.com/anaconda/install/

Following commands can be used on platforms including Linux, macOS, and Windows 10. The screenshots are mainly taken on Ubuntu Linux 18.04 LTS with zsh, however, it may have different style of terminal window display on your system, but the commands and the main output should stay the same cross platforms.

After successful installation of git and conda, you can clone the LipidLynxX source code to your disk. e.g. on Ubuntu Linux 18.04 LTS with zsh:

git clone --depth=50 --branch=master https://github.com/SysMedOs/LipidLynxX.git LipidLynxX

Guide_install_source_01 Now you can create a virtual environment for LipidLynxX. For Windows users, please use the Anaconda Prompt instead of Commandline Pront or Power Shell here a virtual environment named envlynx is created. You might have to type y for enter to confirm the creation of this virtual environment.

conda create -n envlynx python=3.7

e.g. on Ubuntu Linux 18.04 LTS with zsh:

Guide_install_source_02

For Windows users:

Guide_install_source_02 Guide_install_source_02

You can then activate the virtual environment created above. Notice that the indicator of your python environment will be changed from anconda, base, or miniconda to the name of the virtual environment created above (envlynx). e.g. on Ubuntu Linux 18.04 LTS with zsh:

Guide_install_source_03

on Windows 10 using Anaconda Prompt

Guide_install_source_03

Now you can navigate to LipidLynxX source code folder and install required packages using file requirements.txt.

cd LipidLynxX
pip install -r requirements.txt

You might have to type y for enter to confirm the installation of a list of packages.

Guide_install_source_04

Wait until you see the notification message that a list of packages has been successfully installed.

Guide_install_source_05

Then you can start LipidLynxX using following command:

python LipidLynxX.py

Guide_install_source_06

After some debug information, you will see following information:

Guide_install_source_07

And a browser window will pop up with LipidLynxX interface using link:

http://127.0.0.1:1399

Guide_install_source_08

Step by step tutorial

LidpidLynxX currently have two major modules:

  • LipidLynxX Converter
    • Convert different annotations to uniform LipidLynxX ID
  • LipidLynxX Equalizer
    • Bring lipid identifiers to the same level of annotation and perform cross-level matching between different dataset

Test files:

  • Test input file: doc/sample_data/input
  • Test output example files: doc/sample_data/output

How to use LipidLynxX Converter

For Conversion, type/paste your lipid annotations or choose your .xlsx or .csv files. Press “convert abbreviations” or “convert table”, wait for results. You will see the output on the right-hand side or just download the table with converted IDs.

Convert by text input

  • Paste list of abbreviations in the text input field and press “convert abbreviations”.

    • You can find example input in file doc/sample_data/input/LipidLynxX_conveter_test.txt

    user_guide_converter_01

  • You will see the output on the right-hand side or just download the table with converted IDs.

    • You can find example output doc/sample_data/output/LipidLynxX-Converter_from_text.xlsx

    user_guide_converter_02

Convert by table input

  • Press "Choose file"

    user_guide_converter_03

  • Select the input file in .xlsx or .csv format and press “Convert table”

    • You can use example file doc/sample_data/input/LipidLynxX_test.xlsx

    user_guide_converter_04

  • You will see the output on the right-hand side or just download the table with converted IDs.

    • You can find example output doc/sample_data/output/LipidLynxX-Converter_from_table.xlsx

    user_guide_converter_05

How to use LipidLynxX Equalizer

To Equalize, select LipidLynxX Equalizer tab from Home page. Select the level of annotations to which you would like to cross-match your lipid annotations (you can select more than one). For details on annotation levels see the tables on the right hand-side. Choose you datafile and press “Equalize”. Download your results as .xlsx file.

Convert by table input

  • Press "Choose file" and select the input file in .xlsx or .csv format. Then select the level of annotations to which you would like to cross-match your lipid annotations (you can select more than one), in this case levels B0, D0 and D1 are chosen. Then you can press “Equalize” to start processing.
    • You can use example file doc/sample_data/input/LipidLynxX_test.xlsx user_guide_equalizer_01
  • You will see the output when the processing is finished and you can download the file in .xlsx format.
    • You can find example output doc/sample_data/output/LipidLynxX-Equalizer_from_table.xlsx user_guide_equalizer_02

How run LipidLynxX using Terminal commands

  • LipidLynxX Converter
python LynxConverter.py -i doc/sample_data/input/LipidLynxX_test.xlsx -o doc/sample_data/output/LipidLynxX_test_converter_out.xlsx
  • LipidLynxX Equalizer
python LynxEqualizer.py -l "B0,D0,D1" -i doc/sample_data/input/LipidLynxX_test.csv -o doc/sample_data/output/LipidLynxX_test_equalizer_out.xlsx

How run LipidLynxX using API

  • LipidLynxX Converter API Examples
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
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

Errors/bugs

In case you experienced any problems with running LipidLynxX, please report an issue in the issue tracker or contact us.