How to debug the pipeline#

quantms provides multiple strategies to debug and trace the behaviour of the workflow and the corresponding tools. The workflow use different parameters to debug the specific tools or set of tools that perform similar tasks:

pp_debug: this parameter is used to debug the peak picking tool (see Conversion and preprocessing).
db_debug: this parameter is used to debug all the search engines (Comet search engine and MS-GF+ peptide search engine).
luciphor_debug: this parameter is used to debug the modification localization step with luciphor (Modification localization)
inf_quant_debug: this parameter is used to debug the proteomicsLFQ tool, which is used for the LFQ (Label-free quantification with DDA (LFQ)) analysis, including the steps for feature detection, protein inference and peptide/protein quantification.
iso_debug: this parameter is used to debug the isobaric analyzer (Isobaric quantification with DDA) which perform feature detection in isobaric experiments (e.g. TMT, iTRAQ).

Tip

The value of the parameter range from 0 (no debug) to 1000, maximum verbose.

Log files#

Log files are stored in the corresponding folder of each step. For example, for comet searches (Comet search engine) are stored in the folder searchenginecomet/ with the extension .log:

Debug level: 1000
>> CometAdapter -in UM_F_50cm_2019_0414.mzML -out UM_F_50cm_2019_0414_comet.idXML -threads 8 -database Homo-sapiens-uniprot-reviewed-contaminants-decoy-202108.fasta -instrument low_res -missed_cleavages 2 -min_peptide_length 6 -max_peptide_length 40 -num_hits 1 -num_enzyme_termini fully -enzyme Trypsin/P -isotope_error 0/1 -precursor_charge 2:4 -fixed_modifications "Carbamidomethyl (C)" "TMT6plex (K)" -variable_modifications "Acetyl (Protein N-term)" "Oxidation (M)" "TMT6plex (Protein N-term)" "TMT6plex (S)" -max_variable_mods_in_peptide 3 -precursor_mass_tolerance 20 -precursor_error_units ppm -fragment_mass_tolerance 0.6 -fragment_bin_offset 0.4 -debug 1000 -force
Value of string option 'test': 0
Debug level (after ini file): 1000
Value of string option 'no_progress': 0
Value of string option 'comet_executable': comet.exe
..........................

Depending of the debug parameter, the log file will contains more or less details about the running details for the specific tool.

Debug nextflow and architecture errors#

Some errors of the pipeline are not related with the pipeline but with the architecture running the pipeline or nextflow. Nextlow enables to debug the pipeline by using the variable NXF_DEBUG, for example, if the user wants to debug an error not related with the data or a tool, it can set the variable before running export NXF_DEBUG=3.

Tip

Nextflow allows users to resume a previous failing run using the nextflow parameter -resume. This feature enables to start the processing from the steps that have fail and do not need to run the entire pipeline again.

For specific errors, and details about how nextflow is executed on each architecture, please read the details in Nextflow executors.

How to find files in failing process/tools#

When running the pipeline, the quantms (and nextflow) stores the intermediate files and running scripts into a root folder called work/step_running_hash/ (e.g. /work/94/dfdfb63d5816c9c65889ae34511b32/). When the pipeline fails it gives the absolute path of the folder where the step that has fail is stored. The user can go inside the folder and detect the error that has been thrown by the tool or the pipeline.