New upstream version 2.8

Changes

=======

v2.8 (2020-01-13)

-----------------

* :issue:`220`: With option ``--revcomp``, Cutadapt now searches both the read

  and its reverse complement for adapters. The version that matches best is

  kept. This can be used to “normalize” strandedness.

* :issue:`430`: ``--action=lowercase`` now works with linked adapters

* :issue:`431`: Info files can now be written even for linked adapters.

v2.7 (2019-11-22)

-----------------

character <wildcards>` (such as ``N``).

In addition, it is possible to :ref:`remove a fixed number of

bases <cut-bases>` from the beginning or end of each read, and to :ref:`remove

low-quality bases (quality trimming) <quality-trimming>` from the 3' and 5' ends.

bases <cut-bases>` from the beginning or end of each read, to :ref:`remove

low-quality bases (quality trimming) <quality-trimming>` from the 3' and 5' ends,

and to :ref:`search for adapters also in the reverse-complemented reads <reverse-complement>`.

Overview of adapter types

    :ref:`increase the minimum overlap length <random-matches>`.

.. _reverse-complement:

Searching reverse complements

-----------------------------

.. note::

    Option ``--revcomp`` is added on a tentative basis. Its behaviour

By default, Cutadapt expects adapters to be given in the same orientation (5' to 3') as the reads.

To change this, use option ``--revcomp`` or its abbreviation ``--rc``. If given, Cutadapt searches

both the read and its reverse complement for adapters. If the reverse complemented read yields

a better match, then that version of the read is kept. That is, the output file will contain the

reverse-complemented sequence. This can be used to “normalize” read orientation/strandedness.

To determine which version of the read yields the better match, the full adapter search (possibly

multiple rounds if ``--times`` is used) is done independently on both versions, and the version that

results in the higher number of matching nucleotides is considered to be the better one.

The name of a reverse-complemented read is changed by adding a space and ``rc`` to it. (Please

file an issue if you would like this to be configurable.)

The report will show the number of reads that were reverse-complemented, like this::

    Total reads processed:  60

    Reads with adapters:    50 (83.3%)

    Reverse-complemented:   20 (33.3%)

Here, 20 reverse-complemented reads contain an adapter and 50 - 20 = 30 reads that did not need to

be reverse-complemented contain an adapter.

Option ``--revcomp`` is currently available only for single-end data.

.. versionadded:: 2.8

Specifying adapter sequences

============================

    Sequence: 'ACGTACGTACGTTAGCTAGC'; Length: 20; Trimmed: 2402 times.

The meaning of this should be obvious.

The meaning of this should be obvious. If option ``--revcomp`` was used,

this line will additionally contain something like ``Reverse-complemented:

984 times``. This describes how many times of the 2402 total times the

adapter was found on the reverse complement of the read.

The next piece of information is this::

-----------------------

When the ``--info-file`` command-line parameter is given, detailed

information about the found adapters is written to the given file. The

output is a tab-separated text file. Each line corresponds to one read

of the input file (unless `--times` is used, see below). A row is written

for *all* reads, even those that are discarded from the final output

FASTA/FASTQ due to filtering options (such as ``--minimum-length``).

information about where adapters were found in each read are written

to the given file. It is a tab-separated text file that contains at

least one row per input read. Normally, there is exactly one row per

input read, but in the following cases, multiple rows may be output:

The fields in each row are:

  * The option ``--times`` is in use.

  * A linked adapter is used.

A row is written for *all* input reads, even those that are discarded

from the final FASTA/FASTQ output due to filtering options

(such as ``--minimum-length``). Which fields are output in each row

depends on whether an adapter match was found in the read or not.

The fields in a row that describes a match are:

1. Read name

2. Number of errors

If no adapter was found, the format is as follows:

1. Read name

2. The value -1

2. The value -1 (use this to distinguish between match and non-match)

3. The read sequence

4. Quality values

When parsing the file, be aware that additional columns may be added in

the future. Note also that some fields can be empty, resulting in

the future. Also, some fields can be empty, resulting in

consecutive tabs within a line.

If the ``--times`` option is used and greater than 1, each read can appear

ones that were used in subsequent rounds of adapter trimming, that is, they get

successively shorter.

Linked adapters appear with up to two rows for each read, one for each constituent

adapter for which a match has been found. To be able to see which of the two

adapters a row describes, the adapter name in column 8 is modified: If the row

describes a match of the 5' adapter, the string ``;1`` is added. If it describes

a match of the 3' adapter, the string ``;2`` is added. If there are two rows, the

5' match always comes first.

.. versionadded:: 1.9

    Columns 9-11 were added.

.. versionadded:: 2.8

    Linked adapters in info files work.

[mypy]

warn_unused_configs = True

[mypy-xopen]

ignore_missing_imports = True

[mypy-dnaio.*]

ignore_missing_imports = True

[mypy-cutadapt._align.*]

ignore_missing_imports = True

[mypy-cutadapt.qualtrim.*]

ignore_missing_imports = True