Package 'tantale'

Description

Tools to find the TALE genes of Xanthomonas in DNA sequences, compare and group them, align their repeat arrays and predict the plant promoter sites they bind. The package website has worked examples of each step.

Details

Finding TALEs

tell_tales() finds TALE genes with HMMER profiles of the TALE domains, much as AnnoTALE does, and is written for noisy sequences such as draft assemblies or long reads: it can correct frameshifts against reference TALEs before AnnoTALE reads out the RVDs. run_annotale_predict() runs AnnoTALE itself, and correct_tales() runs TALEcorrection. tales_from_telltales() and tales_from_annotale() load either result as a tales object.

Working with TALEs in R

A tales object holds one row per part (N-terminus, repeat or C-terminus) of each TALE, and tales_anomalies() reports the TALEs whose structure is not standard. A tales_msa adds the alignment of the arrays. tale_distances and domain_distances objects hold distances between TALEs or between their domains.

Comparing and grouping TALEs

tales_compare_distal() and tales_compare_functal() reimplement the DisTAL and FuncTAL comparisons of QueTAL. tales_group_kmedoids() and tales_group_hclust() group TALEs from these distances, and talomes_heatmap() compares the groups across strains. AnnoTALE's own classes come from run_annotale_build(), and its published catalogue from run_annotale_load_classes() and run_annotale_assign(). The tale_annotations dataset gives 128 curated TALEs of ten X. oryzae genomes to compare against.

Aligning TALEs

tales_align() aligns the RVD or domain sequences of the arrays with MAFFT; tales_consensus() and the plot() method summarise the alignment.

Predicting targets

tales_predict_targets() runs Talvez (talvez()) or PrediTALE (preditale()) on DNA sequences such as promoters, and plot_target_preds() draws a predicted site with the RVDs facing their bases.

Setting up

MAFFT, HMMER, mmseqs2 and the Perl that Talvez runs on come from a conda environment the package builds for itself, so conda (or mamba, or micromamba) is needed for most of the package. tantale_setup() called bare reports what is present and changes nothing; tantale_setup(install = TRUE) builds or repairs the environment and downloads the Java tools (AnnoTALE, PrediTALE, TALEcorrection) and the example genomes. It checks tool versions as well as presence: MAFFT and HMMER are pinned because later MAFFT versions align TALE repeat strings differently.

Without conda, reticulate::install_miniconda() installs one from inside R. An existing conda, mamba or micromamba is found through reticulate::conda_binary().

Note

tantale runs on Linux and on Intel macOS, the platforms the pinned conda tools exist for; it does not run on Windows. The Java tools need Java on the PATH, which tantale_setup() checks.

Author(s)

Maintainer: Sebastien Cunnac [email protected] (ORCID)

Authors:

• Sebastien Cunnac [email protected] (ORCID)

• Bao Tram Vi [email protected] (ORCID)

Other contributors:

• Alvaro L. Pérez-Quintero (Author of the bundled TALVEZ 3.2 and of the FuncTAL table behind rvd_dna_specificity) [copyright holder]

• Molly Megraw (Author of the PlantTFBS Java classes bundled with TALVEZ (simplescancode/)) [copyright holder]

• Artemis G. Hatzigeorgiou (Author of the PlantTFBS Java classes bundled with TALVEZ (simplescancode/)) [copyright holder]

See Also

Useful links:

• https://scunnac.github.io/tantale/

• https://github.com/scunnac/tantale

• Report bugs at https://github.com/scunnac/tantale/issues

Description

Subsets rows and columns like an ordinary tibble, but the class travels only while the result still satisfies the contract: id1/id2 (both character) and dissim (numeric) all present. Dropping any of them leaves something that can no longer be described as a pairwise distance table, and the result is a plain tibble, without an error.

Usage

## S3 method for class 'pairwise_distances'
x[...]

Arguments

Details

Squareness is not checked here (see distances_assert_square): subsetting rows is an everyday way to end up with a non-square table.

Value

The subset: still a pairwise_distances (or its tale_distances/domain_distances subclass) if the contract holds, otherwise a plain tibble.

See Also

Other pairwise distances: as.matrix.pairwise_distances(), distances_assert_square(), distances_restrict(), is_pairwise_distances(), pairwise_distances(), rvd_dna_specificity, tales_assign_domain_codes(), tales_compare_distal(), tales_compare_functal(), tales_domain_distances(), tales_group_hclust(), tales_group_kmedoids(), tales_tale_distances(), validate_pairwise_distances()

Examples

d <- pairwise_distances(data.frame(
  id1 = c("A1", "A1", "A2", "A2"),
  id2 = c("A1", "A2", "A1", "A2"),
  dissim = c(0, 35, 35, 0)
))
is_pairwise_distances(d[1:2, ]) # row subsetting never breaks the contract
class(d[, "id1"])               # dropping dissim/id2: the class steps aside

Description

Subsets rows and columns like an ordinary tibble, but the class travels only while the result still satisfies the tales contract.

Usage

## S3 method for class 'tales'
x[...]

Arguments

Details

Row subsetting never breaks anything: every invariant a tales checks still holds on any subset of rows, so filtering to one array, or to its repeats only, is still a valid tales. Column subsetting is where it degrades: dropping array_id, or both residue columns (rvd, dom_code) at once, leaves something that can no longer be described as a tales, and the result is a plain tibble, without an error. Dropping an optional column (seqnames, aa_seq, ...) has no such consequence. A tales_msa degrades one step at a time: losing alignment_position alone steps it back to a plain tales.

Attributes travel with a valid subset. dom_code_namespace describes the run the codes came from, so cutting an object down with [ keeps its namespace unchanged.

Value

The subset: still a tales (or tales_msa) if the contract holds, otherwise a plain tibble.

See Also

Other tales objects: as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

x <- tales(data.frame(
  array_id = c("A1", "A1"), position_in_array = c(1L, 2L),
  rvd = c("NTERM", "HD")
))
is_tales(x[1, ]) # row subsetting never breaks the contract
class(x[, -1])   # dropping array_id: the class steps out of the way

Description

Turns sep-separated TALE sequences — RVD strings, or repeat-code strings — into a tales object, taking sequence order as position_in_array and sequence names as array_id.

Usage

as_tales(x, ...)

## S3 method for class 'data.frame'
as_tales(x, ...)

## Default S3 method:
as_tales(x, sep = "-", residue_col = c("rvd", "dom_code"), ...)

Arguments

Details

The result is deliberately column-poor: a bare sequence file carries no domain types, amino acid sequences or source contigs, so only array_id, position_in_array and the chosen residue column are produced. That is a valid tales: seqnames and the other columns are optional.

A tales_msa passed to as_tales() is demoted to a plain tales: alignment_position stays as an ordinary column, and the alignment width is dropped (tales_msa_width returns NULL).

Value

A validated tales object.

See Also

Other tales objects: [.tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

rvd_fasta <- system.file("extdata", "TalA_RVDSeqs_AnnoTALE.fasta",
                         package = "tantale")
as_tales(rvd_fasta, sep = "-")

Description

Materialises the wide form, with ids as both row and column names, sorted.

Usage

## S3 method for class 'pairwise_distances'
as.matrix(x, value = PAIRWISE_DISTANCES_VALUE_COL, ...)

Arguments

Details

x must be square (see distances_assert_square, called here for you): every id present in both id1 and id2. A table filtered on one id column only is not; use distances_restrict to filter both.

Value

A numeric matrix, square, with sorted ids as dimnames.

See Also

Other pairwise distances: [.pairwise_distances(), distances_assert_square(), distances_restrict(), is_pairwise_distances(), pairwise_distances(), rvd_dna_specificity, tales_assign_domain_codes(), tales_compare_distal(), tales_compare_functal(), tales_domain_distances(), tales_group_hclust(), tales_group_kmedoids(), tales_tale_distances(), validate_pairwise_distances()

Examples

d <- pairwise_distances(data.frame(
  id1 = c("A1", "A1", "A2", "A2"),
  id2 = c("A1", "A2", "A1", "A2"),
  dissim = c(0, 35, 35, 0)
))
as.matrix(d)

Description

Materialises the rectangular form: one row per array, one column per alignment position, cells holding the requested layer. This is the only place the gapped matrix is built — the long object is the canonical storage.

Usage

## S3 method for class 'tales_msa'
as.matrix(x, value = NULL, gap = NA, ...)

Arguments

Value

A character matrix with arrays as rows and alignment positions as columns.

See Also

Other TALE alignment: is_tales_msa(), tales_align(), tales_consensus(), tales_consensus_match(), tales_msa(), tales_msa_params(), tales_msa_width(), validate_tales_msa()

Examples

aligned <- data.frame(
  array_id = c("A1", "A1", "A1", "A2", "A2"),
  position_in_array = c(1L, 2L, 3L, 1L, 2L),
  alignment_position = c(1L, 2L, 3L, 1L, 3L),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "CTERM")
)
msa <- tales_msa(aligned)
as.matrix(msa) # gaps as NA
as.matrix(msa, gap = "-") # gaps as "-"

Description

A much faster alternative to running tell_tales in correction mode on error-prone sequences such as ONT-assembled genomes: a wrapper around the Java TALE correction tool from this GitHub page. It takes an input fasta file and writes a file with corrected indels in TALE coding sequences using an approach described in the Erkes et al. paper. tell_tales can subsequently be run on the corrected sequences in no correction mode.

Usage

correct_tales(
  uncorrected_path,
  corrected_path = tempfile("corrected_tales_", fileext = ".fa"),
  hmm_path = .tantale_tool("talecorrection_hmm"),
  return_corrections = FALSE,
  conda_bin = "auto",
  java_args = ""
)

Arguments

Value

A tibble if return_corrections is TRUE or the path to the corrected sequences file.

See Also

Other TALE discovery: tale_annotations, tales_from_annotale(), tales_from_telltales(), tell_tales()

Examples

# Needs nhmmer and a Java runtime.
subj <- system.file("extdata", "bai3_sample_tal_genomic_regions.fasta",
                    package = "tantale")
out_fa <- tempfile(fileext = ".fa")
correct_tales(uncorrected_path = subj, corrected_path = out_fa)

Description

Checks that the table holds every ordered pair of the ids it contains — n^2 rows for n ids. Phrased over the ids present, so that a symmetric subset stays square: filtering both id columns to the same set of entities preserves this, while filtering one of them does not.

Usage

distances_assert_square(x, arg = "x")

Arguments

Details

Squareness is a precondition of the functions that need it. The class itself does not require it, because filtering the two id columns one after the other passes through a legitimate non-square intermediate.

Value

x, invisibly.

See Also

Other pairwise distances: [.pairwise_distances(), as.matrix.pairwise_distances(), distances_restrict(), is_pairwise_distances(), pairwise_distances(), rvd_dna_specificity, tales_assign_domain_codes(), tales_compare_distal(), tales_compare_functal(), tales_domain_distances(), tales_group_hclust(), tales_group_kmedoids(), tales_tale_distances(), validate_pairwise_distances()

Examples

d <- pairwise_distances(data.frame(
  id1 = c("A1", "A1", "A2", "A2"),
  id2 = c("A1", "A2", "A1", "A2"),
  dissim = c(0, 35, 35, 0)
))
distances_assert_square(d)

try(distances_assert_square(d[1:3, ])) # missing the A2-A2 pair -- errors

Description

Filters both id columns, which is what keeps the result square.

Usage

distances_restrict(x, ids)

Arguments

Value

A pairwise_distances over ids only.

See Also

Other pairwise distances: [.pairwise_distances(), as.matrix.pairwise_distances(), distances_assert_square(), is_pairwise_distances(), pairwise_distances(), rvd_dna_specificity, tales_assign_domain_codes(), tales_compare_distal(), tales_compare_functal(), tales_domain_distances(), tales_group_hclust(), tales_group_kmedoids(), tales_tale_distances(), validate_pairwise_distances()

Examples

d <- pairwise_distances(data.frame(
  id1 = c("A1", "A1", "A1", "A2", "A2", "A2", "A3", "A3", "A3"),
  id2 = c("A1", "A2", "A3", "A1", "A2", "A3", "A1", "A2", "A3"),
  dissim = c(0, 35, 60, 35, 0, 40, 60, 40, 0)
))
distances_restrict(d, c("A1", "A2"))

Description

The representation print.tales emits, returned as a character vector, so an object's description can go somewhere other than the console: a log, an error message, a report.

It shows what the class knows and a tibble would not: the number of arrays as distinct from the number of parts, which residue layers the object carries, the dom_code namespace when it is stamped, and a preview of the first and last arrays as sequences.

The preview uses dom_code when present and rvd otherwise. Domain codes are the more discriminating of the two: two arrays can share an RVD sequence while being built from different repeats.

This replaces the format() a tales would otherwise inherit from tibble. Call format(tibble::as_tibble(x)) for that one.

Usage

## S3 method for class 'tales'
format(x, n = 2L, ...)

Arguments

Value

A character vector, one element per line.

See Also

Other tales objects: [.tales(), as_tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

parts <- data.frame(
  array_id = c("A1", "A1", "A1", "A2", "A2", "A2"),
  position_in_array = c(1L, 2L, 3L, 1L, 2L, 3L),
  domain_type = c("N-terminus", "repeat", "C-terminus",
                  "N-terminus", "repeat", "C-terminus"),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "NI", "CTERM")
)
x <- tales(parts)
format(x)

Description

As format.tales, plus the alignment width, and a preview of aligned rows: gaps are drawn and every cell padded to a common width, so the columns line up down the page.

Usage

## S3 method for class 'tales_msa'
format(x, n = 2L, gap = "-", ...)

Arguments

Value

A character vector, one element per line.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

aligned <- data.frame(
  array_id = c("A1", "A1", "A1", "A2", "A2"),
  position_in_array = c(1L, 2L, 3L, 1L, 2L),
  alignment_position = c(1L, 2L, 3L, 1L, 3L),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "CTERM")
)
msa <- tales_msa(aligned)
format(msa)

Description

Is this a pairwise distance table?

Usage

is_pairwise_distances(x)

Arguments

Value

A logical scalar.

See Also

Other pairwise distances: [.pairwise_distances(), as.matrix.pairwise_distances(), distances_assert_square(), distances_restrict(), pairwise_distances(), rvd_dna_specificity, tales_assign_domain_codes(), tales_compare_distal(), tales_compare_functal(), tales_domain_distances(), tales_group_hclust(), tales_group_kmedoids(), tales_tale_distances(), validate_pairwise_distances()

Examples

d <- data.frame(
  id1 = c("A1", "A1", "A2", "A2"),
  id2 = c("A1", "A2", "A1", "A2"),
  dissim = c(0, 35, 35, 0)
)
is_pairwise_distances(d)
is_pairwise_distances(pairwise_distances(d))

Description

Is this a tales object?

Usage

is_tales(x)

Arguments

Value

A logical scalar.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

parts <- data.frame(
  array_id = c("A1", "A1", "A1"),
  position_in_array = 1:3,
  domain_type = c("N-terminus", "repeat", "C-terminus"),
  rvd = c("NTERM", "HD", "CTERM")
)
is_tales(parts)        # a plain data frame
is_tales(tales(parts))

Description

Is this a tales_msa object?

Usage

is_tales_msa(x)

Arguments

Value

A logical scalar.

See Also

Other TALE alignment: as.matrix.tales_msa(), tales_align(), tales_consensus(), tales_consensus_match(), tales_msa(), tales_msa_params(), tales_msa_width(), validate_tales_msa()

Examples

aligned <- data.frame(
  array_id = c("A1", "A1", "A1", "A2", "A2"),
  position_in_array = c(1L, 2L, 3L, 1L, 2L),
  alignment_position = c(1L, 2L, 3L, 1L, 3L),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "CTERM")
)
msa <- tales_msa(aligned)
is_tales_msa(msa)
is_tales_msa(as_tales(msa)) # back to a plain tales

Description

The long form of a square pairwise distance over one entity set: one row per ordered pair of entities, with a dissim value (0 for identical entities, larger for more different ones).

Usage

pairwise_distances(x, dom_code_namespace = NULL)

tale_distances(x, dom_code_namespace = NULL)

domain_distances(x, dom_code_namespace = NULL)

Arguments

Details

tale_distances() and domain_distances() are the entity-specific flavours: distances between whole TALE arrays, and between distinct domains, repeats and the two termini alike. For domain_distances, dissim is the percentage of amino acids that differ between two domains (see tales_domain_distances); for tale_distances, it is the array alignment cost between two TALEs (see tales_tale_distances). The two flavours add no structure, only meaning: every method is written once on the parent.

Value

A validated pairwise_distances object.

See Also

Other pairwise distances: [.pairwise_distances(), as.matrix.pairwise_distances(), distances_assert_square(), distances_restrict(), is_pairwise_distances(), rvd_dna_specificity, tales_assign_domain_codes(), tales_compare_distal(), tales_compare_functal(), tales_domain_distances(), tales_group_hclust(), tales_group_kmedoids(), tales_tale_distances(), validate_pairwise_distances()

Examples

d <- data.frame(
  id1 = c("A1", "A1", "A2", "A2"),
  id2 = c("A1", "A2", "A1", "A2"),
  dissim = c(0, 35, 35, 0)
)
pairwise_distances(d)
domain_distances(d, dom_code_namespace = "example")

# A similarity is folded into the distance.
similar <- data.frame(id1 = "A1", id2 = "A2", sim = 65)
tale_distances(similar)

Description

This function enables visual inspection of TALE target predictions results that are located within a specified subject DNA sequence region

Usage

plot_target_preds(preds, subj_file, filter_range)

Arguments

Details

RVDs sequences predicted to target an EBE on the sense strand of the DNA sequence are plotted on top of the double stranded DNA sequence in parallel to its cognate EBE which is highlighted on the corresponding strand of the DNA sequence. Those predicted to target an EBE on the opposite strand are displayed below.

Each RVD sits in a box whose colour says how strongly the RVD is expected to bind the base at that position, compared with the other three bases. The RVDs labelled "OO" correspond to the first non-canonical repeat also called repeat zero in TALE protein sequences.

Numeric values inside the boxes located immediately to the right of the TALE labels reflect prediction scores.

Value

Returns a ggplot object that can be further altered using ggplot2 package functions.

See Also

Other target prediction: preditale(), tales_predict_targets(), talvez()

Other TALE plots: plot.tales(), plot.tales_msa(), talomes_heatmap()

Examples

# Needs a Java runtime, for preditale().
x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
rvds <- tales_rvd_strings(x)
subj <- system.file("extdata", "cladeIII_sweet_promoters.fasta",
                    package = "tantale")
preds <- preditale(rvd_seqs = rvds, subj_file = subj)
best <- preds[order(-preds$score), ][1, ]
# The site with 10 bp on either side
plot_target_preds(preds = best, subj_file = subj,
                  filter_range = paste0(best$subj_seq_id, ":",
                                        best$start - 10, "-", best$end + 10))

Description

A compact, information-rich view of the arrays in a tales object: one point per part, positioned by its place in the array, outlined by domain type and filled by part type and amino-acid length. Each repeat carries its RVD, each terminus the short name of its code (N-, -C, or ?? for a terminus that does not match its TALE domain profile; see tales_anchor_codes). Arrays are listed from the top in alphabetical order of array_id.

The fill colours follow the role of each part. The canonical 34-aa repeat and the 20-aa half-repeat that ends every array get calm colours, so a repeat of any other length (an aberrant repeat, for instance) stands out. N-termini are shades of wine and C-termini shades of teal, lighter when shorter, which makes a truncated terminus visible. The legend gives the length of each colour, its keys outlined like the parts they stand for. All colours are chosen to stay distinct for colour-blind readers.

A tales_msa dispatches to plot.tales_msa instead, being the more specific class.

Usage

## S3 method for class 'tales'
plot(x, position = c("array", "alignment"), facet_by = "seqnames", ...)

Arguments

Value

A ggplot object. Like any ggplot, it is drawn when printed, which happens automatically at the console; inside a loop or a function, call print() on it.

See Also

Other TALE plots: plot.tales_msa(), plot_target_preds(), talomes_heatmap()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
plot(x)
plot(x, facet_by = NULL)

Description

Draws the alignment as a heatmap: one row per array, one column per alignment position, with cells coloured by one layer and optionally labelled with another.

Usage

## S3 method for class 'tales_msa'
plot(
  x,
  fill = NULL,
  label = NULL,
  tale_distances = NULL,
  domain_distances = NULL,
  h_cut = 10,
  ref_pattern = NULL,
  consensus = FALSE,
  fill_type = "domain_clust",
  ...
)

Arguments

Details

A tales_msa carries every layer at once (rvd, dom_code and whatever else the object holds), so fill and label simply name two of them.

Three settings act independently, and it helps to read the figure that way: what each cell says, what colour that text is, and what colour the block behind it is.

Cell text is whatever label names, or nothing when label = NULL. Termini are relabelled N- and -C; an unidentified terminus keeps its XXXXX code. Domain codes are padded to three characters so columns line up.

Text colour always answers one question: does this element match the consensus of its column? Black for yes, red for no, grey where the column has no consensus (a gap, or a tie). The block fills are all pale, so the text reads on every one of them. The consensus is the most frequent element in the column (tales_consensus), taken over the labelled layer, so the text colour and the text itself always describe the same thing.

Block fill is what fill_type selects, and it is the only part that can be unavailable:

Every value here scores across the whole tales_msa, termini included: domain_distances covers every distinct part sequence, and "domain_clust"/"domain_sim" colour a terminus cell exactly like a repeat cell.

With no domain_distances and no label, every block is flat grey: the text still carries the consensus comparison, but there is nothing to colour blocks by.

A cell with no value for the chosen layer keeps its text and is filled grey. In "rvd_sim" that is the termini, which have no DNA-binding preference and so no position on a specificity scale. The RVD similarity table is TALVEZ's and covers 17 RVDs; a rarer RVD (NV, say) scores 1 where it is identical to the reference's RVD and is grey elsewhere.

The reference matters for both similarity fills. ref_pattern must match exactly one array name; otherwise the function warns and uses the default, which is the array with the most non-gap parts, ties broken alphabetically. The reference row is marked with a trailing _#.

Two panels may be attached. Supplying tale_distances with more than one array adds a dendrogram panel on the left; consensus = TRUE adds a consensus panel on top. When either is present the return value is an aplot composition: modify the alignment through its plotlist element, since layers added to the composition itself do not reach it.

Value

The alignment plot, returned invisibly after being printed as a side effect: a ggplot normally, or, when tale_distances and/or consensus add extra panels, an aplot composition – see Details.

See Also

Other TALE plots: plot.tales(), plot_target_preds(), talomes_heatmap()

Examples

aligned <- data.frame(
  array_id = c("A1", "A1", "A1", "A2", "A2"),
  position_in_array = c(1L, 2L, 3L, 1L, 2L),
  alignment_position = c(1L, 2L, 3L, 1L, 3L),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "CTERM")
)
msa <- tales_msa(aligned)
plot(msa)

Description

An R wrapper around the PrediTale 'PrediTALE.jar preditale' module. Takes a list of TALE RVD sequences and a fasta file of DNA sequences and runs PrediTale.

Usage

preditale(
  rvd_seqs,
  subj_file,
  opt_param = "",
  output_dir = NULL,
  java_args = "-Xms512M -Xmx2G",
  predictor_path = .tantale_tool("preditale")
)

Arguments

Value

A tibble with one row per predicted EBE (effector binding element), the columns renamed from the tool's own output so that talvez and preditale return the same ones in the same order: tale_id, rvds, subj_seq_id, start, end, strand, ebe_seq and score, followed by the tool's own column: pval, the approximate p-value PrediTALE gives each site.

See Also

Other target prediction: plot_target_preds(), tales_predict_targets(), talvez()

Examples

# Needs a Java runtime.
x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
rvds <- tales_rvd_strings(x)
subj <- system.file("extdata", "cladeIII_sweet_promoters.fasta",
                    package = "tantale")
preds <- preditale(rvd_seqs = rvds, subj_file = subj)
head(preds)

Description

Emits what format.tales builds; see there for what is shown and why.

Usage

## S3 method for class 'tales'
print(x, n = 2L, ...)

Arguments

Value

x, invisibly.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

parts <- data.frame(
  array_id = c("A1", "A1", "A1", "A2", "A2", "A2"),
  position_in_array = c(1L, 2L, 3L, 1L, 2L, 3L),
  domain_type = c("N-terminus", "repeat", "C-terminus",
                  "N-terminus", "repeat", "C-terminus"),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "NI", "CTERM")
)
x <- tales(parts)
print(x)

Description

Emits what format.tales_msa builds; see there for what is shown and why.

Usage

## S3 method for class 'tales_msa'
print(x, n = 2L, gap = "-", ...)

Arguments

Value

x, invisibly.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

aligned <- data.frame(
  array_id = c("A1", "A1", "A1", "A2", "A2"),
  position_in_array = c(1L, 2L, 3L, 1L, 2L),
  alignment_position = c(1L, 2L, 3L, 1L, 3L),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "CTERM")
)
msa <- tales_msa(aligned)
print(msa)

Description

An R wrapper around the 'AnnoTALEcli.jar assign' call. AnnoTALE places each TALE in the class of the catalogue it belongs to, and opens a new class for any that fit none. Where run_annotale_build groups the TALEs you hand it among themselves, knowing nothing of what the rest of the world calls them, this one answers "which published class is this TALE in", so its names can be compared with the literature's.

Usage

run_annotale_assign(
  fasta_file,
  class_builder,
  output_dir = tempfile("annotale_assign_"),
  strain = NULL,
  accession = NULL,
  opt_param = "",
  java_args = "-Xms512M -Xmx8G",
  annotale_jar = .tantale_tool("annotale")
)

Arguments

Value

output_dir, invisibly. It holds the per-TALE assignment report, a table of original against proposed systematic names, a report and figure for each class that changed or was created, and a class builder extended with the TALEs given.

See Also

run_annotale_load_classes, which fetches the classes; run_annotale_build, which builds classes from scratch instead.

Other external TALE tools: run_annotale_build(), run_annotale_load_classes(), run_annotale_predict()

Examples

# Needs a Java runtime and the catalogue, which takes a while to fetch.
classes <- run_annotale_load_classes(output_dir = tempfile("annotale_classes_"))
predicted <- run_annotale_predict(tantale_genome("MAI1"))
tales <- list.files(file.path(predicted, "Predict"),
                    pattern = "^TALE_DNA_sequences_", full.names = TRUE)
run_annotale_assign(tales, class_builder = classes, strain = "MAI1")

Description

An R wrapper around the AnnoTALE 'AnnoTALE.jar build' program. It usually takes its input from the file generated by the run_annotale_predict function.

Usage

run_annotale_build(
  fasta_file,
  output_dir = tempfile("annotale_build_"),
  opt_param = "c=5 s=0.01",
  java_args = "-Xms512M -Xmx6G",
  annotale_jar = .tantale_tool("annotale")
)

Arguments

Value

output_dir, invisibly. If AnnoTALE exits with a non-zero status, the function stops with an error of class tantale_error_annotale_failed.

See Also

Other external TALE tools: run_annotale_assign(), run_annotale_load_classes(), run_annotale_predict()

Examples

# Needs a Java runtime and the tools tantale_setup() downloads. Chained
# from run_annotale_predict()'s own output, since that is the file build
# normally classifies.
fasta <- tantale_genome("MAI1")
predict_out <- file.path(tempdir(), "annotale_build_example", "predict")
run_annotale_predict(fasta, output_dir = predict_out)
predicted <- list.files(file.path(predict_out, "Predict"),
                        pattern = "^TALE_DNA_sequences_", full.names = TRUE)
build_out <- file.path(tempdir(), "annotale_build_example", "build")
run_annotale_build(predicted, output_dir = build_out)
list.files(build_out)

Description

A TALE class groups the TALEs of different strains that are similar enough to be considered the same effector, and carries the systematic name the literature uses for it (TalAA, TalAB, ...). AnnoTALE curates that catalogue and publishes it; this is an R wrapper around its 'AnnoTALEcli.jar loadAndView' call, which downloads the current definition. run_annotale_assign consumes what it writes.

Usage

run_annotale_load_classes(
  output_dir = tempfile("annotale_classes_"),
  class_builder = NULL,
  opt_param = "",
  java_args = "-Xms512M -Xmx8G",
  annotale_jar = .tantale_tool("annotale")
)

Arguments

Details

The download is slow and bulky: about a quarter of an hour, and some 440 MB of output, most of it the class builder itself, which carries a cached alignment between every pair of catalogued TALEs. The file is therefore kept once and reused rather than fetched per call, which is what output_dir is for: point it at a directory you keep, and pass the returned path to run_annotale_assign as often as you like.

Record the date along with any class you take from it. A class name is stable, but the catalogue grows, and the index AnnoTALE appends to the class when it names a TALE (TalAH30, the thirtieth member of TalAH) is only true of the catalogue that produced it.

Value

The path of the class builder XML, invisibly, so the call can be passed straight to run_annotale_assign. Beside it, output_dir also holds Lists_of_classes,_strains_and_TALEs/, whose List_of_classes.txt gives every class as plain text, one line per member with its aligned repeat-variable diresidues, strain and systematic name. That file answers "which class is this TALE in" without going through run_annotale_assign at all, when the TALE is already catalogued.

See Also

run_annotale_assign, which places TALEs into these classes.

Other external TALE tools: run_annotale_assign(), run_annotale_build(), run_annotale_predict()

Examples

# Slow: downloads and rebuilds the catalogue, about 15 minutes.
classes <- run_annotale_load_classes(output_dir = tempfile("annotale_classes_"))

Description

An R wrapper around the AnnoTALE 'AnnoTALE.jar predict' and 'AnnoTALE.jar analyze' shell calls. run_annotale_build completes the AnnoTALE workflow.

Usage

run_annotale_predict(
  fasta_file,
  output_dir = tempfile("annotale_predict_"),
  prefix = NULL,
  opt_param = "Sensitive=false",
  java_args = "",
  annotale_jar = .tantale_tool("annotale")
)

Arguments

Value

output_dir, invisibly, so that the call can be passed straight to tales_from_annotale(). If either stage exits with a non-zero status, the function stops with an error of class tantale_error_annotale_failed.

See Also

Other external TALE tools: run_annotale_assign(), run_annotale_build(), run_annotale_load_classes()

Examples

# Needs a Java runtime, and the tools and genomes tantale_setup() downloads.
fasta <- tantale_genome("MAI1")
out <- file.path(tempdir(), "annotale_predict_example")
run_annotale_predict(fasta, output_dir = out)
list.files(file.path(out, "Predict"))

Description

One row per RVD, giving its relative binding weight for each of the four bases. This is the table tales_compare_functal stacks, one row per repeat, to build an array's position weight matrix.

Usage

rvd_dna_specificity

Format

A tibble with 404 rows and 5 columns:

rvd

The two-letter RVD code. "N*" and "H*" are RVDs whose residue 13 is missing; "OO" is position 0, the base just before the first repeat's target, where TALEs prefer a T; "XX" is the flat fallback row used for an unrecognised RVD.

A, C, G, T

Relative binding weight for that base. The weights do not sum to one: tales_compare_functal hands them to create_motif as raw counts (type = "PCM"), which normalises internally.

Details

Taken verbatim from QueTAL FuncTAL's own table (Info/2014mat18 in FuncTAL 1.1, by A. L. Pérez-Quintero, redistributed with permission): the values are unchanged, only a header and column names added. Conceptually related to but distinct from the internal rvdSimDf used by tales_align's RVD scoring: that one is a derived RVD-vs-RVD similarity (a correlation between two RVDs' base-preference profiles, itself built from TALVEZ's much smaller 17-RVD mat1), used to score repeat substitutions during sequence alignment. This one is the raw, per-RVD base preference itself, one level upstream, used to build a whole array's binding-specificity model for comparison against another array's. The two tables serve different consumers and cannot replace each other.

References

Pérez-Quintero A.L. et al. (2015). QueTAL: a suite of tools to classify and compare TAL effectors functionally and phylogenetically. Frontiers in Plant Science 6, 545. doi:10.3389/fpls.2015.00545

See Also

tales_compare_functal, its only consumer.

Other pairwise distances: [.pairwise_distances(), as.matrix.pairwise_distances(), distances_assert_square(), distances_restrict(), is_pairwise_distances(), pairwise_distances(), tales_assign_domain_codes(), tales_compare_distal(), tales_compare_functal(), tales_domain_distances(), tales_group_hclust(), tales_group_kmedoids(), tales_tale_distances(), validate_pairwise_distances()

Examples

rvd_dna_specificity[rvd_dna_specificity$rvd %in% c("HD", "NI", "NG", "NN"), ]

Description

The measures worth knowing about a set of TALE arrays before doing anything with them, and the ones too expensive for print.tales.

Usage

## S3 method for class 'tales'
summary(object, ...)

## S3 method for class 'summary.tales'
print(x, ...)

Arguments

Details

Distinct domains counts different dom_codes against the number of parts, broken down by domain type. These are domains, repeats and termini alike: a dom_code identifies any distinct part sequence, and the two termini are parts like the repeats are. In the example output shipped with the package (see tales_from_telltales), 47 distinct codes cover 39 repeats and 8 termini, so reading the total as a count of distinct repeats would overstate repeat diversity.

The ratio to parts is a property of the biology: TALEs reuse repeats heavily, within an array and between arrays. It is also what decides the cost of tales_compare_distal, whose pairwise comparison runs over distinct domains.

Repeats per array counts repeats only, excluding the termini, so it is the number that determines how long a target box each TALE recognises. Note that tell_tales()'s log reports array length as the number of domain hits, which includes the two termini and is therefore larger by up to two.

Complete arrays are those where both an N- and a C-terminus were identified. An incomplete one is not necessarily wrong (the array may sit at the end of a contig, or a terminus may simply not have been detected), but completeness is a precondition several downstream functions depend on.

Anomalies come from tales_anomalies. They are worth computing but too slow to compute every time an object is printed, which is why they appear here.

Value

An object of class summary.tales: a list of the measures, so they can be used as well as read.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

parts <- data.frame(
  array_id = c("A1", "A1", "A1", "A2", "A2", "A2"),
  position_in_array = c(1L, 2L, 3L, 1L, 2L, 3L),
  domain_type = c("N-terminus", "repeat", "C-terminus",
                  "N-terminus", "repeat", "C-terminus"),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "NI", "CTERM")
)
x <- tales(parts)
summary(x)

Description

What an alignment looks like, in numbers: how gappy it is, and how much the arrays actually agree.

Usage

## S3 method for class 'tales_msa'
summary(object, ...)

## S3 method for class 'summary.tales_msa'
print(x, ...)

Arguments

Details

Columns with no consensus is the measure worth having. A column has no consensus when no element is strictly more common than the rest (see tales_consensus), so the count says how much of the alignment the arrays agree on.

It is reported per layer, and the two usually differ in a way that means something. Repeats that are distinct proteins can carry the same RVD, so a column can lack a dom_code consensus while having a clear rvd one: the arrays disagree about the repeat and agree about the base it binds. The reverse is rarer and more interesting.

Value

An object of class summary.tales_msa.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

aligned <- data.frame(
  array_id = c("A1", "A1", "A1", "A2", "A2"),
  position_in_array = c(1L, 2L, 3L, 1L, 2L),
  alignment_position = c(1L, 2L, 3L, 1L, 3L),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "CTERM")
)
msa <- tales_msa(aligned)
summary(msa)

Description

The TALEs of ten complete, published genomes, named as the literature names them and annotated by hand. It is the reference this package's own discovery can be checked against: three of the ten genomes, MAI1, BAI3 and PXO86, are the ones tantale_genome() installs, so a tell_tales() run on them can be compared array by array with what is recorded here.

Usage

tale_annotations

Format

A tibble with 128 rows and 10 columns. One row is one TALE gene.

strain

The strain, e.g. "PXO99A". Ten of them.

label, tal_name

The TALE's name in the literature, capitalised ("Tal4a") and as written in the source publication ("tal4a"). strain and label together identify a row: a label repeats across strains, never within one. tal_name is missing where the source gives no name.

annotale_class

The AnnoTALE class the TALE belongs to ("TalAH"), from the catalogue of 2026-10-04. A class groups TALEs similar enough to be considered the same TALE across strains, and is how the literature refers to them. Missing for two rows, see Details.

replicon_id, genome_id

The RefSeq replicon and the GenBank assembly the TALE comes from, e.g. "NC_010717" and "GCA_000019585.2". Present for every row: this is what lets a reader fetch the sequence.

pubmed

PubMed identifier(s) of the publication(s) reporting the genome or the TALE, comma-separated where there is more than one.

truncTALE

TRUE for the nine truncTALEs, TALEs whose C-terminal region is naturally shortened so that they no longer activate transcription. See the truncTALE article for what this does to discovery and to frameshift correction.

rvd_seq

The repeat-variable diresidues in array order, dash-separated ("NI-HD-NG-..."), the format of tales_rvd_strings. tales_predict_targets takes them as a named BStringSet: Biostrings::BStringSet(setNames(rvd_seq, paste(strain, label))). A lowercase RVD ("ng", "n*") marks a repeat of non-standard length, the usual convention; 16 of the 128 arrays carry at least one, so do not upper-case this column before comparing it with anything.

unusual_feature

A note, for the nine arrays that carry one, on what makes the gene atypical: repeats of non-standard length, deletions, duplications, a premature stop.

Details

The table is sparse where the sources are: tal_name is absent for 19 rows and pubmed for 19. The gaps are the state of the curation, not placeholders to be filled by a guess.

annotale_class is missing for one row: PXO99A's Tal7b, the five-repeat allele its own unusual_feature describes, too short to be catalogued.

The class is stored without the member index AnnoTALE appends to it ("TalAH", not "TalAH30"). That index numbers the members of a class as of the day it is read, and the catalogue grows: every one of the 73 indices recorded when this table was curated in 2021 had moved by 2026, while the class itself agreed in every case.

Identifiers that name an array within a single run are deliberately not included: the tell_tales array id and AnnoTALE's tempTALE name both depend on the run that produced them, so neither would survive a rerun. Matching a row to a fresh tell_tales result means matching on what the TALE is, its rvd_seq, rather than on what some run called it.

No column of DisTAL groups is included. The working file carried one, but how its values had been computed was not recorded, so they could not be vouched for. tales_compare_distal followed by tales_group_hclust computes such groups from rvd_seq.

Source

Compiled by Bao Tram Vi during the work that became this package, from the genome records and publications cited in each row; published here for the first time. annotale_class was taken from AnnoTALE's class catalogue as downloaded on 2026-10-04. The genome sequences themselves are the GenBank assemblies named in genome_id, at https://www.ncbi.nlm.nih.gov/datasets/genome/.

See Also

talomes_heatmap, which takes a table of this shape directly: the column names below are the ones its group_col, strain_col, rvd_col and trunc_tales_col arguments expect.

Other TALE discovery: correct_tales(), tales_from_annotale(), tales_from_telltales(), tell_tales()

Examples

# the TALEs of one strain
subset(tale_annotations, strain == "PXO86",
       select = c("label", "annotale_class", "truncTALE"))

# the ten strains compared class by class; truncTALEs are marked "T"
grouped <- tale_annotations[!is.na(tale_annotations$annotale_class), ]
talomes_heatmap(grouped, group_col = "annotale_class",
                strain_col = "strain", rvd_col = "rvd_seq",
                trunc_tales_col = "truncTALE")

# the naturally truncated ones, across all ten genomes
table(tale_annotations$strain, tale_annotations$truncTALE)

# what makes the atypical arrays atypical
subset(tale_annotations, !is.na(unusual_feature),
       select = c("strain", "label", "unusual_feature"))

Description

Builds a tales object from a data frame of TALE array parts: one row per (array, slot).

Usage

tales(x, dom_code_namespace = NULL, sanitize = FALSE)

Arguments

Value

A validated tales object.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

parts <- data.frame(
  array_id = c("A1", "A1", "A1", "A2", "A2", "A2"),
  position_in_array = c(1L, 2L, 3L, 1L, 2L, 3L),
  domain_type = c("N-terminus", "repeat", "C-terminus",
                  "N-terminus", "repeat", "C-terminus"),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "NI", "CTERM")
)
tales(parts)

Description

Aligns TALE arrays on one of their residue layers with MAFFT's text mode, returning the alignment as a tales_msa — the input object with an alignment_position column added, so every other layer (rvd, dom_code, aa_seq, ...) remains available.

Usage

tales_align(
  x,
  residue_col = c("rvd", "dom_code"),
  domain_distances = NULL,
  mafft_opts = "--localpair --maxiterate 1000 --reorder --op 0 --ep 5 --thread 1",
  mafft_path = NULL,
  mafft_verbose = FALSE
)

Arguments

Details

The mapping back from MAFFT's output is positional: the k-th non-gap cell of an aligned row is the k-th part fed in. That is well defined only because this function builds MAFFT's input from x itself, which is why tales_assert_complete is enforced first.

Value

A tales_msa object. The settings it was aligned with (residue_col, domain_distances, mafft_opts) are kept with it; tales_msa_params returns them.

See Also

Other TALE alignment: as.matrix.tales_msa(), is_tales_msa(), tales_consensus(), tales_consensus_match(), tales_msa(), tales_msa_params(), tales_msa_width(), validate_tales_msa()

Examples

# Needs MAFFT, resolved from the tantale conda environment on first use.
rvd_fasta <- system.file("extdata", "TalA_RVDSeqs_AnnoTALE.fasta",
                         package = "tantale")
x <- as_tales(rvd_fasta, sep = "-")
msa <- tales_align(x, residue_col = "rvd")
as.matrix(msa)

Description

The values a rvd column takes on non-repeat parts.

Usage

tales_anchor_codes()

Details

AnnoTALE reports as N-terminus whatever the ORF encodes upstream of the first repeat, and as C-terminus whatever it encodes downstream of the last one. tell_tales searches each of these segments with the TALE N- or C-terminal protein profile (hmmsearch). "NTERM" and "CTERM" mark a canonical TALE terminal domain, one that can be expected to do its usual job: the match has an E-value of at most terminus_max_evalue, covers at least terminus_min_cover of the profile (0.9 by default) and reaches the end of the profile that adjoins the repeats. "XXXXX" marks any other segment. An array for which AnnoTALE reported no segment on one side has no terminus part at the protein level on that side.

A terminus can fail to be canonical in several ways, which array_report.tsv tells apart (its *_aa_* and *_dna_* columns, see tell_tales): the segment may be unrelated sequence where the ORF starts or ends inside a frameshifted region, its repeat-side part may be in another reading frame, or the terminus may have lost a large part of its domain. The truncTALEs of Xanthomonas oryzae have lost the activation domain, and their C-termini are coded "XXXXX". A smaller internal deletion, such as the one in the N-terminus of TalC, a major TALE of African X. oryzae pv. oryzae, leaves a terminus canonical.

These share the rvd column with real RVDs, so code that distinguishes repeats from termini by value should use this function rather than spelling the codes out.

Value

A named character vector of the three codes.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

tales_anchor_codes()

Description

Lists the arrays whose content is biologically odd:

• missing sequence data,

• a structure other than that of a standard TALE (an N-terminus, one or more repeats and a C-terminus, both termini canonical TALE terminal domains),

• impossible domain-type arrangements,

• coordinate disagreements,

• an amino acid sequence paired with more than one RVD,

• an attribute that varies within an array when it should not.

Structurally broken input (a duplicated key, a missing required column) is an error in tales instead.

"Odd" arrays are accepted by tales – real TALE predictions are messy, and refusing to load them would force cleaning outside the package and destroy the diagnostic signal. Construction warns about them and this function tells you which and why.

Each anomaly is of one of two kinds. "noncanonical" marks a TALE whose structure departs from the standard one: a terminus that is not a canonical TALE terminal domain (terminus_noncanonical), such as the C-terminus of a truncTALE, or no terminus part on one side (terminus_absent). Such TALEs can be real and interesting. "integrity" marks every other anomaly: data that are inconsistent or incomplete, or an array without repeats. tales(x, sanitize = TRUE) removes the arrays with an anomaly of kind "integrity" and keeps the others; tales(x, sanitize = "canonical") keeps canonical TALEs only.

The structure checks need a domain_type column, and the terminus profile check an rvd column; they are skipped when it is absent. The structure checks report terminus_absent (no N- or no C-terminus part), no_repeat (no repeat part) and terminus_noncanonical (a terminus coded XXXXX, see tales_anchor_codes). They apply to whole arrays: a subset keeping only the repeats is reported as lacking its termini.

Usage

tales_anomalies(x)

Arguments

Value

A tibble of array_id, check, kind ("integrity" or "noncanonical") and detail, one row per anomaly. Zero rows if the object is clean.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

# A2 carries two N-termini -- an impossible arrangement.
odd <- data.frame(
  array_id = c("A1", "A1", "A2", "A2", "A2"),
  position_in_array = c(1L, 2L, 1L, 2L, 3L),
  domain_type = c("N-terminus", "repeat",
                  "N-terminus", "N-terminus", "repeat"),
  rvd = c("NTERM", "HD", "NTERM", "NTERM", "NI")
)
x <- suppressWarnings(tales(odd))
tales_anomalies(x)
tales(odd, sanitize = TRUE) # drops A2 instead of merely warning

# B2 is a truncTALE-like array: its C-terminus is not canonical.
parts <- data.frame(
  array_id = rep(c("B1", "B2"), each = 3),
  position_in_array = rep(1:3, 2),
  domain_type = rep(c("N-terminus", "repeat", "C-terminus"), 2),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "NI", "XXXXX")
)
y <- tales(parts, sanitize = TRUE)          # keeps B2, with a message
tales_anomalies(y)
z <- tales(parts, sanitize = "canonical")   # drops B2
unique(z$array_id)

Description

Checks that every array carries all of its parts: position_in_array running contiguously from 1, and — when domain_type and position_in_crd are present — position_in_crd equal to position_in_array minus the number of non-repeat parts before it.

Usage

tales_assert_complete(x, arg = "x")

Arguments

Details

Completeness is a precondition of some functions; the class itself does not require it: filter(x, domain_type == "repeat") legitimately produces a valid tales that is no longer complete. Alignment requires completeness, because the mapping back from a MAFFT alignment is positional — the k-th aligned residue is the k-th part fed in.

Value

x, invisibly.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_bind(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

rvd_fasta <- system.file("extdata", "TalA_RVDSeqs_AnnoTALE.fasta",
                         package = "tantale")
x <- as_tales(rvd_fasta, sep = "-")
tales_assert_complete(x) # every array is 1..n already -- no error

# Keeping only the repeats breaks completeness, which tales_align() needs.
repeats_only <- x[x$position_in_array > 1, ]
try(tales_assert_complete(repeats_only))

Description

Step 1 of tales_compare_distal(). Gives each distinct aa_seq in x an integer code, recorded in a dom_code column, so that the parts can be compared once each rather than once per occurrence.

A code names a distinct domain sequence, repeats and termini alike: the N- and C-termini are parts like the repeats are, and they get codes too.

Usage

tales_assign_domain_codes(x)

Arguments

Details

TALEs reuse domains heavily, within an array and between arrays, so the number of distinct sequences is far smaller than the number of parts. That ratio is what makes tales_domain_distances() affordable: it compares each distinct domain once.

Value

x with a dom_code column and a dom_code_namespace stamp.

The codes are only meaningful within one call

Codes are assigned with dplyr::cur_group_id() over the distinct aa_seq values present in x. Add an array, remove one, or reorder the sequences, and the same protein can get a different number. They are positions in this table's own vocabulary.

So comparing codes between two calls is an error, and a distance table keyed by one call's codes must never be used with another call's. This is enforced: every object minted here is stamped with a dom_code_namespace derived from the sequences that produced it, and the classes refuse to join across namespaces. Read the stamp with tales_namespace().

See Also

tales_compare_distal(), which runs all three steps; tales_domain_codes(), which reads the code-to-sequence table back out of an object that already has codes.

Other pairwise distances: [.pairwise_distances(), as.matrix.pairwise_distances(), distances_assert_square(), distances_restrict(), is_pairwise_distances(), pairwise_distances(), rvd_dna_specificity, tales_compare_distal(), tales_compare_functal(), tales_domain_distances(), tales_group_hclust(), tales_group_kmedoids(), tales_tale_distances(), validate_pairwise_distances()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
xa <- tales_assign_domain_codes(x)
tales_namespace(xa)

Description

Row-binds one or more tales objects into one, reconciling the invariants that a plain bind_rows would not check: array_id uniqueness across inputs, the dom_code namespace, and the group column. A single input is accepted: it goes through the same reconciliation and re-validation, harmlessly.

Usage

tales_bind(..., on_namespace_mismatch = c("recode", "error"), sanitize = FALSE)

Arguments

Details

There is no c() method: base c() can silently drop attributes when a tales is mixed with another object, and its signature has no room for on_namespace_mismatch.

tales_msa inputs are refused: alignment_width and alignment_position are a coordinate system specific to one alignment run, and binding two runs' matrices would produce an object that misdescribes what a given column means in each row. Demote explicitly with as_tales first if that is really what you want.

group is dropped from the result whenever present on any input: it is a clustering result over one specific distance matrix and one specific set of arrays, so two "group 1"s from separate tales_group_hclust/tales_group_kmedoids calls are not comparable. Recompute it with either on the bound result, after re-running tales_compare_distal.

tale_distances/domain_distances are untouched: this function only binds tales data. A companion distance table from either input does not describe the bound object; re-run tales_compare_distal if you need one.

Value

A validated tales object.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_names(), tales_namespace(), tales_requirements(), validate_tales()

Examples

a <- tales(data.frame(
  array_id = "A1", position_in_array = 1:2,
  rvd = c("NTERM", "HD")
))
b <- tales(data.frame(
  array_id = "A2", position_in_array = 1:2,
  rvd = c("NTERM", "NI")
))
tales_bind(a, b)

Description

Renders each array as a separated string of its dom_codes in part order, where each distinct domain sequence is one "residue". tales_align() and tales_tale_distances() work on arrays in this form.

Usage

tales_coded_strings(x, sep = " ", repeats_only = FALSE)

Arguments

Details

This is the sibling of tales_rvd_strings() and takes the same two arguments, but both defaults differ, because the two projections feed different consumers:

The separator is free to choose here in a way it is not for RVDs: a dom_code is a bare integer rendered as text, so "1 2 3" and "1-2-3" are equally unambiguous. It defaults to a space because that is what MAFFT's text mode expects.

The termini are kept by default, where tales_rvd_strings() drops them. Target prediction concerns the repeat domain only, so dropping them there is right; alignment is the consumer here, and the two termini are the most reliable anchors an alignment of TALE arrays has. Set repeats_only = TRUE to compare bare repeat arrays.

Value

A Biostrings::BStringSet, named by array_id.

See Also

tales_domain_codes() for the code-to-sequence lookup, tales_rvd_strings() for the sibling projection.

Other tales projections: tales_domain_codes(), tales_get_dna_seq(), tales_get_protein_seq(), tales_rvd_strings(), tales_to_universalmotif()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
xa <- tales_assign_domain_codes(x)
tales_coded_strings(xa)[1]
tales_coded_strings(xa, sep = "-", repeats_only = TRUE)[1]

Description

Quantifies how TALE arrays, and the individual domains they are built from – repeats and the two termini alike – relate to one another by aligning their domain sequences. An R re-implementation of the original DisTAL Perl program, including the array alignment step (the ARLEM model, see tales_tale_distances), with parallel domain alignment, which makes it much faster (the exact speedup depends on aln_method).

Usage

tales_compare_distal(
  x,
  ncores = 1,
  aln_method = "DECIPHER",
  conda_bin = "auto"
)

Arguments

Details

The name says which comparison this is: tales_compare_functal compares TALEs by their predicted DNA-binding specificity instead.

It returns the two expensive products (the pairwise protein alignment between distinct domains, and the alignment of the coded arrays) with the coded input; anything else is cheap to derive from these.

This is where dom_code is minted, over the whole set of parts supplied, and where tales/domain_distances are stamped with a namespace identifying that set — see tales_namespace. Passing a subset later is safe; re-running on a different part set mints different codes, and the differing namespace is what stops the two being joined by mistake. tale_distances carries no such stamp: it is keyed by array_id, a name that keeps its meaning across runs.

Value

A list of three objects, all describing the same run:

• tales: the input, with a dom_code column added.

• domain_distances: a domain_distances between distinct domains, keyed by dom_code.

• tale_distances: a tale_distances between whole arrays, keyed by array_id.

References

Pérez-Quintero A.L. et al. (2015). QueTAL: a suite of tools to classify and compare TAL effectors functionally and phylogenetically. Frontiers in Plant Science 6, 545. doi:10.3389/fpls.2015.00545

Abouelhoda M.I., Giegerich R., Behzadi B., Steyaert J.-M. (2009). Alignment of minisatellite maps based on run-length encoding scheme. Journal of Bioinformatics and Computational Biology 7(2), 287–308. doi:10.1142/S0219720009004060

See Also

tales_group_hclust/tales_group_kmedoids to cluster arrays from the returned tale_distances; tales_compare_functal, comparing TALEs by predicted DNA-binding specificity instead of domain-sequence relatedness.

Other pairwise distances: [.pairwise_distances(), as.matrix.pairwise_distances(), distances_assert_square(), distances_restrict(), is_pairwise_distances(), pairwise_distances(), rvd_dna_specificity, tales_assign_domain_codes(), tales_compare_functal(), tales_domain_distances(), tales_group_hclust(), tales_group_kmedoids(), tales_tale_distances(), validate_pairwise_distances()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
cmp <- tales_compare_distal(x)
names(cmp)
cmp$tale_distances

Description

Quantifies how TALE arrays relate by the DNA sequence their repeats are predicted to bind. (tales_compare_distal compares them by domain sequence instead.) The function turns each array's repeats into a position weight matrix (PWM) of the bases its RVDs prefer, and compares the PWMs pairwise with compare_motifs.

Usage

tales_compare_functal(
  x,
  method = "PCC",
  tryRC = FALSE,
  min.overlap = 1,
  normalise.scores = TRUE,
  score.strat = "a.mean",
  nthreads = 1
)

Arguments

Details

This is a reimplementation of QueTAL's FuncTAL comparison on universalmotif; the original Perl tool depends on BioPerl's Bio::Perl module, which current BioPerl no longer provides. Results differ from the original FuncTAL tool, by design. FuncTAL scored two RVD arrays by flattening their entire padded, overlapping alignment (positions and bases together) into one vector and taking a single Pearson correlation. compare_motifs() instead correlates matched columns individually and combines the column scores (score.strat); the two disagree on real data.

tales_to_universalmotif builds the PWMs (see its page for what drives them and how it treats an RVD missing from rvd_dna_specificity). It is exported so that its output can go to any universalmotif function.

Only a handful of compare_motifs's many options are exposed here, chosen for what actually varies across TALE arrays (their differing repeat counts); see ?compare_motifs for the rest.

Value

A tale_distances object, interchangeable with tales_compare_distal's, so it can be handed directly to tales_group_hclust/tales_group_kmedoids. No tree is built here, matching tales_compare_distal()'s own division of labour: compare here, cluster/tree there.

See Also

tales_compare_distal(), comparing by domain sequence instead; tales_to_universalmotif(), the conversion step this uses; called directly, it lets any other universalmotif function ( motif_tree(), view_motifs(), scan_sequences(), merge_motifs(), ...) can be run on the same PWMs.

Other pairwise distances: [.pairwise_distances(), as.matrix.pairwise_distances(), distances_assert_square(), distances_restrict(), is_pairwise_distances(), pairwise_distances(), rvd_dna_specificity, tales_assign_domain_codes(), tales_compare_distal(), tales_domain_distances(), tales_group_hclust(), tales_group_kmedoids(), tales_tale_distances(), validate_pairwise_distances()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
fn <- tales_compare_functal(x)
fn

Description

Pick the most frequent element in each column of the alignment matrix.

Usage

tales_consensus(align)

Arguments

Details

A column has a consensus only when one element is strictly more common than every other. Where two or more are tied for most frequent – as happens whenever each array carries a different repeat at that position – the result is NA, because there is no agreement to report. NA is likewise returned when the most common thing at a position is a gap.

Value

A vector of consensus elements in each column of align.

See Also

Other TALE alignment: as.matrix.tales_msa(), is_tales_msa(), tales_align(), tales_consensus_match(), tales_msa(), tales_msa_params(), tales_msa_width(), validate_tales_msa()

Examples

# column 1: HD is a clear majority. column 2: a three-way tie, no consensus.
aln <- matrix(c("HD", "HD", "NI",
               "NG", "NI", "HD"),
             nrow = 3, dimnames = list(c("A1", "A2", "A3"), NULL))
aln
tales_consensus(aln)

# From a tales_msa, such as tales_align() returns
msa <- tales_msa(data.frame(
  array_id = c("A1", "A1", "A1", "A2", "A2", "A3", "A3", "A3"),
  position_in_array = c(1L, 2L, 3L, 1L, 2L, 1L, 2L, 3L),
  alignment_position = c(1L, 2L, 3L, 1L, 3L, 1L, 2L, 3L),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "CTERM", "NTERM", "HD", "CTERM")
))
tales_consensus(as.matrix(msa))

Description

Compute a logical matrix corresponding to the input align input with TRUE where an element matches the consensus at that position and FALSE where it does not. Columns with no consensus – see tales_consensus – are NA throughout, since there is nothing there to match.

Usage

tales_consensus_match(align, long = TRUE)

Arguments

Value

A multiple Tal sequences alignment in the form of a matrix filled with logical values if long is FALSE and a long tibble representing the original alignment otherwise (default).

See Also

Other TALE alignment: as.matrix.tales_msa(), is_tales_msa(), tales_align(), tales_consensus(), tales_msa(), tales_msa_params(), tales_msa_width(), validate_tales_msa()

Examples

aln <- matrix(c("HD", "HD", "NI",
               "NG", "NI", "HD"),
             nrow = 3, dimnames = list(c("A1", "A2", "A3"), NULL))
tales_consensus_match(aln, long = FALSE)
tales_consensus_match(aln)

Description

One row per distinct domain sequence: its dom_code, the amino acid sequence it stands for, and the RVD carried by that domain.

Usage

tales_domain_codes(x)

Arguments

Value

A tibble with dom_code and aa_seq columns, plus rvd when x carries one, one row per code.

See Also

tales_coded_strings

Other tales projections: tales_coded_strings(), tales_get_dna_seq(), tales_get_protein_seq(), tales_rvd_strings(), tales_to_universalmotif()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
xa <- tales_assign_domain_codes(x)
head(tales_domain_codes(xa))

Description

Step 2 of tales_compare_distal(). Aligns every distinct domain sequence against every other and returns their pairwise dissimilarity.

Usage

tales_domain_distances(
  x,
  aln_method = "DECIPHER",
  ncores = 1,
  conda_bin = "auto"
)

Arguments

Details

This is the expensive step, and the one worth having on its own: the domain-level distances answer questions about domain diversity without any array-level alignment.

Distances are between distinct domains, keyed by dom_code, so the cost goes with the number of distinct sequences rather than the number of parts. See summary() for that ratio on a given object.

dissim follows DisTAL's definition: the percentage of amino acids that change between two domains, normalised by the longer one, with residues one domain lacks counted as changes. A 20-residue half-repeat that is an exact prefix of a 34-residue repeat is therefore 14/34, about 41 percent, from it. All three backends follow this definition. They still differ slightly pair by pair: "DECIPHER" measures distances inside one multiple alignment of all domains, the other two align each pair separately, and "Biostrings" also charges a cost for opening an internal gap.

Value

A domain_distances object, stamped with x's namespace.

See Also

tales_tale_distances(), which consumes this.

Other pairwise distances: [.pairwise_distances(), as.matrix.pairwise_distances(), distances_assert_square(), distances_restrict(), is_pairwise_distances(), pairwise_distances(), rvd_dna_specificity, tales_assign_domain_codes(), tales_compare_distal(), tales_compare_functal(), tales_group_hclust(), tales_group_kmedoids(), tales_tale_distances(), validate_pairwise_distances()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
xa <- tales_assign_domain_codes(x)
tales_domain_distances(xa)

Description

Reads the output of AnnoTALE's analyze stage, as written by run_annotale_predict, and returns a validated tales object with the same columns as tales_from_telltales.

Usage

tales_from_annotale(
  annotale_dir,
  terminus_max_evalue = 1e-05,
  terminus_min_cover = 0.9,
  sanitize = FALSE,
  hmm_dir = system.file("extdata", "hmmProfile", package = "tantale", mustWork = TRUE)
)

Arguments

Details

AnnoTALE predict finds TALE genes in a genome; analyze splits each one into its N-terminal region, repeats and C-terminal region, and reads the RVD of every repeat. tell_tales runs analyze too, on ORFs it delimits itself from nhmmer hits of the TALE DNA profiles, so the two need not report the same set of TALEs.

As in tell_tales(), each terminal segment is searched with the TALE N- or C-terminal protein profile (hmmsearch, from the tantale environment; see tantale_setup). The rvd column holds NTERM/CTERM for a segment that is a canonical terminus by that search and XXXXX for any other (see tales_anchor_codes).

array_id is AnnoTALE's name for the TALE (MAI1-tempTALE1), without the location AnnoTALE appends to it. seqnames is filled when predict's GFF3 file is found under annotale_dir.

Value

A validated tales object.

See Also

Other TALE discovery: correct_tales(), tale_annotations, tales_from_telltales(), tell_tales()

Examples

# Needs the tantale environment for hmmsearch (see tantale_setup()).
tales_from_annotale(system.file("extdata", "annotaleExampleOutput",
                                package = "tantale"))

Description

Reads the AnnoTALE/telltale part files of a single tell_tales output directory and returns a validated tales object.

Usage

tales_from_telltales(telltale_dir, sanitize = FALSE)

Arguments

Details

One row per part: the N-terminus, each repeat and the C-terminus, as AnnoTALE split the array's longest ORF. The rvd column holds the RVD of a repeat, or a terminus code (see tales_anchor_codes): NTERM/CTERM when the terminus is a canonical TALE terminal domain by the protein profile search of tell_tales, XXXXX when it is not. When AnnoTALE reported no terminus on one side, the array has no part there, with a warning. An array whose protein and DNA parts disagree is left out, with a warning.

A candidate array with a TALE terminus DNA hit that AnnoTALE could not split into parts is absent from the result, with a warning naming it. tales_anomalies cannot report such an array, since it is not in the object. After frameshift correction this usually means the array was corrected against a distant reference; see max_comparisons in tell_tales.

The directory must have been written by the current version of tell_tales(), whose array_report.tsv holds the terminus check; an older one is an error.

The result carries no dom_code: that surrogate key is minted later, by the relatedness computation, over the whole set of parts being analysed.

Value

A validated tales object.

See Also

Other TALE discovery: correct_tales(), tale_annotations, tales_from_annotale(), tell_tales()

Examples

tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                 package = "tantale"))

Description

The DNA sibling of tales_get_protein_seq(): reassembles each array's parts, in order, into one full-length nucleotide sequence, by pasting dna_seq together directly. See tales_get_protein_seq()'s Details for why position_in_array is the ordering key even for a tales_msa.

Usage

tales_get_dna_seq(x)

Arguments

Value

A Biostrings::DNAStringSet, named by array_id.

See Also

tales_get_protein_seq() for the protein sequence sibling.

Other tales projections: tales_coded_strings(), tales_domain_codes(), tales_get_protein_seq(), tales_rvd_strings(), tales_to_universalmotif()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
tales_get_dna_seq(x)[1]

Description

Reassembles each array's parts (N-terminus, repeats and C-terminus, in order) into one full-length amino acid sequence, by pasting aa_seq together with no separator: the result is a real protein sequence, where tales_rvd_strings() joins RVD tokens with hyphens.

Usage

tales_get_protein_seq(x)

Arguments

Details

Parts are ordered by position_in_array. An alignment never reorders an array's parts, only inserts gaps between them, and a tales_msa's gaps are never rows: a gap is a column with no row for that array. So position_in_array gives the same part order alignment_position would, without needing to skip anything, and works unchanged whether x is a bare tales or a tales_msa.

Value

An Biostrings::AAStringSet, named by array_id.

See Also

tales_get_dna_seq() for the DNA sequence sibling.

Other tales projections: tales_coded_strings(), tales_domain_codes(), tales_get_dna_seq(), tales_rvd_strings(), tales_to_universalmotif()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
tales_get_protein_seq(x)[1]

Description

Clusters TALE arrays with hclust on their pairwise distance, cuts the tree into exactly k groups, and returns the tales object the distances were computed from with the result attached as its group column.

Usage

tales_group_hclust(x, tale_distances, k = NULL, plot_tree = FALSE)

Arguments

Details

The function clusters tale_distances but returns the tales object those distances came from, with the groups added. group is a recognised tales column, validated as constant within an array – it is an array-level property, like seqnames.

Taking x rather than returning a bare lookup table is what makes the correspondence checkable: the array names in tale_distances must be the array names in x, and this is the only place that can be verified. A mismatch is an error rather than a silent NA group, because a partly-grouped object is the kind of thing that fails much later and confusingly.

The bare mapping is still one line away if you want it: unique(out[c("array_id", "group")]).

The tree is built directly on the distances (stats::hclust(stats::as.dist(distMat))), matching the original DisTAL clustering this package reimplements. The tree is cut with stats::cutree(tree, k = k), which always succeeds, including when a tie in merge heights would make a height-based cut ambiguous.

Value

x with an added (or replaced) group column.

See Also

tales_group_kmedoids(), the alternative method; tales_compare_distal(), which produces both inputs.

Other pairwise distances: [.pairwise_distances(), as.matrix.pairwise_distances(), distances_assert_square(), distances_restrict(), is_pairwise_distances(), pairwise_distances(), rvd_dna_specificity, tales_assign_domain_codes(), tales_compare_distal(), tales_compare_functal(), tales_domain_distances(), tales_group_kmedoids(), tales_tale_distances(), validate_pairwise_distances()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
cmp <- tales_compare_distal(x)
grouped <- tales_group_hclust(cmp$tales, cmp$tale_distances, k = 2)
unique(grouped[c("array_id", "group")])

Description

Clusters TALE arrays with pam for every candidate k in k_range, then returns the tales object the distances were computed from with the chosen clustering's result attached as its group column.

Usage

tales_group_kmedoids(
  x,
  tale_distances,
  k_range = NULL,
  k = NULL,
  seed = 7,
  plot_silhouette = TRUE
)

Arguments

Details

The function clusters tale_distances but returns the tales object those distances came from, with the groups added. group is a recognised tales column, validated as constant within an array – it is an array-level property, like seqnames.

Taking x rather than returning a bare lookup table is what makes the correspondence checkable: the array names in tale_distances must be the array names in x, and this is the only place that can be verified. A mismatch is an error rather than a silent NA group, because a partly-grouped object is the kind of thing that fails much later and confusingly.

The bare mapping is still one line away if you want it: unique(out[c("array_id", "group")]).

Unlike a hierarchical tree, PAM has no single structure that can be cut at an arbitrary k after the fact: k is a parameter of the clustering itself. So one clustering is computed per candidate in k_range, and k picks which of those to keep:

• k a single number uses that candidate directly.

• k = "auto" picks the elbow of the silhouette-vs-k curve, the point after which adding groups stops improving the fit much. It uses the first step of the Kneedle algorithm only, a practical heuristic; check the silhouette plot when the choice matters.

• k = NULL (the default) shows the silhouette plot and asks for a number at the console, but only when interactive() is TRUE. In a script, a test or a vignette render, k = NULL errors instead of blocking on input that will never arrive.

Value

x with an added (or replaced) group column.

See Also

tales_group_hclust(), the alternative method; tales_compare_distal(), which produces both inputs.

Other pairwise distances: [.pairwise_distances(), as.matrix.pairwise_distances(), distances_assert_square(), distances_restrict(), is_pairwise_distances(), pairwise_distances(), rvd_dna_specificity, tales_assign_domain_codes(), tales_compare_distal(), tales_compare_functal(), tales_domain_distances(), tales_group_hclust(), tales_tale_distances(), validate_pairwise_distances()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
cmp <- tales_compare_distal(x)
grouped <- tales_group_kmedoids(cmp$tales, cmp$tale_distances,
                                k_range = 2:3, k = 2)
unique(grouped[c("array_id", "group")])

Description

A tales object plus an alignment_position column. Gaps are implicit: a gap is simply the absence of a row at that (array_id, alignment_position).

Usage

tales_msa(x, alignment_width = NULL, dom_code_namespace = NULL)

Arguments

Details

Normally produced by tales_align rather than called directly.

Value

A validated tales_msa object.

See Also

Other TALE alignment: as.matrix.tales_msa(), is_tales_msa(), tales_align(), tales_consensus(), tales_consensus_match(), tales_msa_params(), tales_msa_width(), validate_tales_msa()

Examples

# A hand-built alignment: A2 has a gap at position 2 relative to A1.
aligned <- data.frame(
  array_id = c("A1", "A1", "A1", "A2", "A2"),
  position_in_array = c(1L, 2L, 3L, 1L, 2L),
  alignment_position = c(1L, 2L, 3L, 1L, 3L),
  rvd = c("NTERM", "HD", "CTERM", "NTERM", "CTERM")
)
msa <- tales_msa(aligned)
tales_msa_width(msa)
as.matrix(msa)

Description

What tales_align aligned on and how, kept with the alignment so that it can be reproduced or interpreted later, for example to tell whether a tales_msa holding both rvd and dom_code columns was aligned on its RVDs or on its domain codes. Subsetting keeps these settings; returning to a plain tales (as_tales) drops them.

Usage

tales_msa_params(x)

Arguments

Value

A list with residue_col, the column aligned on; domain_distances, the scoring given to tales_align() (NULL, "rvd", or the matrix, table or file supplied); and mafft_opts, the options MAFFT ran with. NULL for a tales_msa built by hand with tales_msa.

See Also

Other TALE alignment: as.matrix.tales_msa(), is_tales_msa(), tales_align(), tales_consensus(), tales_consensus_match(), tales_msa(), tales_msa_width(), validate_tales_msa()

Examples

# Needs MAFFT, resolved from the tantale conda environment on first use.
rvd_fasta <- system.file("extdata", "TalA_RVDSeqs_AnnoTALE.fasta",
                         package = "tantale")
msa <- tales_align(as_tales(rvd_fasta, sep = "-"), residue_col = "rvd")
tales_msa_params(msa)$residue_col

Description

The number of columns in the alignment, including those that are all gaps in the object at hand. It is stored with the object, because subsetting arrays can empty the last column, which would silently shrink max(alignment_position). A plain tales has no width.

Usage

tales_msa_width(x)

Arguments

Value

An integer scalar, or NULL if unset.

See Also

Other TALE alignment: as.matrix.tales_msa(), is_tales_msa(), tales_align(), tales_consensus(), tales_consensus_match(), tales_msa(), tales_msa_params(), validate_tales_msa()

Examples

# A2 has no C-terminus, so the last column holds A1's alone.
aligned <- data.frame(
  array_id = c("A1", "A1", "A1", "A1", "A2", "A2"),
  position_in_array = c(1L, 2L, 3L, 4L, 1L, 2L),
  alignment_position = c(1L, 2L, 3L, 4L, 1L, 2L),
  rvd = c("NTERM", "HD", "NI", "CTERM", "NTERM", "HD")
)
msa <- tales_msa(aligned)
tales_msa_width(msa)
# Keeping A2 alone empties columns 3 and 4; the width is still 4.
a2 <- msa[msa$array_id == "A2", ]
max(a2$alignment_position)
tales_msa_width(a2)

Description

Each array in a tales object is one TALE, identified by its array_id. This returns those identifiers once each, in the order the arrays appear in x. They are also the names of the vector that tales_rvd_strings returns. A tales_msa has the same arrays as the tales object it was aligned from.

Usage

tales_names(x)

Arguments

Details

names() is left to its usual meaning: a tales object is a data frame, so names(x) returns its column names.

Value

A character vector of array identifiers.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_namespace(), tales_requirements(), validate_tales()

Examples

rvd_fasta <- system.file("extdata", "TalA_RVDSeqs_AnnoTALE.fasta",
                         package = "tantale")
x <- as_tales(rvd_fasta, sep = "-")
tales_names(x)
length(tales_names(x)) # the number of TALEs

Description

Identifies the run whose dom_code values this object carries. Objects from different runs must not be joined: dom_code is minted per run, so the codes collide across runs and a join would silently succeed against the wrong domains.

Usage

tales_namespace(x)

Arguments

Value

A scalar string, or NULL if the object is not stamped.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_requirements(), validate_tales()

Examples

rvd_fasta <- system.file("extdata", "TalA_RVDSeqs_AnnoTALE.fasta",
                         package = "tantale")
x <- as_tales(rvd_fasta, sep = "-")
tales_namespace(x) # NULL -- dom_code has not been minted yet

Description

Runs a TALE target (EBE) prediction tool over a set of TALE RVD sequences and a set of DNA sequences, and returns the predictions as a tibble.

Usage

tales_predict_targets(x, subj_file, method = c("talvez", "preditale"), ...)

Arguments

Details

talvez and preditale are independent programs, but the package normalises their outputs to a shared set of column names, so they can serve as interchangeable backends of one operation. This is that operation; talvez and preditale remain available and documented individually, and are where each tool's own options and citation live.

Value

A tibble of EBE predictions with the columns both backends share (see talvez), then method, which tool produced them, then the tool's own column (rank for Talvez, pval for PrediTALE).

See Also

talvez, preditale

Other target prediction: plot_target_preds(), preditale(), talvez()

Examples

# Needs the tantale conda environment (for talvez) and a Java runtime
# (for preditale), both built on first use.
x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
subj <- system.file("extdata", "cladeIII_sweet_promoters.fasta",
                    package = "tantale")
head(tales_predict_targets(x, subj_file = subj))
head(tales_predict_targets(x, subj_file = subj, method = "preditale"))

Description

What each function needs of a tales object. This is distinct from the class's own column contract, which says what makes an object valid: a valid tales may still lack what a given operation needs.

Usage

tales_requirements()

Details

tales_compare_distal()

aa_seq or dna_seq (translated)

tales_align()

whichever of rvd / dom_code residue_col names

tales_rvd_strings()

rvd

tales_coded_strings()

dom_code

tales_domain_codes()

dom_code and aa_seq; rvd included when present

plot() on a tales

rvd, aa_seq, domain_type; seqnames adds a facet, alignment_position enables the aligned layout

Value

A tibble of function, requirement kind, and columns.

See Also

Other tales objects: [.tales(), as_tales(), format.tales(), format.tales_msa(), is_tales(), new_tales(), print.tales(), print.tales_msa(), summary.tales(), summary.tales_msa(), tales(), tales_anchor_codes(), tales_anomalies(), tales_assert_complete(), tales_bind(), tales_names(), tales_namespace(), validate_tales()

Examples

tales_requirements()

Description

Renders each array as a separated string of its RVDs in part order — the form target-prediction tools consume.

Usage

tales_rvd_strings(x, sep = "-", repeats_only = TRUE)

Arguments

Value

A BStringSet, named by array_id.

See Also

tales_coded_strings

Other tales projections: tales_coded_strings(), tales_domain_codes(), tales_get_dna_seq(), tales_get_protein_seq(), tales_to_universalmotif()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
tales_rvd_strings(x)[1]
tales_rvd_strings(x, repeats_only = FALSE)[1] # keeps NTERM/CTERM markers

Description

Step 3 of tales_compare_distal(). Aligns the arrays against each other as strings of domain codes, using the domain distances from step 2 as the cost of substituting one domain for another.

Usage

tales_tale_distances(x, domain_distances)

Arguments

Details

The two arguments are not independent, and that is the point. Each array's sequence of dom_codes is aligned against every other's; what it costs to align one domain against a different one is taken from domain_distances, so the TALE-level comparison is built on the domain-level one.

The alignment is the minisatellite map alignment of ARLEM (Abouelhoda, Giegerich, Behzadi and Steyaert, 2009), which DisTAL used because repeat arrays evolve like minisatellites: besides substitutions, a run of domains that one array has and the other lacks can be explained as tandem duplications of a neighbouring domain, each copy then free to diverge. tantale computes it in R with the costs DisTAL gave ARLEM: a duplication costs 10 plus the substitution cost between the copy and its source, and a domain inserted from elsewhere costs 10. The scores are identical to those of the original ARLEM program. arlem_score is the cost of the best alignment, and dissim divides it by the length of the longer array.

The domain distances are first passed through a Minkowski distance (p = 3.5) between their rows and rescaled to 0-100. That step matters: the alignment needs substitution costs satisfying the triangle inequality, and raw pairwise alignment dissimilarities do not.

Value

A tale_distances object, keyed by array_id.

Both arguments must come from the same call

domain_distances is keyed by dom_code, and those codes mean what they mean only within the call that minted them (tales_assign_domain_codes()). Passing distances from one run with codes from another silently compares the wrong domains, which is why both objects carry a namespace stamp and this function refuses when they disagree.

See Also

tales_compare_distal(), which runs all three steps.

Other pairwise distances: [.pairwise_distances(), as.matrix.pairwise_distances(), distances_assert_square(), distances_restrict(), is_pairwise_distances(), pairwise_distances(), rvd_dna_specificity, tales_assign_domain_codes(), tales_compare_distal(), tales_compare_functal(), tales_domain_distances(), tales_group_hclust(), tales_group_kmedoids(), validate_pairwise_distances()

Examples

x <- tales_from_telltales(system.file("extdata", "tellTaleExampleOutput",
                                      package = "tantale"))
xa <- tales_assign_domain_codes(x)
dd <- tales_domain_distances(xa)
tales_tale_distances(xa, dd)

Description

One universalmotif position weight matrix per array, built by looking up each repeat's RVD in rvd_dna_specificity and stacking the rows in repeat order. The conversion tales_compare_functal is built on, exposed on its own so any universalmotif function (compare_motifs(), motif_tree(), view_motifs(), scan_sequences(), merge_motifs(), ...) can be run directly on these TALE binding models.

Usage

tales_to_universalmotif(x)

Arguments

Details

Only rvd, in repeat order, is used (via tales_rvd_strings, which drops the two termini by default): DNA-binding specificity is a property of the repeat region, and QueTAL's FuncTAL, the tool this table comes from, scored repeats only. An RVD absent from rvd_dna_specificity is given a flat, uninformative row, so an unusual RVD lowers the specificity of the comparison without causing an error.

Value

A named list of universalmotif objects, one per array, named by array_id: a plain list, which is what compare_motifs()/motif_tree() accept.

See Also

tales_compare_functal(), the one comparison built on this; tales_rvd_strings(), the sibling projection at the string layer.