Merge pull request #207 from SteffenHeu/mrm

SteffenHeu · web-flow · commit 3a882bb43359 · 2025-01-28T12:08:50.000+01:00
MRM to Scans
diff --git a/docs/module_docs/mrm_mrmtoscans/mrm-to-scans.md b/docs/module_docs/mrm_mrmtoscans/mrm-to-scans.md
@@ -0,0 +1,57 @@
+# MRM to scans
+
+!!! warning
+    To process multiple reaction monitoring (MRM) data, the MRM service of mzmine is required. This is
+    included for PRO customers. Academics can reach out to info[at]mzio.io to request a free license.
+
+:material-menu-open: **MRM → MRM to scans and chromatograms**
+
+Since Triple-Quadrupole MRM or SRM workflows typically produce one or more transition chromatograms 
+per compound instead of individual spectra, the data must be pre-processed to fit into the regular 
+mzmine workflow. This is achieved by the this module.
+
+![mrm_converted.png](mrm_converted.png)
+
+## Parameters
+#### Raw data files
+Select the raw data files that the MRM processing shall be applied to.
+
+#### Build chromatograms
+If enabled, this module automatically generates feature lists with chromatograms for the selected data files, based on the grouped transitions (see [transition grouping](#transition-grouping)). These features will contain the chromatographic data of all transitions of a single compound (see [chromatogram generation](#chromatogram-generation)). This is enabled by default and the recommended way to generate chromatograms for MRM data files.
+
+#### Static baseline subtraction
+If enabled, the lowest non-zero intensity of a transition will be subtracted along the retention time (recommended). 
+
+!!! tip
+    Visualizing features of MRM data will not "fill" the whole area of the extracted XIC, which is accessible from the feature table context menu. This is caused by the summation of all transitions to compute the MS1 intensity (see [Pseudo MS1 generation](#pseudo-ms1-generation)) and the [static baseline subtraction](#static-baseline-subtraction), which is not applied to the spectra.
+
+
+
+## Algorithm
+
+#### Transition grouping
+During the conversion, all transitions of the same Q1 precursor _m_/_z_ (+- 0.01) and within the 
+same retention time window (at least 90% overlap) will be grouped together. For example, Q1 _m_/_z_ 531.00 
+will be grouped with transitions 531.00 -> 429.00 and 531.00 -> 214.00, but not with 531.02 -> 212.00.
+
+#### Pseudo MS2 generation
+After all compounds have been grouped, the transitions of a single compound are used to generate pseudo MS2
+spectra. The MS2 spectra will be generated for the retention time window, in which the set of transitions was acquired. At each dwell cycle, the respective intensities of the transitions will be interpreted as 
+the intensity of the Q3 _m_/_z_ in the pseudo MS2. E.g. if the intensity of 531.00 -> 214.00 was 150 and of 531.00 -> 429.00 was 125 at retention time 5.00 min, the MS2 spectrum with precursor 531.00 will 
+contain two signals. One with m/z 214.00 and intensity 150, and one with m/z 429.00 and intensity 125.
+
+#### Pseudo MS1 generation
+After all pseudo MS2s were generated, the cycle time of the instrument is determined (which ions are 
+fragmented in a single cycle). With this information, the generated pseudo MS2s are grouped by their 
+cycles. To generate a pseudo MS1 spectrum, all precursor (Q1) _m_/_zs_ are represented by the accumulated intensity of all their recorded transitions (= signals in the pseudo MS2). However, these pseudo MS1 and MS2 spectra are only used for visualisation purposes and to stay consistent with the mzmine data structure. 
+The default feature detection and integration of the MRM workflow runs on the generated chromatograms (see [chromatogram generation](#chromatogram-generation). 
+
+#### Chromatogram generation
+Chromatograms are generated for a single grouped compound (see [transition grouping](#transition-grouping)).
+A feature list is generated from these compounds. Since a feature may now have multiple transitions,
+the most intense transition is set as the quantifier by default and used to represent the feature with it's chromatographic shape. Since a static background may be present, the lowest non-zero intensity may be subtracted using the [static baseline subtraction](#static-baseline-subtraction) parameter (recommended). 
+
+
+---
+
+{{ git_page_authors }}
diff --git a/docs/module_docs/mrm_mrmtoscans/mrm_converted.png b/docs/module_docs/mrm_mrmtoscans/mrm_converted.png
diff --git a/docs/workflows/mrmworkflow/mrm-workflow.md b/docs/workflows/mrmworkflow/mrm-workflow.md
@@ -0,0 +1,21 @@
+# MRM workflow
+
+!!! warning
+    To process multiple reaction monitoring (MRM) data, the MRM service of mzmine is required. This is
+    included for PRO customers. Academics can reach out to info[at]mzio.io to request a free license.
+
+In contrast to HRMS data, MRM acquisitions are usually stored as chromatograms of specific transitions,
+e.g., _m_/_z_ 413 -> 96 instead of full spectra. This is a raw data format, that mzmine is not used 
+to handling, since workflows usuallys start with a set of centroided spectra along the retention time.
+
+Therefore, a specific module is required to build scans and chromatograms, which is the [MRM to scans](../../module_docs/mrm_mrmtoscans/mrm-to-scans.md) module.
+
+## Workflow
+
+### Import raw data
+Raw data is import in the usual fashion see [data import](../../module_docs/io/data-import.md).
+
+### MRM to scans
+The imported raw data is converted using the [MRM to scans](../../module_docs/mrm_mrmtoscans/mrm-to-scans.md)
+module. This creates pseudo MS1 and MS2 spectra as well as a feature list, which groups the MRM transitions
+by their retention time and precursor ion mass. 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -16,53 +16,55 @@ nav:
   - Performance options: performance.md
   - Command line tool (batch mode): commandline_tool.md
   - Integration to other tools: tool_integration.md
-#  - Citations: citations.md
+  #  - Citations: citations.md
 
   - Processing modules:
       - I/O:
-        - Raw data import: module_docs/io/data-import.md
-        - Raw data export: module_docs/io/data-export.md
-        - Feature list import: module_docs/io/feat-list-import.md
-        - Feature list export: module_docs/io/feat-list-export.md
-        - Export to other software: module_docs/io/data-exchange-with-other-software.md
-        - Spectral library export: module_docs/io_spectral_library_export/spectral_library_generation.md
-        - Export scans (feature list): module_docs/io_scans_feature/export-scans-feature.md
-#         TODO Add feature list import/export
+          - Raw data import: module_docs/io/data-import.md
+          - Raw data export: module_docs/io/data-export.md
+          - Feature list import: module_docs/io/feat-list-import.md
+          - Feature list export: module_docs/io/feat-list-export.md
+          - Export to other software: module_docs/io/data-exchange-with-other-software.md
+          - Spectral library export: module_docs/io_spectral_library_export/spectral_library_generation.md
+          - Export scans (feature list): module_docs/io_scans_feature/export-scans-feature.md
+      #         TODO Add feature list import/export
       - File merging:
-        - Raw data files merging: module_docs/featdet_file_merging/raw-files-merging.md
-        - Mobility scan merging: module_docs/featdet_mobility_scan_merging/mobility-scan-merging.md
+          - Raw data files merging: module_docs/featdet_file_merging/raw-files-merging.md
+          - Mobility scan merging: module_docs/featdet_mobility_scan_merging/mobility-scan-merging.md
       - Raw data filtering:
           - Scan by scan filtering: module_docs/filter_raw_data/filter-scan-by-scan.md
           - Crop filter: module_docs/filter_raw_data/crop-filter.md
           - Baseline corrections: module_docs/filter_raw_data/baseline-corrections.md
           - Align scans: module_docs/filter_raw_data/align-scans.md
           - Scan smoothing: module_docs/filter_raw_data/scan_smoothing.md
       - Mass detection:
-        - Mass detection: module_docs/featdet_mass_detection/mass-detection.md
-        - Mass detection algorithms: module_docs/featdet_mass_detection/mass-detection-algorithms.md
-        - FTMS shoulder peak finder: module_docs/featdet_mass_detection/FTMS-shoulder-peak-filter.md
-        - Mass calibration: module_docs/featdet_mass_detection/mass-calibration.md
+          - Mass detection: module_docs/featdet_mass_detection/mass-detection.md
+          - Mass detection algorithms: module_docs/featdet_mass_detection/mass-detection-algorithms.md
+          - FTMS shoulder peak finder: module_docs/featdet_mass_detection/FTMS-shoulder-peak-filter.md
+          - Mass calibration: module_docs/featdet_mass_detection/mass-calibration.md
       - LC-MS feature detection:
-        - ADAP Chromatogram builder: module_docs/lc-ms_featdet/featdet_adap_chromatogram_builder/adap-chromatogram-builder.md
-        - GridMass: module_docs/lc-ms_featdet/featdet_gridmass/gridmass.md
-        - Targeted feature detection: module_docs/lc-ms_featdet/targeted_featdet/targeted-featdet.md
-        - Feature detection results: module_docs/lc-ms_featdet/featdet_results/featdet_results.md
+          - ADAP Chromatogram builder: module_docs/lc-ms_featdet/featdet_adap_chromatogram_builder/adap-chromatogram-builder.md
+          - GridMass: module_docs/lc-ms_featdet/featdet_gridmass/gridmass.md
+          - Targeted feature detection: module_docs/lc-ms_featdet/targeted_featdet/targeted-featdet.md
+          - Feature detection results: module_docs/lc-ms_featdet/featdet_results/featdet_results.md
       - LC-IMS-MS feature detection:
-#       TODO Rework this one
-        - Ion mobility expander: module_docs/lc-ims-ms_featdet/featdet_ims_expander/ims-expander.md
-        - Ion mobility trace builder: module_docs/lc-ims-ms_featdet/featdet_ion_mobility_trace_builder/ion-mobility-trace-builder.md
-        - Recursive IMS builder: module_docs/lc-ims-ms_featdet/recursive_ims_builder/recursive-ims-builder.md
+          #       TODO Rework this one
+          - Ion mobility expander: module_docs/lc-ims-ms_featdet/featdet_ims_expander/ims-expander.md
+          - Ion mobility trace builder: module_docs/lc-ims-ms_featdet/featdet_ion_mobility_trace_builder/ion-mobility-trace-builder.md
+          - Recursive IMS builder: module_docs/lc-ims-ms_featdet/recursive_ims_builder/recursive-ims-builder.md
       - MS imaging feature detection:
-        - Image builder: module_docs/imaging_featdet/featdet_image_builder/image-builder.md
+          - Image builder: module_docs/imaging_featdet/featdet_image_builder/image-builder.md
+      - MRM feature detection:
+          - MRM to Scans: module_docs/mrm_mrmtoscans/mrm-to-scans.md
       - Smoothing: module_docs/featdet_smoothing/smoothing.md
       - Resolving:
-        - Local minimum resolver: module_docs/featdet_resolver_local_minimum/local-minimum-resolver.md
-        - ADAP resolver: module_docs/featdet_resolver_adap/adap-resolver.md
-        - Baseline resolver: module_docs/featdet_resolver_baseline/baseline-resolver.md
-        - CentWave resolver: module_docs/featdet_resolver_centwave/centwave-resolver.md
-        - Noise amplitude resolver: module_docs/featdet_resolver_noise_ampl/noise-ampl-resolver.md
-        - Savitzky-Golay resolver: module_docs/featdet_resolver_savitzky-golay/savitzky-golay-resolver.md
-#      TODO Add mobilogram binning
+          - Local minimum resolver: module_docs/featdet_resolver_local_minimum/local-minimum-resolver.md
+          - ADAP resolver: module_docs/featdet_resolver_adap/adap-resolver.md
+          - Baseline resolver: module_docs/featdet_resolver_baseline/baseline-resolver.md
+          - CentWave resolver: module_docs/featdet_resolver_centwave/centwave-resolver.md
+          - Noise amplitude resolver: module_docs/featdet_resolver_noise_ampl/noise-ampl-resolver.md
+          - Savitzky-Golay resolver: module_docs/featdet_resolver_savitzky-golay/savitzky-golay-resolver.md
+      #      TODO Add mobilogram binning
       - Spectral deconvolution (GC):
           - GC-EI spectral deconvolution: module_docs/featdet_spectraldeconvolutiongc/spectraldeconvolutiongc.md
           #- Hierarchical clustering: module_docs/featdet_hierarch_clustering/featdet_hierarch_clustering.md
@@ -79,50 +81,50 @@ nav:
           - Ion Identity Networking: module_docs/id_ion_networking/iin/iin.md
           - Spectral / Molecular Networking: module_docs/group_spectral_net/molecular_networking.md
       - Feature list filtering:
-        - Duplicate feature filter: module_docs/filter_duplicate_features/duplicate_feature_filter.md
-        - Feature list rows filter: module_docs/feature_list_row_filter/feature_list_rows_filter.md
-        - Feature filter: module_docs/feature_filter/feature_filter.md
-        - Peak comparison rows filter: module_docs/filter_peakcomparison_row_filter/filter_peakcomparison_row_filter.md
-        - Neutral loss filter: module_docs/filter_neutral_loss/filter_neutral_loss.md
-        - m/z mobility region extraction: module_docs/filter_mobilitymzregionextraction/filter_mobilitymzregionextraction.md
-        - Feature list blank subtraction: module_docs/filter_blanksubtraction/filter_blanksubtraction.md
+          - Duplicate feature filter: module_docs/filter_duplicate_features/duplicate_feature_filter.md
+          - Feature list rows filter: module_docs/feature_list_row_filter/feature_list_rows_filter.md
+          - Feature filter: module_docs/feature_filter/feature_filter.md
+          - Peak comparison rows filter: module_docs/filter_peakcomparison_row_filter/filter_peakcomparison_row_filter.md
+          - Neutral loss filter: module_docs/filter_neutral_loss/filter_neutral_loss.md
+          - m/z mobility region extraction: module_docs/filter_mobilitymzregionextraction/filter_mobilitymzregionextraction.md
+          - Feature list blank subtraction: module_docs/filter_blanksubtraction/filter_blanksubtraction.md
       - Alignment:
           - Join aligner: module_docs/align_join_aligner/join_aligner.md
           - Merge lists: module_docs/align_merge_lists/align_merge_lists.md
           - RANSAC aligner: module_docs/align_ransac/align_ransac.md
-#          - Hierachical aligner (GC): module_docs/align_hierarch/align_hierarch.md
-#          - ADAP aligner (GC): module_docs/align_adap/align_adap_gc.md
+          #          - Hierachical aligner (GC): module_docs/align_hierarch/align_hierarch.md
+          #          - ADAP aligner (GC): module_docs/align_adap/align_adap_gc.md
           - GC-EI aligner: module_docs/align_gcei/align_gc_ei.md
           - LC Image Aligner: module_docs/align_lc-image/align_lc-image.md
       - Gap filling:
-        - Peak finder: module_docs/gapfill_peak_finder/gap-filling.md
-        - Same RT and m/z range gap filler: module_docs/gapfill_same_mz_and_RT_range/same_mz_and_RT_range_gap_filler.md
+          - Peak finder: module_docs/gapfill_peak_finder/gap-filling.md
+          - Same RT and m/z range gap filler: module_docs/gapfill_same_mz_and_RT_range/same_mz_and_RT_range_gap_filler.md
       - Normalization:
-        - Retention time calibration: module_docs/norm_rt_calibration/norm_rt_calibration.md
-        - Linear normalizer: module_docs/norm_linear/norm_linear.md
-        - Standard compound normalizer: module_docs/norm_stand_cmpd/norm_stand_cmpd.md
-#      TODO decide what to do with spectral lib creation
-#  - Spectral library creation: module_docs/id_spectral_library_creation/spectral_library_creation.md
+          - Retention time calibration: module_docs/norm_rt_calibration/norm_rt_calibration.md
+          - Linear normalizer: module_docs/norm_linear/norm_linear.md
+          - Standard compound normalizer: module_docs/norm_stand_cmpd/norm_stand_cmpd.md
+      #      TODO decide what to do with spectral lib creation
+      #  - Spectral library creation: module_docs/id_spectral_library_creation/spectral_library_creation.md
       - Precursor mass search:
-        - Local database search: module_docs/id_prec_local_cmpd_db/local-cmpd-db-search.md
-        - Precursor search in local spectral MS/MS library: module_docs/id_prec_local_spectra_lib/local-spectra-lib-search.md
-#        - Online compound database search: module_docs/id_prec_online_db/online-cmpd-db-search.md
+          - Local database search: module_docs/id_prec_local_cmpd_db/local-cmpd-db-search.md
+          - Precursor search in local spectral MS/MS library: module_docs/id_prec_local_spectra_lib/local-spectra-lib-search.md
+      #        - Online compound database search: module_docs/id_prec_online_db/online-cmpd-db-search.md
       - Spectra search:
           - Spectral library search: module_docs/id_spectral_library_search/spectral_library_search.md
           - NIST MS search: module_docs/id_spectra_NIST/NIST-ms-search.md
           - Chemical formula prediction: module_docs/id_spectra_chem_formula/chem-formula-pred.md
           - Lipid annotation: module_docs/id_lipid_annotation/lipid-annotation.md
           - MS2 similarity search: module_docs/id_ms2_similarity/ms2-similarity-search.md
       - Other parameters:
-        - Merge & select fragment scans: module_docs/filter_scan_merge_select/scan_merge_select.md
-        - Spectra similarity: module_docs/align_join_aligner/spectra_similarity.md
+          - Merge & select fragment scans: module_docs/filter_scan_merge_select/scan_merge_select.md
+          - Spectra similarity: module_docs/align_join_aligner/spectra_similarity.md
 
   - Visualization modules:
       - Visualization overview: visualization_modules/visualization_overview/visualization-overview.md
       - MS data visualisation:
           - Raw data overview: visualization_modules/raw_data_overview/raw_data_overview.md
-          - Additional tools:  visualization_modules/raw_data_overview/raw_data_additional.md
-      - Ion mobility data visualisation:  visualization_modules/ims_raw_data_overview/IM-data-visualisation.md
+          - Additional tools: visualization_modules/raw_data_overview/raw_data_additional.md
+      - Ion mobility data visualisation: visualization_modules/ims_raw_data_overview/IM-data-visualisation.md
       - Image viewer: visualization_modules/image_raw_data/image_viewer.md
       - Image co-localization: module_docs/group_imagecorrelate/image-colocalization.md
       - Processed data visualition:
@@ -152,30 +154,30 @@ nav:
       - General Terminology: terminology/general-terminology.md
       - IMS Terminology: terminology/ion-mobility-terminology.md
       - LC-MS and LC-IMS-MS data comparison: workflows/imsworkflow/lc-ms-and-lc-ims-ms-data-comparison.md
-#      - Kendrick mass defect: module_docs/feature_list_row_filter/kendrick_mass_defect.md
+      #      - Kendrick mass defect: module_docs/feature_list_row_filter/kendrick_mass_defect.md
       - Spectral similarity measures: module_docs/id_spectral_library_search/spectral-similarity-measures.md
 
   - Contribute:
       - Coding:
-            - mzmine development (in IntelliJ): contribute_intellij.md
-            - Upgrade JDK version: coding/upgrade_jdk_version.md
-            - General structure: coding/general_structure.md
-#            - macOS code signing: coding/macos_signing.md
-            - Module development: coding/module_development.md
-            - Modules list: coding/module_list.md
-
-#            TODO Finish writing these
-#            - Raw data structure: coding/raw_data_structure.md
-#            - Feature data structure: coding/feature_data_structure.md
-#            - Example module - Spectral entropy: coding/example_module.md
+          - mzmine development (in IntelliJ): contribute_intellij.md
+          - Upgrade JDK version: coding/upgrade_jdk_version.md
+          - General structure: coding/general_structure.md
+          #            - macOS code signing: coding/macos_signing.md
+          - Module development: coding/module_development.md
+          - Modules list: coding/module_list.md
+
+      #            TODO Finish writing these
+      #            - Raw data structure: coding/raw_data_structure.md
+      #            - Feature data structure: coding/feature_data_structure.md
+      #            - Example module - Spectral entropy: coding/example_module.md
       - Contribute to documentation: contribute.md
       - Documentation template: contribute_docu_template.md
 
   - Acknowledgements: wikiacknowledgements.md
   - Troubleshooting: troubleshooting.md
   - Changelog: changelog.md
   - Workshops: workshops.md
-  
+
 
 copyright: This documentation is licensed under the MIT License (MIT).
 
