Troubleshooting

Problems with setup or installation

Please leave us an issue and we will try to help out.

No reads found

• Check your reads contain _R1.fastq and _R2.fastq in the read name.
• Reads cannot be gzipped at present (for the read quality filtering tool prinseq)

If you get missing or 0 sized empty bams in output of wochenende

• Check most recent work folder
• cd work && ls -lrt
• Go into most recent folder and subfolder
• ls -l
• cat .command.err
• It could be that trimming adapter files or the program perldup have not been located correctly
• Check your config.yml that the locations to these tools are correct.
• Also check the aligner bwa is accessible within the wochenende conda environment. Type conda activate wochenende && bwa

How to find error messages when pipeline stages fail

• This is also covered in the above point
• Error messages are nicely logged but often somewhat hidden
• Go into the relevant folder in the work (you might need to search a bit)
• Eg cd work/eb/08aa52a2e36d9491acf9cf9ee6ec1f
• Check all the .command.* files, like .command.err .command.log .command.out etc
• You can even re-run the stage from the work directory and check the command there (if the environment is correct, eg you are using the wochenende conda environment
• To re-run type bash .command.sh in the work folder, eg for me work/eb/08aa52a2e36d9491acf9cf9ee6ec1f
• Output and error messages should then be generated live

Reference problems

If you want to use your own reference sequence or add to our offerings, follow the guide on this Wiki at https://github.com/MHH-RCUG/nf_wochenende/wiki/Building-a-reference-sequence for best results. Contact us via issue if problems persist. Our references have been optimised for human lung samples from diseased and healthy patients, but have been useful for freshwater sampling, mouse guts, contaminated mouse filter paper samples, and more.

bwa mem with paired end (PE) reads

We have mostly tested nf_wochenende on SE reads. For PE reads, we noticed the aligner bwa mem outputs very poor alignments by default, eg only 19 bp are aligned in one of the paired reads, while just 40 or so bases are aligned from the second. The rest of the reads are soft-clipped (see https://github.com/MHH-RCUG/nf_wochenende/issues/88 for details). This is actually worse than just aligning one single ended read. We have put some effort into increasing alignment thresholds but results are still very unsatisfactory.

Therefore, we strongly recommend minimap2short and not bwa mem for PE reads. bwa mem PE will terminate with an error (from Nov 2022 onwards).

No output for growth rate

• Considerable numbers of reads are required for good growth rate analysis.
• In practice, this typically means you need a short read metagenome with >500 reads per sample, with more leading to better results
• This limits growth rate analysis to highly covered metagenomes, with only the more common species getting a growth rate estimate.

No output for plots

• Plots might have considered the data too sparse to produce a results.
• Likely the number of reads was too low.
• Plots has mostly been tested on short read metagenomes, but should work fine for long reads.
• Leave us an issue if trouble persists.

No output for Haybaler integration tool

• Haybaler only works with 2+ samples
• We can't do data integration and prepare data for plots from just one sample :-)

Are you having difficulty producing heatmaps or lack an R server in your cluster ?

• Take the outputs from Haybaler, load into your favourite tool ( R, Python, others), and create some visualizations manually
• R code examples are available in our Haybaler repository on github.

Finally - reliability of metagenomics tools

We always recommend using multiple independent tools and methods (and coverage profiles!) of putatively located bacteria before considering the results to be true. Mock communities are useful (also with public data) to test a tool before applying it.