AnnotateAnticodon

Basic Usage

annotateanticodon.sh in=genome.fna gff=genome.gff out=annotated.gff

The simplest use case annotates a single genome FASTA/GFF pair. When gff= is omitted, the tool automatically infers the GFF filename from the FASTA name (same base path with .gff or .gff.gz extension).

Batch Processing Multiple Genomes

For multiple genome pairs, provide comma-delimited input files and specify an output directory:

annotateanticodon.sh in=archaea4/tid_1.fna.gz,archaea4/tid_2.fna.gz outdir=staging/

The tool will write one annotated GFF per input, named after its corresponding input GFF filename, into the specified output directory.

Anticodon Format Handling

AnnotateAnticodon recognizes two anticodon annotation styles:

• NCBI format: Anticodon position given as genomic coordinates (e.g., anticodon=(pos:1234..1236) or anticodon=(pos:complement(1234..1236))). The tool reads the 3 bases at that position from the FASTA, reverse-complements them for minus-strand tRNAs, converts T→U, and extracts the anticodon sequence.
• tRNAscan-SE format: Anticodon stated directly as a triplet (e.g., anticodon=ACG), already in tRNA 5'→3' orientation. The tool uses this triplet as-is (uppercased, T→U, no reverse-complement), providing direct normalization.

Product/anticodon=(pos:...) forms take priority; mixed or NCBI-style GFFs are normalized correctly. tRNAs without an anticodon position (or with out-of-bounds coordinates) are annotated as Note=tRNA-Xxx(UNK), matching the behavior of extract_trnas.py and ensuring all unknown anticodons cluster together in downstream analysis.

Parameters

Usage Examples

Example 1: Single Genome with Explicit GFF

annotateanticodon.sh in=genome.fna.gz gff=genome.gff.gz out=annotated.gff.gz

Reads genome.fna.gz (compressed FASTA), genome.gff.gz (compressed GFF), annotates all tRNA features with anticodon triplets, and writes the result to annotated.gff.gz. Non-tRNA lines pass through unchanged.

Example 2: Single Genome with Inferred GFF

annotateanticodon.sh in=ecoli.fna out=ecoli_annotated.gff

Reads ecoli.fna (uncompressed FASTA) and automatically finds ecoli.gff (or ecoli.gff.gz if that doesn't exist). Annotates tRNA features and writes uncompressed output to ecoli_annotated.gff.

Example 3: Batch Processing Multiple Genomes

annotateanticodon.sh in=archaea/tid_1.fna.gz,archaea/tid_2.fna.gz,archaea/tid_3.fna.gz outdir=annotated_gffs/

Processes three genome FASTA files in batch mode. Automatically infers corresponding GFF files (tid_1.gff.gz, tid_2.gff.gz, tid_3.gff.gz). Writes three annotated GFFs to annotated_gffs/ with the same filenames as the input GFFs. If annotated_gffs/ does not exist, it is created.

Example 4: Verbose Output and Custom File Handling

annotateanticodon.sh in=genome.fna gff=genome.gff out=annotated.gff verbose=true overwrite=false

Annotates genome.gff with verbose output enabled (reports annotated.gff path to stderr). If annotated.gff already exists, the tool skips processing and preserves the existing file (overwrite=false).

Workflow Integration

With CutGff and TrnaConsensusBuilder

The annotated GFF produced by AnnotateAnticodon flows directly into downstream tRNA analysis pipelines. The Note=tRNA-Xxx(YYY) format is the first-priority branch of TrnaConsensusBuilder.parseAnticodon, so annotated GFFs pass through CutGff and TrnaConsensusBuilder unchanged, with no downstream code modifications needed.

Idempotency and Re-running

AnnotateAnticodon is idempotent: tRNA features already carrying the Note=tRNA-Xxx(YYY) attribute are left untouched. This allows safe re-running on previously annotated GFFs without duplicating or corrupting the annotations.

Handling Incomplete Annotations

tRNAs without anticodon positions (or with out-of-bounds coordinates) are annotated as Note=tRNA-Xxx(UNK). This matches extract_trnas.py behavior and ensures all such tRNAs cluster together under a single UNK key in downstream consensus building, rather than scattering by amino acid.

Technical Details

Anticodon Extraction Logic

The tool implements the Java reimplementation of scripts/extract_trnas.py's extraction logic (lines 104-115 of that script), matching its behavior exactly:

• For NCBI format: reads 1-based inclusive range acStart..acStop from the genome, reverse-complements when minus strand, and converts T→U
• For tRNAscan-SE format: uses the triplet as-is after uppercasing and T→U conversion
• Handles _tid_<taxid> suffix stripping to resolve GFF seqids (bare accessions) to FASTA headers
• Returns (UNK) for missing or invalid anticodon positions, enabling downstream grouping

GFF Attribute Handling

The tool preserves all GFF attributes and line structure. When appending the Note= attribute:

• If existing attributes field is empty or ".", the Note= is the sole attribute
• If existing attributes are present, a semicolon separator is added only if the attributes lack a trailing semicolon (tRNAscan outputs end in semicolon by default)
• The Note= is always appended as the final attribute, maintaining GFF compliance

Performance and Memory

The tool loads entire genome FASTA files into memory (one per input pair processed sequentially). Memory usage scales with genome size. For efficient batch processing, consider splitting very large input lists to process them in smaller groups, allowing garbage collection between batches.

Support

For questions and support:

• Email: bbushnell@lbl.gov
• Documentation: bbmap.org
• GitHub: BBTools Repository