anvi-trnaseq
Table of Contents
A program to process reads from a tRNA-seq dataset to generate an anvi'o tRNA-seq database.
🔙 To the main page of anvi’o programs and artifacts.
Authors
Requires
Provides
Usage
This program analyzes a tRNA-seq library, generating de novo predictions of tRNA sequences, structures, and modification positions.
A FASTA file of merged paired-end tRNA-seq reads is required as input. This file is produced by the initial steps of the trnaseq-workflow, in which Illumina-utils, merges paired-end reads and anvi-script-reformat-fasta creates anvi’o-compliant deflines in the FASTA file.
The primary output of anvi-trnaseq is a trnaseq-db. Supplemental outputs are also produced – an analysis summary, a tabular file of unique sequences not identified as tRNA, an a tabular file of 5’ and 3’ extensions trimmed off mature tRNA.
The anvi-trnaseq --help menu provides detailed explanations of the parameters controlling the multifacted analyses performed by the program.
Examples
Generate a trnaseq-db from a sample using 16 cores.
anvi-trnaseq -f trnaseq-fasta \ -S SAMPLE_NAME \ -o OUTPUT_DIRECTORY \ -T 16
Generate a trnaseq-db from a sample flagged as being treated with demethylase. The output directory is overwritten if it already exists.
anvi-trnaseq -f trnaseq-fasta \ -S SAMPLE_NAME \ -o OUTPUT_DIRECTORY \ -T 16 \ --treatment demethylase \ --overwrite-output-destinations
Parameterize tRNA feature profiling
Feature profiling parameters can be modified by the user by in an optional .ini file. For example, the user may want a more permissive definition of a tRNA (more false positive identifications of sequences as tRNA, fewer false negative failures to identify sequences as tRNA), increasing the number of unpaired nucleotides allowed in the T stem or increasing the number of unconserved canonical nucleotides allowed in the anticodon loop. Numerous structural parameters like these can be altered.
Write the .ini file to param.ini.
anvi-trnaseq --default-feature-param-file PARAM.ini
Nicely display the .ini defaults that can be written to the file in standard output.
anvi-trnaseq --print-default-feature-params
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-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-trnaseq [-h] [-f FASTA] [-S NAME] [-o DIR_PATH] [--treatment TREATMENT] [-W] [--description TEXT_FILE] [--write-checkpoints] [--load-checkpoint {profile,normalize,map_fragments,substitutions,indels}] [--feature-param-file FILE] [--threeprime-termini THREEPRIME_TERMINI] [--min-length-long-fiveprime INT] [--min-trna-fragment-size INT] [--agglomeration-max-mismatch-freq FLOAT] [--skip-INDEL-profiling] [--max-indel-freq FLOAT] [--left-indel-buffer INT] [--right-indel-buffer INT] [-T NUM_THREADS] [--skip-fasta-check] [--profiling-chunk-size INT] [--alignment-target-chunk-size INT] [--default-feature-param-file OUTPUT_FILENAME] [--print-default-feature-params]
Parameters and their descriptions
-f, --trnaseq-fastaFASTA- The FASTA file containing merged (quality-controlled) tRNA-seq reads from a sample. We recommend generating this file via `anvi-run-workflow -w trnaseq` to ensure proper merging of read pairs that may be partially or fully overlapping, and to automatically produce anvi'o-compliant simple deflines. If there is a problem, anvi'o will gracefully complain about it.
-S, --sample-nameNAME- Unique sample name, considering all others in the experiment, that only includes ASCII letters and digits, without spaces
-o, --output-dirDIR_PATH- Directory path for output files
--treatmentTREATMENT- The type of treatment applied during tRNA-seq sample preparation. The values which are currently known to anvi'o are "untreated" and "demethylase", as tRNA-seq samples are commonly split for these treatments. Anvi'o will warn you if you do not choose one of these known options, but it will not affect data processing. Treatment type is stored for further reference in the output tRNA-seq database, and can be used in anvi-merge-trnaseq to affect which nucleotides are called at predicted modification sites in tRNA seed sequences. Default:
untreated -W, --overwrite-output-destinations- Overwrite if the output files and/or directories exist.
--descriptionTEXT_FILE- A plain text file that contains some description about the project. You can use Markdown syntax. The description text will be rendered and shown in all relevant interfaces, including the anvi'o interactive interface, or anvi'o summary outputs.
--write-checkpoints- Use this flag to write pickle files of intermediate results at key points in anvi-trnaseq. If anvi'o crashes for some reason, the argument, --load-checkpoint, with the associated checkpoint name can be used to restart the program from the given checkpoint. This can be useful for saving time if anvi'o crashes or in comparing the results of different advanced program parameterizations involved in later stages of the analytical pipeline after the checkpoint, such as --min-trna-fragment-size and --agglomeration-max-mismatch-freq. This flag will overwrite existing intermediate files in the output directory as needed.
--load-checkpointLOAD_CHECKPOINT- This option restarts `anvi-trnaseq` from the specified checkpoint. It can be useful for saving time if anvi'o crashed after the checkpoint. It can also be useful in comparing the results of different advanced program parameterizations that are only involved in stages of the analytical pipeline after the checkpoint. `anvi-trnaseq` must previously have been run with the flag, `--write-checkpoints`, so that intermediate checkpoint files were generated. Checkpoint "profile" restarts after tRNA profiling. "normalize" restarts after sequence trimming and normalization. "map_fragments" restarts after non-3' fragments have been mapped to normalized tRNA sequences. "substitutions" restarts after potential modification-induced substitutions have been found. "indels" restarts after modification-induced indels have been found, the last step in tRNA identification. If `--write-checkpoints` is used in conjunction with `--load-checkpoint` then all existing intermediate files from checkpoints following the one being loaded will be overwritten. Choices:
profilenormalizemap_fragmentssubstitutionsindels --feature-param-fileFILE- A .ini file can be provided to set tRNA feature parameters used in de novo profiling/identification of tRNA sequences from the 3' end. Generate the default file with the command, `anvi-trnaseq --default-feature-param-file`. Dashes in the default file show parameters that cannot be changed, because they do not exist or are set in stone. For instance, the program only detects base pairing in stems, so only stem features are parameterized with a maximum allowed number of unpaired nucleotides, while every other feature has a dash in the "Number allowed unpaired" column. Two quotes in the default file show parameters that are not currently set. To lift a constraint, a parameter value can be replaced by "". For instance, the conserved purine at D loop/position 21 indicated by the value, 0,R, can be replaced by "" to prevent the program from seeking a conserved nucleotide there. Conserved nucleotides in a feature are set by pairs of zero-based indices and nucleotide symbols. The index indicates the conserved position in the feature, relative to the 5' end of the feature. The nucleotide symbol can be A, C, G, T (U in cDNA), R (purine), or Y (pyrimidine). The index is separated from the symbol by a comma. Multiple conserved positions in a feature are separted by a semicolon. Feature profiling of a sequence halts when the number of allowed unconserved nucleotides in a feature or the number of allowed unpaired positions in a stem is exceeded. The default allowed number of unconserved nucleotides in the D loop, for example, is 1, so 4 of the 5 conserved positions must be found for the D loop to be positively identified. By default, 1 position is allowed to be unpaired (no Watson-Crick or G-T wobble base pair) in each of the 4 stems; the user could, for instance, lift this constraint on the acceptor stem by changing the value from 1 to "". There are 3 variable-length sections of tRNA. The user could, for example, change the allowed lengths of the V loop from a discontinuous range, "4-5,9-23", to a continuous range, "4-23".
--threeprime-terminiTHREEPRIME_TERMINI- Termini represent the subsequences (in the 5'->3' orientation) to expect at the 3' end of a tRNA read adjacent to the discriminator nucleotide. tRNA feature profiling from the 3' end seeks a valid terminus prior to the discriminator and more 5' features. 3' terminal sequences can include the nucleotides, A, C, G, and T, and N, symbolizing any nucleotide. A single underscore, "_", can be included in lieu of a sequence, symbolizing the absence of a terminus such that the tRNA feature profile may end with the discriminator. If "_" is not included, tRNA sequences ending in the discriminator will still be sought as *fragments* of profiled tRNA. The order of sequences in the argument is the order of consideration in profiling. For example, if CCA is the first 3' terminus considered, and it produces a complete profile with no unconserved or unpaired nucleotides, then the other possible termini are not considered. Other termini are only considered with the possibility of "improvement" in the feature profile. Default:
CCA,CC,C,CCAN,CCANN --min-length-long-fiveprimeINT- tRNA reads often extend beyond the 5' end of a mature tRNA sequence. This can be biological in origin when the read is from pre-tRNA; artifactual in origin when the reverse transcriptase runs off the end of the template, adding a small number ofs random bases; or artifactual when the read is a chimera of tRNA at the 3' end and another, potentially non-tRNA, transcript at the 5' end. Longer 5' extensions are more likely to be biological than artifactual due to the exclusion of runoff bases. This parameter sets the minimum length of 5' sequence extensions that are recorded in the tRNA-seq database output for further analysis. Default:
4 --min-trna-fragment-sizeINT- Anvi'o profiles a sequence as tRNA by identifying tRNA features from the 3' end of the sequence. tRNA-seq datasets can include a significant number of tRNA fragments that are not from the 3' end of the sequence ending in a recognized terminus, e.g., CCA. These "interior" and 5' fragments can be of significant biological interest. Fragments are identified by mapping unprofiled reads to profiled tRNAs that have their 3' termini trimmed off. This parameter sets the minimum length of unprofiled reads searched in this manner. The choice of 25 as the default value is motivated by considerations of false positive matches and computational performance with a shorter minimum sequence length. Since unprofiled reads are mapped to every unique profiled tRNA sequence, a shorter minimum sequence length can make mapping take a very long time and return too many alignments to store in memory for datasets of millions of reads. Pay attention to python memory usage if you adjust this parameter downwards. Default:
25 --agglomeration-max-mismatch-freqFLOAT- Anvi'o finds potential tRNA modifications by first agglomerating sequences differing from one or more other sequences in the cluster by mismatches at a certain fraction of nucleotides. This parameter sets the maximum mismatch fraction that is allowed, by default 0.03. The value of this parameter is rounded to the nearest hundredth. The default approximates 2/71, representing 2 mismatches in a full-length tRNA of length 74, not 71, as 3' sequence variants, including the canonical 3'-CCA, are trimmed off prior to sequences being agglomerated. (Average non-mitochondrial tRNAs range in length from 74-95.) For example, consider 3 trimmed sequences of length 71 -- A, B and C -- and 1 sequence of length 65, D. If A differs from B by a substitution at position 1 when aligned (mismatch frequency of 0.014), and C differs from B at positions 10 and 20 (mismatch frequency of 0.028), such that C differs from A by 3 substitutions (mismatch frequency of 0.042), then A, B, and C will still agglomerate into a single cluster, as each differs by no more than 2 substitutions from *some other sequence* in the cluster. In contrast, sequence D differs from B at positions 30 and 40 (mismatch frequency of 0.031), exceeding the 0.03 limit needed to agglomerate. D forms its own cluster and is not consolidated into a single modified sequence with the others. Default:
0.03 --skip-INDEL-profiling- This flag prevents the prediction of deletions in tRNA reads, which can save time.
--max-indel-freqFLOAT- The maximum indel frequency constrains the number and length of modification-induced indels that can be found. The value of this parameter is rounded to the nearest hundredth. Anvi'o identifies tRNAs with potential modification-induced substitutions before finding indels. tRNAs with substitutions are aligned with other sequences to find sequences differing only by indels. The default parameter value of 0.05 allows 1 indel of length 3 to be found in a modified sequence of length 71. (Modified sequences have the canonical 3'-CCA trimmed off, so a sequence of length 71 represents the low end of the non-mitochondrial tRNA length range of 74-95.) The default equivalently allows 2 indels of lengths 1 and 2 or 3 indels of length 1 in a sequence of length 71. An indel of length 4 would result in a frequency of 0.056 and so would not be considered. Default:
0.05 --left-indel-bufferINT- This parameter sets the distance an indel must lie from the left end of a sequence alignment in the search for modification-induced indels.The default buffer of 3 matches was chosen to prevent nontemplated and variant nucleotides at the 5' end of tRNA reads from being mistakenly identified as indels. Default:
3 --right-indel-bufferINT- This parameter sets the distance an indel must lie from the right end of a sequence alignment in the search for modification-induced indels. The default buffer of 3 matches was chosen to prevent variant nucleotides at the 3' end of tRNA reads from being mistakenly identified as indels. Default:
3
-T, --num-threadsNUM_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 --skip-fasta-check- Don't check the input FASTA file for such things as proper defline formatting to speed things up.
--profiling-chunk-sizeINT- Anvi'o manages memory consumption during tRNA feature profiling by chunking the unique input sequences. This parameter sets the maximum number of sequences in each chunk. Adjustment of this parameter has little effect on speed. Default:
100000 --alignment-target-chunk-sizeINT- Anvi'o sequence alignment manages memory consumption by chunking the list of alignment targets, so that queries are aligned to the first chunk of targets, then the second chunk, and so on. This parameter sets the maximum number of target sequences in each chunk. Memory management becomes important when aligning short queries to a large number of targets, which involves searching queries against a massive number of k-mers (equal in length to the shortest query) that have been extracted from targets. Adjust this parameter downward if your system runs out of memory during alignment; adjust this parameter upward to speed up alignment if you find that you are not memory-limited. Ideally, we would set this parameter using a heuristic function parameterized with the numbers and lengths of query and target sequences... Default:
25000
--default-feature-param-fileOUTPUT_FILENAME- Writes a tab-delimited .ini file containing default tRNA feature parameterizations used in de novo profiling/identification of tRNA sequences from the 3' end. Parameters can be modified by the user and the file fed back into anvi-trnaseq through the --feature-param-file argument, the help description of which explains the file format.
--print-default-feature-params- Prints to standard output a nicely formatted table of the default tRNA feature parameterizations (which can be written to a tab-delimited .ini file by the option, --default-feature-param-file).
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.