# AlphaMap
> A python-based library that enables the exploration of proteomic datasets on the peptide level.
## About
AlphaMap is a tool for peptide level MS data exploration. You can load and inspect MS data analyzed by [AlphaPept](https://github.com/MannLabs/alphapept), DIA-NN, MaxQuant, Spectronaut or FragPipe. Uploaded data is processed and formatted for visual inspection of the sequence coverage of any selected protein and its identified post-translational modifications (PTMs). UniProt information is available to directly annotate sequence regions of interest such as protein domains, secondary structures, sequence variants, known PTMs, etc. Additionally, users can select proteases to further evaluate the distribution of proteolytic cleavage sites across a protein sequence. The functionality of AlphaMap can be accessed via an intuitive graphical user interface or - more flexibly - as a Python package that allows its integration into common analysis workflows for data visualization.
## License
AlphaMap was developed by the [Mann Labs at the Max Planck Institute of Biochemistry](https://www.biochem.mpg.de/mann) and is freely available with an [Apache License](LICENSE).
## Installation
AlphaMap can be installed and used on Windows and MacOS.
There are three different types of installation possible:
* [**One-click GUI installer:**](#one-click-gui) Choose this installation if you only want the GUI and/or keep things as simple as possible.
* [**Pip installer:**](#pip) Choose this installation if you want to use AlphaMap as a Python package in an existing Python 3.8 environment (e.g. a Jupyter notebook). If needed, the GUI can be installed with pip as well.
* [**Developer installer:**](#developer) Choose this installation if you are familiar with CLI tools, [conda](https://docs.conda.io/en/latest/) and Python. This installation allows access to all available features of AlphaMap and even allows to modify its source code directly.
### One-click GUI
The GUI of AlphaMap is a completely stand-alone tool that requires no knowledge of Python. Click on one of the links below to download the latest release for:
* [**Windows**](https://github.com/MannLabs/alphamap/releases/latest/download/alphamap_installer_windows.exe)
* [**MacOS**](https://github.com/MannLabs/alphamap/releases/latest/download/alphamap_gui_installer_macos.pkg)
***IMPORTANT: Please refer to the [GUI manual](alphamap/data/alphamap_tutorial.pdf) for detailed instructions on the installation, troubleshooting and usage of the stand-alone AlphaMap GUI.***
***IMPORTANT***: The one-click-installers on macOS and Windows require **at least macOS Catalina (10.15) or higher** and **Windows 10** respectively. For Windows, a system update might be necessary in case older versions do not work. To prevent installation errors on **Windows**, we recommend **uninstalling the previous AlphaMap version before installing a new one**.
### Pip
AlphaMap 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 `!`*.
```bash
pip install alphamap[stable,structuremap-stable]
```
The [stable] tag ensures you get the latest stable release with fixed dependencies. However, it can be omitted if you prefer more flexible dependency versions:
```bash
pip install alphamap[structuremap]
```
When a new version of AlphaMap becomes available, the old version can easily be upgraded by running e.g. the command again with an additional `--upgrade` flag:
```bash
pip install --upgrade alphamap[stable,structuremap-stable]
```
Note: The `structuremap` extra can be omitted in case use of `plot_3d_structuremap()` is not desired.
Note: When installing with `pip`, UniProt information is not included. Upon first usage of a specific Organism, its information will be automatically downloaded from UniProt.
### Developer
AlphaMap 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:
```bash
mkdir ~/folder/where/to/install/software && cd ~/folder/where/to/install/software
```
Next, download the AlphaMap repository from GitHub either directly or with a `git` command. This creates a new AlphaMap subfolder in your current directory.
```bash
git clone https://github.com/MannLabs/alphamap.git && cd alphamap
```
For any Python package, it is highly recommended to use a [conda virtual environment](https://docs.conda.io/en/latest/). AlphaMap can either be installed in a new conda environment or in an already existing environment. *Note that dependency conflicts can occur with already existing packages in the latter case*! Once a conda environment is activated, AlphaMap and all its [dependencies](requirements) need to be installed.
```bash
conda create -n alphamap python=3.8 -y
conda activate alphamap
pip install -e ".[stable,structuremap-stable]"
```
* By using the editable flag `-e`, all modifications to the AlphaMap [source code folder](alphamap) are directly reflected when running AlphaMap. Note that the AlphaMap folder cannot be moved and/or renamed if an editable version is installed.
* When using Jupyter notebooks and multiple conda environments directly from the terminal, it is recommended to `conda install nb_conda_kernels` in the conda base environment. Hereafter, running a `jupyter notebook` from the conda base environment should have a `python [conda env: alphamap]` kernel available, in addition to all other conda kernels in which the command `conda install ipykernel` was run.
## Test data
AlphaMap has direct data import options for AlphaPept, DIA-NN, MaxQuant, Spectronaut and FragPipe.
### AlphaPept
AlphaMap takes the *results.csv* file from AlphaPept as input format. An example is available for [download here](https://github.com/MannLabs/alphamap/blob/main/testdata/test_alphapept_input.csv).
### DIA-NN
AlphaMap takes the peptide-level output .tsv file from DIA-NN as input format. An example is available for [download here](https://github.com/MannLabs/alphamap/blob/main/testdata/test_diann_input.tsv).
### MaxQuant
AlphaMap takes the *evidence.txt* file from MaxQuant as input format. A reduced example file is available for [download here](https://github.com/MannLabs/alphamap/blob/main/testdata/test_maxquant_input.txt).
### Spectronaut
AlphaMap takes Spectronaut results exported in normal long format (.csv or .tsv) as input. Necessary columns include:
* PEP.AllOccuringProteinAccessions
* EG.ModifiedSequence
* R.FileName
To ensure proper formatting of the Spectronaut output, an export scheme is available for [download here](https://github.com/MannLabs/alphamap/blob/main/alphamap/data/spectronaut_export_scheme.rs).
A reduced example file is also available for [download here](https://github.com/MannLabs/alphamap/blob/main/testdata/test_spectronaut_input.tsv).
### FragPipe
There are two options to visualize data analyzed by FragPipe:
1) Upload individual **"peptide.tsv"** files for single MS runs. A reduced example file is available for [download here](https://github.com/MannLabs/alphamap/releases/download/0.1.3/test_fragpipe_input.tsv).
2) Upload the **"combined_peptide.tsv"** file with the joint information about peptides identified in all runs (there is an option to select the experiment(s)). Be aware that the combined_peptide.tsv does not provide information about PTM localization. PTMs are therefore not shown for this option. A reduced example file is available for [download here](https://github.com/MannLabs/alphamap/releases/download/0.1.3/combined_peptide.txt).
## Usage
There are two ways to use AlphaMap:
* [**GUI:**](#gui) This allows to interactively import and visualize the data.
* [**Python:**](#python-and-jupyter-notebooks) This allows to access data and explore it interactively with custom code.
NOTE: The first time you use a fresh installation of AlphaMap, 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.
### GUI
Please refer to the [GUI manual](https://github.com/MannLabs/alphamap/blob/master/alphamap/data/alphamap_tutorial.pdf) for detailed instructions on the installation and usage of the stand-alone AlphaMap GUI.
If the GUI was not installed through a one-click GUI installer, it can be activated with the following `bash` command:
```bash
alphamap
```
Note that this needs to be prepended with a `!` when you want to run this from within a Jupyter notebook. When the command is run directly from the command-line, make sure you use the right environment (activate it with e.g. `conda activate alphamap` or set an alias to the binary executable).
### Python and Jupyter notebooks
AlphaMap can be imported as a Python package into any Python script or notebook with the command `import alphamap`.
A Jupyter notebook tutorial ['Workflow.ipynb'](Workflow.ipynb) is available to demonstrate how to load AlphaMap as python module and how to visualize data interactively. When running locally it provides interactive plots, which are not rendered on GitHub.
AlphaMap includes fasta files and UniProt annotations for: 'Human', 'Mouse', 'Rat', 'Cow', 'Zebrafish', 'Drosophila', 'Caenorhabditis elegans', 'Slime mold', 'Arabidopsis thaliana', 'Rice', 'Escherichia coli', 'Bacillus subtilis', 'Saccharomyces cerevisiae', 'SARS-COV' and 'SARS-COV-2'. If additional organisms are of interest, corresponding .fasta files and sequence annotations can be downloaded directly from UniProt. A Jupyter notebook tutorial ['Uniprot_preprocessing.ipynb'](Uniprot_preprocessing.ipynb) shows how to load and format a UniProt annotation file.
## Developer Guide
This document gathers information on how to develop and contribute to this project.
### Release process
#### Tagging of changes
In order to have release notes automatically generated, changes need to be tagged with labels.
The following labels are used (should be safe-explanatory):
`breaking-change`, `bug`, `enhancement`.
#### Release a new version
This package uses a shared release process defined in the
[alphashared](https://github.com/MannLabs/alphashared) repository. Please see the instructions
[there](https://github.com/MannLabs/alphashared/blob/reusable-release-workflow/.github/workflows/README.md#release-a-new-version)
Raw data
{
"_id": null,
"home_page": null,
"name": "alphamap",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": null,
"keywords": "mass spectrometry, proteomics, search engine, DIA, data-independent acquisition, bioinformatics, AlphaPept, AlphaPept ecosystem",
"author": null,
"author_email": "\"Isabell Bludau, Eugenia Voytik\" <bludau@biochem.mpg.de>",
"download_url": null,
"platform": null,
"description": "# AlphaMap\n> A python-based library that enables the exploration of proteomic datasets on the peptide level.\n\n\n## About\n\nAlphaMap is a tool for peptide level MS data exploration. You can load and inspect MS data analyzed by [AlphaPept](https://github.com/MannLabs/alphapept), DIA-NN, MaxQuant, Spectronaut or FragPipe. Uploaded data is processed and formatted for visual inspection of the sequence coverage of any selected protein and its identified post-translational modifications (PTMs). UniProt information is available to directly annotate sequence regions of interest such as protein domains, secondary structures, sequence variants, known PTMs, etc. Additionally, users can select proteases to further evaluate the distribution of proteolytic cleavage sites across a protein sequence. The functionality of AlphaMap can be accessed via an intuitive graphical user interface or - more flexibly - as a Python package that allows its integration into common analysis workflows for data visualization. \n\n\n## License\n\nAlphaMap was developed by the [Mann Labs at the Max Planck Institute of Biochemistry](https://www.biochem.mpg.de/mann) and is freely available with an [Apache License](LICENSE).\n\n\n## Installation\n\nAlphaMap can be installed and used on Windows and MacOS.\nThere are three different types of installation possible:\n\n* [**One-click GUI installer:**](#one-click-gui) Choose this installation if you only want the GUI and/or keep things as simple as possible.\n* [**Pip installer:**](#pip) Choose this installation if you want to use AlphaMap as a Python package in an existing Python 3.8 environment (e.g. a Jupyter notebook). If needed, the GUI can be installed with pip as well.\n* [**Developer installer:**](#developer) Choose this installation if you are familiar with CLI tools, [conda](https://docs.conda.io/en/latest/) and Python. This installation allows access to all available features of AlphaMap and even allows to modify its source code directly.\n\n\n### One-click GUI\n\nThe GUI of AlphaMap is a completely stand-alone tool that requires no knowledge of Python. Click on one of the links below to download the latest release for:\n\n* [**Windows**](https://github.com/MannLabs/alphamap/releases/latest/download/alphamap_installer_windows.exe)\n* [**MacOS**](https://github.com/MannLabs/alphamap/releases/latest/download/alphamap_gui_installer_macos.pkg)\n\n***IMPORTANT: Please refer to the [GUI manual](alphamap/data/alphamap_tutorial.pdf) for detailed instructions on the installation, troubleshooting and usage of the stand-alone AlphaMap GUI.*** \n\n***IMPORTANT***: The one-click-installers on macOS and Windows require **at least macOS Catalina (10.15) or higher** and **Windows 10** respectively. For Windows, a system update might be necessary in case older versions do not work. To prevent installation errors on **Windows**, we recommend **uninstalling the previous AlphaMap version before installing a new one**.\n\n### Pip\n\nAlphaMap 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 `!`*.\n\n```bash\npip install alphamap[stable,structuremap-stable]\n```\nThe [stable] tag ensures you get the latest stable release with fixed dependencies. However, it can be omitted if you prefer more flexible dependency versions:\n\n```bash\npip install alphamap[structuremap]\n```\n\nWhen a new version of AlphaMap becomes available, the old version can easily be upgraded by running e.g. the command again with an additional `--upgrade` flag:\n\n```bash\npip install --upgrade alphamap[stable,structuremap-stable] \n```\n\nNote: The `structuremap` extra can be omitted in case use of `plot_3d_structuremap()` is not desired. \nNote: When installing with `pip`, UniProt information is not included. Upon first usage of a specific Organism, its information will be automatically downloaded from UniProt.\n\n\n### Developer\n\nAlphaMap 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:\n\n```bash\nmkdir ~/folder/where/to/install/software && cd ~/folder/where/to/install/software\n```\n\nNext, download the AlphaMap repository from GitHub either directly or with a `git` command. This creates a new AlphaMap subfolder in your current directory.\n\n```bash\ngit clone https://github.com/MannLabs/alphamap.git && cd alphamap\n```\n\nFor any Python package, it is highly recommended to use a [conda virtual environment](https://docs.conda.io/en/latest/). AlphaMap can either be installed in a new conda environment or in an already existing environment. *Note that dependency conflicts can occur with already existing packages in the latter case*! Once a conda environment is activated, AlphaMap and all its [dependencies](requirements) need to be installed.\n\n```bash\nconda create -n alphamap python=3.8 -y\nconda activate alphamap\npip install -e \".[stable,structuremap-stable]\"\n```\n\n* By using the editable flag `-e`, all modifications to the AlphaMap [source code folder](alphamap) are directly reflected when running AlphaMap. Note that the AlphaMap folder cannot be moved and/or renamed if an editable version is installed.\n\n* When using Jupyter notebooks and multiple conda environments directly from the terminal, it is recommended to `conda install nb_conda_kernels` in the conda base environment. Hereafter, running a `jupyter notebook` from the conda base environment should have a `python [conda env: alphamap]` kernel available, in addition to all other conda kernels in which the command `conda install ipykernel` was run.\n\n\n## Test data\nAlphaMap has direct data import options for AlphaPept, DIA-NN, MaxQuant, Spectronaut and FragPipe.\n\n### AlphaPept\nAlphaMap takes the *results.csv* file from AlphaPept as input format. An example is available for [download here](https://github.com/MannLabs/alphamap/blob/main/testdata/test_alphapept_input.csv).\n\n### DIA-NN\nAlphaMap takes the peptide-level output .tsv file from DIA-NN as input format. An example is available for [download here](https://github.com/MannLabs/alphamap/blob/main/testdata/test_diann_input.tsv).\n\n### MaxQuant\nAlphaMap takes the *evidence.txt* file from MaxQuant as input format. A reduced example file is available for [download here](https://github.com/MannLabs/alphamap/blob/main/testdata/test_maxquant_input.txt).\n\n### Spectronaut\nAlphaMap takes Spectronaut results exported in normal long format (.csv or .tsv) as input. Necessary columns include:\n* PEP.AllOccuringProteinAccessions\n* EG.ModifiedSequence\n* R.FileName\n\nTo ensure proper formatting of the Spectronaut output, an export scheme is available for [download here](https://github.com/MannLabs/alphamap/blob/main/alphamap/data/spectronaut_export_scheme.rs).\n\nA reduced example file is also available for [download here](https://github.com/MannLabs/alphamap/blob/main/testdata/test_spectronaut_input.tsv).\n\n### FragPipe\nThere are two options to visualize data analyzed by FragPipe:\n1) Upload individual **\"peptide.tsv\"** files for single MS runs. A reduced example file is available for [download here](https://github.com/MannLabs/alphamap/releases/download/0.1.3/test_fragpipe_input.tsv).\n\n2) Upload the **\"combined_peptide.tsv\"** file with the joint information about peptides identified in all runs (there is an option to select the experiment(s)). Be aware that the combined_peptide.tsv does not provide information about PTM localization. PTMs are therefore not shown for this option. A reduced example file is available for [download here](https://github.com/MannLabs/alphamap/releases/download/0.1.3/combined_peptide.txt).\n\n## Usage\n\nThere are two ways to use AlphaMap:\n\n* [**GUI:**](#gui) This allows to interactively import and visualize the data.\n* [**Python:**](#python-and-jupyter-notebooks) This allows to access data and explore it interactively with custom code.\n\nNOTE: The first time you use a fresh installation of AlphaMap, 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.\n\n### GUI\n\nPlease refer to the [GUI manual](https://github.com/MannLabs/alphamap/blob/master/alphamap/data/alphamap_tutorial.pdf) for detailed instructions on the installation and usage of the stand-alone AlphaMap GUI.\n\nIf the GUI was not installed through a one-click GUI installer, it can be activated with the following `bash` command:\n\n```bash\nalphamap\n```\n\nNote that this needs to be prepended with a `!` when you want to run this from within a Jupyter notebook. When the command is run directly from the command-line, make sure you use the right environment (activate it with e.g. `conda activate alphamap` or set an alias to the binary executable).\n\n### Python and Jupyter notebooks\n\nAlphaMap can be imported as a Python package into any Python script or notebook with the command `import alphamap`.\n\nA Jupyter notebook tutorial ['Workflow.ipynb'](Workflow.ipynb) is available to demonstrate how to load AlphaMap as python module and how to visualize data interactively. When running locally it provides interactive plots, which are not rendered on GitHub.\n\nAlphaMap includes fasta files and UniProt annotations for: 'Human', 'Mouse', 'Rat', 'Cow', 'Zebrafish', 'Drosophila', 'Caenorhabditis elegans', 'Slime mold', 'Arabidopsis thaliana', 'Rice', 'Escherichia coli', 'Bacillus subtilis', 'Saccharomyces cerevisiae', 'SARS-COV' and 'SARS-COV-2'. If additional organisms are of interest, corresponding .fasta files and sequence annotations can be downloaded directly from UniProt. A Jupyter notebook tutorial ['Uniprot_preprocessing.ipynb'](Uniprot_preprocessing.ipynb) shows how to load and format a UniProt annotation file.\n\n## Developer Guide\nThis document gathers information on how to develop and contribute to this project.\n\n### Release process\n\n#### Tagging of changes\nIn order to have release notes automatically generated, changes need to be tagged with labels.\nThe following labels are used (should be safe-explanatory):\n`breaking-change`, `bug`, `enhancement`.\n\n#### Release a new version\nThis package uses a shared release process defined in the\n[alphashared](https://github.com/MannLabs/alphashared) repository. Please see the instructions\n[there](https://github.com/MannLabs/alphashared/blob/reusable-release-workflow/.github/workflows/README.md#release-a-new-version)\n",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "0.1.13",
"project_urls": {
"Issues": "https://github.com/MannLabs/alphamap/issues",
"Mann Labs Homepage": "https://www.biochem.mpg.de/mann",
"Paper preprint": "https://www.biochem.mpg.de/mann",
"Repository": "https://github.com/MannLabs/alphamap"
},
"split_keywords": [
"mass spectrometry",
" proteomics",
" search engine",
" dia",
" data-independent acquisition",
" bioinformatics",
" alphapept",
" alphapept ecosystem"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "24eaf5299eacd2d8da1c0456c7f064d30f346d71312cc96bb18c26446b8f55f4",
"md5": "d3d1295dac8333d91d541da2aaf57ecd",
"sha256": "3748476d33520e17a342ec9861644b89cdcd5841f4da8815d15a787be8c5b431"
},
"downloads": -1,
"filename": "alphamap-0.1.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d3d1295dac8333d91d541da2aaf57ecd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 8905018,
"upload_time": "2025-02-19T21:30:28",
"upload_time_iso_8601": "2025-02-19T21:30:28.789671Z",
"url": "https://files.pythonhosted.org/packages/24/ea/f5299eacd2d8da1c0456c7f064d30f346d71312cc96bb18c26446b8f55f4/alphamap-0.1.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-19 21:30:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MannLabs",
"github_project": "alphamap",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "alphamap"
}
JSON
