diff --git a/README.md b/README.md index bf48b06..c6d6b71 100644 --- a/README.md +++ b/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) +**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) + **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.** diff --git a/docs/source/userguide/configuration.rst b/docs/source/userguide/configuration.rst index e22b3ec..a692f77 100644 --- a/docs/source/userguide/configuration.rst +++ b/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 `_) +would be notated as ``Formula:C-2[13C2]N-1[15N]``, meaning that two C atoms are removed, two +:raw-html:`13C` atoms are added, one N atom is removed and one +:raw-html:`15N` atom is added. + And example of the :py:obj:`modification_mapping` could be: .. tab:: JSON diff --git a/docs/source/userguide/tims2Rescore.rst b/docs/source/userguide/tims2Rescore.rst index f9b9096..51a18b1 100644 --- a/docs/source/userguide/tims2Rescore.rst +++ b/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 `). - - 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 `). + - 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 -s -o + tims2rescore -p -s + + Replace ``, ``, and `` with the + actual paths to your input and output files. - Replace ``, ``, and `` 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 - Replace `` with the actual output prefix of the result files to the output file. + Replace `` 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 diff --git a/ms2rescore/__main__.py b/ms2rescore/__main__.py index 70e384c..400a1fa 100644 --- a/ms2rescore/__main__.py +++ b/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")