Search and report on the features of TALE protein domains potentially encoded in subject DNA sequences

tell_tales has been primarily written to report on 'corrected' TALE RVD sequences in indels prone, noisy DNA sequences (suboptimally polished genomes assembly, raw reads of long read sequencing technologies such as PacBio or ONT) that may otherwise be missed by conventional tools (eg AnnoTALE).

Usage

tell_tales(
  subject_file,
  output_dir = tempfile("tell_tales_"),
  hmm_dir = system.file("extdata", "hmmProfile", package = "tantale", mustWork = T),
  nterm_min_score = 300,
  repeat_min_score = 20,
  cterm_min_score = 200,
  terminus_max_evalue = 1e-05,
  terminus_min_cover = 0.9,
  min_dna_hits = 4,
  min_array_length = 0,
  min_gap = 35,
  extremity_codes = TRUE,
  rvd_sep = "-",
  hmmer_path = NULL,
  extend_len = 300,
  correct_array = FALSE,
  correction_ref = system.file("extdata", "tale_correction_ref.fa.gz", package =
    "tantale", mustWork = T),
  max_comparisons = 50,
  frameshift = -11,
  ...
)

Arguments

subject_file

Fasta file with DNA sequence(s) to be searched for the presence of TALE coding sequences (CDS).

output_dir

Path of the output directory, created if it does not exist. The default is a new directory under tempdir(), which R deletes when the session ends: give a path to keep the results. The directory is returned, so tales_from_telltales(tell_tales(genome)) reads the run straight back.

hmm_dir

Folder holding the profile HMMs, if you do not want the ones provided with tantale. It must hold files with the same names: the three DNA profiles of the nhmmer search (Xo_TALE_Nterm_CDS_profile.hmm, Xo_TALE_repeat_CDS_profile.hmm, Xo_TALE_Cterm_CDS_profile.hmm) and the two protein profiles of the terminus check (Xo_TALE_Nterm_AA_profile.hmm, Xo_TALE_Cterm_AA_profile.hmm).

nterm_min_score

Minimal nhmmer score cut_off value to consider the DNA hit as genuine

repeat_min_score

Minimal nhmmer score cut_off value to consider the DNA hit as genuine

cterm_min_score

Minimal nhmmer score cut_off value to consider the DNA hit as genuine

terminus_max_evalue, terminus_min_cover

What it takes for the segment AnnoTALE reports on either side of the repeats to be flagged as a canonical TALE N- or C-terminus, NTERM or CTERM rather than XXXXX (see tales_anchor_codes). The segment is searched with the TALE terminal-domain protein profile of hmm_dir; the match must have an E-value of at most terminus_max_evalue, cover at least terminus_min_cover of the profile's positions, and reach, within 10 positions, the end of the profile that adjoins the repeats. The default of 0.9 comes from the termini of the curated TALEs of tale_annotations: their canonical termini cover 0.93 of the profile or more, the truncated termini of the truncTALEs 0.84 or less.

min_dna_hits

Minimum number of nhmmer hits for a subject sequence (a contig, a chromosome) to be considered further. A cheap way to discard whole sequences that carry nothing but stray matches, before any expensive work is done on them. It says nothing about the length of the TALE arrays found within a sequence that passes – see min_array_length for that.

min_array_length

Minimum number of repeat units for a TALE array to be kept. Defaults to 0, which keeps everything.

Counting repeats rather than all hits means an array is not penalised for having had its termini missed, and matches what "array length" usually means for a TALE: the number of repeats is what determines how long a target box it recognises.

Whether a short array is noise or a genuinely truncated TALE is a judgement about the biology, which is why nothing is discarded unless you ask. A pseudogene with three surviving repeats is real, and may be what you are looking for.

min_gap

Minimum gap in base pairs between two tale domain DNA hits for them to be considered distinct. If the length of the gap is below this value, domains are considered "contiguous" and grouped in the same array.

extremity_codes

Set this to FALSE if you do not want the terminus codes in the RVD strings of rvd_sequences.fas and array_report.tsv.

rvd_sep

Symbol acting as a separator in RVD sequences

hmmer_path

Specify the path to a directory holding the HMMER executable if you do not want to use the ones provided with tantale.

extend_len

number of nucleotides to extend in 3'-end at the tal ORF prediction stage.

correct_array

Whether to pass each array through CorrectFrameshifts before AnnoTALE sees it. FALSE by default; see Details for what turning it on buys (removing artefactual indels) and risks (erroneously "correcting" a genuine frameshift).

correction_ref

Fasta of reference TALE proteins to correct against. Two are shipped, both built by data-raw/make_correction_references.R from the same source:

tale_correction_ref.fa.gz (default, 494 sequences) – every distinct TALE protein of at least 300 aa found across 70 Xanthomonas oryzae genomes.
tale_correction_ref_representative.fa.gz (136) – a diversity-sampled subset, for a smaller footprint.

Both keep the pseudogenes. Their frameshifts came from high-quality genomes and so are assumed real. A reference holding only intact TALEs would "repair" a genuine pseudogene into an ORF that no strain carries.

max_comparisons

How many reference proteins each array may be aligned against during frameshift correction, and the main control on how long correction takes. NULL allows all of them. It is passed to DECIPHER::CorrectFrameshifts(), which ranks the references by a quick distance and aligns the array against the closest max_comparisons of them. The TALE mining article compares values on the genomes shipped with the package.

frameshift

Frameshift penalty passed to CorrectFrameshifts's frameShift. tantale's default is -11, overriding DECIPHER's own -15; change it only with a reason.

...

Additional parameters for the CorrectFrameshifts function.

Value

Called for its side effects (writing files). If everything runs smoothly, it invisibly returns the path of the directory where output files were written.

List of output files:

all_ranges.gff: gff file of all Tal arrays detected by HMMer
array_report.tsv: one row per candidate TALE array. Columns named *_dna_* describe the nhmmer search of the subject DNA; columns named *_aa_* describe the protein segments AnnoTALE extracted from the array's longest ORF.
- array_id, seqnames, start, end, strand: the array's identifier and the span of its nhmmer hits on the subject sequence.
- n_dna_hits: number of nhmmer hits (N-terminus, repeats and C-terminus profiles together) grouped in the array. A terminus hit usually overlaps the adjacent repeat hit by a few nucleotides, at the boundary between the two domains.
- array_seq: DNA sequence of that span.
- nterm_dna_hit, cterm_dna_hit: whether an nhmmer hit of the N- (C-) terminus DNA profile is part of the array. Only hits scoring at least nterm_min_score (cterm_min_score) count.
- rvd_string: the RVDs AnnoTALE read, separated by rvd_sep, with the terminus codes described under rvd_sequences.fas. Empty when AnnoTALE found no RVD.
- has_aberrant_repeat: whether AnnoTALE flagged a repeat of non-canonical length (a lowercase letter in its RVD).
- nterm_dna_score, cterm_dna_score, nterm_dna_evalue, cterm_dna_evalue: bit score and E-value of the best nhmmer hit of the N- (C-) terminus DNA profile next to the array's repeats, whatever its score: on the same strand, upstream of the first repeat (downstream of the last one), within twice the profile length. NA when there is none.
- nterm_dna_cover, cterm_dna_cover: fraction of the DNA profile's positions those hits cover together; 0 when there is none.
- nterm_dna_pieces, cterm_dna_pieces: how many such hits. More than one usually means the terminus is split, often by an insertion or a deletion.
- nterm_aa_evalue, cterm_aa_evalue, nterm_aa_score, cterm_aa_score: E-value and bit score of the hmmsearch match between the segment AnnoTALE reported upstream (downstream) of the repeats and the TALE N- (C-) terminal protein profile. NA when there is no segment, or no match with an E-value up to 10.
- nterm_aa_profile_gap, cterm_aa_profile_gap: number of profile positions between the end of that match and the end of the profile that adjoins the repeats (the last position of the N-terminal profile, the first of the C-terminal one). 0 for a match that reaches the repeats, NA when there is no match.
- nterm_aa_far_gap, cterm_aa_far_gap: the same at the other end of the profile, the start of the N-terminal one (the end of the C-terminal one). A terminus that stops early, like the C-terminus of a truncTALE, leaves a large gap here.
- nterm_aa_cover, cterm_aa_cover: fraction of the protein profile's positions the match covers. Below 1 minus the two gaps when part of the terminus is missing in between.
- nterm_aa_domains, cterm_aa_domains: how many separate stretches of the profile the match consists of. More than one means the terminus is split, by a deletion or a change of reading frame.
- nterm_aa_hit, cterm_aa_hit: TRUE for a canonical terminus: E-value at most terminus_max_evalue, cover at least terminus_min_cover, profile gap at most 10. FALSE for any other segment, NA when AnnoTALE reported no segment on that side.
- nterm_aa_length, cterm_aa_length: length of those segments in amino acid residues, excluding a stop codon, as in the tales object's aa_seq.
- longest_orf_length, longest_orf_seq: the longest ORF found in the array region extended by extend_len nucleotides at its 3' end.
- orf_coverage: that ORF's length as a percentage of the extended region's length.
- predicted_dels_count, predicted_ins_count (with correct_array = TRUE): number of putative deletions/insertions in the raw sequence that CorrectFrameshifts corrected.
hits_report.tsv: report of all hits detected by HMMer, with their bit score, evalue and the profile positions they cover, hmm_from to hmm_to (for hits merged into one, the best score and E-value and the span they cover together)
hits_report.gff: gff file of all hits detected by HMMer
domains_report.tsv: report of all Tal amino acid domains detected by AnnoTALE analyze
putative_tal_orf.fasta: for each array in which AnnoTALE found RVDs, the DNA of the longest ORF of the array region extended by extend_len nucleotides at its 3' end (after frameshift correction with correct_array = TRUE). This is the putative TALE coding sequence AnnoTALE analysed.
pseudo_tal_cds.fasta: for each array in which AnnoTALE found no RVD, the DNA of the array region extended by extend_len nucleotides at its 3' end, as found in subject_file: candidate pseudogenes, assembly errors or false detections, kept for inspection.
rvd_sequences.fas: the RVDs (separated by rvd_sep) of each array for which AnnoTALE found at least one. With extremity_codes = TRUE (the default), each string is bracketed by terminus codes (see tales_anchor_codes): NTERM (CTERM) when the segment AnnoTALE reported upstream (downstream) of the repeats matches the TALE N- (C-) terminal protein profile, XXXXX when it does not, and no code when AnnoTALE reported no segment on that side.
c_terminus_aa_alignment.html: protein alignment of all C-termini (only written when at least 2 were found; skipped with a warning otherwise)
c_terminus_dna_alignment.html: DNA alignment of all C-termini (same condition)
n_terminus_aa_alignment.html: protein alignment of all N-termini (same condition)
n_terminus_dna_alignment.html: DNA alignment of all N-termini (same condition)
tale_cds_all_diagnostic_regions_hmmfile.out: HMMER profile used for tale cds search.
hmmer_search_out.txt: ignore
nhmmer_human_readable_output_of_last_run.txt: primary HMMER output file.
tell_tales.log: a log file
annotale folder: folder containing result of AnnoTALE analyze for all Tal arrays
correction_alignment_aa folder: folder containing protein alignment of Tal array detected by HMMer and corrected Tal array if correct_array = TRUE
correction_alignment_dna folder: folder containing DNA alignment of Tal array detected by HMMer and corrected Tal array if correct_array = TRUE

Details

The approach is first to use HMMER to find and categorize regions in the input DNA sequence that are related to the coding sequence of canonical TALE protein domains (N-Term, repeats, C-term). It then groups hits that are adjacent, or nearly so (see min_gap), into "taleArrays", each a potential tal gene.

With correct_array = FALSE, tell_tales() gives AnnoTALE the longest open reading frame of each taleArray (extended by extend_len) to detect TALE domains in the predicted translation product. The Results should hence be very similar to what would be obtained with AnnoTALE, plus many additional informative output files such as tabular reports.

With correct_array = TRUE, CorrectFrameshifts first tries to 'correct' potential frameshifts in the taleArray sequences. This conveniently removes many artefactual indels but bear in mind that this may also erroneously 'correct' genuine frame shifts which can be highly relevant especially for truncTALEs or iTALEs. The resulting 'corrected' taleArray open reading frames are then passed to AnnoTALE.

Note that occasionally, when a putative open reading frame does not encode a canonical TALE protein (early frame shift, incomplete ORF, etc...), the "analyze" module of AnnoTALE outputs DNA parts but no protein parts and/or RVD sequence. This should be detected and reported in the tell_tales log.

Each sequence of subject_file is treated as linear. A tal gene that spans the junction of a circular molecule (the two ends of an assembled chromosome or plasmid) is cut in two, and is reported, if at all, as two partial arrays at the ends of the sequence. Rotating the sequence so that it starts elsewhere avoids this.

Examples

# \donttest{
# Needs nhmmer and AnnoTALE, resolved from the tantale conda environment
# (and a Java runtime) on first use.
subj <- system.file("extdata", "bai3_sample_tal_genomic_regions.fasta",
                    package = "tantale")
out <- tempfile("tell_tales_example")
tell_tales(subject_file = subj, output_dir = out)
#> HMMER is very picky about forbiden characters in sequence name. Renaming
#> sequences in
#> /home/cunnac/Lab-Related/MyScripts/tantale/inst/extdata/bai3_sample_tal_genomic_regions.fasta.
#> Original seq names : talRegion5 ; talRegion6
#> Dummy seq names : seq1 ; seq2
#> HMMER 3.3.2 (Nov 2020); http://hmmer.org/
#> Copyright (C) 2020 Howard Hughes Medical Institute.
#> Now running AnnoTALE analyze for ROI_00001
#> Now running AnnoTALE analyze for ROI_00002
#> Now running AnnoTALE analyze for ROI_00003
#> Now running AnnoTALE analyze for ROI_00004
#> #****************************************
#> #**   tell_tales analysis done     **
#> Current date:	Fri Oct  9 14:30:36 2026
#> #_________Provided I/O parameters __________
#> File of subject DNA sequences:	/home/cunnac/Lab-Related/MyScripts/tantale/inst/extdata/bai3_sample_tal_genomic_regions.fasta
#> TALE N-term CDS region detection HMM file:	/home/cunnac/Lab-Related/MyScripts/tantale/inst/extdata/hmmProfile/Xo_TALE_Nterm_CDS_profile.hmm
#> TALE repeat unit CDS detection HMM file:	/home/cunnac/Lab-Related/MyScripts/tantale/inst/extdata/hmmProfile/Xo_TALE_repeat_CDS_profile.hmm
#> TALE C-term CDS region detection HMM file:	/home/cunnac/Lab-Related/MyScripts/tantale/inst/extdata/hmmProfile/Xo_TALE_Cterm_CDS_profile.hmm
#> Output directory:	/tmp/RtmpEQXqY1/tell_tales_examplefeab14677a19a
#> #____________Other parameters________________
#> nterm_min_score:	300
#> repeat_min_score:	20
#> cterm_min_score:	200
#> terminus_max_evalue:	1e-05
#> terminus_min_cover:	0.9
#> min_dna_hits:	4
#> min_array_length:	0
#> min_gap:	35
#> extend_len:	300
#> correct_array:	FALSE
#> correction_ref:	/home/cunnac/Lab-Related/MyScripts/tantale/inst/extdata/tale_correction_ref.fa.gz
#> max_comparisons:	50
#> frameshift:	-11
#> #__________Summary measures of TALE search outcome__________
#> Number of analysed subject sequences :	2
#> Total number of TALE repeat DNA coding sequence motif hits found with the nhmmer approach:	88
#> Total number of subject seqs with TALE motif hits after low hit number filtering:	2
#> Total number of distinct regions (repeat arrays) with adjacent TALE motifs :	4
#> Number of arrays with nhmmer DNA hits for both termini:	4
#> Number of arrays whose AnnoTALE N-terminus matches the TALE N-terminal protein profile:	4
#> Number of arrays whose AnnoTALE C-terminus matches the TALE C-terminal protein profile:	4
#> Minimum array length (number of nhmmer DNA hits):	16
#> Maximum array length:	28
#> Median array length:	26
#> Number of gaps of size below 500nt between TALE motifs arrays:	1.5
#> First quartile of size of gaps (below 500nt) between TALE motifs arrays:	108
#> Median size of gaps (below 500nt) between TALE motifs arrays:	108
#> Upper quartile of size of gaps (below 500nt) between TALE motifs arrays:	108
#> #__________Noteworthy AnnoTale issues__________
#> # 
#> #*************************
tales_from_telltales(out)
#> <tales> 4 arrays, 96 parts
#>   layers: rvd   |   6 other columns
#>              rvd
#>   ROI_00001  NTERM NN NG NN HD HD NI N* NG HD NI NG NN HD NI NG NI NG NN N ...
#>   ROI_00002  NTERM NN HD NI NN HD NG HD HD NG NG NI NG NI NG CTERM
#>   ROI_00003  NTERM NN ND NN NI NK NN HD NN NG NG N* HD N* HD NI NN HD NG H ...
#>   ROI_00004  NTERM NI HD NN NS NN NG HD NG HD NG NN NG HD NS HD NI NG HD H ...
# }

Search and report on the features of TALE protein domains potentially encoded in subject DNA sequences

Usage

Arguments

Value

Details

See also

Examples