Package 'tTEscanR'

Description

This function calculates the amino acid (AA) demand and/or supply from a codon and/or anticodon usage matrices of a tTEscanR_Object. It aggregates the contribution of their features based on the standard genetic code (mapping codons/anticodons to AA), The resulting values reflect total usage (demand) or availability (supply) of each amino acid, depending on the input type.

Usage

computeAAUsage(
  object,
  level,
  genetic_code = "Standard",
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Details

In order to generalize the analysis to any organism available in Ensembl, tTEscanR can be used with the 33 different genetic codes described by NCBI Taxonomy:

“Standard”, "Vertebrate Mitochondrial”, "Yeast Mitochondrial”, ”Mold Mitochondrial; Protozoan Mitochondrial; Coelenterate Mitochondrial; Mycoplasma; Spiroplasma”, "Invertebrate Mitochondrial”, "Ciliate Nuclear; Dasycladacean Nuclear; Hexamita Nuclear”, "Echinoderm Mitochondrial; Flatworm Mitochondrial”, ”Euplotid Nuclear”, "Bacterial, Archaeal and Plant Plastid”, "Alternative Yeast Nuclear”, "Ascidian Mitochondrial”, "Alternative Flatworm Mitochondrial”, "Blepharisma Macronuclear”, "Chlorophycean Mitochondrial”, "Trematode Mitochondrial”, "Scenedesmus obliquus mitochondrial”, "Thraustochytrium mitochondrial code”, "Rhabdopleuridae Mitochondrial”, "Candidate Division SR1 and Gracilibacteria”, "Pachysolen tannophilus Nuclear”, "Karyorelict Nuclear”, "Condylostoma Nuclear”, "Mesodinium Nuclear”, "Peritrich Nuclear”, "Blastocrithidia Nuclear”, "Balanophoraceae Plastid”, "Cephalodiscidae Mitochondrial"

Value

An updated tTEscanR_Object containing a new layer of information in the assays slot representing the AA demand and/or supply.

Examples

data(default_tTEscanR_tRNA_data)
tTEscanR_obj <-createObject(
    counts = default_tTEscanR_tRNA_data,
    assay = "tRNA"
)
tTEscanR_obj <- computeAnticodonUsage(object = tTEscanR_obj)
tTEscanR_obj <- computeAAUsage(object = tTEscanR_obj, level = "supply")

Description

This function calculates anticodon usage profiles from tRNA gene expression data stored in a tTEscanR_Object. It summarizes the expression of tRNAs by their anticodon identity, which can be used to estimate the tRNA supply landscape. The tRNA gene names need to be properly annotated for proper recognition. Expected format: tRNA-Asn-GTT-5-1.

Usage

computeAnticodonUsage(object, overwrite = FALSE, verbose = TRUE)

Arguments

Value

An updated tTEscanR_Object containing a new layer of information "AnticodonUsage" in the assays slot representing the anticodon usage.

Examples

data(default_tTEscanR_tRNA_data)
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_tRNA_data,
    assay = "tRNA"
)
tTEscanR_obj <- computeAnticodonUsage(object = tTEscanR_obj)

Description

This function estimates codon usage profiles based on gene-level mRNA expression data stored in a tTEscanR_Object. It optionally accepts pre-computed codon frequency tables or uses internally generated default tables when not provided. When enabled, it can evaluate the correlation between background codon composition and observed mean codon usage. If the additional metrics are to be computed the input tTEscanR_Object needs to The default codon_freq were built using the canonical filter to select one transcript if several were available for the same gene.

Usage

computeCodonUsage(
  object,
  codon_freq = NULL,
  species = NULL,
  additional_metrics = TRUE,
  reduce = 100,
  corr_method = "spearman",
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

An updated tTEscanR_Object containing a new layer of information "CodonUsage" in the assays slot representing the codon usage. Additional computations will be stored in the meta.data slot as "CodonUsage_AdditionalMetrics".

Examples

data(default_tTEscanR_mRNA_data, default_tTEscanR_metadata)
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_mRNA_data,
    assay = "mRNA",
    meta.data = list(default_tTEscanR_metadata, "tissue"),
    meta.data.ids = list("ConditionsLabels", "CorrectionFactor")
)
tTEscanR_obj <- computeCodonUsage(
    object = tTEscanR_obj, species = "hg38",
    additional_metrics = FALSE, reduce = 1000
)

Description

This function calculates the correlation between observed mean usage and the exonic background. It provides a metric for evaluating how much usage is driven by underlying sequence composition versus condition-specific expression.

Usage

computeCorrelationBackground(
  mean,
  background,
  corr_method = "spearman",
  verbose = TRUE
)

Arguments

Value

Integer; correlation information between mean and background.

Examples

data(default_tTEscanR_mRNA_data, default_tTEscanR_metadata)
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_mRNA_data,
    assay = "mRNA"
)
tTEscanR_obj <- computeCodonUsage(
    object = tTEscanR_obj, species = "hg38",
    additional_metrics = FALSE, reduce = 1000
)
codon_usage <- getAssay(tTEscanR_obj, "CodonUsage")
exonic_background <- computeExonicBackground(data = codon_usage)
# Input: expression count matrix, need to provide metadata & batch parameters
mean_codon_usage <- computeMeanUsage(
    data = codon_usage,
    mode = "raw",
    metadata = default_tTEscanR_metadata,
    batch = "tissue"
)
corr_back <- computeCorrelationBackground(
    mean = mean_codon_usage,
    background = exonic_background
)

Description

Compute the DESeq2 Analysis

Usage

computeDEResults(
  list_data,
  metadata,
  target = NULL,
  batch = NULL,
  reference = NULL,
  reduce = 100,
  padj_threshold = 0.05,
  verbose = TRUE,
  compute_pairwise = TRUE
)

Arguments

Value

A DESeq2 object with the normalized and vst counts.

Examples

data(default_tTEscanR_tRNA_data, default_tTEscanR_metadata)
DE_analysis <- computeDEResults(
    list_data = list(tRNA = default_tTEscanR_tRNA_data),
    metadata = default_tTEscanR_metadata, batch = "tissue"
)

Description

This function calculates the codon/anticodon usage background based solely on exonic sequence composition, independent of expression levels. It provides a reference distribution of codon/anticodon frequencies across conditions, used to normalize/compare against observed usage patterns derived from expression data.

Usage

computeExonicBackground(data)

Arguments

Value

A matrix with the codon/anticodon background.

Examples

data(default_tTEscanR_mRNA_data)
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_mRNA_data,
    assay = "mRNA"
)
tTEscanR_obj <- computeCodonUsage(
    object = tTEscanR_obj, species = "hg38",
    additional_metrics = FALSE, reduce = 1000
)
exonic_background <- computeExonicBackground(data = getAssay(
    tTEscanR_obj,
    "CodonUsage"
))

Description

This function computes the average usage of codons, anticodons, or amino acids across conditions, useful for summarizing feature usage trends across sample groups. It supports direct input of a count matrix and extraction from a tTEscanR_Object. When the input data is a tTEscanR_Object the parameters metadata and batch will be extracted from the object, and ignored if specified as input parameters. Therefore, variables assay and metadata need to be coherent with the rules described in createObject.

Usage

computeMeanUsage(
  data,
  assay = NULL,
  metadata = NULL,
  id_col = NULL,
  batch = NULL,
  mode = c("raw", "size-corrected", "long_format"),
  verbose = TRUE
)

Arguments

Value

An updated tTEscanR_Object if data is a tTEscanR_Object. A data.frame containing a new layer of information representing the mean codon usage if data is an expression count matrix.

Examples

data(default_tTEscanR_tRNA_data, default_tTEscanR_metadata)
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_tRNA_data,
    assay = "tRNA",
    meta.data = list(default_tTEscanR_metadata, "tissue"),
    meta.data.ids = list(
        "ConditionsLabels",
        "CorrectionFactor"
    )
)
# Input: tTEscanR object containing metadata and batch parameters
tTEscanR_obj <- computeAnticodonUsage(object = tTEscanR_obj)
anticodon_mean_usage <- computeMeanUsage(
    data = tTEscanR_obj,
    assay = "AnticodonUsage"
)

Description

This function calculates the theoretical translation efficiency (tTE) score by integrating codon-anticodon usage and/or amino acid demand-supply across conditions.

Usage

computeTheoreticalTE(
  object,
  level = c("codon", "aa", "both"),
  genetic_code = "Standard",
  corr_method = c("spearman", "pearson", "kendall"),
  compute_significance = TRUE,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

An updated tTEscanR_Object containing a new layer of information representing the translation efficiency table for the matching conditions in the mRNA and tRNA data.

Examples

data(
    default_tTEscanR_mRNA_data, default_tTEscanR_tRNA_data,
    default_tTEscanR_metadata
)
tTEscanR_obj <- createObject(
    counts = list(
        mRNA = default_tTEscanR_mRNA_data, tRNA = default_tTEscanR_tRNA_data
    ),
    meta.data = list(default_tTEscanR_metadata, "tissue"),
    meta.data.ids = list("ConditionsLabels", "CorrectionFactor")
)
tTEscanR_obj <- computeCodonUsage(
    object = tTEscanR_obj, species = "hg38",
    additional_metrics = FALSE, reduce = 10000
)
tTEscanR_obj <- computeAnticodonUsage(object = tTEscanR_obj)
tTEscanR_obj <- computeTheoreticalTE(
    object = tTEscanR_obj, level = "codon", compute_significance = FALSE
)

Description

This function initializes a tTEscanR_Object, a structured container designed to hold translational efficiency-related data. The object consists of two main components; assays, which stores data matrices (e.g. expression, codon usage), and meta.data, which stores associated information and additional intermediate calculations. A tTEscanR_Object can be created using a single dataset, or initialized with a list of datasets provided at once. Additional assays and metadata layers can be appended later using the updateObject function.

Usage

createObject(
  counts,
  assay = NULL,
  meta.data = NULL,
  meta.data.ids = NULL,
  verbose = TRUE
)

Arguments

Details

In order to ensure robustness throughout the pipeline specific ids have been assigned and should be respected by the user. assays slot:

• mRNA and tRNA count matrices as "mRNA" and "tRNA"

• Codon and anticodon usage count matrices as "CodonUsage" and "AnticodonUsage"

• Amino acid demand and supply count matrices as "AADemand" and "AASupply"

• Size corrected count matrices contain the prefix "SizeCorrected" added to the raw count matrices names (e.g. "SizeCorrected_mRNA} or \code{"SizeCorrectedCodonUsage) meta.data slot:

• Table with the conditions of the mRNA and tRNA data as "ConditionsLabels"

• Active correction factor to use when running differential expression analyses as "CorrectionFactor"

• Optional; Identifier DataMetadataIndex to indicate the column in "ConditionsLabels" that contains the labels of the conditions of the assay.

Value

A tTEscanR_Object.

Examples

data(
    default_tTEscanR_mRNA_data, default_tTEscanR_tRNA_data,
    default_tTEscanR_metadata
)
tTEscanR_obj <- createObject(
    counts = list(
        mRNA = default_tTEscanR_mRNA_data,
        tRNA = default_tTEscanR_tRNA_data
    ),
    meta.data = default_tTEscanR_metadata,
    meta.data.ids = "ConditionsLabels"
)

Description

This dataset contains the extra information to indicate the conditions of the data

Usage

data(default_tTEscanR_metadata)

Format

A data frame with samples as rows and annotation columns such as:

tissue

The sequencing batch or sample origin

cell.type

The experimental group or cell type

conditions

The combination of the previous items as will be referred in the columns of the count matrices

Description

This dataset contains an example of mRNA gene expression data with protein-coding genes as rows and cell types as columns.

Usage

data(default_tTEscanR_mRNA_data)

Format

A matrix where rows represent genes and columns represent individual samples or cell types.

Description

This dataset contains an example of tRNA gene expression data with tRNA genes as rows and cell types as columns.

Usage

data(default_tTEscanR_tRNA_data)

Format

A matrix or data frame where rows represent tRNA gene names and columns represent individual samples or cell types.

Description

This function analyzes a given set of nucleotide sequences and computes the count of each codon present.

Usage

extractCodons(sequences, verbose = TRUE)

Arguments

Value

Codon frequency per gene table of the sequences.

Examples

codon_composition <- extractCodons(sequences = list(
    "ATGCGTACG",
    "TTAAGGCCG"
))

Description

This function converts: codons and anticodons into anticodons, codons or amino acids based on the genetic code.

Usage

featuresToAA(
  data,
  position = NULL,
  genetic_code = "Standard",
  verbose = TRUE,
  notation_from = c("codon", "anticodon"),
  notation_to = c("aa", "anticodon", "codon")
)

Arguments

Value

Translated features (codons, anticodons or amino acids) from data_to_translate.

Examples

data(default_tTEscanR_mRNA_data, default_tTEscanR_metadata)
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_mRNA_data,
    assay = "mRNA",
    meta.data = list(default_tTEscanR_metadata, "tissue"),
    meta.data.ids = list("ConditionsLabels", "CorrectionFactor")
)
tTEscanR_obj <- computeCodonUsage(
    object = tTEscanR_obj, codon_freq = NULL,
    species = "hg38", additional_metrics = FALSE
)
codons <- rownames(getAssay(tTEscanR_obj, "CodonUsage"))
codons_to_AA <- featuresToAA(
    data = codons, notation_from = "codon", notation_to = "aa"
)
codons_to_anticodons <- featuresToAA(
    data = codons,
    notation_from = "codon", notation_to = "anticodon"
)

Description

This function safely retrieves the specified data from a tTEscanR_Object.

Usage

getAssay(object, name)

## S4 method for signature 'tTEscanR_Object'
getAssay(object, name)

Arguments

Value

The requested assay data (typically a matrix or data.frame).

Examples

data(default_tTEscanR_mRNA_data)
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_mRNA_data,
    assay = "mRNA"
)
mRNA_data <- getAssay(tTEscanR_obj, "mRNA")

Description

This function computes codon usage frequencies for each gene based on a provided set of gene sequences. It can optionally subset the analysis to specific transcripts and apply filtering criteria when multiple transcripts are available for the same gene. Consequently, no filter parameter will be considered if parameters transcripts and genes_file are given.

Usage

getCodonFreq(
  dataset_name = NULL,
  genes_file = NULL,
  verbose = TRUE,
  transcripts = NULL,
  retain_mitochondrial = FALSE,
  filter = c("canonical", "length"),
  retain_unannotated = FALSE,
  retain_geneversion = TRUE,
  out_format = c("external_gene_name", "ensembl_transcript_id", "ensembl_gene_id")
)

Arguments

Value

Codon frequency-per-gene table and a translator gene annotation table (if available).

Description

This function safely retrieves the specified metadata from a tTEscanR_Object.

Usage

getMetadata(object, name)

## S4 method for signature 'tTEscanR_Object'
getMetadata(object, name)

Arguments

Value

A data.frame or a vector depending of the name parameter.

Examples

data(default_tTEscanR_mRNA_data, default_tTEscanR_metadata)
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_mRNA_data,
    assay = "mRNA",
    meta.data = default_tTEscanR_metadata,
    meta.data.ids = "ConditionsLabels"
)
conditions <- getMetadata(tTEscanR_obj, "ConditionsLabels")

Description

This function performs a permutation test to compare a mRNA dataset to the reference codon frequency-per-gene matrix.

Usage

getPermutationDist(
  n_permut = 1000,
  n_features = 100,
  target_data = NULL,
  codon_freq = NULL,
  species = NULL,
  verbose = TRUE
)

Arguments

Value

A table with the codons and their frequencies after computing all the permutations.

Examples

data(default_tTEscanR_mRNA_data)
genes <- default_tTEscanR_mRNA_data[1:20, ]
permut <- getPermutationDist(
    n_permut = 100, target_data = genes,
    species = "hg38"
)

Description

This function calculates the row sums of a given matrix to combine columns that share the same group.

Usage

groupConditions(data, group_labels)

Arguments

Value

A matrix with the conditions merged based on the metadata.

Examples

data <- data.frame(
    sample_1 = c(10, 5, 20), sample_2 = c(15, 8, 25),
    sample_3 = c(12, 6, 22), sample_4 = c(1, 2, 3),
    sample_5 = c(4, 5, 6), sample_6 = c(7, 8, 9)
)
rownames(data) <- c("gene_1", "gene_2", "gene_3")
groups <- c("cond_A", "cond_A", "cond_A", "cond_B", "cond_B", "cond_B")
data_combined <- groupConditions(data = data, group_labels = groups)

Description

This function efficiently combines individual matrices.

Usage

mergeMatrices(...)

Arguments

Value

A single sparse matrix with as a combination of all the input matrices.

Examples

df1 <- matrix(c(1, 0, 0, 2), nrow = 2, dimnames = list(
    c("geneA", "geneB"),
    c("s1", "s2")
))
df2 <- matrix(c(3, 0, 0, 4), nrow = 2, dimnames = list(
    c("geneB", "geneC"),
    c("s2", "s3")
))
merged_matrix <- mergeMatrices(df1, df2)

Description

Assess Significance (P-value) & Corrects for Multiple Hypothesis Testing

Usage

obtainSignificance(dist, value, padj_threshold = 0.05, verbose = TRUE)

Arguments

Value

A table with the codon exonic background and their significance level before (p-value) and after the correction (p-adjusted value).

Examples

data(default_tTEscanR_mRNA_data, default_tTEscanR_metadata)
selected_genes <- default_tTEscanR_mRNA_data[1:20, ]
permutation_test <- getPermutationDist(
    n_permut = 100, target_data = selected_genes, species = "hg38"
)
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_mRNA_data,
    assay = "mRNA",
    meta.data = list(default_tTEscanR_metadata, "tissue"),
    meta.data.ids = list("ConditionsLabels", "CorrectionFactor")
)
tTEscanR_obj <- computeCodonUsage(
    object = tTEscanR_obj, species = "hg38",
    additional_metrics = FALSE, reduce = 1000
)

codon_usage <- getAssay(tTEscanR_obj, "CodonUsage")
codon_background <- rowSums(codon_usage) / sum(rowSums(codon_usage))
codons_to_AA <- featuresToAA(
    data = names(codon_background),
    notation_from = "codon", notation_to = "aa"
)
codon_background <- data.frame(
    group = codons_to_AA, codon = names(codon_background),
    freq = as.numeric(codon_background), row.names = NULL
)
significance <- obtainSignificance(
    dist = permutation_test, value = codon_background
)

Description

This function generates a visualization to correlate different parameters of the data. The input data (data) is expected to be in long format and contain a minimum information regarding the features, the conditions they belong to and their usage counts. A common usage of this kind of plot is to represent the codon frequencies correlations of the exonic background and the mean codon usage across conditions. Based on the selected plot parameter the user can select the most convenient layout to display the data. It is crucial to ensure consistency between the name of the columns in data and the parameters x_axis_col, y_axis_col and condition_col.

Usage

plotCorrelation(
  data,
  plot = "MeanCodonUsage",
  x_axis_col,
  y_axis_col,
  condition_col,
  extra_val = NULL,
  label_col = NULL,
  color_palette = NULL,
  out_name = NULL,
  show_legend = "none",
  targeted_arg = NULL,
  save_format = NULL,
  out_directory = NULL,
  add_titles = TRUE,
  verbose = TRUE
)

Arguments

Value

A ggplot object representing the correlation. If save_format is provided, the plot will also be saved to the specified location.

Examples

data(default_tTEscanR_mRNA_data, default_tTEscanR_metadata)

# Define the object and compute the codon usage
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_mRNA_data, assay = "mRNA",
    meta.data = list(default_tTEscanR_metadata, "tissue"),
    meta.data.ids = list("ConditionsLabels", "CorrectionFactor")
)
tTEscanR_obj <- computeCodonUsage(
    object = tTEscanR_obj, species = "hg38",
    additional_metrics = TRUE, reduce = 1000
)

# Compute and extract the mean codon usage
additional_metrics <- getMetadata(
    tTEscanR_obj,
    "CodonUsage_AdditionalMetrics"
)
mean_codon_usage <- additional_metrics$MeanCodonUsage
exonic_background <- additional_metrics$CodonExonicBackground
exonic_background <- as.data.frame(exonic_background)
correlation_mean_background <- cbind(mean_codon_usage, exonic_background)

plotCorrelation(
    data = correlation_mean_background, plot = "MeanCodonUsage",
    x_axis_col = "mean_usage_across_conditions",
    y_axis_col = "exonic_background", condition_col = "feature",
    extra_val = additional_metrics$MeanCodonCorr, add_titles = TRUE,
    show_legend = "none"
)

Description

Generates Visualizations from the DEA data

Usage

plotDEResults(
  DE_results_list,
  dataset_name = NULL,
  heatmap = TRUE,
  dim_reduct = NULL,
  numPC = 2,
  target = NULL,
  verbose = TRUE,
  color_factor = NULL,
  shape_factor = NULL,
  label_factor = NULL,
  highlight_median = FALSE,
  scale_pca = TRUE,
  color_palette = NULL,
  fc_threshold = 1,
  padj_threshold = 0.05,
  label_significant = TRUE,
  show_legend = "none"
)

Arguments

Value

Visualization of the DEA results.

Examples

data(default_tTEscanR_tRNA_data, default_tTEscanR_metadata)
DE_analysis <- computeDEResults(
    list_data = list(tRNA = default_tTEscanR_tRNA_data),
    metadata = default_tTEscanR_metadata, batch = "tissue"
)
DE_plots <- plotDEResults(
    DE_results_list = DE_analysis, dataset_name = "tRNA",
    dim_reduct = "PCA", color_factor = "tissue", heatmap = FALSE
)

Description

This function generates a visualization of codon-anticodon usage or amino acid demand-supply distributions across conditions. The input data (data) is expected to be in long format and contain a minimum information regarding the features, the conditions they belong to and their usage counts. Based on the selected plot parameter the user can select the most convenient layout to display the data. It is crucial to ensure consistency between the name of the columns in data and the parameters x_axis_col, y_axis_col and condition_col.

Usage

plotDistribution(
  data,
  plot = "jitter",
  bar_position = "dodge",
  x_axis_col,
  y_axis_col,
  condition_col,
  color_palette = NULL,
  ncols = 1,
  facet_col = NULL,
  add_stats = FALSE,
  targeted_arg = NULL,
  save_format = NULL,
  out_name = NULL,
  out_directory = NULL,
  show_legend = "none",
  add_titles = TRUE,
  verbose = TRUE
)

Arguments

Value

A ggplot object representing the requested distribution plot. If save_format is provided, the plot will also be saved to the specified location.

Examples

data(default_tTEscanR_mRNA_data, default_tTEscanR_metadata)

# Define the object and compute the codon usage
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_mRNA_data,
    assay = "mRNA",
    meta.data = list(default_tTEscanR_metadata, "tissue"),
    meta.data.ids = list("ConditionsLabels", "CorrectionFactor")
)
tTEscanR_obj <- computeCodonUsage(
    object = tTEscanR_obj, species = "hg38",
    additional_metrics = FALSE, reduce = 1000
)

# Transform the data
long_cu <- transformFormat(
    data = getAssay(tTEscanR_obj, "CodonUsage"), normalize = TRUE,
    rownames_to_column = "codon", names_to = "condition", values_to = "usage"
)
long_cu <- long_cu |>
    tidyr::separate(condition, into = c("tissue", "cell_type"), sep = "-")

# Generate the plot
codon_usage_plot <- plotDistribution(
    data = long_cu, plot = "jitter", x_axis_col = "codon",
    y_axis_col = "usage", condition_col = "tissue", show_legend = "right",
    add_titles = FALSE
)

Description

This function generates a plot to compare the baseline codon exonic background against the current codon usage. For a better interpretation, the codons are colored by amino acid.

Usage

plotPermutation(
  permut_data,
  sig_data,
  color_palette = NULL,
  save_format = NULL,
  out_name = NULL,
  out_directory = NULL,
  show_legend = "none",
  add_titles = TRUE,
  verbose = TRUE
)

Arguments

Value

Permutation plot.

Examples

data(default_tTEscanR_mRNA_data, default_tTEscanR_metadata)
selected_genes <- default_tTEscanR_mRNA_data[1:20, ]
permutation_test <- getPermutationDist(
    n_permut = 100, target_data = selected_genes, species = "hg38"
) # Generate table with codon and freq
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_mRNA_data, assay = "mRNA",
    meta.data = list(default_tTEscanR_metadata, "tissue"),
    meta.data.ids = list("ConditionsLabels", "CorrectionFactor")
)
tTEscanR_obj <- computeCodonUsage(
    object = tTEscanR_obj, species = "hg38",
    additional_metrics = FALSE, reduce = 1000
)

codon_usage <- getAssay(tTEscanR_obj, "CodonUsage")
codon_background <- rowSums(codon_usage) / sum(rowSums(codon_usage))
codons_to_AA <- featuresToAA(
    data = names(codon_background),
    notation_from = "codon", notation_to = "aa"
)
codon_background <- data.frame(
    group = codons_to_AA, codon = names(codon_background),
    freq = as.numeric(codon_background), row.names = NULL
)
significance <- obtainSignificance(
    dist = permutation_test, value = codon_background
)

plotPermutation(permut_data = permutation_test, sig_data = significance)

Description

This function generates a proportion plot to compare codon-anticodon usage or amino acid demand-supply frequencies across conditions. The input data (data) is expected to be in long format and contain a minimum information regarding the features, the conditions they belong to and their usage counts. Based on the selected plot parameter the user can select the most convenient layout to display the data. It is crucial to ensure consistency between the name of the columns in data and the parameters var_numerical, var_categorical and var_color.

Usage

plotProportion(
  data,
  plot = "bar",
  var_numerical,
  var_categorical,
  var_color = NULL,
  facet_col = NULL,
  color_palette = NULL,
  num_limits = NULL,
  num_rings = 5,
  save_format = NULL,
  out_name = NULL,
  out_directory = NULL,
  zoom = FALSE,
  show_legend = "none",
  add_titles = TRUE,
  order = NULL,
  normalize = TRUE,
  verbose = TRUE
)

Arguments

Value

A ggplot object representing the requested proportion plot. If save_format is provided, the plot will also be saved to the specified location.

Examples

data(default_tTEscanR_mRNA_data, default_tTEscanR_metadata)

# Define the object and compute the codon usage
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_mRNA_data, assay = "mRNA",
    meta.data = list(default_tTEscanR_metadata, "tissue"),
    meta.data.ids = list("ConditionsLabels", "CorrectionFactor")
)
tTEscanR_obj <- computeCodonUsage(
    object = tTEscanR_obj, species = "hg38",
    additional_metrics = TRUE, reduce = 1000
)

# Compute and extract the mean codon usage
additional_metrics <- getMetadata(
    tTEscanR_obj, "CodonUsage_AdditionalMetrics"
)
mean_codon_usage <- additional_metrics$MeanCodonUsage
mean_codon_usage$codon <- mean_codon_usage$feature

# Translate the codons to amino acids
mean_codon_usage <- featuresToAA(
    data = mean_codon_usage, position = "feature",
    notation_from = "codon", notation_to = "aa", verbose = FALSE
)

# Generate the plot
plotProportion(
    data = mean_codon_usage, plot = "bar",
    var_numerical = "mean_usage_across_conditions",
    var_categorical = "codon", var_color = "feature", show_legend = "none"
)

Description

This function generates a distribution plot to compare distribution usages between a targeted set of conditions against the rest. A common application of this plot is to compare mean usages across conditions. Both input data sources (target_data and overall_data) are expected to be in long format and contain a minimum information regarding the features, the conditions they belong to and their usage counts. It is crucial to ensure consistency between the name of the columns in target_data and overall_data, together with the parameters x_axis_col and y_axis_col.

Usage

plotTargetComparison(
  target_data,
  overall_data,
  x_axis_col,
  y_axis_col,
  color_palette = NULL,
  show_difference = TRUE,
  save_format = NULL,
  out_name = NULL,
  add_titles = TRUE,
  out_directory = NULL,
  show_legend = "none",
  verbose = TRUE
)

Arguments

Value

A ggplot object representing the requested distribution plot. If save_format is provided, the plot will also be saved to the specified location.

Description

This function generates a violin plot to visualize the distribution of tTE scores across different condition. The tTE scores should be obtained using computeTheoreticalTE. The plot allows the user to easily compare the tTE distribution between different conditions, with the option to highlight specific feature clusters based on the provided targets.

Usage

plotTEscore(
  data,
  metadata,
  class_col,
  index_col,
  target_col = NULL,
  score_col = "tTE",
  cond_col = "condition",
  pval_col = "p_value",
  facet_col = NULL,
  color_palette = NULL,
  save_format = NULL,
  out_name = NULL,
  add_stats = TRUE,
  out_directory = NULL,
  verbose = TRUE,
  show_legend = "none",
  add_titles = TRUE,
  show_outliers = FALSE
)

Arguments

Value

A ggplot object representing the tTE scores. If save_format is provided, the plot will also be saved to the specified location. If add_stats reports a table with the statitical measures summarized.

Examples

data(
    default_tTEscanR_mRNA_data, default_tTEscanR_tRNA_data,
    default_tTEscanR_metadata
)

# Define the tTEscanR object
tTEscanR_obj <- createObject(
    counts = list(
        mRNA = default_tTEscanR_mRNA_data, tRNA = default_tTEscanR_tRNA_data
    ),
    meta.data = list(default_tTEscanR_metadata, "tissue"),
    meta.data.ids = list("ConditionsLabels", "CorrectionFactor")
)

# Compute the codon and anticodon usage
tTEscanR_obj <- computeCodonUsage(
    object = tTEscanR_obj, species = "hg38",
    additional_metrics = FALSE, reduce = 10000
)
tTEscanR_obj <- computeAnticodonUsage(object = tTEscanR_obj)

# Compute the theoretical translation efficiency (tTE scores)
tTEscanR_obj <- computeTheoreticalTE(
    object = tTEscanR_obj, level = "codon", compute_significance = TRUE
)
tTEresults_codon <- getMetadata(tTEscanR_obj, "tTEresults_codon")
conditions_metadata <- getMetadata(tTEscanR_obj, "ConditionsLabels")

# Visualize the tTE scores
plotTEscore(
    data = tTEresults_codon, metadata = conditions_metadata,
    index_col = "conditions", class_col = "tissue", add_stats = TRUE
)

Description

This function applies differential expression analysis using the DESeq2 framework on a matrix of expression values. It supports both exploratory visualizations (heatmap and PCA) and targeted comparisons using a custom contrast table.

Usage

runDEAnalysis(
  list_data,
  metadata,
  batch = NULL,
  reference = NULL,
  reduce = 100,
  dim_reduct = NULL,
  color_factor = batch,
  heatmap = TRUE,
  shape_factor = NULL,
  label_factor = NULL,
  target = NULL,
  highlight_median = FALSE,
  numPC = 2,
  color_palette = NULL,
  fc_threshold = 1,
  show_legend = "none",
  padj_threshold = 0.05,
  label_significant = TRUE,
  compute_pairwise = TRUE,
  verbose = TRUE
)

Arguments

Value

A list of outputs per each matrix in list_data, based on the enabled parameters: (i) exploratory plots (heatmap and/or PCA), (ii) targeted plot (volcano), and (iii) size-corrected data.

Examples

data(default_tTEscanR_tRNA_data, default_tTEscanR_metadata)
DE_analysis <- runDEAnalysis(
    list_data = list(tRNA = default_tTEscanR_tRNA_data),
    metadata = default_tTEscanR_metadata, batch = "tissue",
    color_factor = "tissue"
)

Description

This function wraps up all the independent functions of theoretical translation efficiency pipeline. Requires an mRNA and tRNA count matrices to compute the codon and anticodon usage and further derive the amino acid demand and supply. With matching condition in the former matrices the theoretical translation efficiency would be computed.

Usage

runPipeline(
  mRNA_data,
  tRNA_data,
  metadata,
  batch,
  corr_method = "spearman",
  additional_metrics = TRUE,
  runDESeq = TRUE,
  compute_significance = TRUE,
  codon_freq = NULL,
  species = NULL,
  genetic_code = "Standard",
  dim_reduct = NULL,
  reduce = 100,
  color_factor = NULL,
  verbose = TRUE
)

Arguments

Value

A tTEscanR_Object with the assays and metadata computed through the tTE pipeline.

Examples

data(
    default_tTEscanR_mRNA_data, default_tTEscanR_tRNA_data,
    default_tTEscanR_metadata
)
tTEscanR_obj <- runPipeline(
    mRNA_data = default_tTEscanR_mRNA_data,
    tRNA_data = default_tTEscanR_tRNA_data,
    metadata = default_tTEscanR_metadata,
    species = "hg38", batch = "tissue", additional_metrics = FALSE,
    compute_significance = FALSE, runDESeq = FALSE
)

Description

This function analyzes the contribution of the most highly expressed genes to the overall codon pool across conditions. It is particularly useful for evaluating codon bias in highly expressed genes and how it varies across conditions. If needed, gene annotations can be translated for consistency, and internal species-specific for human ("hg38") and mouse ("mm39") are supported.

Usage

showPoolContribution(
  object,
  codon_freq = NULL,
  species = NULL,
  N = 10,
  corr_method = "spearman",
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

An updated tTEscanR_Object containing new layers of information in the meta.data slot, representing the codon pool contribution.

Examples

data(default_tTEscanR_mRNA_data, default_tTEscanR_metadata)
tTEscanR_obj <- createObject(
    counts = list(mRNA = default_tTEscanR_mRNA_data),
    meta.data = list(default_tTEscanR_metadata, "tissue"),
    meta.data.ids = list("ConditionsLabels", "CorrectionFactor")
)
tTEscanR_obj <- computeCodonUsage(
    object = tTEscanR_obj, species = "hg38", additional_metrics = FALSE
)
tTEscanR_obj <- showPoolContribution(
    object = tTEscanR_obj, species = "hg38"
)

Description

This function converts a matrix or data.frame into a tidy, long-format tibble. Optionally normalizes the values.

Usage

transformFormat(data, normalize, rownames_to_column, names_to, values_to)

Arguments

Value

A tibble of the input data

Examples

data(default_tTEscanR_tRNA_data)
tRNA_long_format <- transformFormat(
    data = default_tTEscanR_tRNA_data,
    normalize = FALSE,
    rownames_to_column = "tRNA_genes",
    names_to = "condition",
    values_to = "abundance"
)
tTEobj <- createObject(
    counts = default_tTEscanR_tRNA_data,
    assay = "tRNA"
)
tTEobj <- computeAnticodonUsage(object = tTEobj)
anticodon_long_format <- transformFormat(
    data = getAssay(tTEobj, "AnticodonUsage"),
    normalize = TRUE,
    rownames_to_column = "anticodons",
    names_to = "condition", values_to = "usage"
)

Description

This function filters a tRNA expression matrix by removing conditions (columns) that fall below a specific total read count (cutoff). It is useful for eliminating low-quality or poorly sequenced conditions that may bias downstream analyses.

Usage

tRNAFilterCuts(data, cutoff = 5000, verbose = TRUE)

Arguments

Value

A filtered matrix or data.frame with tRNAs below the cutoff removed.

Examples

data(default_tTEscanR_tRNA_data)
tRNA_data_filtered <- tRNAFilterCuts(
    data = default_tTEscanR_tRNA_data,
    cutoff = 5000
)

Description

Generate a tRNA expression matrix

Usage

tRNAGetMatrix(
  data,
  assay = "peaks",
  confidence_set = NULL,
  tRNA_name_map = NULL,
  species = NULL,
  flanking_region = 100,
  name_sep = c("-", "-"),
  save = TRUE,
  out_name = NULL,
  out_directory = NULL,
  verbose = TRUE
)

Arguments

Value

Sparse matrix of tRNA counts (tRNAs x cells)

Description

Selection of the Optimal tRNA Cut Cutoff

Usage

tRNASetCutoff(
  data,
  num_iter = 1000,
  cutoffs_limits = c(50, 10000),
  generate_plot = TRUE,
  slope_threshold = 0.001,
  rho_threshold = 0.95,
  compute_aa = FALSE,
  verbose = TRUE
)

Arguments

Value

Table with the optimal cutoff at the anticodon isoacceptor and amino acid isotype.

Examples

data(default_tTEscanR_tRNA_data)
optimal_tRNA_cutoffs <- tRNASetCutoff(
    data = default_tTEscanR_tRNA_data,
    generate_plot = FALSE, num_iter = 50,
    cutoffs_limits = c(3500, 4000)
)

Description

Annotate the tRNA genes from tRNA tags

Usage

tRNASetGenes(data, tRNA_bed, flanking_region = 100, name_sep = c("-", "-"))

Arguments

Value

A data with the translated tRNA gene names.

Description

The tTEscanR object is dynamically updated to store assays and meta.data at each analysis step. Ensures efficient tracking and organization of inputs and outputs throughout the pipeline. In order to ensure robustness throughout the pipeline, specific ids have been assigned and should be respected by the user.

Slots

assays

A list of assays.

meta.data

A list of meta-information associated with the assays.

Description

Updates an existing tTEscanR_object using createObject. For more details, refer to createObject.

Usage

updateObject(
  object,
  counts = NULL,
  assay = NULL,
  main_name = NULL,
  meta.data = NULL,
  meta.data.ids = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

An updated tTEscanR_Object.

Examples

data(default_tTEscanR_mRNA_data, default_tTEscanR_tRNA_data)
tTEscanR_obj <- createObject(
    counts = default_tTEscanR_mRNA_data,
    assay = "mRNA"
)
tTEscanR_obj <- updateObject(
    object = tTEscanR_obj,
    counts = default_tTEscanR_tRNA_data,
    assay = "tRNA"
)