search

ElucidataInc / ElMaven

LC-MS data processing tool for large-scale metabolomics experiments.
https://resources.elucidata.io/elmaven/
GNU General Public License v2.0
88 stars 52 forks source link
c-plus-plus lc-ms lc-msms mass-spectrometry metabolomics qt

readme

El-MAVEN

An intuitive, open-source LC-MS data processing tool

from

Build Status Build status codecov DOI

Index

Features

Maven and El-MAVEN share following features:

El-MAVEN is robust, faster and with more user friendly features compared to Maven, and includes the following additional capabilities:

Download

El-MAVEN installers are available for Windows (7 and above) and Mac OS (10.12 and above). Users can download the latest release for these platforms from the official website.

Build from source

Contributers and developers can build El-MAVEN on Windows, Ubuntu or Mac OS by following the following instructions.

Setting up a development environment (64 bit platforms only)

Each of the three operating systems need to be set-up differently to be able to compile El-MAVEN from its source. Please follow instructions according to your platform.

Windows

We use MSYS2 (and mingw64) envoronment for developing El-MAVEN on Windows.

Note: To verify whether the above installation steps completed successfully make sure you have "libeay32.dll" and "ssleay32.dll" in path C:\msys64\mingw64\bin\. You might see a shortcut for the MSYS2 shell on your Desktop or Start menu, unless you chose to not add them during installation.

After completing the above steps, the following commands needs to be executed from the MSYS2 shell. This updates and installs required dependencies to compile El-MAVEN:

pacman --force -Sy
pacman --force -Syu
pacman --force -Su
pacman --force -Sy base-devel msys2-devel mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt5 mingw64/mingw-w64-x86_64-hdf5 mingw64/mingw-w64-x86_64-netcdf mingw64/mingw-w64-x86_64-boost msys/git mingw-w64-x86_64-curl

It can be helpful if the $PATH variable is changed permanently to point to our newly installed packages. To do this, you will have to make changes in your .bashrc file for MSYS2, which can be done manually or via shell's command line.

Manually editing .bashrc:

Editing .bashrc via the MSYS2 command line:

echo export PATH=/c/msys64/usr/bin/:/c/msys64/mingw64/bin/:$PATH > ~/.bashrc
source ~/.bashrc

Ubuntu

The following commands can be executed to update packages, repositories and package lists as well as install dependencies required for all versions of Ubuntu:

sudo apt-get update
sudo apt-get install g++
sudo apt-get install libsqlite3-dev libboost-all-dev lcov libnetcdf-dev

Please note that, we do not intend to support El-MAVEN on Ubuntu 16.xx or below anymore. You may or may not be able to compile it successfull if you are running one of these older Ubuntu systems.

We can now finally install Qt framework, along with related libraries and plugins:

sudo apt-get install qt5-qmake qtbase5-dev qtscript5-dev qtdeclarative5-dev libqt5multimedia5
sudo apt-get install libqt5multimedia5-plugins qtmultimedia5-dev libqt5webkit5-dev

Mac OS

Development on Mac OS requires the installation of Xcode (and the host of tools that it brings). Please install Xcode from the "App Store" before proceeding.

Once Xcode has been installed, use "Terminal" to perform a necessary action and install xcode-select:

sudo xcodebuild -license accept
xcode-select --install

Next, install Homebrew and using brew, install dependencies of El-MAVEN.

usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew install boost
brew install qt
brew install llvm@6
brew install netcdf

Find out the path where LLVM and Qt have been installed by brew. Typically this is usually /usr/local/opt/llvm@6 and /usr/local/opt/qt, respectively.

Configure the $PATH variable to allow your build system to find these installed packages and binaries in all future sessions (replace LLVM_DIR and QT_DIR with the appropriate paths found in the last step):

cd ~
touch .bash_profile
echo "export PATH=/QT_DIR/bin:/LLVM_DIR/bin/:$PATH" >> .bash_profile
echo "export LDFLAGS="-L/QT_DIR/lib -L/LLVM_DIR/lib -Wl,-rpath,/LLVM_DIR/lib" >> .bash_profile
echo "export CPPFLAGS+="-I/QT_DIR/include -I/LLVM_DIR/include  -I/LLVM_DIR/c++/v1/" >> .bash_profile
source .bash_profile

Additionally, for MacOS, if building in release mode, sentry-native (Crashpad backend) should be compiled and available through the build environment. In a separate location, download the latest release, unzip and compile:

curl -O -J -L https://github.com/getsentry/sentry-native/releases/download/0.1.2/sentry-native-0.1.2.zip
unzip sentry-native-0.1.2.zip &> /dev/null
cd sentry-native/gen_macosx
make config=release sentry_crashpad
echo "export SENTRY_MACOSX_BIN='$PWD/bin/Release'" >> ~/.bash_profile
cd -

Once this has been done the path to sentry-native binaries and libraries should be exported in the user's enviroment:

echo "export PATH='$SENTRY_MACOSX_BIN:$PATH'" >> ~/.bash_profile
echo "export LDFLAGS='$LDFLAGS -L/$SENTRY_MACOSX_BIN'" >> ~/.bash_profile
source ~/.bash_profile

While the above set-up will allow compilation and linking in release mode without any errors, the crash reporting itself will not be functional until a unique Sentry DSN value is exported and available as a base64-encoded string before platform config (qmake) step.

export SENTRY_DSN=<YOUR_SECRECT_SENTRY_DSN>
export SENTRY_DSN_BASE64=`echo $SENTRY_DSN | base64`

Getting the source code

Switch to a directory to where you want the code and then clone this repo (including submodules) using:

cd <path/to/work/>
git clone --recursive https://github.com/ElucidataInc/ElMaven.git

Build

Before building, make sure the environment has ben setup correctly and make sure that the correct versions of libraries have been installed by issuing the following commands:

For building the application and peakdetector CLI in release mode (without any tests) execute the following commands:

cd ElMaven
qmake CONFIG+=release NOTESTS=yes build.pro
make -j4

If, following earlier steps, El-MAVEN was linked to sentry-native on MacOS, then two additional commands need to be run for crash reporter to work correctly (this assumes that the $SENTRY_MACOSX_BIN env var is defined already):

install_name_tool -change @rpath/libsentry_crashpad.dylib $SENTRY_MACOSX_BIN/libsentry_crashpad.dylib bin/El-MAVEN.app/Contents/MacOS/El-MAVEN
cp $SENTRY_MACOSX_BIN/crashpad_handler bin/El-MAVEN.app/Contents/MacOS/

For compiling El-MAVEN in debug mode (along with tests), execute these commands instead:

cd ElMaven
qmake CONFIG+=debug build.pro
make -j4

To run the GUI application run one of the following, according to your OS:

To run the peakdetector CLI application run (example shows -h for help on available arguments):

To help with this process, we provide the build script named ./run.sh, available in in root source directory. It will ask whether you want to build in release or debug mode when executed. If you want to switch from/to release or debug mode, a clean build must be done. Use the uninstall.sh script to clean any built objects of artifacts.

To run tests, please execute the run_tests.sh script - which assumes that the test executables (bin/MavenTests and bin/test-libmaven) were compiled and built beforehand.

Bugs and feature requests

Existing bugs and feature requests can be found on El-MAVEN github issue page. Please make sure that your bug/feature does not already exist in the issues list before you file new bugs or request a feature.

Documentation

El-MAVEN user documentation can be found on the project's GitHub wiki page.

Contributing

All contributions are welcome. Please go through our contributing guidelines and code of conduct. These guidelines include directions for coding standards, filing issues and development guidelines.

All the functional features should be tested before committing the code and creating pull requests. When contributing C++ code, please make sure that it follows the style guide for this project.

Any and all contributions/corrections to the documentation itself will also be very helpful (to the project and the community at large).

Contributors

References

To understand El-MAVEN's workflows and features, please refer to following literature on El-MAVEN and MAVEN:

How to Cite

Cite the protocol as:

Agrawal S. et al. (2019) El-MAVEN: A Fast, Robust, and User-Friendly Mass Spectrometry Data Processing Engine for Metabolomics. In: D'Alessandro A. (eds) High-Throughput Metabolomics. Methods in Molecular Biology, vol 1978. Humana, New York, NY

When citing analyses performed using the program, cite the DOI for the relevant version of El-MAVEN used for the analyses. To ensure that a reader is able to reproduce your analysis, please mention the key algorithms and parameters used to obtain the final results in your research.

Acknowledgment

El-MAVEN would not have been possible without the unwavering support, constant feedback and financial support from Agios. All contributors and supporters are also thankful to the metabolomics community for its immense contribution in taking the tool forward and making it a great success.

Copyright and license

Code and documentation copyright 2017 Elucidata Inc. Code released under the GPL v2.0. Documentation is released under MIT license.