Merge pull request #160 from compomics/update-documentation

Update tims2rescore documentation

README.md

@@ -44,6 +44,17 @@ files:
 MS²Rescore is available as a [desktop application][desktop], a [command line tool][cli], and a
 [modular Python API][python-package].
 
+## TIMS²Rescore: Direct support for DDA-PASEF data
+
+MS²Rescore v3.1+ includes TIMS²Rescore, a usage mode with specialized default configurations for
+DDA-PASEF data from timsTOF instruments. TIMS²Rescore makes use of new MS²PIP prediction models for
+timsTOF fragmentation and IM2Deep for ion mobility separation. Bruker .d and miniTDF spectrum
+files are directly supported through the [timsrust](https://github.com/MannLabs/timsrust) library.
+
+Checkout our [preprint](https://doi.org/10.1101/2024.05.29.596400) for more information and the
+[TIMS²Rescore documentation](https://ms2rescore.readthedocs.io/userguide/tims2rescore)
+to get started.
+
 ## Citing
 
 **Latest MS²Rescore publication:**
@@ -54,10 +65,16 @@ MS²Rescore is available as a [desktop application][desktop], a [command line to
 
 **MS²Rescore for immunopeptidomics:**
 
-> **MS2Rescore: Data-driven rescoring dramatically boosts immunopeptide identification rates.**
+> **MS²Rescore: Data-driven rescoring dramatically boosts immunopeptide identification rates.**
 > Arthur Declercq, Robbin Bouwmeester, Aurélie Hirschler, Christine Carapito, Sven Degroeve, Lennart Martens, and Ralf Gabriels.
 > _Molecular & Cellular Proteomics_ (2021) [doi:10.1016/j.mcpro.2022.100266](https://doi.org/10.1016/j.mcpro.2022.100266) <span class="__dimensions_badge_embed__" data-doi="10.1016/j.mcpro.2022.100266" data-hide-zero-citations="true" data-style="small_rectangle"></span>
 
+**MS²Rescore for timsTOF DDA-PASEF data:**
+
+> **TIMS²Rescore: A DDA-PASEF optimized data-driven rescoring pipeline based on MS²Rescore.**
+> Arthur Declercq*, Robbe Devreese*, Jonas Scheid, Caroline Jachmann, Tim Van Den Bossche, Annica Preikschat, David Gomez-Zepeda, Jeewan Babu Rijal, Aurélie Hirschler, Jonathan R Krieger, Tharan Srikumar, George Rosenberger, Dennis Trede, Christine Carapito, Stefan Tenzer, Juliane S Walz, Sven Degroeve, Robbin Bouwmeester, Lennart Martens, and Ralf Gabriels.
+> _bioRxiv_ (2024) [doi:10.1101/2024.05.29.596400](https://doi.org/10.1101/2024.05.29.596400) <span class="__dimensions_badge_embed__" data-doi="10.1101/2024.05.29.596400" data-hide-zero-citations="true" data-style="small_rectangle"></span>
+
 **Original publication describing the concept of rescoring with predicted spectra:**
 
 > **Accurate peptide fragmentation predictions allow data driven approaches to replace and improve upon proteomics search engine scoring functions.**

docs/source/userguide/configuration.rst

@@ -81,6 +81,19 @@ preferably provide the formula instead of a mass shift, as the mass shift can al
 be calculated from the formula, but not vice-versa, and some feature generators (such as DeepLC)
 require the modification formula.
 
+.. role:: raw-html(raw)
+   :format: html
+
+Formula modification labels can be defined with the ``Formula:`` prefix, followed by each atom
+symbol and its count, denoting which atoms are added or removed by the modification. If no count is
+provided, it is assumed to be 1. For example, ``Formula:HO3P`` is equivalent to ``Formula:H1O3P1``.
+For isotopes, prefix the atom symbol with the isotope number and place the entire block (isotope
+number, atom symbol, and number of atoms) in square brackets. For example, the SILAC 13C(2) 15N(1)
+label (`UNIMOD:2088 <https://unimod.org/modifications_view.php?editid1=2088>`_)
+would be notated as ``Formula:C-2[13C2]N-1[15N]``, meaning that two C atoms are removed, two
+:raw-html:`<sup>13</sup>C` atoms are added, one N atom is removed and one
+:raw-html:`<sup>15</sup>N` atom is added.
+
 And example of the :py:obj:`modification_mapping` could be:
 
 .. tab:: JSON

docs/source/userguide/tims2Rescore.rst

@@ -1,61 +1,76 @@
-.. _timsrescore:
+.. _tims2rescore:
 
-TIMS²Rescore User Guide
-=======================
+TIMS²Rescore
+============
 
 Introduction
 ------------
 
-The `TIMS²Rescore` tool is a DDA-PASEF adapted version of `ms2rescore` that allows users to perform rescoring of peptide-spectrum matches (PSMs) acquired on Bruker instruments. This guide provides an overview of how to use `timsrescore` in `ms2rescore` effectively.
+`TIMS²Rescore` is a specialized version of `MS²Rescore` for timsTOF DDA-PASEF data. This guide
+provides an overview of how to use TIMS²Rescore effectively.
 
-Installation
-------------
-
-Before using `timsrescore`, ensure that you have `ms2rescore` installed on your system. You can install `ms2rescore` using the following command:
-
-.. code-block:: bash
+Installing TIMS²Rescore
+-----------------------
 
-    pip install ms2rescore
+TIMS²Rescore is part of the ``ms2rescore`` package. Check out the :ref:`installation` instructions
+to get started.
 
 Usage
 -----
 
-To use `timsrescore`, follow these steps:
+To use TIMS²Rescore, follow these steps:
 
 1. Prepare your input files:
-    - Ensure that you have the necessary input files, including the PSM file spectrum files
-    - Make sure that the PSM file format from a supported search engine or a standard format like .mzid(:external+psm_utils:ref:`supported file formats <supported file formats>`).
-    - Spectrum files can directly be given as .d or minitdf files from Bruker instruments or first converted to .mzML format.
-
-2. Run `timsrescore`:
+    - To boost DDA-PASEF peptide identifications, TIMS²Rescore requires the spectrum files from
+      the timsTOF instrument and the PSM files with identifications from a supported search engine.
+    - Make sure that the PSM file format comes from a supported search engine or is a standard
+      format such as mzIdentML (See
+      :external+psm_utils:ref:`supported file formats <supported file formats>`).
+    - Spectrum files can directly be passed as ``.d`` or `miniTDF` raw data or can optionally be
+      first converted to mzML or MGF. We recommend using the format that was passed to the search
+      engine.
+
+2. Run ``tims2rescore``:
     - Open a terminal or command prompt.
     - Navigate to the directory where your input files are located.
     - Execute the following command:
 
       .. code-block:: bash
 
-          timsrescore -p <path_to_psm_file> -s <path_to_spectrum_file> -o <path_to_output_file>
+          tims2rescore -p <path_to_psm_file> -s <path_to_spectrum_file>
+
+    Replace `<path_to_psm_file>`, `<path_to_tims_file>`, and `<path_to_output_file>` with the
+    actual paths to your input and output files.
 
-    Replace `<path_to_psm_file>`, `<path_to_tims_file>`, and `<path_to_output_file>` with the actual paths to your input and output files.
-    _NOTE_ By default timsTOF specific models will be used for predictions. Optionally you can further configure settings through a configuration file. For more information on configuring `timsrescore`, refer to the :doc:`configuration` tab in the user guide.
+    .. admonition:: note
+
+        By default, specialized timsTOF models will be used for predictions. Optionally you can
+        further configure TIMS²Rescore through a configuration file. For more information, refer
+        to the :ref:`configuration` tab in the user guide.
 
 3. Review the results:
-    - Once the `timsrescore` process completes, you will find the rescoring results in the specified output file or if not specified in the same directory as the input files
-    - If you want a detailed overview of the performance, you can either give the set `write_report` to `True` in the configuration file, use the `--write_report` option in the command line or run the following command:
-
+    - Once the ``tims2rescore`` process completes, you will find the rescoring results in the
+      same directory as the input files.
+    - If you want a detailed report of the rescoring performance, you can either give the set
+      `write_report` to `True` in the configuration file, use the `--write_report` option in the
+      ``tims2rescore`` command line. Alternatively, run the following command after rescoring:
+
       .. code-block:: bash
 
           ms2rescore-report <output_prefix>
 
-    Replace `<output_prefix>` with the actual output prefix of the result files to the output file.
+      Replace `<output_prefix>` with the actual output prefix of the result files to the output
+      file. For instance, if the output file is ``identifications.psms.tsv``, then the output
+      prefix is ``identifications``.
 
-Additional Options
+Additional options
 ------------------
 
-`ms2rescore` provides additional options to customize the `timsrescore` process. You can explore these options by running the following command:
+`tims2rescore` provides additional options to customize rescoring. You can explore these options
+by running the following command:
 
 .. code-block:: bash
 
-    timsrescore --help
+    tims2rescore --help
 
 

ms2rescore/__main__.py

@@ -41,18 +41,24 @@ def _print_credits(tims=False):
     text = Text()
     text.append("\n")
     if tims:
-        text.append("TIMS²Rescore", style="bold link https://github.com/compomics/ms2rescore")
+        text.append("TIMS²Rescore", style="bold link https://github.com/compomics/tims2rescore")
     else:
         text.append("MS²Rescore", style="bold link https://github.com/compomics/ms2rescore")
     text.append(f" (v{__version__})\n", style="bold")
     if tims:
-        text.append("MS²Rescore tuned for Bruker timsTOF instruments.\n", style="italic")
+        text.append("MS²Rescore tuned for timsTOF DDA-PASEF data.\n", style="italic")
     text.append("Developed at CompOmics, VIB / Ghent University, Belgium.\n")
     text.append("Please cite: ")
-    text.append(
-        "Buur & Declercq et al. JPR (2024)",
-        style="link https://doi.org/10.1021/acs.jproteome.3c00785",
-    )
+    if tims:
+        text.append(
+            "Declercq & Devreese et al. bioRxiv (2024)",
+            style="link https://doi.org/10.1101/2024.05.29.596400",
+        )
+    else:
+        text.append(
+            "Buur & Declercq et al. JPR (2024)",
+            style="link https://doi.org/10.1021/acs.jproteome.3c00785",
+        )
     text.append("\n")
     if tims:
         text.stylize("#006cb5")