Merge pull request #108 from bigbio/feat/strip-unknown-mods

feat(diann): add --strip_unknown_mods to recover hydroxyproline / non-standard PTMs

Author: ypriverol

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### `Added`
 
+- New `--strip_unknown_mods` parameter (default `false`) that adds `--strip-unknown-mods` to the DIA-NN steps. Some declared variable modifications are not built into the DIA-NN deep-learning predictor — for example **Oxidation on proline**. During in-silico library generation DIA-NN **silently skips** those precursors (logged as `skipping N precursors, unrecognised modifications`), so they never enter the library and are never identified. Enabling `--strip_unknown_mods` forces DIA-NN to predict spectra/RTs/IMs for them so they are retained and searchable; it is a no-op when every declared modification is already recognised. Documented under [Where each GUI flag goes](docs/usage.md) and [Common pitfalls](docs/usage.md).
 - DIA-NN **2.5.1** (academic) version profile `-profile diann_v2_5_1` (container `ghcr.io/bigbio/diann:2.5.1`).
 - **DIA-NN Enterprise (2.5.1) support** via `-profile diann_v2_5_1_enterprise` (container `ghcr.io/bigbio/diann-enterprise:2.5.1`). New `--enable_kb` flag adds the Enterprise Knowledge Base (`--kb`) to the first-pass search to boost identifications (mainly human data); it is gated to the Enterprise build and **on by default** under the `diann_v2_5_1_enterprise` profile (disable with `--enable_kb false`). New `--diann_license <file>` stages the Enterprise license key into each DIA-NN step as `--license`, with fallback to a key bundled next to the binary when unset. The license key is a per-user secret and is never committed or bundled into the shared image.
 

docs/usage.md

@@ -51,6 +51,7 @@ process ASSEMBLE_EMPIRICAL_LIBRARY {
     scoring_mode = params.scoring_mode == 'proteoforms' ? '--proteoforms' :
                          params.scoring_mode == 'peptidoforms' ? '--peptidoforms' : ''
     aa_eq = params.aa_eq ? '--aa-eq' : ''
+    strip_unknown_mods = params.strip_unknown_mods ? "--strip-unknown-mods" : ""
     diann_tims_sum = params.tims_sum ? "--quant-tims-sum" : ""
     diann_im_window = params.im_window ? "--im-window $params.im_window" : ""
     diann_dda_flag = meta.acquisition_method == 'dda' ? "--dda" : ""
@@ -82,6 +83,7 @@ process ASSEMBLE_EMPIRICAL_LIBRARY {
             --gen-spec-lib \\
             ${scoring_mode} \\
             ${aa_eq} \\
+            ${strip_unknown_mods} \\
             ${license_arg} \\
             ${kb} \\
             ${diann_tims_sum} \\

modules/local/diann/assemble_empirical_library/main.nf

@@ -67,6 +67,7 @@ process FINAL_QUANTIFICATION {
     scoring_mode = params.scoring_mode == 'proteoforms' ? '--proteoforms' :
                          params.scoring_mode == 'peptidoforms' ? '--peptidoforms' : ''
     aa_eq = params.aa_eq ? '--aa-eq' : ''
+    strip_unknown_mods = params.strip_unknown_mods ? "--strip-unknown-mods" : ""
     // Precursor q-value: explicit param wins, else auto by diann_version (<2.5 -> 0.01, >=2.5 -> 0.05)
     precursor_qvalue = VersionUtils.resolvePrecursorQvalue(params)
     // DIA-NN Enterprise license; falls back to a key next to the binary when no path is provided
@@ -109,6 +110,7 @@ process FINAL_QUANTIFICATION {
             ${quantums_params} \\
             ${scoring_mode} \\
             ${aa_eq} \\
+            ${strip_unknown_mods} \\
             ${diann_use_quant} \\
             ${diann_dda_flag} \\
             ${diann_export_quant} \\

modules/local/diann/final_quantification/main.nf

@@ -72,6 +72,7 @@ process INDIVIDUAL_ANALYSIS {
     scoring_mode = params.scoring_mode == 'proteoforms' ? '--proteoforms' :
                          params.scoring_mode == 'peptidoforms' ? '--peptidoforms' : ''
     aa_eq = params.aa_eq ? '--aa-eq' : ''
+    strip_unknown_mods = params.strip_unknown_mods ? "--strip-unknown-mods" : ""
     diann_tims_sum = params.tims_sum ? "--quant-tims-sum" : ""
     diann_im_window = params.im_window ? "--im-window $params.im_window" : ""
     diann_dda_flag = meta.acquisition_method == 'dda' ? "--dda" : ""
@@ -119,6 +120,7 @@ process INDIVIDUAL_ANALYSIS {
             ${max_fr_mz} \\
             ${scoring_mode} \\
             ${aa_eq} \\
+            ${strip_unknown_mods} \\
             ${diann_tims_sum} \\
             ${diann_im_window} \\
             ${diann_dda_flag} \\

modules/local/diann/individual_analysis/main.nf

@@ -40,6 +40,7 @@ process INSILICO_LIBRARY_GENERATION {
     scoring_mode = params.scoring_mode == 'proteoforms' ? '--proteoforms' :
                          params.scoring_mode == 'peptidoforms' ? '--peptidoforms' : ''
     aa_eq = params.aa_eq ? '--aa-eq' : ''
+    strip_unknown_mods = params.strip_unknown_mods ? "--strip-unknown-mods" : ""
     diann_dda_flag = is_dda ? "--dda" : ""
     diann_light_models = params.light_models ? "--light-models" : ""
     // Fine-tuned model flags — only set when tuned model files are provided
@@ -72,6 +73,7 @@ process INSILICO_LIBRARY_GENERATION {
             --gen-spec-lib \\
             ${scoring_mode} \\
             ${aa_eq} \\
+            ${strip_unknown_mods} \\
             ${license_arg} \\
             ${diann_light_models} \\
             ${tuned_tokens_flag} \\

modules/local/diann/insilico_library_generation/main.nf

@@ -43,6 +43,7 @@ process PRELIMINARY_ANALYSIS {
     scoring_mode = params.scoring_mode == 'proteoforms' ? '--proteoforms' :
                          params.scoring_mode == 'peptidoforms' ? '--peptidoforms' : ''
     aa_eq = params.aa_eq ? '--aa-eq' : ''
+    strip_unknown_mods = params.strip_unknown_mods ? "--strip-unknown-mods" : ""
 
     // I am using here the ["key"] syntax, since the preprocessed meta makes
     // was evaluating to null when using the dot notation.
@@ -107,6 +108,7 @@ process PRELIMINARY_ANALYSIS {
             ${max_fr_mz} \\
             ${scoring_mode} \\
             ${aa_eq} \\
+            ${strip_unknown_mods} \\
             ${diann_tims_sum} \\
             ${diann_im_window} \\
             --no-prot-inf \\

modules/local/diann/preliminary_analysis/main.nf

@@ -68,6 +68,7 @@ params {
     debug_level             = 3
     speclib                 = null
     extra_args              = null
+    strip_unknown_mods      = false  // add '--strip-unknown-mods': force DIA-NN to predict spectra/RTs/IMs for declared modifications its deep-learning predictor does not recognise (e.g. Oxidation on proline). Without it those precursors are silently skipped from the in-silico library and never identified. No-op when all declared modifications are recognised.
     scoring_mode      = 'generic'  // Scoring mode: 'generic' (default), 'proteoforms' (variant detection, >= 2.0), 'peptidoforms' (PTM analysis)
     aa_eq                   = false  // add '--aa-eq': treat I&L, Q&E, N&D as equivalent during reannotation (essential for entrapment FDR benchmarks)
     dda                     = false  // Fallback: explicitly enable DDA when SDRF lacks acquisition method (requires DIA-NN >= 2.3.2)

nextflow.config

@@ -536,6 +536,13 @@
                     "fa_icon": "fas fa-filter",
                     "hidden": true
                 },
+                "strip_unknown_mods": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Add --strip-unknown-mods so DIA-NN predicts spectra/RTs/IMs for declared modifications its predictor does not recognise (e.g. Oxidation on proline). Without it those precursors are skipped from the in-silico library.",
+                    "fa_icon": "fas fa-prescription-bottle",
+                    "help_text": "Some declared variable modifications are not built into the DIA-NN deep-learning predictor (e.g. Oxidation on proline). During in-silico library generation DIA-NN silently skips those precursors (logged as 'skipping N precursors, unrecognised modifications') unless this is enabled, so they never enter the library and are never identified. No-op when all declared modifications are recognised by the predictor."
+                },
                 "extra_args": {
                     "type": "string",
                     "description": "Extra arguments appended to all DIA-NN steps. Flags incompatible with specific steps are automatically stripped with a warning.",