From 2df51184bf72b6eb20b2d13c26a85a6720dccf31 Mon Sep 17 00:00:00 2001 From: greengypsy Date: Wed, 25 May 2022 19:54:17 +0930 Subject: [PATCH 1/4] added one noteto installation on gnu linux md file --- docs/installations/installation-on-gnu-linux.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installations/installation-on-gnu-linux.md b/docs/installations/installation-on-gnu-linux.md index 6dd4ac25..d2a0609b 100644 --- a/docs/installations/installation-on-gnu-linux.md +++ b/docs/installations/installation-on-gnu-linux.md @@ -4,7 +4,7 @@ Installation on GNU/Linux ## Install via Debian Package For Debian-based Linux users, it is suggested to use the [deb-package](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/OpenMSInstaller/release/latest/) provided. It is most easily installed with **[gdebi](https://launchpad.net/gdebi)** -which automatically resolves the dependencies available in the PPA Respositories. +which automatically resolves the dependencies available in the PPA Repositories. ```bash sudo apt-get install gdebi From 9eb7a5308ef3c8830134879c1eecef505f7d206f Mon Sep 17 00:00:00 2001 From: greengypsy Date: Wed, 25 May 2022 19:58:53 +0930 Subject: [PATCH 2/4] added one noteto installation on gnu linux md file --- docs/installations/installation-on-gnu-linux.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/installations/installation-on-gnu-linux.md b/docs/installations/installation-on-gnu-linux.md index d2a0609b..776ddc7a 100644 --- a/docs/installations/installation-on-gnu-linux.md +++ b/docs/installations/installation-on-gnu-linux.md @@ -46,6 +46,13 @@ same behaviour as when building it on from source code. Also, their availability support might be limited (due to unforeseen or untested behaviour). It is suggested not to install them parallel to our Debian package. +```{note} +These packages are not directly maintained by OpenMS and they can not be guaranteed the +same behaviour as when building it on from source code. Also, their availability and version is subject to change and +support might be limited (due to unforeseen or untested behaviour). It is suggested not to install them parallel to our +Debian package. +``` + ## Installation via Building From Source Code The source code of OpenMS is available on GitHub. Follow [Building OpenMS on GNU/Linux](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/install_linux.html) instructions on how to build OpenMS from source. From 830f7b7058ea47d534941e45e5c8d7b3445dba00 Mon Sep 17 00:00:00 2001 From: greengypsy Date: Wed, 25 May 2022 20:22:00 +0930 Subject: [PATCH 3/4] added admonitions to noted text --- docs/installations/installation-on-gnu-linux.md | 12 +++++------- docs/installations/installation-on-macos.md | 4 +++- docs/installations/installation-on-windows.md | 4 +++- docs/tutorials/TOPP/data-analysis-in-toppview.md | 4 +++- docs/tutorials/TOPP/feature-detection.md | 4 +++- docs/tutorials/TOPP/feature-grouping.md | 4 +++- docs/tutorials/TOPP/general-introduction.md | 5 +++-- docs/tutorials/TOPP/hotkeys-table.md | 4 +++- docs/tutorials/TOPP/topp-for-advanced-users.md | 8 ++++++-- docs/tutorials/TOPPAS/examples.md | 4 +++- docs/tutorials/TOPPAS/user-interface.md | 2 ++ 11 files changed, 37 insertions(+), 18 deletions(-) diff --git a/docs/installations/installation-on-gnu-linux.md b/docs/installations/installation-on-gnu-linux.md index 776ddc7a..b9fcc984 100644 --- a/docs/installations/installation-on-gnu-linux.md +++ b/docs/installations/installation-on-gnu-linux.md @@ -41,23 +41,21 @@ Packaged versions of **OpenMS** are provided for Fedora, OpenSUSE, Debian, and U [here](https://pkgs.org/download/openms). For other GNU/Linux distributions or to obtain the most recent version of the library, installation should be done via building from the source code. -> **_NOTE:_** Please note that these packages are not directly maintained by OpenMS and they can not be guaranteed the -same behaviour as when building it on from source code. Also, their availability and version is subject to change and -support might be limited (due to unforeseen or untested behaviour). It is suggested not to install them parallel to our -Debian package. - -```{note} +```{important} These packages are not directly maintained by OpenMS and they can not be guaranteed the same behaviour as when building it on from source code. Also, their availability and version is subject to change and support might be limited (due to unforeseen or untested behaviour). It is suggested not to install them parallel to our Debian package. + ``` ## Installation via Building From Source Code The source code of OpenMS is available on GitHub. Follow [Building OpenMS on GNU/Linux](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/install_linux.html) instructions on how to build OpenMS from source. -> **_NOTE:_** Some thirdparty software used via adapter tools in OpenMS might also require an installed JavaVM. +```{note} +Some thirdparty software used via adapter tools in OpenMS might also require an installed JavaVM. +``` ## Run via a (Bio)Docker Image diff --git a/docs/installations/installation-on-macos.md b/docs/installations/installation-on-macos.md index 08cc9e06..0da79e99 100644 --- a/docs/installations/installation-on-macos.md +++ b/docs/installations/installation-on-macos.md @@ -41,9 +41,11 @@ Make sure `` points to the folder where OpenMS is installed locally Since macOS Catalina (maybe also Mojave) notarized apps and executables are mandatory. - > **_NOTE:_** Although there is a lot of effort in signing and notarizing everything, it seems like openms software + ```{note} + Although there is a lot of effort in signing and notarizing everything, it seems like openms software still lands in quarantine on the above mentioned systems, after installation of the DMG (when downloading it from a browser). + ``` To have a streamlined experience without blocking popups, it is recommended to remove the quarantine flag manually, using the following steps: diff --git a/docs/installations/installation-on-windows.md b/docs/installations/installation-on-windows.md index 6b14aa89..fcff4ad1 100644 --- a/docs/installations/installation-on-windows.md +++ b/docs/installations/installation-on-windows.md @@ -7,8 +7,10 @@ To Install the binary package of OpenMS & TOPP: 2. Run the installer under the user account that later runs OpenMS. It is not advised to use admin account for installation. When asked for an admin authentication, please enter the credentials. -> **_NOTE:_** The windows binary version works with most versions of windows from Win7 to Win10 (older versions might +```{note} +The windows binary version works with most versions of windows from Win7 to Win10 (older versions might still work but are untested). +``` ## Known Issues diff --git a/docs/tutorials/TOPP/data-analysis-in-toppview.md b/docs/tutorials/TOPP/data-analysis-in-toppview.md index b6beb86d..56ed18d4 100644 --- a/docs/tutorials/TOPP/data-analysis-in-toppview.md +++ b/docs/tutorials/TOPP/data-analysis-in-toppview.md @@ -27,8 +27,10 @@ and sample description. ![Meta Data Browser](../../images/tutorials/topp/MetaDataBrowser.png) -> **_NOTE:_** Identification data, e.g. from a Mascot run, can be annotated to the spectra or features, too. After +```{tip} +Identification data, e.g. from a Mascot run, can be annotated to the spectra or features, too. After annotation, this data is listed in the metadata. +``` ## Statistics diff --git a/docs/tutorials/TOPP/feature-detection.md b/docs/tutorials/TOPP/feature-detection.md index bc76b81a..90821347 100644 --- a/docs/tutorials/TOPP/feature-detection.md +++ b/docs/tutorials/TOPP/feature-detection.md @@ -14,7 +14,8 @@ wavelet**, which has been tailored to the detection of isotopic patterns followi information about the theory behind this technique, please refer to Hussong et al.: "Efficient Analysis of Mass Spectrometry Data Using the Isotope Wavelet" (2007). -Please note that this algorithm features no "modelling stage", since the structure of the isotopic pattern is explicitly +```{note} +This algorithm features no "modelling stage", since the structure of the isotopic pattern is explicitly coded by the wavelet itself. The algorithm also works for 2D maps (in combination with the so-called *sweep-line* technique (Schulz-Trieglaff et al.: "A Fast and Accurate Algorithm for the Quantification of Peptides from Mass Spectrometry Data" (2007))). The algorithm could originally be executed on (several) high-speed CUDA graphics cards. @@ -22,6 +23,7 @@ Tests on real-world data sets revealed potential speedups beyond factors of 200 Support for CUDA was removed in [OpenMS]() due to maintenance overhead. Please refer to Hussong et al.: "Highly accelerated feature detection in proteomics data sets using modern graphics processing units" (2009) for more details on the implementation. +``` ### Seeding diff --git a/docs/tutorials/TOPP/feature-grouping.md b/docs/tutorials/TOPP/feature-grouping.md index 171ce16c..a65dba86 100644 --- a/docs/tutorials/TOPP/feature-grouping.md +++ b/docs/tutorials/TOPP/feature-grouping.md @@ -29,5 +29,7 @@ To differentially quantify the features of two or more label-free HPLC-MS map. ![TOPP labelfree quant](../../images/tutorials/topp/TOPP_labelfree_quant.png) -> **_NOTE:_** This algorithm assumes that the retention time axes of all input maps are very similar. To correct for +```{note} +This algorithm assumes that the retention time axes of all input maps are very similar. To correct for retention time distortions, please have a look at [Map alignment](map-alignment.md). +``` diff --git a/docs/tutorials/TOPP/general-introduction.md b/docs/tutorials/TOPP/general-introduction.md index 0724f8c1..c5d1a334 100644 --- a/docs/tutorials/TOPP/general-introduction.md +++ b/docs/tutorials/TOPP/general-introduction.md @@ -61,10 +61,11 @@ can contain the configuration of one or several TOPP tools. The following examples will give an overview of how TOPP tools can be chained in order to create analysis pipelines. INI files are the recommended way to store all settings of such a pipeline in a single place. -Note that the issue of finding suitable parameters for the tools is not addressed here. For problems during the +```{note} +The issue of finding suitable parameters for the tools is not addressed here. For problems during the execution of the example pipelines on the data, adapt the parameters. Have a look at the documentation of the corresponding TOPP tool in that case. - +``` ### Parameter documentation diff --git a/docs/tutorials/TOPP/hotkeys-table.md b/docs/tutorials/TOPP/hotkeys-table.md index df14769d..9d4ef4a7 100644 --- a/docs/tutorials/TOPP/hotkeys-table.md +++ b/docs/tutorials/TOPP/hotkeys-table.md @@ -41,7 +41,9 @@ TOPPView Hotkeys | CTRL + ALT + + | 2D draw mode: increase maximum point size (for raw peak scaling) | | CTRL + ALT + - | 2D draw mode: decrease maximum point size (for raw peak scaling) | -> **_NOTE:_** Home on macOS keyboards is also Fn + ArrowLeft. End on macOSX keyboards is also Fn + ArrowRight. +```{tip} +kbd>Home on macOS keyboards is also Fn + ArrowLeft. End on macOSX keyboards is also Fn + ArrowRight. +``` ## Annotations in 1D view diff --git a/docs/tutorials/TOPP/topp-for-advanced-users.md b/docs/tutorials/TOPP/topp-for-advanced-users.md index 1effd425..5f327f9a 100644 --- a/docs/tutorials/TOPP/topp-for-advanced-users.md +++ b/docs/tutorials/TOPP/topp-for-advanced-users.md @@ -12,14 +12,18 @@ specify one or more directories where FASTA files (or related, e.g., `.psq` file directories specified in `id_db_dir` will be searched. This allows to build scripts and/or TOPPAS pipelines which are portable across several computers, just adapt the OpenMS.ini once on each machine. -> **_NOTE:_** When using TOPPAS: Use an "input file" node to specify the FASTA file for several engines simultaneously. +```{tip} +When using TOPPAS: Use an "input file" node to specify the FASTA file for several engines simultaneously. However, when selecting the file, TOPPAS will use the absolute pathname and the dialog will not allow to name a non-existing file. After selecting the file you can however edit the filename and remove the path (this will issue a warning which can be ignored). +``` -> **_NOTE:_** This approach does not work for OpenMS MascotAdapters, as each Mascot instance has its own database +```{note} +This approach does not work for OpenMS MascotAdapters, as each Mascot instance has its own database managed internally. Make sure that the database is present on all mascot servers you're going to use, thus making the INI settings portable. +``` ## Using external tools in workflows diff --git a/docs/tutorials/TOPPAS/examples.md b/docs/tutorials/TOPPAS/examples.md index e9c129ec..ea18ea1b 100644 --- a/docs/tutorials/TOPPAS/examples.md +++ b/docs/tutorials/TOPPAS/examples.md @@ -52,8 +52,10 @@ text based format using the TextExporter for further processing (e.g., in Micros The results can be opened in TOPPView. The next figures show the results in 2D and 3D view, together with the feature intermediate results. -> **_NOTE:_** The intensities and retention times are slightly different between the runs. To correct for retention +```{note} +The intensities and retention times are slightly different between the runs. To correct for retention times shift, a map alignment could be done, either on the spectral data or on the feature data. +``` ![TOPPAS BSA Results 2D](../../images/tutorials/toppas/TOPPAS_BSA_results_2d.png) diff --git a/docs/tutorials/TOPPAS/user-interface.md b/docs/tutorials/TOPPAS/user-interface.md index 68702578..d7956d03 100644 --- a/docs/tutorials/TOPPAS/user-interface.md +++ b/docs/tutorials/TOPPAS/user-interface.md @@ -54,6 +54,7 @@ selected, TOPPAS will parallelize the pipeline execution in the following scenar - The pipeline contains multiple branches that are independent of each other. In this case, multiple tools can run in parallel. +```{caution} Be careful with this setting, however, as some of the TOPP tools require large amounts of RAM (depending on the size of the dataset). Running too many parallel jobs on a machine with not enough memory will cause problems. Also, do not confuse this setting with the `threads` parameter of the individual TOPP tools: every TOPP tool has this parameter @@ -61,6 +62,7 @@ specifying the maximum number of threads the tool is allowed to use (although on of this parameter, since there are tasks that cannot be computed in parallel). Be especially careful with combinations of both parameters! For a pipeline containing the `FeatureFinderCentroided`, as an example, and set its `threads` parameter to 8, and additionally set the number of parallel jobs in **TOPPAS** to 8, then you end up using 64 threads. +``` In addition to `TOPPAS_out`, a `TOPPAS_tmp` directory will be created in the OpenMS temp path (call the `OpenMSInfo` tool to see where exactly). It will contain all temporary files that are passed from tool to tool within the pipeline. From d21697e0f56a7de8f9f32b1ab757d9fb27b6c648 Mon Sep 17 00:00:00 2001 From: greengypsy Date: Wed, 25 May 2022 21:17:06 +0930 Subject: [PATCH 4/4] changed admonition types as discussed in review --- docs/installations/installation-on-macos.md | 2 +- docs/installations/installation-on-windows.md | 2 +- docs/tutorials/TOPP/feature-detection.md | 2 +- docs/tutorials/TOPP/feature-grouping.md | 2 +- docs/tutorials/TOPP/general-introduction.md | 2 +- docs/tutorials/TOPPAS/examples.md | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/installations/installation-on-macos.md b/docs/installations/installation-on-macos.md index 0da79e99..2cad2a25 100644 --- a/docs/installations/installation-on-macos.md +++ b/docs/installations/installation-on-macos.md @@ -41,7 +41,7 @@ Make sure `` points to the folder where OpenMS is installed locally Since macOS Catalina (maybe also Mojave) notarized apps and executables are mandatory. - ```{note} + ```{important} Although there is a lot of effort in signing and notarizing everything, it seems like openms software still lands in quarantine on the above mentioned systems, after installation of the DMG (when downloading it from a browser). diff --git a/docs/installations/installation-on-windows.md b/docs/installations/installation-on-windows.md index fcff4ad1..af57931e 100644 --- a/docs/installations/installation-on-windows.md +++ b/docs/installations/installation-on-windows.md @@ -7,7 +7,7 @@ To Install the binary package of OpenMS & TOPP: 2. Run the installer under the user account that later runs OpenMS. It is not advised to use admin account for installation. When asked for an admin authentication, please enter the credentials. -```{note} +```{tip} The windows binary version works with most versions of windows from Win7 to Win10 (older versions might still work but are untested). ``` diff --git a/docs/tutorials/TOPP/feature-detection.md b/docs/tutorials/TOPP/feature-detection.md index 90821347..da9369bf 100644 --- a/docs/tutorials/TOPP/feature-detection.md +++ b/docs/tutorials/TOPP/feature-detection.md @@ -14,7 +14,7 @@ wavelet**, which has been tailored to the detection of isotopic patterns followi information about the theory behind this technique, please refer to Hussong et al.: "Efficient Analysis of Mass Spectrometry Data Using the Isotope Wavelet" (2007). -```{note} +```{attention} This algorithm features no "modelling stage", since the structure of the isotopic pattern is explicitly coded by the wavelet itself. The algorithm also works for 2D maps (in combination with the so-called *sweep-line* technique (Schulz-Trieglaff et al.: "A Fast and Accurate Algorithm for the Quantification of Peptides from Mass diff --git a/docs/tutorials/TOPP/feature-grouping.md b/docs/tutorials/TOPP/feature-grouping.md index a65dba86..9d8ac124 100644 --- a/docs/tutorials/TOPP/feature-grouping.md +++ b/docs/tutorials/TOPP/feature-grouping.md @@ -29,7 +29,7 @@ To differentially quantify the features of two or more label-free HPLC-MS map. ![TOPP labelfree quant](../../images/tutorials/topp/TOPP_labelfree_quant.png) -```{note} +```{tip} This algorithm assumes that the retention time axes of all input maps are very similar. To correct for retention time distortions, please have a look at [Map alignment](map-alignment.md). ``` diff --git a/docs/tutorials/TOPP/general-introduction.md b/docs/tutorials/TOPP/general-introduction.md index c5d1a334..8878dd5e 100644 --- a/docs/tutorials/TOPP/general-introduction.md +++ b/docs/tutorials/TOPP/general-introduction.md @@ -61,7 +61,7 @@ can contain the configuration of one or several TOPP tools. The following examples will give an overview of how TOPP tools can be chained in order to create analysis pipelines. INI files are the recommended way to store all settings of such a pipeline in a single place. -```{note} +```{attention} The issue of finding suitable parameters for the tools is not addressed here. For problems during the execution of the example pipelines on the data, adapt the parameters. Have a look at the documentation of the corresponding TOPP tool in that case. diff --git a/docs/tutorials/TOPPAS/examples.md b/docs/tutorials/TOPPAS/examples.md index ea18ea1b..9d42c732 100644 --- a/docs/tutorials/TOPPAS/examples.md +++ b/docs/tutorials/TOPPAS/examples.md @@ -52,7 +52,7 @@ text based format using the TextExporter for further processing (e.g., in Micros The results can be opened in TOPPView. The next figures show the results in 2D and 3D view, together with the feature intermediate results. -```{note} +```{tip} The intensities and retention times are slightly different between the runs. To correct for retention times shift, a map alignment could be done, either on the spectral data or on the feature data. ```