SmartPeak

SmartPeak is an application that encapsulates advanced algorithms to enable fast, accurate, and automated processing of CE-, GC- and LC-MS(/MS) data, and HPLC data for targeted and semi-targeted metabolomics, lipidomics, and fluxomics experiments. The software is based on the OpenMS toolkit.

SmartPeak provides graphical- and/or command-line-based user input validation, workflow configuration, data visualization and review, logging, and reporting. SmartPeak can be run on multiple operating systems or run on cloud infrastructures. The workflow automates all steps from peak detection and integration over calibration curve optimization, to quality control reporting.

Building from source

Windows

STEP 1: Build OpenMS dependencies

Build OpenMS-contrib by following the OpenMS wiki instructions

Download and install the pre-compiled Boost library binaries for windows (i.e. SourceForge) and

• The minimum required Boost version is 1.71.0
• Ensure that these binaries are used both for OpenMS and SmartPeak
• The only boost package required by SmartPeak is Unit Test for unit testing, however, the same version of boost must be used when compiling both OpenMS and SmartPeak

Download and install QT5 using the offline installer for windows

• NOTE: only install the 5.12.1 for the relevant version of visual studios
• Add the "lib" folder in the newly created qt5 directory to the system path variable so that the .dll's will be found during run-time
• or add e.g. PATH=%PATH%;C:/qt/Qt5.12.1b/5.12.1/msvc2017_64/lib;C:/local/boost_1_73_0/lib64-msvc-14.2 to the environment

STEP 2: Build OpenMS

Build OpenMS following the OpenMS wiki instructions. Example cmake command on windows

cmake -DBoost_NO_SYSTEM_PATHS=ON -BOOST_INCLUDEDIR="C:/local/boost_1_73_0" -DBOOST_ROOT="C:/local/boost_1_73_0" ^
-DBOOST_LIBRARYDIR="C:/local/boost_1_73_0/lib64-msvc-14.2" -DBOOST_USE_STATIC=OFF -DWITH_GUI=OFF -DPYOPENMS=OFF ^
-DOPENMS_CONTRIB_LIBS="[OpenMS directory]/contrib/build" -DCMAKE_PREFIX_PATH="C:/qt/Qt5.12.1b/5.12.1/msvc2017_64/lib/cmake" ^
-G "Visual Studio 16 2019" -A x64 ..

• Open "OpenMS_host" in visual studios and build only the solution for "OpenSwathAlgo" and then for "OpenMS" IN THAT ORDER
• Add the "lib" folder in the openms-build directory to the system path variable so that the .dll's will be found during run-time
• or extend your current path with the following command in powershell as an elevated user:

setx path "%PATH%;[OpenMS directory]\openms-build\lib\debug;C:\qt\Qt5.12.1b\5.12.1\msvc2017_64\lib"
setx path "%PATH%;C:\local\boost_1_73_0\lib64-msvc-14.2;[SDL directory]\lib\x64"

STEP 3: Build SmartPeak dependencies

Download the latest SDL2 libraries. Add the SDL2 folder to the path environmental variable. Compile using cmake and build for "external projects" Example cmake command to download all external projects assuming that you are in the location [home directory]/smartPeak2/build_external cmake -G "Visual Studio 16 2019" -A x64 -T host=x64 -DUSE_SUPERBUILD=ON .. However, many of the requirements overlap with OpenMS so for practical purposes the only libraries that will need to be download are "ImGui", "ImPlot", and "Plog"

STEP 4: Build SmartPeak

Compile using cmake. Example cmake command on windows assuming that all external dependency libraries are in the path [home directory]/smartPeak/build_external

cmake -DEIGEN_USE_GPU=OFF -DBoost_NO_SYSTEM_PATHS=ON -BOOST_INCLUDEDIR="C:/local/boost_1_73_0/boost" -DBOOST_ROOT="C:/local/boost_1_73_0" ^
-DBOOST_LIBRARYDIR="C:/local/boost_1_73_0/lib64-msvc-14.2" -DBOOST_USE_STATIC=OFF -G "Visual Studio 16 2019" -A x64 -T host=x64 -DUSE_SUPERBUILD=OFF ^
-DEIGEN3_INCLUDE_DIR=[home directory]/smartPeak2/build_external/Dependencies/Source/eigen ^
-DPLOG_INCLUDE_DIR=[home directory]/smartPeak2/build_external/Dependencies/Source/plog/include ^
-DIMGUI_DIR=[home directory]/smartPeak2/build_external/Dependencies/Source/imgui ^
-DIMPLOT_DIR=[home directory]/smartPeak2/build_external/Dependencies/Source/implot ^
-DCMAKE_PREFIX_PATH="[OpenMS directory]/openms-build";"C:/qt/Qt5.12.1b/5.12.1/msvc2017_64/lib/cmake";"[SDL directory]/SDL"; ..

Open "SmartPeak_host" in visual studios and build the project of choice. Projects can be built using Visual Studios in the IDE by opening msbuild [build_dir]/src/SmartPeak_host and selecting the specific target to build in the SmartPeakGUI or on the command line by running e.g., msbuild [build_dir]/src/smartpeak/SmartPeak.sln /verbosity:normal /maxcpucount which will build the main SmartPeak library and then running e.g., msbuild [build_dir]/examples/SmartPeak_class_examples_smartpeak.sln -target:SmartPeakGUI /verbosity:normal /maxcpucount which will build the SmartPeak GUI.

STEP 5: Build SmartPeak-Docs

Generating the docs for SmartPeak on windows platforms is done by calling the docs build target.

In ordert to build the docs locally the following dependencies are needed:

• Doxygen : Download and install
• Sphinx : pip install --user sphinx
• Breathe : pip install --user breathe
• Exhale : pip install --user exhale

Note

Sphinx needs to be present in PATH so that the sphinx-executable can be found by CMake i.e. C:\Users\$USER\AppData\Roaming\Python\Python37\Scripts

Linux

In the below instructions it is assumed OpenMS code resides in ~/OpenMS and SmartPeak code is in ~/SmartPeak.

STEP 1: Build OpenMS dependencies

Build OpenMS-contrib by following the OpenMS wiki instructions.

Starting from Ubuntu 18.04, it's not necessary to manually build OpenMS' contrib. The packages available in the repositories are recent enough.

STEP 2: Build OpenMS

Build OpenMS following the OpenMS wiki instructions. Example workflow:

cd ~
mkdir OpenMS-build
cd OpenMS-build
cmake -DBOOST_USE_STATIC=OFF -DHAS_XSERVER=OFF -DWITH_GUI=OFF -DENABLE_TUTORIALS=OFF -DENABLE_DOCS=OFF -DGIT_TRACKING=OFF -DENABLE_UPDATE_CHECK=OFF -DCMAKE_BUILD_TYPE=Debug -DPYOPENMS=OFF -DOPENMS_COVERAGE=OFF ~/OpenMS
make -j4 OpenMS

STEP 3: Building SmartPeak

SuperBuild helps downloading the dependencies for SmartPeak.

cd ~
mkdir SmartPeak_superbuild SmartPeak_build
cd SmartPeak_superbuild
cmake -DUSE_SUPERBUILD=ON -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug ~/SmartPeak
make -j4
cd ~/SmartPeak_build
cmake -DEIGEN_USE_GPU=OFF -DUSE_SUPERBUILD=OFF -DBOOST_USE_STATIC=OFF -G "Unix Makefiles" -DCMAKE_PREFIX_PATH=$HOME/OpenMS-build/ -DPLOG_INCLUDE_DIR=$HOME/SmartPeak_superbuild/Dependencies/Source/plog/include -DIMGUI_DIR=$HOME/SmartPeak_superbuild/Dependencies/Source/imgui -DIMPLOT_DIR=$HOME/SmartPeak_superbuild/Dependencies/Source/implot -DCMAKE_BUILD_TYPE=Debug ~/SmartPeak
make -j4

Some dependencies one might have to install:

sudo apt install qt5-default libeigen3-dev libxerces-c-dev coinor-libcbc-dev libsvm-dev libboost-all-dev libwildmagic-dev libsqlite3-dev libglpk-dev seqan-dev libhdf5-dev python3-pip

STEP 4: Build SmartPeak-Docs

Generating the docs for SmartPeak on Linux is done by calling the make -B docs build target.

In ordert to build the docs locally the following dependencies are needed:

• Doxygen : sudo apt-get install -y graphviz doxygen doxygen-doc
• Sphinx : pip install --user sphinx
• Breathe : pip install --user breathe
• Exhale : pip install --user exhale

macOS

Building SmartPeak and all its dependencies is as easy as on Linux. Assuming the source code for OpenMS and SmartPeak reside in the home directory i.e. ~/OpenMS ~/SmartPeak, the following steps can be taken verbatim:

STEP 1: Installing external libraries

brew is the tool of choice to get all the necessary libraries installed with ease, if it's not present on your machines, you can install it using the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

brew install cmake qt5 sdl2 boost glpk eigen sqlite hdf5 libsvm xerces-c
brew install coin-or-tools/coinor/cbc coin-or-tools/coinor/cgl coin-or-tools/coinor/clp coin-or-tools/coinor/coin_data_netlib
brew install coin-or-tools/coinor/coin_data_sample coin-or-tools/coinor/coinutils coin-or-tools/coinor/osi

STEP 2: Build OpenMS

OpemMS libs can be built wihtout GUI capabilities using the following set of commands:

cd ~
git clone --branch develop --depth 1 https://github.com/OpenMS/OpenMS.git
cd OpenMS && git submodule update --init contrib && mkdir contrib_build && cd contrib_build
cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang -DBUILD_TYPE=ALL ../contrib
cd ~/OpenMS &&  mkdir openms_debug_build && cd openms_debug_build
cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_STANDARD=17 \
-DCMAKE_CXX_EXTENSIONS=OFF -DCMAKE_PREFIX_PATH="$(brew --prefix qt5);$(brew --prefix boost);$(brew --prefix)" \
-DBOOST_USE_STATIC=OFF -DOPENMS_CONTRIB_LIBS=~/OpenMS/contrib_build/ \
-DSEQAN_INCLUDE_DIRS=~/OpenMS/contrib_build/include/seqan -DCOIN_INCLUDE_DIR=../contrib_build/include/ \
-DWM5_INCLUDE_DIR=../contrib_build/include/WildMagic/ -DWM5_Wm5Core_LIBRARY=../contrib_build/lib/libWm5Core.a \
-DWM5_Wm5Mathematics_LIBRARY=../contrib_build/lib/libWm5Mathematics.a -DHAS_XSERVER=OFF -DWITH_GUI=OFF \
-DENABLE_TUTORIALS=OFF -DENABLE_DOCS=OFF -DGIT_TRACKING=OFF -DENABLE_UPDATE_CHECK=OFF -DCMAKE_BUILD_TYPE=Debug \
-DPYOPENMS=OFF -DOPENMS_COVERAGE=OFF ..
make -j4 OpenMS

The contrib libraries are also offered by the OpenMS Team precompiled for the recent versions of clang and can be installed as follows, make sure to nagivate and fetch the contrib builds based on your macOS and Xcode versions:

cd OpenMS && mkdir contrib_build && cd contrib_build
curl -O https://abibuilder.informatik.uni-tuebingen.de/archive/openms/contrib/macOS/10.15.4/x64/appleclang-11.0.0/contrib_build.tar.gz
tar -xzf contrib_build.tar.gz
rm lib/libboost_* && rm -r include/boost && rm -r lib/cmake/Boost* && rm -r lib/cmake/boost*

STEP 3: Building SmartPeak

Building SmartPeak is done in 2 steps:

• Fetching required libraries for SmartPeak (SuperBuild)
• Building SmartPeak library, examples and SmartPeak GUI

This can be done using the following set of commands:

cd ~/SmartPeak && mkdir smartpeak2_debug_superbuild smartpeak2_debug_build
cd smartpeak2_debug_superbuild
cmake -DUSE_SUPERBUILD=ON -DCMAKE_BUILD_TYPE=Debug .. && make -j4

cd ../smartpeak2_debug_build
cmake -DEIGEN_USE_GPU=OFF -DUSE_SUPERBUILD=OFF -DBOOST_USE_STATIC=OFF \
-DCMAKE_PREFIX_PATH="~/OpenMS/openms_debug_build/;$(brew --prefix qt5);$(brew --prefix boost)" \
-DPLOG_INCLUDE_DIR=~/SmartPeak2/smartpeak2_debug_superbuild/Dependencies/Source/plog/include \
-DIMGUI_DIR=~/SmartPeak2/smartpeak2_debug_superbuild/Dependencies/Source/imgui \
-DIMPLOT_DIR=~/SmartPeak2/smartpeak2_debug_superbuild/Dependencies/Source/implot \
-DCMAKE_BUILD_TYPE=Debug ~/SmartPeak2
make -j4

STEP 4: Build SmartPeak-Docs

Generating the docs for SmartPeak on macOS is done by calling the make -B docs build target.

In ordert to build the docs locally the following dependencies are needed:

• Doxygen : brew install doxygen
• Sphinx : pip install --user sphinx
• Breathe : pip install --user breathe
• Exhale : pip install --user exhale

Running the tests

The tests are run with ctest command.

ctest

In order to run a specific test, use -R option and the test class name (without .cpp extension)

ctest -R Utilities_test

Running the examples

The collection of examples is located at src/example/data directory of the SmartPeak source code. The directory contains examples of different kinds of data in .mzML format and their corresponding configuration files.

Log path

Default locations of logs:

• Windows: C:\\Users\\<user>\\AppData\\Local\\SmartPeak
• Linux and MacOS: ~/.SmartPeak

User can change default location and specify directory where the logs are stored by setting SMARTPEAK_LOGS env variable. If directory specified by the path doesn't exist, SmartPeak will create it.

Using SmartPeak GUI

• After successful installation of SmartPeak, on Windows open menu start and browse for relevant icon, you can also find the shortcut on desktop.
• If built SmartPeak from the source code, from the build directory run ./bin/SmartPeakGUI for Mac and Linux, or ./bin/[Debug or Release]/SmartPeakGUI for Windows. Or double-click SmartPeakGUI executable in the file browser of your OS.
• Start the session with File | Load session from sequence
• Choose the corresponding directory with Change dir. The path to example folder can be shortened to f.e. /data/GCMS_SIM_Unknowns
• Select the sequence file

• The integrity of the loaded data can be checked with Actions | Integrity checks. The results of the integrity checks can be viewed with View | Info.
• Edit the workflow with Edit | Workflow. You have an option to cherry pick the custom workflow or to choose the predefined set of operations. For example, the workflow steps for GC-MS SIM Unknowns are the following:

• View and verify the workflow steps and input files with View | [table].

• The explorer panes can be used to filter the table views with View | Injections or Transitions. Click on the checkbox under plot or table to include or exclude the injection or tansition from the view.

• Changes to any of the input files can be made by reloading a modified .csv version of the file with File | Import File.
• Run the workflow with Actions | Run workflow. Verify or change the data input/output directories before running the workflow.

• The status of the workflow can be monitored with View | info. An estimated time is available. This value is only a rough estimation. It will be updated regaluary while the workflow is running. The progress bar however shows workflow steps completed. As some steps can be longer to execute, it may not reflect remaining time. More details are available about the items that are currently running.

• Alternatively, a more detailed status can be obtained with View | log which will display the most recent SmartPeak log information.

• After the workflow has finished, the results can be viewed in a tabular form as a large data table with View | features (table). The feature metavalues shown can be added or removed with View | Features and clicking on the checkboxes under plot or table. For performance reasons, the amount of data that one can view is limited to 5000 entries.
• The results can be viewed in a graphical form as a line plot or as a heatmap with View | features (line).

or View | features (heatmap)

• The underlying data can also be displayed as a table matrix with View | features (matrix). Samples, transitions, or feature metavalues can be included or excluded from any of the views using the explorer panes.

• The results of calibration curve fitting can be inspected with View | Workflow settings | Quant Methods.

• A detailed look at the calibration fitted model and selected points for the model can be seen with View | Calibrators.

• For debugging problematic peaks, the raw chromatographic data and the picked and selected peaks can be viewed graphically with View | Chromatograms. For performance reasons, the amount of data that one can view is limited to 9000 points.

• Export the results with Actions | Report. There is an option to choose the set of variables of interest

• The results will be exported to PivotTable.csv in the same folder

The above applies for Mac and Linux.