OpenMS · trickyck · Jul 4, 2022 · Jun 30, 2022 · Jul 2, 2022 · Jul 2, 2022
diff --git a/docs/images/tutorials/toppview/apply-topp-tool-to-layer.png b/docs/images/tutorials/toppview/apply-topp-tool-to-layer.png
diff --git a/docs/images/tutorials/toppview/data-import-options.png b/docs/images/tutorials/toppview/data-import-options.png
diff --git a/docs/images/tutorials/toppview/file-import-options.png b/docs/images/tutorials/toppview/file-import-options.png
diff --git a/docs/images/tutorials/toppview/filtering-options.png b/docs/images/tutorials/toppview/filtering-options.png
diff --git a/docs/images/tutorials/toppview/layer-loaded-in-viewer.png b/docs/images/tutorials/toppview/layer-loaded-in-viewer.png
diff --git a/docs/images/tutorials/toppview/layers-window.png b/docs/images/tutorials/toppview/layers-window.png
diff --git a/docs/images/tutorials/toppview/select-data-filters-window.png b/docs/images/tutorials/toppview/select-data-filters-window.png
diff --git a/docs/images/tutorials/toppview/topp-tool-arguments-and-description.png b/docs/images/tutorials/toppview/topp-tool-arguments-and-description.png
diff --git a/docs/images/tutorials/toppview/topp-tool-parameters.png b/docs/images/tutorials/toppview/topp-tool-parameters.png
diff --git a/docs/images/tutorials/toppview/user-interface.png b/docs/images/tutorials/toppview/user-interface.png
diff --git a/docs/openms-applications-and-tools/openms-applications.md b/docs/openms-applications-and-tools/openms-applications.md
@@ -1,21 +1,26 @@
 OpenMS Applications
 ===================
 
-OpenMS provides a suite of applications, designed for users who want easy access to TOPP tools. These applications include:
+OpenMS provides a suite of graphical 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 GUI application used to edit INI files. INI files are used to configure TOPP tool parameters. INI files are files with the extension `.ini`. For more information, read our [INIFile Editor](openms-applications/ini-file-editor.md) section.
 
-  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.
+  A GUI application used to inspect, visualize and compare mass spectrometry data. Read more in-depth documentation about TOPPView. For more information, read our [TOPPView: Visualize with OpenMS](visualize-with-openms.md) section.
 
 - **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.
+  An application for SWATH analysis. SwathWizard is used to analyze DIA swath data. For mor information, read our [SwathWizard](openms-applications/swathwizard.md)
+
+
+A typical workflow would consist of the following steps:
+
+1. Edit the INI file in the INIFile Editor.
+2. Import data into TOPPView.
+3. Apply TOPP tool to data in TOPPView. You will need to load the INI file edited in step 1.
diff --git a/docs/graphical-topp-tools/ini-file-editor.md → ...ls/openms-applications/ini-file-editor.md b/docs/graphical-topp-tools/ini-file-editor.md → ...ls/openms-applications/ini-file-editor.md
@@ -1,10 +1,10 @@
 INIFileEditor
 ============
 
-Can be used to visually edit INI files of TOPP tools.
+The INIFileEditor is an application used to visually edit INI files of TOPP tools.
 
 The values can be edited by double-clicking or pressing <kbd>F2</kbd>.
 
 The documentation of each value is shown in the text area on the bottom of the widget.
 
-![INIFileEditor](../images/topp/INIFileEditor.png)
+![INIFileEditor](../../images/topp/INIFileEditor.png)
diff --git a/docs/graphical-topp-tools/swathwizard.md → ...-tools/openms-applications/swathwizard.md b/docs/graphical-topp-tools/swathwizard.md → ...-tools/openms-applications/swathwizard.md
@@ -1,7 +1,7 @@
 SwathWizard
-==========
+============
 
-An assistant for Swath analysis.
+SwathWizard is 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.
@@ -16,7 +16,7 @@ both the intermediate files from OpenSWATH (e.g. the XIC data in `.sqMass` forma
 
 This is how the wizard looks like:
 
-![SwathWizard](../images/topp/SwathWizard.png)
+![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).

diff --git a/docs/openms-applications-and-tools/topp-tools.md b/docs/openms-applications-and-tools/topp-tools.md
@@ -7,7 +7,6 @@ The following sections introduce TOPP, some general concepts and more specific i
 :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
@@ -1,6 +1,66 @@
 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.
+**TOPP - The OpenMS Pipeline** is a set of tools for the analysis of HPLC-MS data. These tools can be either:
+
+- [Executed from the command line](../openms-applications-and-tools/command-line-interface.md) or,
+- Applied individually using OpenMS graphical applications.
+- Applied in sequence as a workflow using a workflow editor such as KNIME, Nextflow or Galaxy.
+
+Before you choose one of the above options, there are few concepts that need to be understood.
+
+## File formats
+
+OpenMS only accepts files in the following formats:
+
+- **mzML**: The HUPO-PSI standard format for mass spectrometry data.
+- **featureXML**: The OpenMS format for quantitation results.
+- **consensusXML**: The OpenMS format for grouping features in one map or across several maps.
+- **idXML**: The OpenMS format for protein and peptide identification.
+
+Documented schemas of the OpenMS formats can be found [here](https://github.com/OpenMS/OpenMS/tree/develop/share/OpenMS/SCHEMAS).
+
+If your data is not in the above formats, you may need to use one of a file conversion TOPP tool.
+
+## 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
+  <PARAMETERS>
+
+  <NODE name="FileFilter">
+    <NODE name="1">
+      <ITEM name="rt" value="0:1200" type="string"/>
+    </NODE>
+    <NODE name="2">
+      <ITEM name="mz" value="700:1000" type="string"/>
+    </NODE>
+  </NODE>
+
+  <NODE name="common">
+    <NODE name="FileFilter">
+      <ITEM name="rt" value=":" type="string"/>
+      <ITEM name="mz" value=":" type="string"/>
+    </NODE>
+    <ITEM name="debug" value="2" type="int"/>
+  </NODE>
+
+  </PARAMETERS>
+  ```
+## 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/key-concepts.md b/docs/openms-applications-and-tools/topp-tools/key-concepts.md
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
@@ -3,14 +3,45 @@ Types of TOPP Tools
 
 The following tools are offered:
 
-```{toctree}
-:maxdepth: 1
+- **File conversion**
 
-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
+  TOPP file conversion tools can be used to convert files into a supported format. Supported formats include:
+  - mzML
+  - featureXML
+  - consensusXML
+  - idXML
 
-```
+- **File handling**
+
+  TOPP file handling tools are largely used to extract or merge data.
+
+- **Centroiding**
+
+  The conversion of the "raw" ion count data acquired by the machine into peak lists for further processing is usually called peak picking or centroiding. The choice of the algorithm should mainly depend on the resolution of the data. OpenMS provides different algorithms for centroiding depending on the resolution of the data.
+- **Spectrum processing**
+
+  A number of spectrum processing tools are available. These include peak filtering and peak normalization tools, as well as other miscellaneous tools.
+
+- **Mass correction and calibration**
+
+  To ensure that your data is sound, OpenMS have provided a number of mass correction and calibration tools. The types of tools used will depend on the type of equipment you have employed.
+- **Spectrum clustering**
+- **Map alignment**
+
+  When looking to identify molecules, it is common to run multiple experiments, where each experiment produces a set of data. In OpenMS, every set of data is represented by a feature map. Before combining feature maps to create a consensus map, it is advised to use OpenMS’s map alignment tools so that all your datasets are comparable and based on a common retention time axis.
+- **Feature linking**
+
+  OpenMS provides a number of algorithms for feature grouping or linking.
+- **Quantitation**
+
+  A number of tools are available that allow for the identification and quantification of features. The tools you use will depend on the type of mass spectrometry experiment you have set up, and the type of molecules you wish to identify.
+- **Protein/Peptide identification**
+- **Protein/Peptide processing**
+- **Targeted experiments and OpenSWATH**
+- **Peptide property prediction**
+
+  A number of deep learning tools are available that can train a model using a number of data sets. These can be used to predict peptide properties such as…..
+- **Cross-linking**
+- **Quality control**
+
+For the full list of TOPP tools, visit the [API website](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/2.8.0/html/TOPP_documentation.html).
diff --git a/docs/openms-applications-and-tools/visualize-with-openms.md b/docs/openms-applications-and-tools/visualize-with-openms.md
@@ -1,2 +1,119 @@
-Visualize with OpenMS
-=====================
+TOPPView: Visualize with OpenMS
+===============================
+
+## Introduction
+
+{term}`TOPPView` is a graphical application for inspecting and visualizing {term}`MS` and {term}`HPLC-MS` data. It can be used to inspect files in {term}`mzML`, {term}`mzData`, {term}`mzXML` and several other text-based file formats.
+
+In each view, several datasets can be displayed simultaneously using the layer concept. This allows visual comparison of several
+datasets as well as displaying input data and output data of an algorithm together.
+
+{term}`TOPPView` is intended for visual inspection of the data by experimentalists as well as for analysis software by
+developers.
+
+## User interface
+
+The following image illustrates different components of TOPPView's user interface.
+
+![toppview user interface](../images/tutorials/toppview/user-interface.png)
+
+Components include:
+
+- **Display modes and options**
+- A **Viewer** that displays visual data.
+- **Layers**
+
+  You can visualize several datasets by creating **layers**. In the **Layers window** (dock window in the upper right
+  corner), layers can be hidden and shown using the check box in front of each layer name.
+- **Data filtering window**
+- **Log window** to view textual output of applying TOPP tools to data.
+- **Views windows** that show tabulated information about the dataset.
+
+## Getting Started
+
+The following section details how to perform basic tasks in TOPPView.
+
+### Import a file
+
+To import data into TOPPView:
+
+1. Go to **File** > **Open file**.
+2. Choose a file from the file importer and click **Open**.
+3. Select options from the following panel and click **Ok**:
+
+  ![file import options](../images/tutorials/toppview/file-import-options.png)
+
+  You can choose to open the new dataset as a **new window** or **new layer**. Choosing **new window** will open a new tab. If you are planning on comparing multiple datasets and want to view them all at once, choose **new layer**.
+
+  TOPPView automatically selects the **Map view** depending on the data you have imported.
+
+  <TODO: explain display options>
+
+You should be able to see your data in the **Viewer**.
+
+### Apply TOPP tool
+
+OpenMS provides a number of TOPP tools that can be applied to your data.
+
+To apply a TOPP tool to your dataset:
+
+1. Select a layer in the **Layers window**. The selected layer will be highlighted blue.
+
+  ![display selected layer](../images/tutorials/toppview/layers-window.png)
+
+2. Go to **Tools** > **Apply TOPP tool to whole layer**. This will open a panel to select and configure your TOPP tool.
+
+3. Select a **TOPP tool** from the dropdown menu. A description of the TOPP tool will be displayed on the right. You may have to also specify the **input argument** as well though TOPPView might automatically select this option for you. To save the output to a file, specify the **output argument**.
+
+  ![display selected layer](../images/tutorials/toppview/topp-tool-arguments-and-description.png)
+
+4. Specify the TOPP tool parameters by either:
+   <ol type="a">
+    <li>Loading an INI file by clicking <b>Load</b> and selecting an INI File from the file importer.</li>
+
+    <li>Editing the parameters shown in the table and then saving the INI file. To edit a parameter, double click a row in the table and enter a value or choose from the options available. The modified value will be highlighted yellow. To save the parameters, click <b>Store</b> and enter a file name for the INI file.</li>
+   </ol>
+
+   ![topp tool parameters](../images/tutorials/toppview/topp-tool-parameters.png)
+5. Click **Ok**. You will be prompted to load the new     dataset as a **new window** or a **new layer**. Choose an option and click **Ok**.
+
+  ![data import options](../images/tutorials/toppview/data-import-options.png)
+
+6. If you chose to load the data in a new window, a new tab will appear. To view that data, select the tab. If you chose to load the data as a new layer, the data will be visualized in the **Viewer**. You can also see the new layer wihout a name in the **Layers window**.
+
+  ![layer loaded in Viewer](../images/tutorials/toppview/layer-loaded-in-viewer.png)
+
+7. (Optional) If you did choose to import the data as a new layer, give the new layer a name. To do this, right-click the layer in the **Layers window** and select **Rename**. Enter a name and click OK.
+
+### Filter data
+
+You may only want to see some data from your dataset and hide the rest. OpenMS allows you to filter data based on the following fields: **Intensity**, **Quality**, **Charge**, **Size** and **Meta data**.
+
+To filter your data:
+
+1. Select a layer from the **Layers window**.
+
+  ![display selected layer](../images/tutorials/toppview/layers-window.png)  
+
+2. Open the **Data filters window** by clicking the tab at the bottom of the screen.
+
+  ![select data filters window](../images/tutorials/toppview/select-data-filters-window.png)
+
+3. Add a filter to the **Data filters window** by right-clicking the window and then selecting **Add filter** from the context menu.
+
+4. Select a field, select an operation and enter a value. For example, to exclude all peaks with an intensity of less than 6999, set **field** to **Intensity**, **operation** to **=>** and set the value to 7000. Click **Ok** on the panel to apply the changes.
+
+  ![filtering options](../images/tutorials/toppview/filtering-options.png)
+
+5. You should see only see data that satisfies the specified criteria.
+
+### Additional topics
+
+You might want to check out the following topics:
+
+```{toctree}
+:maxdepth: 1
+
+visualize-with-openms/views-in-toppview.md
+visualize-with-openms/hotkeys-table.md
+```
diff --git a/docs/tutorials/TOPP/hotkeys-table.md → ...ls/visualize-with-openms/hotkeys-table.md b/docs/tutorials/TOPP/hotkeys-table.md → ...ls/visualize-with-openms/hotkeys-table.md
diff --git a/docs/tutorials/TOPP/views-in-toppview.md → ...isualize-with-openms/views-in-toppview.md b/docs/tutorials/TOPP/views-in-toppview.md → ...isualize-with-openms/views-in-toppview.md