Skip to content

Latest commit

 

History

History
229 lines (169 loc) · 9.42 KB

README.md

File metadata and controls

229 lines (169 loc) · 9.42 KB
Raw

AlphaRaw

Default installation and tests Publish on PyPi and release on GitHub pypi pip downloads Python Documentation Status

About

An open-source Python package of the AlphaPept ecosystem from the Mann Labs at the Max Planck Institute of Biochemistry to unify raw MS data accession and storage. To enable all hyperlinks in this document, please view it at GitHub.

License

AlphaRaw was developed by the Mann Labs at the Max Planck Institute of Biochemistry and is freely available with an Apache License. External Python packages (available in the requirements folder) have their own licenses, which can be consulted on their respective websites.

Installation

Pythonnet must be installed to access Thermo or Sciex raw data.

For Windows

Pythonnet will be automatically installed via pip.

For Linux (or MacOS without M1/M2/M3/..., not tested yet)

  1. conda install mono.
  2. Install pythonnet with pip install pythonnet.

If conda install mono does not work, we can install Mono from mono-project website Mono Linux. NOTE, the installed mono version should be at least 6.10, which requires you to add the ppa to your trusted sources!

For MacOS including M1/M2 platform

  1. Install brew.
  2. Install mono: brew install mono.
  3. If the pseudo mono folder /Library/Frameworks/Mono.framework/Versions does not exist, create it by running sudo mkdir -p /Library/Frameworks/Mono.framework/Versions.
  4. Link homebrew mono to pseudo mono folder: sudo ln -s /opt/homebrew/Cellar/mono/6.12.0.182 /Library/Frameworks/Mono.framework/Versions/Current. Here, 6.12.0.182 is the brew-installed mono version, please check your installed version. Navigate to /Library/Frameworks/Mono.framework/Versions and run ls -l to verify that the link Current points to /opt/homebrew/Cellar/mono/6.12.0.182. If Current points to a different installation and/or /opt/homebrew/Cellar/mono/6.12.0.182 is referenced by a different link, delete the corresponding links and run sudo ln -s /opt/homebrew/Cellar/mono/6.12.0.182 Current.
  5. Install pythonnet: pip install pythonnet.

AlphaRaw can be installed and used on all major operating systems (Windows, macOS and Linux). There are three different types of installation possible:

  • Pip installer: Choose this installation if you want to use AlphaRaw as a Python package in an existing Python 3.8 environment (e.g. a Jupyter notebook).
  • Developer installer: Choose this installation if you are familiar with CLI tools, conda and Python. This installation allows access to all available features of AlphaRaw and even allows to modify its source code directly. Generally, the developer version of AlphaRaw outperforms the precompiled versions which makes this the installation of choice for high-throughput experiments.

Pip

AlphaRaw can be installed in an existing Python 3.8 environment with a single bash command. This bash command can also be run directly from within a Jupyter notebook by prepending it with a !:

pip install alpharaw

Installing AlphaRaw like this avoids conflicts when integrating it in other tools, as this does not enforce strict versioning of dependancies. However, if new versions of dependancies are released, they are not guaranteed to be fully compatible with AlphaRaw. While this should only occur in rare cases where dependencies are not backwards compatible, you can always force AlphaRaw to use dependancy versions which are known to be compatible with:

pip install "alpharaw[stable]"

NOTE: You might need to run pip install pip --upgrade before installing AlphaRaw like this. Also note the double quotes ".

For those who are really adventurous, it is also possible to directly install any branch (e.g. @development) with any extras (e.g. #egg=alpharaw[stable,development-stable]) from GitHub with e.g.

pip install "git+https://github.com/MannLabs/alpharaw.git@development#egg=alpharaw[stable,development-stable]"

Developer

AlphaRaw can also be installed in editable (i.e. developer) mode with a few bash commands. This allows to fully customize the software and even modify the source code to your specific needs. When an editable Python package is installed, its source code is stored in a transparent location of your choice. While optional, it is advised to first (create and) navigate to e.g. a general software folder:

mkdir ~/folder/where/to/install/software
cd ~/folder/where/to/install/software

The following commands assume you do not perform any additional cd commands anymore.

Next, download the AlphaRaw repository from GitHub either directly or with a git command. This creates a new AlphaRaw subfolder in your current directory.

git clone https://github.com/MannLabs/alpharaw.git

For any Python package, it is highly recommended to use a separate conda virtual environment, as otherwise dependancy conflicts can occur with already existing packages.

conda create --name alpharaw python=3.9 -y
conda activate alpharaw

Finally, AlphaRaw and all its dependancies need to be installed. To take advantage of all features and allow development (with the -e flag), this is best done by also installing the development dependencies instead of only the core dependencies:

pip install -e "./alpharaw[development]"

By default this installs loose dependancies (no explicit versioning), although it is also possible to use stable dependencies (e.g. pip install -e "./alpharaw[stable,development-stable]").

By using the editable flag -e, all modifications to the AlphaRaw source code folder are directly reflected when running AlphaRaw. Note that the AlphaRaw folder cannot be moved and/or renamed if an editable version is installed.

Usage

NOTE: The first time you use a fresh installation of AlphaRaw, it is often quite slow because some functions might still need compilation on your local operating system and architecture. Subsequent use should be a lot faster.

Python and Jupyter notebooks

AlphaRaw can be imported as a Python package into any Python script or notebook with the command import alpharaw.

A brief Jupyter notebook tutorial on how to use the API is also present in the nbs folder.

Troubleshooting

In case of issues, check out the following:

  • Issues: Try a few different search terms to find out if a similar problem has been encountered before
  • Discussions: Check if your problem or feature requests has been discussed before.

Citations

There are currently no plans to draft a manuscript.

How to contribute

If you like this software, you can give us a star to boost our visibility! All direct contributions are also welcome. Feel free to post a new issue or clone the repository and create a pull request with a new branch. For an even more interactive participation, check out the discussions and the the Contributors License Agreement.

Changelog

See the HISTORY.md for a full overview of the changes made in each version.