Reference guide¶
JSON report format¶
The JSON reported is generated if --json=filename.cutadapt.json
is used. The file name
extension must be .cutadapt.json
for the file to be recognized by log-parsing tools such
as MultiQC. (However, at the time of writing, MultiQC does not support
Cutadapt’s JSON report format.)
See how to extract information from the JSON report with jq.
Example¶
This example was reformatted to use less vertical space:
{
"tag": "Cutadapt report",
"schema_version": [0, 1],
"cutadapt_version": "3.5",
"python_version": "3.8.10",
"command_line_arguments": [
"--json=out.cutadapt.json", "-m", "20", "-a", "AACCGGTTACGTTGCA",
"-q", "20", "--discard-trimmed", "-o", "out.fastq.gz", "reads.fastq"],
"cores": 1,
"input": {
"path1": "reads.fastq",
"path2": null,
"paired": false,
"interleaved": null
},
"read_counts": {
"input": 100000,
"filtered": {
"too_short": 251,
"too_long": null,
"too_many_n": null,
"too_many_expected_errors": null,
"casava_filtered": null,
"discard_trimmed": 2061,
"discard_untrimmed": null
},
"output": 97688,
"reverse_complemented": null,
"read1_with_adapter": 2254,
"read2_with_adapter": null
},
"basepair_counts": {
"input": 10100000,
"input_read1": 10100000,
"input_read2": null,
"quality_trimmed": 842048,
"quality_trimmed_read1": 842048,
"quality_trimmed_read2": null,
"output": 9038081,
"output_read1": 9038081,
"output_read2": null
},
"adapters_read1": [
{
"name": "1",
"total_matches": 2254,
"on_reverse_complement": null,
"linked": false,
"five_prime_end": null,
"three_prime_end": {
"type": "regular_three_prime",
"sequence": "AACCGGTTACGTTGCA",
"error_rate": 0.1,
"indels": true,
"error_lengths": [6],
"matches": 2254,
"adjacent_bases": {
"A": 473,
"C": 1240,
"G": 328,
"T": 207,
"": 6
},
"dominant_adjacent_base": null,
"trimmed_lengths": [
{"len": 3, "expect": 1562.5, "counts": [1220]},
{"len": 4, "expect": 390.6, "counts": [319]},
{"len": 5, "expect": 97.7, "counts": [30]},
{"len": 6, "expect": 24.4, "counts": [4]},
{"len": 7, "expect": 24.4, "counts": [5]},
{"len": 8, "expect": 24.4, "counts": [7]},
{"len": 9, "expect": 24.4, "counts": [4]},
{"len": 10, "expect": 24.4, "counts": [7]},
{"len": 11, "expect": 24.4, "counts": [7]},
{"len": 12, "expect": 24.4, "counts": [6]},
{"len": 13, "expect": 24.4, "counts": [8, 2]},
{"len": 14, "expect": 24.4, "counts": [1, 1]},
{"len": 15, "expect": 24.4, "counts": [2, 0]},
{"len": 16, "expect": 24.4, "counts": [3, 1]},
]
}
}
],
"adapters_read2": null
}
Schema¶
Some concepts used in the JSON file:
- Keys are always included. If a key is not applicable, its value is set to null.
- Single-end data appears as “paired-end data without read 2”. That is, values for read 1 are filled in and values for read 2 are set to null.
The file defines the following keys. For nested objects (dictionaries), a dot notation is used, as in “outer_key.inner_key”.
- tag : string
- Always
"Cutadapt report"
. A marker so that this can be recognized as a file produced by Cutadapt. - schema_version : list of two integers
Major and minor version of the schema. If additions are made to the schema, the minor version is increased. If backwards incompatible changes are made, the major version is increased.
Example:
[0, 1]
- cutadapt_version : str
The version of Cutadapt that generated the report.
Example:
"3.5"
- python_version : str
The Python version used to run Cutadapt.
Example:
"3.9"
- command_line_arguments : list of strings
The command-line arguments for this invocation. Only for information, do not parse this.
Example:
["-a", "ACGT", "-o", "out.fastq", "input.fastq"]`
- cores : int
- Number of cores used
- input : dictionary
- Input files
- input.path1 : str
Path to the first input file.
Example:
"reads.1.fastq"
- input.path2 : str | null
- Path to the second input file if given, null otherwise.
- input.paired : bool
- True if input was paired-end reads, false if input was single-end reads. If this is true and input.path2 is null, input was interleaved.
- read_counts : dictionary
- Read count statistics
- read_counts.input : int
- Number of reads (for single-end data) or read pairs (for paired-end data) in the input.
- read_counts.filtered : dictionary
- Statistics about filtered reads. Keys of the dictionary correspond to a filter. If a filter was not used, its value is set to null.
- read_counts.filtered.too_short : int | null
- Number of reads or read pairs that were filtered because they were too short
- read_counts.filtered.too_long : int | null
- Number of reads or read pairs that were filtered because they were too long
- read_counts.filtered.too_many_n : int | null
- Number of reads or read pairs that were filtered because they had too many N bases
- read_counts.filtered.too_many_expected_errors : int | null
- Number of reads or read pairs that were filtered because they had too many expected errors
- read_counts.filtered.casava_filtered : int | null
- Number of reads or read pairs that were filtered because the CASAVA filter was
Y
- read_counts.filtered.discard_trimmed : int | null
- Number of reads or read pairs that were filtered because at least one adapter match was found for them
- read_counts.filtered.discard_untrimmed : int | null
- Number of reads or read pairs that were filtered because no adapter match was found for them
- read_counts.output : int
- Number of reads written to the final output. This plus the sum of all filtered reads/read will equal the number of input reads.
- read_counts.reverse_complemented : int | null
- If
--revcomp
was used, the number of reads that were output reverse-complemented, null otherwise. - read_counts.read1_with_adapter : int | null
- Number of R1 reads (or single-end reads) with at least one adapter match, null if no adapter trimming was done.
- read_counts.read2_with_adapter : int | null
- Number of R2 reads with at least one adapter match, null if input is single end or no adapter trimming was done.
- basepair_counts : dictionary
- Statistics about the number of basepairs.
- basepair_counts.input : int
- Total number of basepairs in the input. (The sum of the lengths of all input reads.)
- basepair_counts.input_read1 : int
- Number of basepairs in the input, read 1 only.
- basepair_counts.input_read2 : int | null
- If paired-end, number of basepairs in the input counting read 2 only, null otherwise.
- basepair_counts.quality_trimmed : int | null
- Total number of basepairs removed due to quality trimming, null if no quality trimming was done.
- basepair_counts.quality_trimmed_read1 : int | null
- Number of basepairs removed from read 1 due to quality trimming, null if no quality trimming was done.
- basepair_counts.quality_trimmed_read2 : int
- Number of basepairs removed from read 2 due to quality trimming, null if no quality trimming was done or if input was single end.
- basepair_counts.output : int
- Total number of basepairs in the final output.
- basepair_counts.output_read1 : int
- Number of basepairs written to the read 1 final output.
- basepair_counts.output_read2 : int | null
- Number of basepairs written to the read 2 final output.
- adapters_read1 : list of dictionaries
- A list with statistics about all adapters that were matched against read 1. The list is empty if no adapter trimming was done. The schema for the items in this list is described below.
- adapters_read2 : list of dictionaries | null
- A list with statistics about all adapters that were matched against read 2. The list is empty if no adapter trimming was done against R2. The value is set to null if the input was single end reads. The schema for the items in this list is described below.
Adapter statistics¶
The statistics about each adapter (items in the adapters_read1 and adapters_read2 list) are dictionaries with the following keys.
- name : str
- The adapter name. If no adapter name was given, a name is automatically generated as “1”, “2”, “3” etc.
- total_matches : int
- Number of times this adapter was found on a read. If
--times
is used, multiple matches per read are possible. - on_reverse_complement : int | null
- If
--revcomp
was used, the number of times the adapter was found on the reverse-complemented read, null otherwise. - linked : bool
- Whether this is a linked adapter. If true, then both
five_prime_end
andthree_prime_end
(below) are filled in and describe the 5’ and 3’ components, respectively, of the linked adapter. - five_prime_end : dictionary | null
Statistics about matches of this adapter to the 5’ end, that is, causing a prefix of the read to be removed.
If the adapter is of type regular_five_prime, noninternal_five_prime or anchored_five_prime, all its matches are summarized here.
If the adapter is a linked adapter (
linked
is true), the matches of its 5’ component are summarized here.If the adapter is of type “anywhere”, the matches that were determined to be 5’ matches are summarized here.
This is null for the other adapter types.
- three_prime_end : dictionary | null
Statistics about matches of this adapter to the 3’ end, that is, causing a suffix of the read to be removed.
If the adapter is of type regular_three_prime, noninternal_three_prime or anchored_three_prime, all its matches are summarized here.
If the adapter is a linked adapter (
linked
is true), the matches of its 3’ component are summarized here.If the adapter is of type “anywhere”, the matches that were determined to be 3’ matches are summarized here.
This is null for the other adapter types.
- three/five_prime_end.type : str
- Type of the adapter. One of these strings:
"regular_five_prime"
"regular_three_prime"
"noninternal_five_prime"
"noninternal_three_prime"
"anchored_five_prime"
"anchored_three_prime"
"anywhere"
For linked adapters, this is the type of its 5’ or 3’ component.
- three/five_prime_end.sequence : str
Sequence of this adapter. For linked adapters, this is the sequence of its 5’ or 3’ component.
Example:
"AACCGGTT"
- three/five_prime_end.error_rate : float
- Error rate for this adapter. For linked adapters, the error rate for the respective end.
- three/five_prime_end.indels : bool
- Whether indels are allowed when matching this adapter against the read.
- three/five_prime_end.error_lengths : list of ints
If the adapter type allows partial matches, this lists the lengths up to which 0, 1, 2 etc. errors are allowed. Example:
[9, 16]
means: 0 errors allowed up to a match of length 9, 1 error up to a match of length 16. The last number in this list is the length of the adapter sequence.For anchored adapter types, this is null.
- three/five_prime_end.matches : int
- The number of matches of this adapter against the 5’ or 3’ end.
- three/five_prime_end.adjacent_bases : dictionary | null
For 3’ adapter types, this shows which bases occurred adjacent to (upstream of) the 3’ adapter match. It is a dictionary mapping the strings “A”, “C”, “G”, “T” and “” (empty string) to the number of occurrences. The empty string covers those cases in which the adjacent base was not one of A, C, G or T or in which there was no adjacent base (3’ adapter found at the beginning of the read).
This is null for 5’ adapters (adjacent base statistics are currently not tracked for those).
- three/five_prime_end.dominant_adjacent_base : str | null
This is set to the dominant adjacent base if adjacent_bases exist and were determined to be sufficiently skewed, corresponding to the warning: “The adapter is preceded by “x” extremely often.”
This is null otherwise.
- three/five_prime_end.trimmed_lengths : list of dictionaries
The histogram of the lengths of removed sequences. Each item in the list is a dictionary that describes how often a sequence of a certain length was removed, broken down by the number of errors in the adapter match.
Example:
"trimmed_lengths": [ {"len": 4, "expect": 390.6, "counts": [319]}, {"len": 5, "expect": 97.7, "counts": [30]}, {"len": 6, "expect": 24.4, "counts": [4]}, {"len": 7, "expect": 24.4, "counts": [5]}, {"len": 15, "expect": 24.4, "counts": [2, 1]}, ]
- three/five_prime_end.trimmed_lengths.expect : float
- How often a sequence of length len would be expected to be removed due to random chance.
- three/five_prime_end.trimmed_lengths.counts : list of int
Element at index i in this list gives how often a sequence of length len was removed due to an adapter match with i errors. Sum these values to get the total count.
Example (5 sequences had 0 errors in the adapter matches, 3 had 1 and 1 had 2):
[5, 3, 1]
Info file format¶
When the --info-file
command-line parameter is given, detailed
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 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.
Which fields are output in each row depends on whether an adapter match was found in the read or not.
If an adapter match was found, these fields are output in a row:
- Read name
- Number of errors
- 0-based start coordinate of the adapter match
- 0-based end coordinate of the adapter match
- Sequence of the read to the left of the adapter match (can be empty)
- Sequence of the read that was matched to the adapter
- Sequence of the read to the right of the adapter match (can be empty)
- Name of the found adapter.
- Quality values corresponding to sequence left of the adapter match (can be empty)
- Quality values corresponding to sequence matched to the adapter (can be empty)
- Quality values corresponding to sequence to the right of the adapter match (can be empty)
- Flag indicating whether the read was reverse complemented: 1 if yes, 0 if not,
and empty if
--revcomp
was not used.
The concatenation of the fields 5-7 yields the full read sequence. Column 8 identifies the found adapter. The section about named adapters <named-adapters> describes how to give a name to an adapter. Adapters without a name are numbered starting from 1. Fields 9-11 are empty if quality values are not available. Concatenating them yields the full sequence of quality values.
If the adapter match was found on the reverse complement of the read, fields 5 to 7 show the reverse-complemented sequence, and fields 9-11 contain the qualities in reversed order.
If no adapter was found, the format is as follows:
- Read name
- The value -1 (use this to distinguish between match and non-match)
- The read sequence
- Quality values
When parsing the file, be aware that additional columns may be added 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
more than once in the info file. There will be one line for each found adapter,
all with identical read names. Only for the first of those lines will the
concatenation of columns 5-7 be identical to the original read sequence (and
accordingly for columns 9-11). For subsequent lines, the shown sequence are the
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.
New in version 1.9: Columns 9-11 were added.
New in version 2.8: Linked adapters in info files work.
New in version 3.4: Column 12 (revcomp flag) added
Properly paired reads¶
When reading paired-end files, Cutadapt checks whether the read names match.
Only the part of the read name before the first space is considered. If the
read name ends with 1
or 2
or 3
, then that is also ignored. For example,
two FASTQ headers that would be considered to denote properly paired reads are:
@my_read/1 a comment
and:
@my_read/2 another comment
This is an example for improperly paired read names:
@my_read/1;1
and:
@my_read/2;1
Since the 1
and 2
(and 3
) are ignored only if the occur at the end of the read
name, and since the ;1
is considered to be part of the read name, these
reads will not be considered to be propely paired.