anvi-integrate-trnaseq

Integrate tRNA-seq with (meta)genomic data, relating tRNA-seq seeds to tRNA genes.

🔙 To the main page of anvi’o programs and artifacts.

Authors

Samuel Miller
WebEmailTwitterGithub

Requires

trnaseq-contigs-db seeds-specific-txt modifications-txt contigs-db

Provides

trna-gene-hits

Usage

This program integrates tRNA-seq seeds with tRNA genes in (meta)genomic contigs. It produces trna-gene-hits in a trnaseq-contigs-db.

Seeds, or predicted tRNA transcripts, are the end product of the anvi’o trnaseq workflow. Seeds are generated by the program anvi-merge-trnaseq, with seeds being the merged product of the tRNA sequence information, including modifications, predicted by anvi-trnaseq from individual tRNA-seq samples in an experiment. anvi-merge-trnaseq produces a trnaseq-contigs-db and trnaseq-profile-dbs. Seed and (specific) coverage information from these databases are summarized by anvi-tabulate-trnaseq in a concise, easily parsable table, seeds-specific-txt (see the trnaseq-profile-db artifact for an explanation of “specific” and “nonspecific” coverage). Modification information from the databases are summarized a modifications-txt table. The trnaseq-contigs-db is a mandatory input, as it is modified by anvi-integrate-trnaseq, and the seeds-specific-txt and modifications-txt tables are mandatory inputs used in the computational steps of the program.

The final mandatory input is a (meta)genomic contigs-db annotated with tRNA gene calls by anvi-scan-trnas. The program related seeds (predicted transcripts) to tRNA genes responsible for their expression. Multiple copies of the same tRNA gene are often present in a genome, so read recruitment to any one of these genes cannot be resolved. In a metagenome, the same tRNA gene may be found in multiple bins or in binned and unbinned contigs. Though this can be due to binning errors, identical tRNA genes are often found across taxa as a consequence of their short length and, in many cases, broad phylogenetic distribution. With --unambiguous-genome-assignment, the program ignores seeds assigned to genes that are not restricted to a single bin of a collection or a single genome (each gene is assigned the seed that best matches it).

Gene search process

Seed sequence permutation

The first step in this program is permutation of seed sequences at sites of predicted modifications, to generate a set of permuted sequences per seed. Permuted sequences, including the original seed sequence, are BLASTed against the tRNA genes from the contigs database. Nucleotide permutations account for the fact that the majority nucleotide at a position – which is used in the seed sequence – need not be the unmodified nucleotide. Modification-induced substitutions in tRNA-seq reads result in a semi-random set of nucleotides at modified positions, with mutation fraction proportional to modification fraction. The permuted sequence with the strongest alignment to one or more genes is selected and the others discarded. If multiple permuted sequences have equally strong hits, the one with fewer permutations is favored.

There are two parameters related to permutation.

--min-nt-frequency is the minimum relative frequency, summed across all tRNA-seq samples, required for a nucleotide to be substituted in a permuted sequence. For example, the default value of 0.05 means that a nucleotide with a frequency of 0.04 at a predicted modified position in a seed will not be used in permuted sequences of the seed.

--max-variable-positions is the maximum number of nucleotides that can be permuted at once in a seed sequence. For example, the default value of 5 means that a seed with 6 predicted modification positions will generate a set of permuted sequences with 1, 2, 3, 4, or 5 of these positions containing different nucleotides than the seed (subject to the constraint of --min-nt-frequency, which may preclude permutation of certain positions with low-level mutations).

Alignment

The parameter, --max-mismatches, sets the maximum number of mismatches allowed in the alignment of a (permuted) seed to a tRNA gene, counted over the whole length of the seed. The default value is 3.

Selected seed sequences (permuted or not) may differ from aligned gene sequences for two principal reasons. First, the seed can have undetected modification-induced nucleotide substitutions (or indels, which are ignored here). For example, A34 in many tRNAs can be fully modified to inosine, which is detected as a G rather than A in tRNA-seq reads. Second, the seed can have a single nucleotide variant that differs from the contig sequence. It is not uncommon for populations to have tRNAs with SNVs. When a seed is assigned to multiple genes (each gene is assigned the seed that best matches it), it may be possible to distinguish latent modifications from SNVs: if the different genes contain different nucleotides at the position in question, the seed mismatch is likely due to a SNV rather than a modification.

Alignments are ungapped and must cover the full length of the seed query, except for the post-transcriptional G added to the 5’ end of tRNA-His, which may precede the 5’ end of the gene. BLAST alignments are local, stopping short of mismatches near the ends of the seed, so each BLAST hit is extended to the whole seed before its mismatches are counted. The BLAST word size is set from the length of the shortest seed and --max-mismatches, so that seeds with mismatches spread along their length are still found. Since tRNA-seq reads start from the 3’ end of tRNA and often stop before the 5’ end, seeds need not cover the whole tRNA gene (unless specified in the trnaseq workflow). Seeds must align with the 3’ end of the gene or with the 3’ end of the gene less the 3 nucleotides, CCA: the 3’-CCA acceptor sequence was removed from the seed sequence, as it is often, but not always, added post-transcriptionally.

Edit this file to update this information.

Command line interface

The following is the list of parameters and their descriptions in the latest version of anvi-integrate-trnaseq.

The code that generates this web page ensures that this information is the latest available in 9-dev (eunice). Which means, in some cases the information in this section (generated automatically) might be more comprehensive or up-to-date compared to the descriptions above (written by humans).

Command line usage

anvi-integrate-trnaseq [-h] -t TRNASEQ_CONTIGS_DB [--seeds-specific-txt TEXT_FILE] [--modifications-txt TEXT_FILE] [-c CONTIGS_DB] [-p PROFILE_DB] [-C COLLECTION_NAME] [-b BIN_NAME] [-B FILE_PATH] [-i FILE_PATH] [-e FILE_PATH] [-n FLOAT] [-v INT] [-x INT] [-f] [--unambiguous-genome-assignment] [-u FILE_PATH] [-d DIRECTORY_PATH] [-T NUM_THREADS] [-r] [-l]

Parameters and their descriptions

TRNASEQ INPUTS THREE FILES are required: (1) A 'trnaseq'-variant contigs database produced by `anvi-merge-trnaseq`, (2) a table of **specific** coverages of seeds produced by `anvi-tabulate-trnaseq`, (3) a table of seed modifications also produced by `anvi-tabulate-trnaseq`.
-t, --trnaseq-contigs-db TRNASEQ_CONTIGS_DB required
Anvi'o `trnaseq`-variant contigs database generated by 'anvi-merge-trnaseq'.
--seeds-specific-txt, -s TEXT_FILE
A tab-delimited text file containing data on tRNA seeds including specific coverages. `anvi-tabulate-trnaseq` generates this file from anvi'o tRNA-seq databases.
--modifications-txt, -m TEXT_FILE
A tab-delimited text file containing modification data on tRNA seeds. `anvi-tabulate-trnaseq` generates this file from anvi'o tRNA-seq databases.
GENOMIC INPUTS Different (meta)genomic inputs can be provided. The selection of input type depends on the purpose of running this program. One purpose could be finding tRNAs that are uniquely expressed by genomes in a metagenome, followed by running `anvi-compute-trnaseq-functional-affinity`. Another purpose could be finding all possible genomes that could be responsible for expression of the tRNAs. Note that the flag `--unambiguous-genome-assignment` prevents seed hits to multiple genomes and prevents running the program again with another genome to append new hits. The following are valid inputs: (1) A single contigs database. This could represent a genome or metagenome. (2) A collection of bins, representing genomes in a metagenome. This requires a contigs database, profile database, and collection. (3) A single bin. This requires a contigs database, profile database, collection and bin ID. (4) Internal genomes, or a list of metagenomic bins (can be used with external genomes). (5) External genomes, or a list of contigs databases representing genomes (can be used with internal genomes). With bins (2-4), seeds are matched against all tRNA genes in the contigs databases, so that a seed better matching a gene outside the bins is not assigned to a gene in a bin, but only matches to genes in the bins are stored, unless the contigs database is also given as an external genome.
-c, --contigs-db CONTIGS_DB
Anvi'o (meta)genomic contigs database generated by `anvi-gen-contigs-database`: NOT the tRNA-seq contigs database supplied to `-t/--trnaseq-contigs-db`!
-p, --profile-db PROFILE_DB
Anvi'o profile database
-C, --collection-name COLLECTION_NAME
Collection name.
-b, --bin-id BIN_NAME
Bin name you are interested in.
-B, --bin-ids-file FILE_PATH
Text file for bins (each line should be a unique bin id).
-i, --internal-genomes FILE_PATH
A five-column TAB-delimited flat text file. The header line must contain these columns: 'name', 'bin_id', 'collection_id', 'profile_db_path', 'contigs_db_path'. Each line should list a single entry, where 'name' can be any name to describe the anvi'o bin identified as 'bin_id' that is stored in a collection.
-e, --external-genomes FILE_PATH
A two-column TAB-delimited flat text file that lists anvi'o contigs databases. The first item in the header line should read 'name', and the second should read 'contigs_db_path'. Each line in the file should describe a single entry, where the first column is the name of the genome (or MAG), and the second column is the anvi'o contigs database generated for this genome.
PERMUTATION OF MODIFICATIONS For tRNA-seq seeds to be accurately matched to tRNA genes, nucleotide positions with predicted modifications in the seeds are permuted, generating a set of query sequences per seed. Permutation is needed to find the gene sequences, which lack the mutation signatures induced by modifications in tRNA-seq reads. Seed sequences are built from a simple majority consensus of the reads; if a majority of reads have a mutation at a position, the underlying unmodified nucleotide is not represented in the seed. Permutation does not entirely solve the problem for positions that have such high levels of a modification that there is no signature of mutational variability. The common modification of this sort is I34. The unmodified nucleotide is A, but inosine is read as G, and is typically found in virtually all tRNA transcripts when it occurs. The algorithm solves the problem of I34 with a tailored solution; contact the developers to accommodate any other cases like this that might arise.
-n, --min-nt-frequency FLOAT
For a position in a tRNA-seq seed sequence, this is the minimum nucleotide relative frequency, averaged across samples in which the modification is detected, that is required for the nucleotide to be substituted in the permuted sequence. For example, if this argument is 0.05, and a predicted modified position in a seed has average relative frequencies of A, C, G, and T equal to 0.02, 0.03, 0.1, and 0.85, respectively, then permuted versions of the seed will contain G and T at the position but not A or C. Default: 0.05
-v, --max-variable-positions INT
The maximum number of positions with predicted modifications that can be permuted at once in a tRNA-seq seed sequence. For example, if this argument is 5, and a seed has 6 positions with predicted modifications, then a permuted sequence can have at most 5 of the 6 nucleotides changed relative to the seed. Default: 5
SEED/GENE MATCHING After tRNA-seq seed sequences are permuted, the original and permuted sequences are aligned to tRNA genes in the supplied contigs database(s). Matches are selected from filtered alignments.
-x, --max-mismatches INT
The maximum number of mismatches allowed in a gapless alignment between a permuted or non-permuted tRNA-seq seed and a tRNA gene. Mismatches are counted over the whole length of the seed, including its 5' and 3' ends. Default: 3
-f, --full-gene
Use this flag to only retain tRNA-seq seeds that align with a full tRNA gene, excluding seeds representing 3' fragments.
--unambiguous-genome-assignment
Use this flag to prevent tRNA-seq seeds from being assigned to tRNA genes in multiple genomes or in a single genome and unbinned contigs. Each gene is assigned the seed that best matches it. Consider what happens with two bins. With this flag, if a seed is assigned to genes in both bins, the seed is disregarded; if a seed is assigned to genes in one bin and also to genes in unbinned contigs, the seed is also disregarded. The seed can only be assigned to one or more genes in a single bin. This flag requires bins, internal genomes, or external genomes: a contigs database alone is treated as a single (meta)genome. Note that running this program again without this flag appends new seed/gene assignments to existing ones in the database. With this flag, new results cannot be appended to existing ones and an error is thrown (unless `--remove-previous-matches` is used to discard existing assignments).
TEMPORARY FILES By default, temporary files are produced: (1) A FASTA file of permuted tRNA-seq seed sequences and (2) BLAST databases and output tables from searching permuted seeds against tRNA genes. Each run writes these to new directories in the system's temporary directory, or in the directory given by the global anvi'o option, `--tmp-dir`, and removes them after finishing successfully. Alternatively, program-specific options give more control over temp file storage, and files written to paths given by these options are kept.
-u, --permuted-seeds-fasta FILE_PATH
FASTA file of original and permuted tRNA-seq seed sequences.
-d, --blast-dir DIRECTORY_PATH
Directory to store BLAST databases and tables generated in searching original and permuted seeds against tRNA genes. The directory is created if it does not exist.
OTHER
-T, --num-threads NUM_THREADS
Maximum number of threads to use for multithreading whenever possible. Very conservatively, the default is 1, unless the environmental variable `ANVIO_THREADS` sets another positive integer. If you use this parameter, it will override `ANVIO_THREADS`. It is a good idea to not exceed the number of CPUs / cores on your system. Plus, please be careful with this option if you are running your commands on a SGE -- if you are clusterizing your runs, and asking for multiple threads to use, you may deplete your resources very fast. Default: 1
-r, --remove-previous-matches
Remove existing tRNA-seq seed assignments to tRNA genes in the tRNA-seq contigs database. Without this flag, new assignments are appended to existing ones, replacing any existing assignments to the genomes being integrated.
INFO
-l, --list-genomes
Report information on the sources of tRNA genes that have already been associated with a tRNA-seq contigs database. The `--trnaseq-contigs-db` argument must be provided along with this flag. The project names and hashes of (meta)genomic contigs databases and any collections/bins in which linked tRNA genes were found are printed to the terminal.

Additional Resources

Are you aware of resources that may help users better understand the utility of this program? Please feel free to edit this file on GitHub. If you are not sure how to do that, find the __resources__ tag in this file to see an example.

Copyleft, The anvi'o Project