Diagnostic characters

Diagnostic Characters looks for alignment positions at which a species differs from every other species of its genus in the recordset. Unlike the distance methods, it does not reduce sequences to a number; it reports the positions and the bases that set a species apart, so that an identification can be supported by named characters rather than by a threshold.

Inputs

Records of the chosen marker that pass the shared filters. For this method the length filter counts every character except gaps, not only A, C, G and T. The convert stage writes each record to FASTA with a key=value header carrying the record ID and taxonomy. Records without both a genus and a species are set aside and counted in the statistics as missing taxonomy.

The analysis reads sequences as columns of one alignment, so every sequence must have the same length. With MAFFT under "Align Sequences" this is guaranteed. With None, sequences of unequal length stop the job at stage 4 with the message that sequences must already be aligned.

Parameters

Method

Grouping. Records are grouped by genus, then by species. Within a genus, a species is eligible when it has at least the minimum number of records. The genus needs at least two eligible species: each eligible species is then analysed as the target, with the records of all other eligible congeners pooled as the reference set. A genus with fewer than two eligible species gets the status no_congeneric_reference for its species and no characters.

Character states. At each column, a base is read as a set of possible nucleotides: A, C, G and T are single sets, and IUPAC ambiguity codes such as R or Y are the corresponding multi-base sets. N, ? and X are unknown, and - or . is a gap; both are empty sets.

Column classification. A column is examined only when no reference record is unknown at that position. The diagnostic states of a column are the bases seen in the target that are never seen in the reference. The column is classed as one of:

Paired columns. When a species has no pure and no full_unique_set column, the job looks for pairs. A candidate column is one where every target record has the same single base and that base also occurs in the reference. Two candidate columns form a compound_pure pair when no single reference record carries the target base at both positions. The pair row lists the reference species that match at either position. Pairs are ordered by the distance between the two columns, closest first, and at most 25 pairs are kept per species.

Positions. Every position reported is a 1-based column number in this run's alignment. It is not a coordinate on the gene or on any reference sequence, and it changes whenever the set of records or the alignment changes.

Outputs

• diagnostic_chars.tsv: one row per diagnostic column or pair, with genus, species, character_type, position_1based, position_2_1based (pairs only), the diagnostic, target and reference states, coverage count and fraction, target and reference record counts, unknown and gap counts on each side, the number of reference species, the reference species matched by a pair, and the target record IDs.
• diagnostic_summary.tsv: one row per eligible species with its status, record counts, the number of eligible and excluded species in its genus, and counts of pure, full_unique_set, partial and compound_pure characters.
• diagnostic_stats.json: run totals, including alignment length, records parsed and analysed, records missing taxonomy, eligible species and genera, and character counts by class.
• aligned_sequences.fas: the alignment the positions refer to.
• filtered_records.jsonl: the records included.

The report shows an Analysis Overview of these totals, a Diagnostic Character Counts by Species bar chart for the ten species with the most characters, broken down by class, and a Species Summary table of up to twenty species with status and per-class counts.

Limitations and interpretation

• Relative to the recordset only. A character is diagnostic against the congeners present in this run with enough records, not against the genus as a whole. Adding a species, or lowering the minimum records so that another species becomes eligible, can remove characters.
• The alignment is the coordinate system. Keep aligned_sequences.fas with any result you cite; a position number without it cannot be interpreted. Nothing in the pipeline maps columns to gene coordinates.
• Gaps cannot be diagnostic. A gap is an empty set, so an insertion or deletion unique to a species is never reported as a character, and a target record with a gap or N at a column is not counted as covered.
• Unknown reference bases hide columns. One N in one reference record removes that column from consideration for the target species.
• Pairs are a fallback. Compound pairs are searched only when single-column characters of full coverage are absent, and are capped at 25; the cap keeps the closest pairs, not any measure of strength.
• Species of different genera are never compared, so the method says nothing about distinguishing a species from look-alikes outside its genus.

Related

• The methods and their shared pipeline
• Barcode gap
• Which method should I use?
• Known limitations