Migrating from older version

Migrating AdapterRemoval to 3.x from 2.x

AdapterRemoval v3 makes a number of changes in default behavior, including the renaming of a number of options (old names may still be used, but are deprecated) and the renaming of all output filenames. See the changelog for an exhaustive list of changes in behavior.

Adapter trimming
  • Default adapters have been changed to the recommended Illumina sequences. This makes the default settings more generally applicable, but may result in slightly different results. If nessesary, the old default adapter sequences can be specified using --adapter1 and --adapter2.
Read merging
  • Read-merging is now assigns N to any mismatching position where both candidate bases have the same quality score, to make results deterministic, instead of picking one of the two at random, and picks the higest quality score for each merged position rather than calculate (roughly) the sum of quality scores, to prevent overestimation of base qualities. If the old behavior is desired, then the --merge-strategy option may be set to original.
  • Merged reads are no longer given a M_ name prefix by default, but this may be re-enabled by using the new --prefix-merged option if this is needed.
  • It is no longer possible to "merge" unpaired reads.
Qualty trimming and filtering
  • The various quality trimming options --trimwindows, --trimns, --trimqualities, and --minquality have been deprecated in favor of the new --trim-mott-rate option, which uses the modified Mott's algorithm. This is enabled by default with a threshold of 0.05, but the algorithm used may be changed back (or disabled) using the new --trim-strategy option.
  • Filtering by sequence complexity using an method inspired by fastp has been added and enabled by default, requiring that 30% of positions differ from the previous position (--min-complexity 0.3).
Reports
  • The .settings file has been replaced by two reports, one report in HTML intended for human consumption and one report in JSON format intended for machine consumption.
Misc
  • FASTQ are now always written using Phred+33 quality scores. If you need FASTQ data in another format, then use a tool like seqtk to convert the output.
  • The --qualitymax option has been removed, and AdapterRemoval instead uses loser criteria to verify that input data is valid. Support for the full range valid of quality scores has been added via the --quality-format sam option.
  • The --combined-output option has been removed, but it is now possible to arbitrarily combine output files simply by specifying the same filename for multiple outputs. However, the ability to maintain pairing by writing 0-length trimmed reads as a single N was removed due to a negative impact on some downstream analyses.

Migrating to AdapterRemoval 2.x from 1.x

Command-line options mostly behave the same between AdapterRemoval v1 and AdapterRemoval v2, and scripts written with AdapterRemoval v1.x in mind should work with AdapterRemoval v2.x. A notable exception is the --pcr1 and --pcr2 options, which have been replaced by the --adapter1 and --adapter2 options described above. While the --pcr options are still supported for backwards compatibility, these should not be used going forward.

The difference between these two options is that --adapter2 expects the mate 2 adapter sequence to be specified in the read orientation as described above, while the --pcr2 expects the sequence to be in the same orientation as the mate 1 sequence, the reverse complement of the sequence observed in the mate 2 reads.

Using the common 13 bp Illumina adapter sequence (AGATCGGAAGAGC) as an example, this is how the options would be used in AdapterRemoval v2.x:

adapterremoval3 --adapter1 AGATCGGAAGAGC --adapter2 AGATCGGAAGAGC ...

And in AdapterRemoval v1.x:

adapterremoval3 --adapter1 AGATCGGAAGAGC --adapter2 GCTCTTCCGATCT ...