diff --git a/conf.py b/conf.py index 1fd961a6..8554f1d9 100644 --- a/conf.py +++ b/conf.py @@ -78,6 +78,8 @@ # html_theme = 'furo' html_logo = 'assets/logo/OpenMS_transparent_background.png' +html_favicon = 'assets/logo/OpenMS_transparent_background.png' + html_theme_options = { "navigation_with_keys": True, "light_css_variables": { @@ -90,7 +92,6 @@ pygments_dark_style = 'rrt' - # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/docs/contribute-to-openms/adding-new-tool-to-topp.md b/docs/contribute-to-openms/adding-new-tool-to-topp.md new file mode 100644 index 00000000..36b9082c --- /dev/null +++ b/docs/contribute-to-openms/adding-new-tool-to-topp.md @@ -0,0 +1,100 @@ +Adding New Tool to The TOPP suite +===================================== + +## The OpenMS pipeline (TOPP) + +Any tool that is written with the OpenMS library can easily be made into a TOPP tool by simply using the OpenMS command +line parser which is able to parse ParamXML, a powerful XML based description of the tool. Hence most analysis algorithms +in OpenMS are available as a stand-alone tool which can be called on the command line or integrated into workflow engines +via the CTD mechanism. A current list of TOPP tools can be found in [the documentation](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/TOPP_documentation.html). + +## What do I have to do to add a new TOPP tool? + +The recommended way is to inherit from the class TOPPBase as in existing TOPP tools (sources available in /src/topp/). This will add command line parsing functionality to your tool as described in the TOPP section of this page. + +- Add the code to `src/topp/` and register it in `src/topp/executables.cmake` +- Add your tool (with the correct category) to `getTOPPToolList()` in `src/openms/source/APPLICATIONS/ToolHandler.cpp`. + This creates a doxygen page with the `–help` output of the tool (using `TOPPDocumenter`). This page must be included + at the end of the doxygen documentation of your tool (see other tools for an example). +- Add it to the TOPP docu page (in `doc/doxygen/public/TOPP.doxygen`) +- Add the name to `src/topp/executables.cmake` +- Write a TOPP test (add it to `src/tests/topp/CMakeLists.txt`) + +```{warning} +Handle any kind of input files to your TOPP tool via command line flags and use the `${DATA_DIR_TOPP}` prefix. Use +ini-files to specify output-files, but not input-files. Doing otherwise will break out-of-source builds. +``` + +```{hint} +add `-test` to the call of your TOPP tool and also create the expected output that you put in `src/tests/topp` with that +flag active. The flag ensures that UniqueId's, dates etc are equal no matter where and when the tool is run. +``` + +## What do I have to do to add a new UTILS tool? + +- Add the code to `src/utils/` and register it in `src/utils/executables.cmake`. +- Add your tool to `getUtilList()` in `src/openms/source/APPLICATIONS/ToolHandler.cpp`. This creates a doxygen page with + the `–help` output of the tool (using `TOPPDocumenter`). This page must be included at the end of the doxygen + documentation of your tool (see other tools for an example). +- Add it to the UTILS docu page (in `doc/doxygen/public/UTILS.doxygen`) +- Write a test (this is optional for UTILS). See TOPP tools above and add the test to the bottom of `src/tests/topp/CMakeLists.txt`. + +## I want to implement a new file adapter. What is to be done? + +First, add a file adapter class to the `include/OpenMS/FORMAT/` and `source/FORMAT/` folders. The file adapter should +implement a default constructor, a load method and a store method. Make sure your code conforms to the OpenMS Coding +conventions. For automatic file type recognition, you need to + +- register your new file type at the Type enum in `/include/OpenMS/FORMAT/FileTypes.h`, +- flag the file type as supported in the isSupported method of `/source/FORMAT/FileHandler.C` +- register the file extension in the getTypeByFileName method of `/source/FORMAT/FileHandler.C` + +If the new file is a peak or feature file format you should also add it to loadExperiment or loadFeatures, respectively, +of the FileHandler class. To add the file format to the TOPPView open dialog, you have to modify the file +`/source/APPLICATIONS/TOPPViewBase.C`. + +- Add the file extensions to the filter_all and filter_single variables of the getFileList_ method. + +To add your format to TOPP applications: + +- add the file extension to the extensions list of the respective parameter: + ``` + e.g. setValidStrings_("in_type", StringList::create("mzData,mzXML,mzML")); in FileInfo + ``` + +## How to create an icon file for a TOPP tool under Windows? + +- Create an .ico file: first, you need some graphics program (The GIMP is recommended) think of a motive and remind + yourself that you have limited space. Create at least a 16x16, 32x32, 48x48 and 64x64 pixel version and save each of + them in a separate layer of the respective size. Do not add any larger sized layers, since Win XP will not display any + icon then. When saving the image as type `.ico` the GIMP will ask you for the color depth of each layer. As it is + recommended to have multiple color depths of each icon-size, go back to the layers and duplicate each layer twice. + That should give you 12 layers. Now, save the image as `.ico` (e.g. TOPPView.ico) file, giving each group of equal + sized layers a 32 bit (8 bit transparency), 8 bit (1 bit transparency), 4 bit (1 bit transparency) color depth. + +```{attention} +Make sure to assign the higher color depth to the upper layers as Windows will not pick the highest possible color +otherwise. +``` + +- Create a resource file: Create a text file named `.rc` (e.g. TOPPView.rc) Insert the following line: 101 ICON + "TOPPView.ico" , replacing TOPPView with your binary name. Put both files in `OpenMS/source/APPLICATIONS/TOPP/` + (similar files for other TOPP tools already present). Re-run cmake and re-link your TOPP tool. + +Voila. You should have an iconized TOPP tool. + +## Develop your Tool in an external project using OpenMS + +To include the OpenMS library in one of your projects, we recommend to have a look at a small emulated external project +in our repository. We strongly suggest to use CMake for building your project together with OpenMS to make use of the +macros and environment information generated during the build of the OpenMS library. + +## The Common Tool Description (CTD) + +The CTD is a format developed from the OpenMS team to allow the user to use TOPP tools also in other workflow engines. +Each tool can output a CTD description of itself (the XML scheme for the CTD can be found here), which can then be used +by a node generator program to generate nodes for different workflow engines. The CTD mechanism is shared by OpenMS with +other mature libraries like SeqAn and BALL. An example for a node generation program are the Generic KNIME Nodes. The +most complete description on how to generate your own Generic KNIME Nodes based on a CTD (e.g. from your freshly +developed command line tool), can be found on the SeqAn documentation. We are working on a tutorial specifically +tailored to OpenMS. diff --git a/docs/contribute-to-openms/advanced.md b/docs/contribute-to-openms/advanced.md new file mode 100644 index 00000000..58552ada --- /dev/null +++ b/docs/contribute-to-openms/advanced.md @@ -0,0 +1,10 @@ +Advanced +======== +```{toctree} +:maxdepth: 1 + +advanced/developer-guidelines-for-adding-new-dependent-libraries.md +advanced/build-custom-knime-plugin.md +advanced/custom-compilation.md + +``` diff --git a/docs/contribute-to-openms/advanced/build-custom-knime-plugin.md b/docs/contribute-to-openms/advanced/build-custom-knime-plugin.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/advanced-resources/custom-compilation.md b/docs/contribute-to-openms/advanced/custom-compilation.md similarity index 100% rename from docs/advanced-resources/custom-compilation.md rename to docs/contribute-to-openms/advanced/custom-compilation.md diff --git a/docs/additional-resources/developer-guidelines-for-addding-new-dependent-libraries.md b/docs/contribute-to-openms/advanced/developer-guidelines-for-adding-new-dependent-libraries.md similarity index 100% rename from docs/additional-resources/developer-guidelines-for-addding-new-dependent-libraries.md rename to docs/contribute-to-openms/advanced/developer-guidelines-for-adding-new-dependent-libraries.md diff --git a/docs/additional-resources/openms-git-workflow.md b/docs/contribute-to-openms/openms-git-workflow.md similarity index 100% rename from docs/additional-resources/openms-git-workflow.md rename to docs/contribute-to-openms/openms-git-workflow.md diff --git a/docs/additional-resources/pull-request-checklist.md b/docs/contribute-to-openms/pull-request-checklist.md similarity index 100% rename from docs/additional-resources/pull-request-checklist.md rename to docs/contribute-to-openms/pull-request-checklist.md diff --git a/docs/additional-resources/reporting-bugs-and-issues.md b/docs/contribute-to-openms/reporting-bugs-and-issues.md similarity index 100% rename from docs/additional-resources/reporting-bugs-and-issues.md rename to docs/contribute-to-openms/reporting-bugs-and-issues.md diff --git a/docs/additional-resources/write-and-label-github-issues.md b/docs/contribute-to-openms/write-and-label-github-issues.md similarity index 100% rename from docs/additional-resources/write-and-label-github-issues.md rename to docs/contribute-to-openms/write-and-label-github-issues.md diff --git a/docs/develop-with-openms/api-reference.md b/docs/develop-with-openms/api-reference.md new file mode 100644 index 00000000..bcb43b41 --- /dev/null +++ b/docs/develop-with-openms/api-reference.md @@ -0,0 +1,2 @@ +API Reference +============= diff --git a/docs/develop-with-openms/build-openms-from-source.md b/docs/develop-with-openms/build-openms-from-source.md new file mode 100644 index 00000000..83b89946 --- /dev/null +++ b/docs/develop-with-openms/build-openms-from-source.md @@ -0,0 +1,2 @@ +Build OpenMS from Source +======================== diff --git a/docs/develop-with-openms/developer-tutorial.md b/docs/develop-with-openms/developer-tutorial.md new file mode 100644 index 00000000..df47ade2 --- /dev/null +++ b/docs/develop-with-openms/developer-tutorial.md @@ -0,0 +1,2 @@ +Developer Tutorial +================== diff --git a/docs/additional-resources/external-code-using-openms.md b/docs/develop-with-openms/link-external-code-to-openms.md similarity index 100% rename from docs/additional-resources/external-code-using-openms.md rename to docs/develop-with-openms/link-external-code-to-openms.md diff --git a/docs/develop-with-openms/openms-core-library.md b/docs/develop-with-openms/openms-core-library.md new file mode 100644 index 00000000..6e732f88 --- /dev/null +++ b/docs/develop-with-openms/openms-core-library.md @@ -0,0 +1,2 @@ +OpenMS C++ Core Library +======================= diff --git a/docs/develop-with-openms/pyopenms.md b/docs/develop-with-openms/pyopenms.md new file mode 100644 index 00000000..773d3774 --- /dev/null +++ b/docs/develop-with-openms/pyopenms.md @@ -0,0 +1,2 @@ +pyOpenMS +======== diff --git a/docs/graphical-topp-tools/ini-file-editor.md b/docs/graphical-topp-tools/ini-file-editor.md new file mode 100644 index 00000000..541316c1 --- /dev/null +++ b/docs/graphical-topp-tools/ini-file-editor.md @@ -0,0 +1,10 @@ +INIFileEditor +============ + +Can be used to visually edit INI files of TOPP tools. + +The values can be edited by double-clicking or pressing F2. + +The documentation of each value is shown in the text area on the bottom of the widget. + +![INIFileEditor](../images/topp/INIFileEditor.png) diff --git a/docs/graphical-topp-tools/swathwizard.md b/docs/graphical-topp-tools/swathwizard.md new file mode 100644 index 00000000..22412fdd --- /dev/null +++ b/docs/graphical-topp-tools/swathwizard.md @@ -0,0 +1,24 @@ +SwathWizard +========== + +An assistant for Swath analysis. + +The Wizard takes the user through the whole analysis pipeline for SWATH proteomics data analysis, i.e. the +[TOPP Documentation: OpenSwathWorkflow](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/UTILS_OpenSwathWorkflow.html) tool, including downstream tools such as [GitHub:PyProphet/pyProphet](https://github.com/PyProphet/pyprophet) and the [GitHub:msproteomicstools/TRIC alignment](https://github.com/msproteomicstools/msproteomicstools) tool. + +Since the downstream tools require Python and the respective modules, the Wizard will check their proper installation +status and warn the user if a component is missing. + +Users can enter the required input data (mzML MS/MS data, configuration files) in dedicated fields, usually by drag and +droping files from the operating systems' file explorer (Explorer, Nautilus, Finder...). The output of the Wizard is +both the intermediate files from OpenSWATH (e.g. the XIC data in `.sqMass` format) and the tab-separated table format +(`.tsv`) from pyProphet and TRIC. + +This is how the wizard looks like: + +![SwathWizard](../images/topp/SwathWizard.png) + +A schematic of the internal data flow (all tools are called by SwathWizard in the background) can be found in the +[TOPP Documentation: SwathWizard](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/TOPP_SwathWizard.html). + +A recommended test data for the Wizard is the [PASS00779](https://db.systemsbiology.net/sbeams/cgi/PeptideAtlas/PASS_View?identifier=PASS00779) dataset. diff --git a/docs/graphical-topp-tools/topp.md b/docs/graphical-topp-tools/topp.md new file mode 100644 index 00000000..7309d620 --- /dev/null +++ b/docs/graphical-topp-tools/topp.md @@ -0,0 +1,22 @@ +TOPP +=== + +**TOPP - The OpenMS Proteomics Pipeline** is a pipeline for the analysis of HPLC-MS data. It consists of several small +applications that can be chained to create analysis pipelines tailored for a specific problem. + +The TOPP tools are divided into several subgroups, like graphical tools, file handling, signal processing and +preprocessing, quantitation, map alignment, protein/peptide identification, protein/peptide processing, targeted +experiments and OpenSWATH, peptide property prediction, cross-linking, quality-control, among a few. + +Few of the graphical tools are explained below: + +```{toctree} +:maxdepth: 1 + +toppview +toppas +ini-file-editor +swathwizard +``` + +For advanced documentation on every TOPP tool, see the [OpenMS TOPP API Reference](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/TOPP_documentation.html). diff --git a/docs/graphical-topp-tools/toppas.md b/docs/graphical-topp-tools/toppas.md new file mode 100644 index 00000000..cd496144 --- /dev/null +++ b/docs/graphical-topp-tools/toppas.md @@ -0,0 +1,30 @@ +TOPPAS +====== + +An assistant for GUI-driven TOPP workflow design. + +**TOPPAS** allows to create, edit, open, save, and run TOPP workflows. Pipelines can be created conveniently in a GUI by +means of mouse interactions. The parameters of all involved tools can be edited within the application and are also +saved as part of the pipeline definition in the `.toppas` file. Furthermore, TOPPAS interactively performs validity +checks during the pipeline editing process, in order to make it more difficult to create an invalid workflow. Once set +up and saved, a workflow can also be run without the GUI using the `ExecutePipeline` TOPP tool. + +The following figure shows a simple example pipeline that has just been created and executed successfully: + +![TOPPAS simple example](../images/topp/TOPPAS_simple_example.png) + +More information about TOPPAS can be found in the [TOPPAS tutorial](../tutorials/TOPP/TOPPAS-tutorial.md). + +**The command line parameters of this tool are**: + +```bash +TOPPAS -- An assistant for GUI-driven TOPP workflow design. + +Usage: + TOPPAS [options] [files] + +Options are: + --help Shows this help + --debug Enables debug messages + -ini Sets the INI file (default: ~/.TOPPAS.ini) +``` diff --git a/docs/graphical-topp-tools/toppview.md b/docs/graphical-topp-tools/toppview.md new file mode 100644 index 00000000..0b001e51 --- /dev/null +++ b/docs/graphical-topp-tools/toppview.md @@ -0,0 +1,34 @@ +TOPPView +======= + +**TOPPView** is a viewer for MS and HPLC-MS data. It can be used to inspect files in mzML, mzData, mzXML and several other +file formats. It also supports viewing data from an OpenMS database. The following figure shows two instances of TOPPView +displaying a HPLC-MS map and a MS raw spectrum: + +![TOPPView](../images/topp/TOPPView.png) + +More information about TOPPView can be found in the [TOPP tutorial](../tutorials/TOPP/TOPP-tutorial.md). + +**The command line parameters of this tool are**: + +```bash +TOPPView -- A viewer for mass spectrometry data. + +Usage: + TOPPView [options] [files] + +Options are: + --help Shows this help + -ini Sets the INI file (default: ~/.TOPPView.ini) + --force Forces scan for new tools/utils + +Hints: + - To open several files in one window put a '+' in between the files. + - '@bw' after a map file displays the dots in a white to black gradient. + - '@bg' after a map file displays the dots in a grey to black gradient. + - '@b' after a map file displays the dots in black. + - '@r' after a map file displays the dots in red. + - '@g' after a map file displays the dots in green. + - '@m' after a map file displays the dots in magenta. + - Example: 'TOPPView 1.mzML + 2.mzML @bw + 3.mzML @bg' +``` diff --git a/docs/images/introduction/hplc-mass-spectrometry-setup.png b/docs/images/introduction/hplc-mass-spectrometry-setup.png new file mode 100644 index 00000000..bbe83186 Binary files /dev/null and b/docs/images/introduction/hplc-mass-spectrometry-setup.png differ diff --git a/docs/images/introduction/openms-architecture.png b/docs/images/introduction/openms-architecture.png new file mode 100644 index 00000000..2f4b925d Binary files /dev/null and b/docs/images/introduction/openms-architecture.png differ diff --git a/docs/images/topp/command-line-call.png b/docs/images/topp/command-line-call.png new file mode 100644 index 00000000..cb9c6444 Binary files /dev/null and b/docs/images/topp/command-line-call.png differ diff --git a/docs/images/tutorials/knime/add-node-to-workspace.gif b/docs/images/tutorials/knime/add-node-to-workspace.gif new file mode 100644 index 00000000..7e638668 Binary files /dev/null and b/docs/images/tutorials/knime/add-node-to-workspace.gif differ diff --git a/docs/images/tutorials/knime/connected-nodes-configured.png b/docs/images/tutorials/knime/connected-nodes-configured.png new file mode 100644 index 00000000..dcff5c52 Binary files /dev/null and b/docs/images/tutorials/knime/connected-nodes-configured.png differ diff --git a/docs/images/tutorials/knime/connected-nodes-not-configured.png b/docs/images/tutorials/knime/connected-nodes-not-configured.png new file mode 100644 index 00000000..9d9fc27c Binary files /dev/null and b/docs/images/tutorials/knime/connected-nodes-not-configured.png differ diff --git a/docs/images/tutorials/knime/output-file.png b/docs/images/tutorials/knime/output-file.png new file mode 100644 index 00000000..2e53e9f8 Binary files /dev/null and b/docs/images/tutorials/knime/output-file.png differ diff --git a/docs/images/tutorials/knime/play-button.png b/docs/images/tutorials/knime/play-button.png new file mode 100644 index 00000000..959d0d9b Binary files /dev/null and b/docs/images/tutorials/knime/play-button.png differ diff --git a/docs/images/tutorials/toppview/apply-topp-tool-to-layer.png b/docs/images/tutorials/toppview/apply-topp-tool-to-layer.png new file mode 100644 index 00000000..0824362e Binary files /dev/null and b/docs/images/tutorials/toppview/apply-topp-tool-to-layer.png differ diff --git a/docs/index.rst b/docs/index.rst index 89f95730..ffca28fe 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,7 +27,6 @@ a unified parameter handling via a 'common tool description' (CTD) scheme. data analysis framework that supports the generation of workflows for data analysis. Using a Common Tool Description (CTD) file which is writeable by every TOPP tool and a node generator program (`Generic KNIME Nodes `_), all :term:`TOPP tools` can be made available to run in KNIME. - With :term:`pyOpenMS`, OpenMS offers Python bindings to a large part of the :term:`OpenMS API` to enable rapid algorithm development. OpenMS supports the Proteomics Standard Initiative (PSI) formats for MS data. The main contributors of OpenMS are @@ -42,71 +41,63 @@ Contents :caption: Introduction :titlesonly: - introduction + introduction/about-open-ms.md + introduction/background.md + introduction/how-openms-works.md .. toctree:: :maxdepth: 2 - :caption: Getting Started - :titlesonly: + :caption: Installation Guides - installations/installation-on-gnu-linux - installations/installation-on-windows - installations/installation-on-macos - installations/build-openms-from-source + installations/installation-on-gnu-linux.md + installations/installation-on-macos.md + installations/installation-on-windows.md .. toctree:: :maxdepth: 2 - :caption: Quick Start Guides - :titlesonly: + :caption: OpenMS Applications and Tools - guides/user-guides/user-quickstart-guide - guides/contributors-quickstart-guide.md + openms-applications-and-tools/openms-applications.md + openms-applications-and-tools/topp-tools.md + openms-applications-and-tools/utils-tools.md + openms-applications-and-tools/command-line-interface.md + openms-applications-and-tools/visualize-with-openms.md .. toctree:: :maxdepth: 2 - :caption: Tutorials - :titlesonly: - - tutorials/TOPP/TOPP-tutorial - tutorials/TOPPAS/TOPPAS-tutorial - tutorials/KNIME/KNIME-tutorial - -.. toctree:: - :maxdepth: 2 - :caption: OpenMS TOPP Tools - :titlesonly: + :caption: Run Workflows with OpenMS Tools - topp-and-utils/topp-and-utils.md - topp-and-utils/adding-new-tool-to-topp.md + run-workflows-with-openms-tools/openms-in-knime.md + run-workflows-with-openms-tools/openms-in-nextflow.md + run-workflows-with-openms-tools/openms-on-galaxy.md .. toctree:: :maxdepth: 2 - :caption: Developer Resources - :titlesonly: + :caption: Tutorials and Quick Start Guides - additional-resources/developer-guidelines-for-addding-new-dependent-libraries.md - additional-resources/external-code-using-openms.md - advanced-resources/custom-compilation.md - advanced-resources/build-custom-openms-knime-package.md + tutorials-and-quickstart-guides/tutorials.md + tutorials-and-quickstart-guides/quickstart-guides.md .. toctree:: :maxdepth: 2 - :caption: OpenMS GitHub Workflow - :titlesonly: + :caption: Develop with OpenMS - additional-resources/openms-git-workflow.md - additional-resources/reporting-bugs-and-issues.md - additional-resources/write-and-label-github-issues.md - additional-resources/pull-request-checklist.md + develop-with-openms/openms-core-library.md + develop-with-openms/pyopenms.md + develop-with-openms/build-openms-from-source.md + develop-with-openms/link-external-code-to-openms.md + develop-with-openms/developer-tutorial.md + develop-with-openms/api-reference.md .. toctree:: :maxdepth: 2 - :caption: Frequently Asked Questions - :titlesonly: - - faqs/developer-faq.md - faqs/contributor-faq.md + :caption: Contribute to OpenMS + contribute-to-openms/openms-git-workflow.md + contribute-to-openms/write-and-label-github-issues.md + contribute-to-openms/adding-new-tool-to-topp.md + contribute-to-openms/pull-request-checklist.md + contribute-to-openms/advanced.md .. toctree:: :maxdepth: 2 @@ -116,16 +107,12 @@ Contents .. toctree:: :maxdepth: 2 - :caption: Glossary - - glossary.md - -.. toctree:: - :maxdepth: 2 - :caption: Contact Us - - contact-us + :caption: Quick Reference + quick-reference/contributor-faq.md + quick-reference/developer-faq.md + quick-reference/contact-us.md + quick-reference/glossary.md Indices and tables ================== diff --git a/docs/installations/installation-on-gnu-linux.md b/docs/installations/installation-on-gnu-linux.md index a8d7c3ed..cc76cabe 100644 --- a/docs/installations/installation-on-gnu-linux.md +++ b/docs/installations/installation-on-gnu-linux.md @@ -1,4 +1,4 @@ -Installation on GNU/Linux +GNU/Linux ========================= ## Install via Conda diff --git a/docs/installations/installation-on-macos.md b/docs/installations/installation-on-macos.md index 4e1769c3..8abfd65e 100644 --- a/docs/installations/installation-on-macos.md +++ b/docs/installations/installation-on-macos.md @@ -1,4 +1,4 @@ -Installation on macOS +macOS ==================== ## Install via macOS installer @@ -39,7 +39,7 @@ Make sure `` points to the folder where OpenMS is installed locally ## Install via Conda or Bioconda -Follow [these](installation-on-gnu-linux.md#install-via-conda) instructions. +Follow the [instructions](installation-on-gnu-linux.md#install-via-conda) . ## Build OpenMS from source diff --git a/docs/installations/installation-on-windows.md b/docs/installations/installation-on-windows.md index 9ba0b18a..5a5b41d5 100644 --- a/docs/installations/installation-on-windows.md +++ b/docs/installations/installation-on-windows.md @@ -1,4 +1,4 @@ -Installation on Windows +Windows ======================= ## Install via Windows installer diff --git a/docs/introduction.md b/docs/introduction.md deleted file mode 100644 index c8d6ef45..00000000 --- a/docs/introduction.md +++ /dev/null @@ -1,119 +0,0 @@ -Introduction -============ - -[OpenMS](http://www.openms.org/) -is an open-source software C++ library for {term}`LC-MS` data management and -analyses. It offers an infrastructure for rapid development of mass -spectrometry related software. OpenMS is free software available under the -three clause BSD license and runs under Windows, macOS, and Linux. - -```{note} -This introduction is aimed at users new to the field of LC-MS data analysis and will introduce some basics terms -and concepts. How to handle the data analysis, available data structures, algorithms and more are covered in the various -subsections of this documentation. -``` - -# Background - -Proteomics and metabolomics are interdisciplinary research fields that study structure, function, and interaction of -proteins and metabolites. They employ large-scale experimental techniques that allow acquiring data at the level of -cellular systems to whole organisms. Mass spectrometry combined with chromatographic separation is commonly used to -identify, characterize or quantify the amount of proteins and metabolites. - -In mass spectrometry-based proteomics and metabolomics, biological samples are extracted, prepared, and separated to -reduce sample complexity. The separated analytes are ionized and measured in the mass spectrometer. Mass and abundance -of ions are stored in mass spectra and used to identify and quantify the analytes in the sample using computational -methods. The quantity and identity of analytes can then be used, for instance, in biomarker discovery, medical diagnostics, -or basic research. - -## Liquid Chromatography(LC) - -LC aims to reduce the complexity of the measured sample by separating analytes based on their physicochemical properties. -Separating analytes in time ensures that a manageable amount of analytes elute at the same time. In mass -spectrometry-based proteomics, (high-pressure) liquid chromatographic separation techniques (HPLC) are methods of choice -to achieve a high degree of separation. In HPLC, {term}`peptides` are separated on a column. Solved in a pressurized liquid -(mobile phase) they are pumped through a solid adsorbent material (stationary phase) packet into a capillary column. -Physicochemical properties of each peptide determine how strongly it interacts with the stationary phase. The most -common HPLC technique in proteomics and metabolomics uses reversed-phase chromatography (RPC) columns. RPC employs a -hydrophobic stationary phase like {term}`octadecyl (C18)`, a nonpolar carbon chain bonded to a silica base, and a polar mobile -phase. Polar molecules interact weakly with the stationary phase and elute earlier, while non-polar molecules are retained. -Interaction can be further modulated by changing the gradient of solvent concentration in the mobile phase over time. -Elution times in LC are inherently prone to variation, for example, due to fluctuations in the flow rate of the mobile -phase or change of column. Retention time shifts between runs may be compensated using computational chromatographic -retention time alignment methods. In the {term}`LC-MS` setup, the column is directly coupled to the ion source of the mass -spectrometer. - -![](images/introduction/introduction_LC.png) - -## Mass Spectrometry - -MS is an analytical technique used to determine the {term}`mass` of molecules. In order to achieve highly accurate and sensitive -mass measurements at the atomic scale, mass spectrometers manipulate charged particles using magnetic and electrostatic -fields. - -![](images/introduction/introduction_MS.png) - -In a typical mass spectrometer, three principal components can be identified: - -- **Ion Source**: A mass spectrometer only handles {term}`ions`. Thus, charge needs first be transferred to uncharged - particles. The component responsible for the ionization is the ion source. Different types of ion sources and ionization - techniques exist with {term}`electrospray ionization (ESI)` being currently the most widely used ionization technique - for mass spectrometry-based proteomics. - -- **Mass Analyzer**: Most commonly used mass analyzer in proteomics are {term}`time-of-flight (TOF)` mass analyzers, - {term}`quadrupole mass filters`, and {term}`orbitrap analyzers`. In TOF mass analyzers, the ions are accelerated in an electric field. - The flight time of an ion allows calculating the velocity which in turn is used to calculate the mass-to-charge ratio - (m/z). Varying the electric field allows filtering certain mass-to-charge ratios before they enter the detector. In - quadrupole mass filters, ions pass through an oscillating electric field created by four parallel rods. For a - particular voltage, only ions in a certain mass-to-charge range will reach the detector. The orbitrap is an ion trap - mass analyzer (and detector) that traps ions in orbital motion between a barrel-like outer electrode and a spindle-like - central electrode allowing for prolonged mass measurement. As a result of the prolonged mass measurements, a high mass - resolution can be achieved. - -- **Detector**: The last component of the mass spectrometer is the detector. It determines the abundance of ions that - passed through the mass analyzer. Ion intensities (a value that relates to its abundance) and the mass-to-charge ratio - are recorded in a mass spectrum. - -A sample is measured over the retention time of the chromatography typically resulting in tens of thousands of spectra. -The measurement of one sample is called an MS run and the set of spectra called an {term}`MS(1)` map or peak map. - -![](images/introduction/spectrum_peakmap.png) - -The left image displays spectrum with peaks (m/z and intensity values) and the right image shows spectra stacked in -retention time yielding a peak map. - -In proteomics and metabolomics, the {term}`MS(1)` intensity is often used for the quantification of an analyte. Identification -based on the {term}`MS(1)` mass-to-charge and the isotope pattern is highly ambiguous. To improve identification, tandem mass -spectrometry {term}`(MS/MS)` can be applied to assess the analyte substructure. To this end, the precursor ion is isolated and -kinetically fragmented using an inert gas (e.g., Argon). Fragments produced by {term}`collision-induced dissociation (CID)` -are stored in an {term}`MS^2` (or {term}`MS/MS`) spectrum and provide information that helps to resolve the ambiguities in identification. -Alternatively, {term}`MS/MS` spectra can be used for quantification. - -Get started with installing OpenMS using the installers available for different operating systems! - -## Installation on different platforms - -```{tab} GNU/Linux - -```bash -wget https://abibuilder.informatik.uni-tuebingen.de/archive/openms/OpenMSInstaller/release/latest/OpenMS-2.8.0-Debian-Linux-x86_64.deb - -``` - -``` - -```{tab} Windows - -```bash -wget https://abibuilder.informatik.uni-tuebingen.de/archive/openms/OpenMSInstaller/release/latest/OpenMS-2.8.0-Win64.exe -``` - -``` - -```{tab} macOS - -```bash -wget https://abibuilder.informatik.uni-tuebingen.de/archive/openms/OpenMSInstaller/release/latest/OpenMS-2.8.0-macOS.dmg -``` - -``` diff --git a/docs/introduction/about-open-ms.md b/docs/introduction/about-open-ms.md new file mode 100644 index 00000000..abbff286 --- /dev/null +++ b/docs/introduction/about-open-ms.md @@ -0,0 +1,9 @@ +What is OpenMS? +=============== + +OpenMS is an open-source software platform designed for the analysis and visualization of high-throughput mass spectrometry data. OpenMS has been designed to operate on all platforms, and provides a flexible framework for users to access a wide range of built-in tools or build their own tools using the existing functionality. These tools can be applied separately to data or be applied in sequence (as a workflow or pipeline) to mass spectrometry data. OpenMS is well established and has been used widely in [literature](https://openms.github.io/publications/), particularly in the life sciences. + +Fields such as proteomics and metabolomics require the rapid, large-scale identification, quantification and characterization of biomolecules which traditional analytical techniques struggle to offer. OpenMS has been created by a team of biologists and computer scientists to create a completely open-source solution that offers customisable tools for high-throughput processing of mass spectrometry data. + +OpenMS provides a number of tools built from a C++ core library. These tools are collectively referred to as “The OpenMS PiPeline (TOPP) (formerly known as The OpenMS Proteomic Pipeline) tools. TOPP tools can be chained in a sequence to form workflows and can be applied to mass spectrometry data. +Note: TOPP’s capabilities have been expanded to apply to a wide range of areas in the life sciences. diff --git a/docs/introduction/background.md b/docs/introduction/background.md new file mode 100644 index 00000000..bfd913f7 --- /dev/null +++ b/docs/introduction/background.md @@ -0,0 +1,31 @@ +Background +========== + +OpenMS was primarily designed to process, analyze and visualize liquid chromatography - mass spectrometry (LC-MS) data. + +```{note} +OpenMS in recent times has been expanded to include other mass spectrometry methods. To design your experimental analysis solution, [contact the OpenMS team](../quick-reference/contact-us.md) today. +``` + +To understand how to use OpenMS, one must have a basic understanding of an LC-MS setup. + + +## Liquid Chromatography (LC) + +Liquid chromatography is an analytical technique used to separate analytes according to their physicochemical properties. A sample is transported via a liquid (known as the mobile phase) through a stationary phase which is packed into a capillary column. The time it takes for a separated analyte to move through the stationary phase (or how long it takes to elute) is known as its {term}`retention time`. Each analyte will have a different retention time, depending on how strongly the analyte interacts with the stationary phase. The total amount of analyte eluting from the column at every (retention) time point can be plotted as a {term}`chromatogram`. In LC-MS, the measured ion intensities are used as a proxy for the total amount. + +![liquid chromatography setup](../images/introduction/introduction_LC.png) + +## Mass Spectrometry + +Mass spectrometry is an analytical technique used to determine the abundance of molecules in a sample. There are three major components in a mass spectrometer: +- An **ion source**, which generates ions from the incoming sample. +- A **mass analyzer**, which separates the ions according to their mass-to-charge ratio. There are several types of mass analyzers. Depending on the mass analyzer used in the experiment, OpenMS offers calibration tools, so that highly accurate results can be achieved. +- A **detector**, which records the mass-to-charge ratio of each ion against their relative abundance in a plot known as a {term}`mass spectrum`. + +![mass spectrometry](../images/introduction/introduction_MS.png) + +## Liquid Chromatography - Mass Spectrometry +Liquid chromatography is often coupled with mass spectrometry in order to reduce complexity in the mass spectra. The separated analytes from the liquid chromatography setup are directly injected into the ion source from the mass spectrometry setup. Multiple analytes that elute at the same time are separated by mass using the mass spectrometer. + +![lc-ms setup](../images/introduction/hplc-mass-spectrometry-setup.png) diff --git a/docs/introduction/how-openms-works.md b/docs/introduction/how-openms-works.md new file mode 100644 index 00000000..0fc18ea2 --- /dev/null +++ b/docs/introduction/how-openms-works.md @@ -0,0 +1,24 @@ +How OpenMS Works +================ + +OpenMS has been structured so that users from a wide range of fields can access what they need to solve their particular problem, depending on their skillset. + +The following entry points for OpenMS and its TOPP tools are available for users: +- **Download the OpenMS C++ core library** + + As shown in the image below, TOPP tools have been created using the OpenMS core library and some external libraries, which are written in C++. Using the OpenMS core library directly provides faster access to tools and shorter run-times. Additional TOPP tools can also be developed, customized or extended based on the user’s needs. View the instructions to download the OpenMS core library here. +- **Install the pyOpenMs python library** + + Classes and methods originally written in C++ have been exposed to a Python interface (pyOpenMS) using python bindings. pyOpenMS was created for users with Python knowledge who want to quickly prototype new methods. View the instructions to install pyOpenMS here. + +- **Use command-line tools** + + All TOPP tools can be executed from a Command Line Interface (CLI) directly or using a shell script. By using a CLI, users can easily automate tasks and create workflows that can be saved, stored and used on multiple datasets. Command line interfaces include, but are not limited to PowerShell in Windows or Terminal in Linux or macOS. View the command-line usage quick start guide here. + +- **Use OpenMS graphical applications** + + When OpenMS is installed, a number of graphical user interfaces are available. Life science experts that want to quickly process their mass spectrometry data with the TOPP tools available can use this option. View the instructions to install OpenMS here. + +- **Use a supported workflow editor** + + Suppose you want to run the same sequence of TOPP tools on a number of data sets. You can use applications such as KNIME and Galaxy (where TOPP tools are available as a plugin), to apply predefined workflows or custom workflows you have designed on your data. KNIME and Galaxy are recommended over TOPPAS, which can also be used to create workflows however is no longer supported. diff --git a/docs/openms-applications-and-tools/command-line-interface.md b/docs/openms-applications-and-tools/command-line-interface.md new file mode 100644 index 00000000..2969b3f5 --- /dev/null +++ b/docs/openms-applications-and-tools/command-line-interface.md @@ -0,0 +1,38 @@ +Command Line Interface +====================== + +TOPP tools are designed to be called from the command line. OpenMS provides a Command Line Interface (CLI) called TOPP shell to easily execute TOPP tools on mass spectrometry data. However, you can configure the CLI of your choice to run TOPP tools. + +Command line calls will depend on the TOPP tools used, as each TOPP tool has its own set of parameters. However, the following arguments are typically used: + +- `-in` + + Specify an input file in the command line using the `-in` argument. The input file should have an mzML format. If not, use the file converter to convert the file to one using an mzML format. For more information, view the file handling documentation. +- `-out` + + Specify an output file in the command line using the `-out` argument. The output file should have an mzML format, the same format as the input file. +- `-ini` + + Specify an INI file in the command line using the `-ini` argument. TOPP uses INI files to set parameters specific to the command line tool being called. +- `-write_ini` + + Create an INI file using the `-write_ini` file argument. + Create an INI file with this call: + ` -write_ini ` + If you want a visual tool to assist setting parameters, use [INIFileEditor](graphical-topp-tools/ini-file-editor.md), an application provided when you download OpenMS. Otherwise, you can set the parameters from the command line. +- `-help` + + Get information about basic options related to the tool using the -help parameter. For more advanced options (algorithmic parameters), use `--help`. +- `--help` + + Get detailed information about algorithmic parameters using the `--help` parameter. + +Many (but not all) command line calls will have the following structure: + +```bash + -in -out -ini +``` + +The following command line call uses the FileFilter tool to extract data from an mzML file. Note, that this call directly specifies the tool-specific parameters and doesn’t rely on an INI file: + +![break down of example command line call](../images/topp/command-line-call.png) diff --git a/docs/openms-applications-and-tools/openms-applications.md b/docs/openms-applications-and-tools/openms-applications.md new file mode 100644 index 00000000..448a6733 --- /dev/null +++ b/docs/openms-applications-and-tools/openms-applications.md @@ -0,0 +1,21 @@ +OpenMS Applications +=================== + +OpenMS provides a suite of applications, designed for users who want easy access to TOPP tools. These applications include: +- **INIFileEditor** + + A GUI application used to edit INI files. INI files are files with the extension .ini and are common configuration files for all TOPP tools. + +- **TOPP shell** + + A Command Line Interface (CLI) that provides easy access to tools. Users don’t need to use TOPP shell; instead, they can configure their own CLI to directly use TOPP tools. +- **TOPPView** + + A GUI application used to inspect, visualize and compare mass spectrometry data. Read more in-depth documentation about TOPPView. + +- **TOPPAS (deprecated)** + + A GUI application used to apply multiple tools sequentially on mass spectrometry data. Applying multiple tools in a sequence is referred to as a workflow or a pipeline. OpenMS no longer supports TOPPAS and instead recommends the use of [KNIME](https://www.knime.com/), for which we provide a community plugin. + +- **SwathWizard** +An application for SWATH analysis. SwathWizard is used to analyze DIA swath data. diff --git a/docs/openms-applications-and-tools/topp-tools.md b/docs/openms-applications-and-tools/topp-tools.md new file mode 100644 index 00000000..49596b8d --- /dev/null +++ b/docs/openms-applications-and-tools/topp-tools.md @@ -0,0 +1,13 @@ +TOPP Tools +========== + +The following sections introduce TOPP, some general concepts and more specific information regarding each tool. + +```{toctree} +:maxdepth: 1 + +topp-tools/introduction-to-topp.md +topp-tools/key-concepts.md +topp-tools/types-of-topp-tools.md + +``` diff --git a/docs/openms-applications-and-tools/topp-tools/introduction-to-topp.md b/docs/openms-applications-and-tools/topp-tools/introduction-to-topp.md new file mode 100644 index 00000000..c4217c7b --- /dev/null +++ b/docs/openms-applications-and-tools/topp-tools/introduction-to-topp.md @@ -0,0 +1,6 @@ +Introduction to TOPP +==================== + +OpenMS provides a vast array of tools called TOPP tools that automate typical mass processing tasks. They can be either: +- Executed from the command line or, +- Applied using graphical applications. diff --git a/docs/openms-applications-and-tools/topp-tools/key-concepts.md b/docs/openms-applications-and-tools/topp-tools/key-concepts.md new file mode 100644 index 00000000..24a7e0f4 --- /dev/null +++ b/docs/openms-applications-and-tools/topp-tools/key-concepts.md @@ -0,0 +1,46 @@ +Key Concepts +============ + +Before using TOPP tools, there are a number of concepts to understand. These include: +- **TOPP INI files** + + TOPP INI files are XML-based files with an `.ini extension`. OpenMS uses TOPP INI files to set parameters for one or more TOPP tools. Alternatively, the command line can be used to set TOPP tool parameters. + Here is an example of a TOPP INI file: + + ```xml + + + + + + + + + + + + + + + + + + + + +``` +- **Features, feature maps and featureXML files** + + An LC-MS feature is a construct in OpenMS that is used to describe a 2D peak caused by an analyte interacting with the stationary phase. Each feature contains the following metadata: an id, retention time, mass-to-charge ratio, intensity, overall quality and one or more convex hulls. + + A feature map is a container for features. One feature map can contain many features. + + A featureXML file is an XML based file which contains one feature map. + + FeatureXML files can be created from mzML files using OpenMS’s feature detection algorithms. + +- **Consensus feature, consensus maps, consensusXML files** + + A consensus feature is a special type of LC-MS feature that is quantified across multiple experiments. A consensus feature is formed by linking or grouping features with similar mass-to-charge ratios and intensities from various experiment runs. Each consensus feature references the features used to form the consensus feature. + + Similar to a feature map, a consensus map is a container for consensus features. One consensus map can contain many consensus features. diff --git a/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools.md b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools.md new file mode 100644 index 00000000..806172a9 --- /dev/null +++ b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools.md @@ -0,0 +1,16 @@ +Types of TOPP Tools +=================== + +The following tools are offered: + +```{toctree} +:maxdepth: 1 + +types-of-topp-tools/graphical-tools.md +types-of-topp-tools/file-handling.md +types-of-topp-tools/signal-processing-and-preprocessing.md +types-of-topp-tools/quantitation.md +types-of-topp-tools/map-alignment.md +types-of-topp-tools/protein-and-peptide-identification.md + +``` diff --git a/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/file-handling.md b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/file-handling.md new file mode 100644 index 00000000..b19a115b --- /dev/null +++ b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/file-handling.md @@ -0,0 +1,61 @@ +File Handling +============= + +File Handling +============ + +## General information about peak and feature maps + +For general information about a peak or feature map, use the **FileInfo** tool. + +- It can print RT, m/z and intensity ranges, the overall number of peaks, and the distribution of MS levels. +- It can print a statistical summary of intensities. +- It can print some meta information. +- It can validate XML files against their schema. +- It can check for corrupt data in peak files See the `FileInfo –help` for details. + +## Problems with input files + +If you are experiencing problems while processing an XML file, check if the file does validate against the XML schema: + +`FileInfo -v -in infile.mzML` + +Validation is available for several file formats including mzML, mzData, mzXML, featureXML and idXML. + +Another frequently-occurring problem is corrupt data. You can check for corrupt data in peak files with `FileInfo` as well: + +`FileInfo -c -in infile.mzML` + +## Converting your files to mzML + +The TOPP tools work only on the HUPO-PSI `mzML` format. If you need to convert *mzData*, *mzXML* or *ANDI/MS* data to +*mzML*, use the FileConverter, e.g. + +`FileConverter -in infile.mzXML -out outfile.mzML` + +For format names as file extension, the tool derives the format from the extension. For other extensions, the file +formats of the input and output file can be given explicitly. + +## Converting between DTA and mzML + +Sequest DTA files can be extracted from a mzML file using the `DTAExtractor`: + +`DTAExtractor -in infile.mzML -out outfile` + +The retention time of a scan, the precursor mass-to-charge ratio (for MS/MS scans) and the file extension are appended +to the output file name. + +To combine several files (e.g. DTA files) to an `mzML` file use the `FileMerger`: + +`FileMerger -in infile_list.txt -out outfile.mzML` + +The retention times of the scans can be generated, taken from the `infile_list.txt` or can be extracted from the DTA +file names. See the FileMerger documentation for details. + +## Extracting part of the data from a file + +To extract part of the data from an `mzML` file, use the `FileFilter` tool. It allows filtering for RT, `m/z` and +intensity range or for MS level. To extract the MS/MS scans between retention time `100` and `1500`, use the following +command: + +`FileFilter -in infile.mzML -levels 2 -rt 100:1500 -out outfile.mzML` diff --git a/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/graphical-tools.md b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/graphical-tools.md new file mode 100644 index 00000000..eeb1dd78 --- /dev/null +++ b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/graphical-tools.md @@ -0,0 +1,19 @@ +Graphical Tools +=============== + +OpenMS provides a suite of graphical applications, designed for users who want easy access to TOPP tools. These applications include: +- [INIFileEditor](graphical-topp-tools/ini-file-editor.md) + + A GUI application used to edit INI files. INI files are files with the extension .ini and are a common input file for mass spectrometry data. +- TOPP shell + + A Command Line Interface (CLI) that provides easy access to tools. Users don’t need to use TOPP shell; instead, they can configure their own CLI to directly use TOPP tools. +- [TOPPView](graphical-topp-tools/toppview.md) + + A GUI application used to inspect, visualize and compare mass spectrometry data. Read more in-depth documentation about TOPPView. +- [TOPPAS (deprecated)](graphical-topp-tools/toppas.md) + + A GUI application used to apply multiple tools sequentially on mass spectrometry data. Applying multiple tools in a sequence is referred to as a workflow or a pipeline. OpenMS no longer supports TOPPAS and instead recommends the use of [KNIME](https://www.knime.com/), for which we provide a community plugin. +- [SwathWizard](graphical-topp-tools/swathwizard.md) + + An application for SWATH analysis. SwathWizard is used to analyze DIA swath data. diff --git a/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/map-alignment.md b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/map-alignment.md new file mode 100644 index 00000000..1967bbac --- /dev/null +++ b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/map-alignment.md @@ -0,0 +1,21 @@ +Map Alignment +============= + +## Map alignment + +The goal of map alignment is to transform different HPLC-MS maps (or derived maps) to a common retention time axis. It +corrects for shifted and scaled retention times, which may result from changes of the chromatography. + +The different **MapAligner** tools take `n` input maps, de-warp them and store the `n` de-warped maps. The following +image shows the general procedure: + +![TOPP Alignment](../../images/tutorials/topp/TOPP_alignment.png) + +There are different map alignment tools available. The following table gives a rough overview of them: + +| Tool | Applicable To | Description | +|-------------|---------------|-------------| +| `MapAlignerPoseClustering` | feature maps, peak maps | This algorithm does a star-wise alignment of the input data. The center of the star is the map with most data points. All other maps are then aligned to the center map by estimating a linear transformation (shift and scaling) of retention times. The transformation is estimated using a pose clustering approach as described in doi:10.1093/bioinformatics/btm209 | +| `MapAlignerIdentification` | feature maps, consensus maps, identifications | This algorithm utilizes peptide identifications, and is thus applicable to files containing peptide IDs (idXML, annotated featureXML/consensusXML). It finds peptide sequences that different input files have in common and uses them as points of correspondence. From the retention times of these peptides, transformations are computed that convert each file to a consensus time scale. | +| `MapAlignerSpectrum` | peak maps | This *experimental* algorithm uses a dynamic-programming approach based on spectrum similarity for the alignment. The resulting retention time mapping of dynamic-programming is then smoothed by fitting a spline to the retention time pairs. | +| `MapRTTransformer` | peak maps, feature maps, consensus maps, identifications | This algorithm merely *applies* a set of transformations that are read from files (in TransformationXML format). These transformations might have been generated by a previous invocation of a MapAligner tool. For example, compute a transformation based on identifications and then apply it to the features or raw data. The transformation file format is not very complicated, so it is relatively easy to write (or generate) the transformation files | diff --git a/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/protein-and-peptide-identification.md b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/protein-and-peptide-identification.md new file mode 100644 index 00000000..71d60818 --- /dev/null +++ b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/protein-and-peptide-identification.md @@ -0,0 +1,2 @@ +Protein and Peptide Identification +================================== diff --git a/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/quantitation.md b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/quantitation.md new file mode 100644 index 00000000..aacd5212 --- /dev/null +++ b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/quantitation.md @@ -0,0 +1,2 @@ +Quantitation +============ diff --git a/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/signal-processing-and-preprocessing.md b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/signal-processing-and-preprocessing.md new file mode 100644 index 00000000..bb58b12d --- /dev/null +++ b/docs/openms-applications-and-tools/topp-tools/types-of-topp-tools/signal-processing-and-preprocessing.md @@ -0,0 +1,2 @@ +Signal Processing and Preprocessing +=================================== diff --git a/docs/openms-applications-and-tools/utils-tools.md b/docs/openms-applications-and-tools/utils-tools.md new file mode 100644 index 00000000..4bd48f03 --- /dev/null +++ b/docs/openms-applications-and-tools/utils-tools.md @@ -0,0 +1,10 @@ +Utils Tools +=========== + +```{toctree} +:maxdepth: 1 + +utils-tools/introduction-to-utils.md +utils-tools/key-concepts-utils.md +utils-tools/types-of-utils-tools.md +``` diff --git a/docs/openms-applications-and-tools/utils-tools/introduction-to-utils.md b/docs/openms-applications-and-tools/utils-tools/introduction-to-utils.md new file mode 100644 index 00000000..c19205ac --- /dev/null +++ b/docs/openms-applications-and-tools/utils-tools/introduction-to-utils.md @@ -0,0 +1,2 @@ +Introduction to UTILS +===================== diff --git a/docs/openms-applications-and-tools/utils-tools/key-concepts-utils.md b/docs/openms-applications-and-tools/utils-tools/key-concepts-utils.md new file mode 100644 index 00000000..6126fa8b --- /dev/null +++ b/docs/openms-applications-and-tools/utils-tools/key-concepts-utils.md @@ -0,0 +1,2 @@ +Key Concepts (Utils) +==================== diff --git a/docs/openms-applications-and-tools/utils-tools/types-of-utils-tools.md b/docs/openms-applications-and-tools/utils-tools/types-of-utils-tools.md new file mode 100644 index 00000000..1f2999f0 --- /dev/null +++ b/docs/openms-applications-and-tools/utils-tools/types-of-utils-tools.md @@ -0,0 +1,17 @@ +Types of UTILS Tools +==================== + +There are also a number of tools in the beta stage called UTILS. They include but are not limited to: + +- Signal processing and preprocessing +- File handling +- Algorithm evaluation +- Protein/peptide identification +- Cross-linking +- Quantitation +- Metabolite identification +- Targeted experiments and OpenSWATH +- RNA +- Quality control + +For the full list of UTILS tools, visit the [API Reference](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/UTILS_documentation.html) website. diff --git a/docs/openms-applications-and-tools/visualize-with-openms.md b/docs/openms-applications-and-tools/visualize-with-openms.md new file mode 100644 index 00000000..37b995ce --- /dev/null +++ b/docs/openms-applications-and-tools/visualize-with-openms.md @@ -0,0 +1,2 @@ +Visualize with OpenMS +===================== diff --git a/docs/contact-us.md b/docs/quick-reference/contact-us.md similarity index 100% rename from docs/contact-us.md rename to docs/quick-reference/contact-us.md diff --git a/docs/faqs/contributor-faq.md b/docs/quick-reference/contributor-faq.md similarity index 100% rename from docs/faqs/contributor-faq.md rename to docs/quick-reference/contributor-faq.md diff --git a/docs/faqs/developer-faq.md b/docs/quick-reference/developer-faq.md similarity index 100% rename from docs/faqs/developer-faq.md rename to docs/quick-reference/developer-faq.md diff --git a/docs/glossary.md b/docs/quick-reference/glossary.md similarity index 71% rename from docs/glossary.md rename to docs/quick-reference/glossary.md index 764ae707..cabd225c 100644 --- a/docs/glossary.md +++ b/docs/quick-reference/glossary.md @@ -4,52 +4,17 @@ OpenMS Glossary A glossary of common terms used throughout OpenMS documentation. ```{glossary} - -OpenMS API - [OpenMS API Reference](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/index.html). - The object-oriented OpenMS core library contains over 1,300 classes and is built on modern C++ infrastructure - with native compiler support on Windows, Linux and macOS. The classes are representing core concepts in mass - spectrometry as well as the corresponding ontologies defined by the Human Proteome Organization Proteomics - Standard Initiative (HUPO-PSI). - -Workflow - A set of over 185 different tools for common mass spectrometric tasks can be accessed by routine users through - the KNIME, and Galaxy workflow systems. - -SILAC - **S**table **I**sotope **L**abeling by/with **A**mino acids in **C**ell culture is a technique based on mass - spectrometry that detects differences in protein abundance among samples using non-radioactive isotopic labeling. - -iTRAQ - **I**sobaric **T**ags for **R**elative and **A**bsolute **A**uantitation (iTRAQ) is an isobaric labeling method - used in quantitative proteomics by tandem mass spectrometry to determine the amount of proteins from different - sources in a single experiment. - -TMT - A **T**andem **M**ass **T**ag (TMT) is a chemical label that facilitates sample multiplexing in mass spectrometry - ({term}`MS`)-based quantification and identification of biological macromolecules such as proteins, {term}`peptides` - and nucleic acids. - -SRM - **S**elected **R**eaction **M**onitoring (SRM), also called Multiple reaction monitoring, (MRM), is a method used - in tandem mass spectrometry in which an ion of a particular mass is selected in the first stage of a tandem mass - spectrometer and an ion product of a fragmentation reaction of the precursor ions is selected in the second mass - spectrometer stage for detection. - -SWATH - SWATH-mass spectrometry consists of data-independent acquisition and a targeted data analysis strategy that aims - to maintain the favorable quantitative characteristics (accuracy, sensitivity, and selectivity) of targeted - proteomics at large scale. - -KNIME - **K**onstanz **I**nformation **M**iner, is a free and open-source data analytics, reporting and integration platform. +:sorted: LC-MS [Liquid Chromatography(LC)](introduction.md#liquid-chromatography-lc) and [Mass Spectrometry(MS)](introduction.md#mass-spectrometry). -Peptides +peptides A short chain of amino acids. +FASTA format + A text-based format for representing nucleotide or amino acid sequences. + Octadecyl(C18) An alkyl radical C(18)H(37) derived from an octadecane by removal of one hydrogen atom. @@ -57,28 +22,28 @@ Mass Mass is a measure of the amount of matter that an object contains. In comparison to often used term weight, which is a measure of the force of gravity on that object. -Ion +ion Any {term}`atom` or group of atoms that bears one or more positive or negative electrical charges. Positively charged are cations, negavtively charged anions. -Atom +atom An atom is the smallest unit of ordinary matter that forms a chemical element. -Electrospray ionization +electrospray ionization A technique used in mass spectrometry to produce ions using an electrospray in which a high voltage is applied to a liquid to create an {term}`aerosol`. -Aerosol +aerosol An aerosol is a suspension of fine solid particles or liquid droplets in air or another gas. -Time-of-flight (TOF) +time-of-flight (TOF) A measurement of the time taken by an object, particle of wave (be it acoustic, electromagnetic, e.t.c) to travel a distance through a medium. -Quadrupole mass filters +quadrupole mass filters A mass filter allowing one mass channel at a time to reach the detector as the mass range is scanned. -Orbitrap analyzers +orbitrap analyzers In mass spectrometry, an ion trap mass analyzer consisting of an outer barrel-like electrode and a coaxial inner spindle-like electrode that traps ions in an orbital motion around the spindle. A high resoltion mass spectrometry analyzer. @@ -95,12 +60,12 @@ MS/MS Tandem mass spectrometry, MS^2^, a technique where two or more mass analyzers are coupled together using an additional reaction step to increase their abilities to analyse chemical samples. -Collision-induced dissociation (CID) +collision-induced dissociation (CID) A mass spectrometry technique to induce fragmentation of selected ions in the gas phase. Also known as Collision induced dissociation. TOPP - The OpenMS Proteomics Pipeline. + The OpenMS Pipeline. MSGFPlusAdapter Adapter for the MS-GF+ protein identification (database search) engine. More information is available [here](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/TOPP_MSGFPlusAdapter.html). @@ -126,10 +91,10 @@ TOPPView [Nightly Snapshot](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/index.html) Untested installers and containers are known as the nightly snapshot. -Proteomics +proteomics Proteomics is the large-scale study of proteins. -Proteins +proteins Proteins are vital parts of living organisms, with many functions, for example composing the structural fibers of muscle to the enzymes that catalyze the digestion of food to synthesizing and replicating DNA. @@ -152,10 +117,10 @@ mzXML mzXML is an open data format for storage and exchange of mass spectroscopy data, developed at the SPC/Institute for Systems Biology. -Spectra - Singluar of spectrum. +spectra + Singular of spectrum. -Spectrum +mass spectrum A mass spectrum is a type of plot of the ion signal as a function of the mass-to-charge ratio. These spectra are used to determine the elemental or isotopic signature of a sample, the masses of particles and of molecules, and to elucidate the chemical identity or structure of molecules and other chemical compounds. @@ -163,8 +128,8 @@ Spectrum m/z mass to charge ratio. -RT - Retention time (RT). +retention time + retention time (RT) in liquid chromatography, is the time it takes for a separated analyte to move through the stationary phase. ProteoWizard ProteoWizard is a set of open-source, cross-platform tools and libraries for proteomics data analyses. It provides a @@ -177,11 +142,13 @@ OMSSA PepNovo PepNovo is a de novo sequencing algorithm for {term}`MS/MS` {term}`spectra`. -De novo peptide sequencing +de novo peptide sequencing A peptide’s amino acid sequence is inferred directly from the precursor peptide mass and tandem mass spectrum ({term}`MS/MS` or {term}`MS^3`) fragment ions, without comparison to a reference proteome. TOPPAS An assistant for GUI-driven TOPP workflow design. It is recommended to use OpenMS through the KNIME plugins. -``` +chromatogram + A two-dimensional plot that describes the amount of analyte eluted from a chromatography versus the analyte's retention time. +``` diff --git a/docs/run-workflows-with-openms-tools/openms-in-knime.md b/docs/run-workflows-with-openms-tools/openms-in-knime.md new file mode 100644 index 00000000..b653f42c --- /dev/null +++ b/docs/run-workflows-with-openms-tools/openms-in-knime.md @@ -0,0 +1,10 @@ +OpenMS in KNIME +=============== + +```{toctree} +:maxdepth: 1 + +openms-in-knime/getting-started.md +openms-in-knime/installation.md +openms-in-knime/workflows.md +``` diff --git a/docs/run-workflows-with-openms-tools/openms-in-knime/getting-started.md b/docs/run-workflows-with-openms-tools/openms-in-knime/getting-started.md new file mode 100644 index 00000000..3ce1d78a --- /dev/null +++ b/docs/run-workflows-with-openms-tools/openms-in-knime/getting-started.md @@ -0,0 +1,2 @@ +Getting Started +=============== diff --git a/docs/run-workflows-with-openms-tools/openms-in-knime/installation.md b/docs/run-workflows-with-openms-tools/openms-in-knime/installation.md new file mode 100644 index 00000000..11e44375 --- /dev/null +++ b/docs/run-workflows-with-openms-tools/openms-in-knime/installation.md @@ -0,0 +1,2 @@ +Installation +============ diff --git a/docs/run-workflows-with-openms-tools/openms-in-knime/workflows.md b/docs/run-workflows-with-openms-tools/openms-in-knime/workflows.md new file mode 100644 index 00000000..a3745af4 --- /dev/null +++ b/docs/run-workflows-with-openms-tools/openms-in-knime/workflows.md @@ -0,0 +1,2 @@ +Workflows +========= diff --git a/docs/run-workflows-with-openms-tools/openms-in-nextflow.md b/docs/run-workflows-with-openms-tools/openms-in-nextflow.md new file mode 100644 index 00000000..960e423e --- /dev/null +++ b/docs/run-workflows-with-openms-tools/openms-in-nextflow.md @@ -0,0 +1,10 @@ +OpenMS in Nextflow +================== + +```{toctree} +:maxdepth: 1 + +openms-in-nextflow/getting-started.md +openms-in-nextflow/installation.md +openms-in-nextflow/workflows.md +``` diff --git a/docs/run-workflows-with-openms-tools/openms-in-nextflow/getting-started.md b/docs/run-workflows-with-openms-tools/openms-in-nextflow/getting-started.md new file mode 100644 index 00000000..3ce1d78a --- /dev/null +++ b/docs/run-workflows-with-openms-tools/openms-in-nextflow/getting-started.md @@ -0,0 +1,2 @@ +Getting Started +=============== diff --git a/docs/run-workflows-with-openms-tools/openms-in-nextflow/installation.md b/docs/run-workflows-with-openms-tools/openms-in-nextflow/installation.md new file mode 100644 index 00000000..11e44375 --- /dev/null +++ b/docs/run-workflows-with-openms-tools/openms-in-nextflow/installation.md @@ -0,0 +1,2 @@ +Installation +============ diff --git a/docs/run-workflows-with-openms-tools/openms-in-nextflow/workflows.md b/docs/run-workflows-with-openms-tools/openms-in-nextflow/workflows.md new file mode 100644 index 00000000..a3745af4 --- /dev/null +++ b/docs/run-workflows-with-openms-tools/openms-in-nextflow/workflows.md @@ -0,0 +1,2 @@ +Workflows +========= diff --git a/docs/run-workflows-with-openms-tools/openms-on-galaxy.md b/docs/run-workflows-with-openms-tools/openms-on-galaxy.md new file mode 100644 index 00000000..1323acd3 --- /dev/null +++ b/docs/run-workflows-with-openms-tools/openms-on-galaxy.md @@ -0,0 +1,10 @@ +OpenMS on Galaxy +================ + +```{toctree} +:maxdepth: 1 + +openms-on-galaxy/getting-started.md +openms-on-galaxy/installation.md +openms-on-galaxy/workflows.md +``` diff --git a/docs/run-workflows-with-openms-tools/openms-on-galaxy/getting-started.md b/docs/run-workflows-with-openms-tools/openms-on-galaxy/getting-started.md new file mode 100644 index 00000000..3ce1d78a --- /dev/null +++ b/docs/run-workflows-with-openms-tools/openms-on-galaxy/getting-started.md @@ -0,0 +1,2 @@ +Getting Started +=============== diff --git a/docs/run-workflows-with-openms-tools/openms-on-galaxy/installation.md b/docs/run-workflows-with-openms-tools/openms-on-galaxy/installation.md new file mode 100644 index 00000000..11e44375 --- /dev/null +++ b/docs/run-workflows-with-openms-tools/openms-on-galaxy/installation.md @@ -0,0 +1,2 @@ +Installation +============ diff --git a/docs/run-workflows-with-openms-tools/openms-on-galaxy/workflows.md b/docs/run-workflows-with-openms-tools/openms-on-galaxy/workflows.md new file mode 100644 index 00000000..a3745af4 --- /dev/null +++ b/docs/run-workflows-with-openms-tools/openms-on-galaxy/workflows.md @@ -0,0 +1,2 @@ +Workflows +========= diff --git a/docs/tutorials/TOPP/calibration.md b/docs/topp-command-line-tools/calibration.md similarity index 100% rename from docs/tutorials/TOPP/calibration.md rename to docs/topp-command-line-tools/calibration.md diff --git a/docs/tutorials/TOPP/consensus-peptide-identification.md b/docs/topp-command-line-tools/consensus-peptide-identification.md similarity index 100% rename from docs/tutorials/TOPP/consensus-peptide-identification.md rename to docs/topp-command-line-tools/consensus-peptide-identification.md diff --git a/docs/tutorials/TOPP/conversion-between-openms-xml-formats-and-text-formats.md b/docs/topp-command-line-tools/conversion-between-openms-xml-formats-and-text-formats.md similarity index 100% rename from docs/tutorials/TOPP/conversion-between-openms-xml-formats-and-text-formats.md rename to docs/topp-command-line-tools/conversion-between-openms-xml-formats-and-text-formats.md diff --git a/docs/tutorials/TOPP/data-analysis-in-toppview.md b/docs/topp-command-line-tools/data-analysis-in-toppview.md similarity index 100% rename from docs/tutorials/TOPP/data-analysis-in-toppview.md rename to docs/topp-command-line-tools/data-analysis-in-toppview.md diff --git a/docs/tutorials/TOPP/data-editing-in-toppview.md b/docs/topp-command-line-tools/data-editing-in-toppview.md similarity index 100% rename from docs/tutorials/TOPP/data-editing-in-toppview.md rename to docs/topp-command-line-tools/data-editing-in-toppview.md diff --git a/docs/tutorials/TOPP/display-modes-and-view-options.md b/docs/topp-command-line-tools/display-modes-and-view-options.md similarity index 100% rename from docs/tutorials/TOPP/display-modes-and-view-options.md rename to docs/topp-command-line-tools/display-modes-and-view-options.md diff --git a/docs/tutorials/TOPP/feature-detection-on-centroided-data.md b/docs/topp-command-line-tools/feature-detection-on-centroided-data.md similarity index 100% rename from docs/tutorials/TOPP/feature-detection-on-centroided-data.md rename to docs/topp-command-line-tools/feature-detection-on-centroided-data.md diff --git a/docs/tutorials/TOPP/feature-detection.md b/docs/topp-command-line-tools/feature-detection.md similarity index 100% rename from docs/tutorials/TOPP/feature-detection.md rename to docs/topp-command-line-tools/feature-detection.md diff --git a/docs/tutorials/TOPP/feature-grouping.md b/docs/topp-command-line-tools/feature-grouping.md similarity index 100% rename from docs/tutorials/TOPP/feature-grouping.md rename to docs/topp-command-line-tools/feature-grouping.md diff --git a/docs/tutorials/TOPP/file-handling.md b/docs/topp-command-line-tools/file-handling.md similarity index 100% rename from docs/tutorials/TOPP/file-handling.md rename to docs/topp-command-line-tools/file-handling.md diff --git a/docs/tutorials/TOPP/map-alignment.md b/docs/topp-command-line-tools/map-alignment.md similarity index 100% rename from docs/tutorials/TOPP/map-alignment.md rename to docs/topp-command-line-tools/map-alignment.md diff --git a/docs/tutorials/TOPP/peptide-property-prediction.md b/docs/topp-command-line-tools/peptide-property-prediction.md similarity index 100% rename from docs/tutorials/TOPP/peptide-property-prediction.md rename to docs/topp-command-line-tools/peptide-property-prediction.md diff --git a/docs/tutorials/TOPP/picking-peaks.md b/docs/topp-command-line-tools/picking-peaks.md similarity index 100% rename from docs/tutorials/TOPP/picking-peaks.md rename to docs/topp-command-line-tools/picking-peaks.md diff --git a/docs/tutorials/TOPP/profile-data-processing.md b/docs/topp-command-line-tools/profile-data-processing.md similarity index 100% rename from docs/tutorials/TOPP/profile-data-processing.md rename to docs/topp-command-line-tools/profile-data-processing.md diff --git a/docs/tutorials/TOPP/quality-control.md b/docs/topp-command-line-tools/quality-control.md similarity index 100% rename from docs/tutorials/TOPP/quality-control.md rename to docs/topp-command-line-tools/quality-control.md diff --git a/docs/tutorials/TOPP/smoothing-raw-data.md b/docs/topp-command-line-tools/smoothing-raw-data.md similarity index 100% rename from docs/tutorials/TOPP/smoothing-raw-data.md rename to docs/topp-command-line-tools/smoothing-raw-data.md diff --git a/docs/tutorials/TOPP/subtracting-a-baseline-from-a-spectrum.md b/docs/topp-command-line-tools/subtracting-a-baseline-from-a-spectrum.md similarity index 100% rename from docs/tutorials/TOPP/subtracting-a-baseline-from-a-spectrum.md rename to docs/topp-command-line-tools/subtracting-a-baseline-from-a-spectrum.md diff --git a/docs/guides/contributors-quickstart-guide.md b/docs/tutorials-and-quickstart-guides/guides/contributors-quickstart-guide.md similarity index 98% rename from docs/guides/contributors-quickstart-guide.md rename to docs/tutorials-and-quickstart-guides/guides/contributors-quickstart-guide.md index f89bbd15..a3b72a60 100644 --- a/docs/guides/contributors-quickstart-guide.md +++ b/docs/tutorials-and-quickstart-guides/guides/contributors-quickstart-guide.md @@ -1,5 +1,5 @@ -Contribute to OpenMS -==================== +Contributor's Quick Start Guide +=============================== To contribute to OpenMS: diff --git a/docs/guides/user-guides/user-quickstart-guide.md b/docs/tutorials-and-quickstart-guides/guides/user-quickstart-guide.md similarity index 100% rename from docs/guides/user-guides/user-quickstart-guide.md rename to docs/tutorials-and-quickstart-guides/guides/user-quickstart-guide.md diff --git a/docs/tutorials-and-quickstart-guides/quickstart-guides.md b/docs/tutorials-and-quickstart-guides/quickstart-guides.md new file mode 100644 index 00000000..c78f5c6b --- /dev/null +++ b/docs/tutorials-and-quickstart-guides/quickstart-guides.md @@ -0,0 +1,9 @@ +Quick Start Guides +================== + +```{toctree} +:maxdepth: 1 + +guides/contributors-quickstart-guide.md +guides/user-quickstart-guide.md +``` diff --git a/docs/tutorials-and-quickstart-guides/tutorials.md b/docs/tutorials-and-quickstart-guides/tutorials.md new file mode 100644 index 00000000..5db0e369 --- /dev/null +++ b/docs/tutorials-and-quickstart-guides/tutorials.md @@ -0,0 +1,164 @@ +Tutorials +========= + +The following tutorials provide the opportunity to complete a real-world example while also seeing the different methods OpenMS makes available to complete the same task. + +There are four ways to use OpenMS to complete a task. For example, say you want to read a file and store the information in an output file. You can do this by: + +- **Using TOPP shell** to run a shell script or execute a command directly. +- **Using pyOpenMS** and creating and running a python script. +- **Using TOPPView**, a graphical user interface provided by OpenMS. +- **Constructing a workflow in KNIME**, which can be saved and executed on multiple input files + +The following sections explain how to read a file and store the information in an output file using these four different methods. + +## Using TOPP shell + +As explained in the command-line quick start guide, TOPP shell is available for those who are comfortable with executing command line tools and writing scripts. + +To read the information of a file, just type the following in the command line and press Enter. + +```bash +FileInfo -in -out +``` + +You can also copy and paste this into a shell script (file with an .sh extension), and then type bash in the command line to execute the script. + +## Using pyOpenMS + +You can replicate the functionality of the `FileInfo` TOPP tool in pyOpenMS, using one of the following examples, depending on the type of file you want to get information about. + +- Example for `mzML` file + + ```python + from pyopenms import * + + exp = MSExperiment() + MzMLFile().load("sample.mzML", exp) + exp.updateRanges() + + ms_levels = exp.getMSLevels() + num_spectra = {level: 0 for level in ms_levels} + + for spec in exp: + num_spectra[spec.getMSLevel()] += 1 + + print("Instrument:") + for analyzer in exp.getInstrument().getMassAnalyzers(): + print(f"\tMass Analyzer: {analyzer.getType()} (resolution: {analyzer.getResolution()})") + + print("\nMS levels: "+", ".join([str(level) for level in ms_levels])) + print(f"Total number of peaks: {sum([spec.size() for spec in exp])}") + print(f"Total number of spectra: {exp.size()}") + + print("\nRanges:") + print(f"\tretention time: {exp.getMinRT()} .. {exp.getMaxRT()} ({round((exp.getMaxRT()-exp.getMinRT())/60, 2)} min)") + print(f"\tmass-to-charge: {exp.getMinMZ()} .. {exp.getMaxMZ()}") + print(f"\tintensity: {exp.getMinIntensity()} .. {exp.getMaxIntensity()}") + + print("\nNumber of spectra per MS level:") + for level, number in num_spectra.items(): + print(f"\tlevel {level}: {number}") + ``` + - Example for `featureXML` file + + ```python + feature_map = FeatureMap() + FeatureXMLFile().load("sample.featureXML", feature_map) + + charges = {} + number_of_ids = {} + tic = 0 + + for feature in feature_map: + charge = feature.getCharge() + if charge in charges.keys(): + charges[charge] += 1 + else: + charges[charge] = 1 + num_ids = len(feature.getPeptideIdentifications()) + if num_ids in number_of_ids.keys(): + number_of_ids[num_ids] += 1 + else: + number_of_ids[num_ids] = 1 + tic += feature.getIntensity() + + print(f"Number of features: {feature_map.size()}") + + print("\nRanges:") + print(f"\tretention time: {feature_map.getMinRT()} .. {feature_map.getMaxRT()} ({round((feature_map.getMaxRT()-feature_map.getMinRT())/60, 2)} min)") + print(f"\tmass-to-charge: {feature_map.getMinMZ()} .. {feature_map.getMaxMZ()}") + print(f"\tintensity: {feature_map.getMinIntensity()} .. {feature_map.getMaxIntensity()}") + + print(f"\nTotal ion current in features: {int(tic)}") + + print("\nCharge distribution:") + for charge, occurence in charges.items(): + print(f"\tcharge {charge}: {occurence}x") + + print("\nDistribution of peptide identifications (IDs) per feature:") + for num_ids, occurence in number_of_ids.items(): + print(f"\t{num_ids} IDs: {occurence}") + + print(f"\nUnassigned peptide identifications: {len(feature_map.getUnassignedPeptideIdentifications())}") + ``` + +## Using TOPPView + +If you want a graphical interface to interact with, then use TOPPView. Follow these steps to read the file information using TOPPView: + +1. Go to **File** > **Open file** and open a file by following the prompts. +2. Go to **Tools** > **Apply TOPP tool (whole layer)**. +3. Set **TOPP tool** to **FileInfo** and **output argument** to **out**. +4. Load an existing INI file by clicking **Load** and selecting an INI file from the file importer. If you don’t have an INI file, click **Store**, enter a file name and click **OK** to generate an INI file, then click **Load** and load the file. + + ![apply topp tool to layer](../images/tutorials/toppview/apply-topp-tool-to-layer.png) +5. Click **OK**. +6. Open the **Log** panel at the bottom of the screen to view the resulting file information. + +## Constructing a workflow in KNIME + +KNIME is available for those who want a graphical application to create and use workflows. Here is an example of how to report file information on an input file to an output file using KNIME. + +**1. Install OpenMS plugin**. +
    +
  1. Go to File > Install KNIME Extensions.
    2. +
  2. Search for OpenMS.
    3. +
  3. Select the checkbox next to OpenMS and click Next.
    4. +
  4. Click Next.
    5. +
  5. Accept the terms of conditions.
    6. +
  6. Restart KNIME
    7. +
+ +**2. Open a new file** by going to **File** > **New file**. + +**3. Construct workflow by adding nodes.** +
    +
  1. Go to the Node repository
    2. +
  2. In the search field, type Input File. You should see an Input File node in the filtered list.
    3. +
  3. Drag and drop the Input File node from the Node repository into the workspace.
    4. + add node to workspace +
  4. Repeat steps b and c for the FileInfo node and the Output File node.
    5. +
  5. Connect the Input File node to the FileInfo node. Connect the FileInfo node to the Output File node. Your workflow should look like this:
    6. + connected nodes + Once you configure your nodes in the next step, the warnings should disappear. +
+ +**4. Configure the nodes in workflow.** +
    +
  1. Right-click the Input File node and select Configure.
    2. +
  2. Click Browse and choose the appropriate file from the file importer.
    3. +
  3. Click OK.
    4. +
  4. Right-click the Output File node and select Configure.
    5. +
  5. Either choose an existing file or enter the file name of the new file. If you choose an existing file, select the Overwrite file(s) if it/they exist checkbox.
    6. +
  6. Click OK.
    7. +
  7. Your workflow should be cleared of warnings and look like this:
    8. + connected-nodes-no-warnings +
+ +**5. Play the workflow.** +
    +
  1. Click the Execute all executable nodes button in the toolbar at the top of the screen.
    2. +
  2. You should produce an output file at the specified location. Here is an example of what can be produced:
    3. + +