An R6 class representing an RNA-Seq expression dataset.

This class represents a RNA sequencing dataset containing the following information:

expression values (raw count) of expressed tags (genes or transcripts) for all samples.
effective lengths of expressed tags (genes or transcripts) for all samples.
normalization factors for expressed tags (genes or transcripts) for all samples.
design and annotation information; see PairwiseDesignWith for details.

By convention, the dataset is represented as a matrix:

A column represents the expression values for one sample.
A row represents the expression values for one expression tag. Column names are the sample names, and row names are the expression tag names.

Methods

Method `show_etags_summary()`

This function computes a summary per tax_id, tax_name and rna type for selected expressed tags, and returns a list of tables per feature.

Usage

ExprData$show_etags_summary(
  in_batch = NULL,
  tr_fn = NULL,
  sum_fn = sum,
  intra_norm = FALSE,
  inter_norm = FALSE
)

Arguments

in_batch: (optional) A character vector specifying the batch(es) to include.
tr_fn: A function to transform the expression values before summarizing. Default is identity function (no transformation).
sum_fn: A function to aggregate the transformed values. Default is "sum", but can be "sum_fn = function(x) sum(as.integer(x > 0))" to count non zero genes for example.
intra_norm: A boolean indicating whether to apply intra-sample normalization. Only used when type="norm".
inter_norm: A boolean indicating whether to apply inter-sample normalization. Only used when type="norm".

Returns

A list of tables per feature Plot results from show_etags_summary.

Method `plot_etags_summary()`

Usage

ExprData$plot_etags_summary(
  in_batch = NULL,
  tr_fn = NULL,
  sum_fn = sum,
  intra_norm = FALSE,
  inter_norm = FALSE
)

Arguments

in_batch: (optional) A character vector specifying the batch(es) to include.
tr_fn: A function to transform the expression values before summarizing. Default is identity function (no transformation).
sum_fn: A function to aggregate the transformed values. Default is "sum", but can be "sum_fn = function(x) sum(as.integer(x > 0))" to count non zero genes for example.
intra_norm: A boolean indicating whether to apply intra-sample normalization. Only used when type="norm".
inter_norm: A boolean indicating whether to apply inter-sample normalization. Only used when type="norm".

Returns

A list of tables per feature

Method `filter_and_set_selected_ids()`

Select expressed tags based on filtering on taxon or rna type. The results will be an intersect with the previous selection. You can reset the object if it's not desired.

Usage

ExprData$filter_and_set_selected_ids(
  values,
  filtered_var = "type",
  filter_type = "keep"
)

Arguments

values

A list of values used for filtering. e.g c("mRNA", "transcript")

filtered_var

The variable being filtered. Possible values are

"tax_id" for filtering based on taxon id
"tax_name" for filtering based on taxon name
"type" for filtering based on rna type (default)

filter_type

The filtering method. Possible values are:

"keep" to keep only an expression tag if its value for the variable designated with filtered_var is in values
"excl" to keep only an expression tag if its value for the variable designated with filtered_var is not in values. Compute and set inter normalization factors

Method `compute_and_set_inter_norm_fact()`

Compute and set inter normalization factors

This function computes scaling factors using a ratio-based method to correct for systematic technical biases between samples, such as differences in sequencing depth or library composition. By default, it performs Median Ratio Normalization (MRN), as norm_mean is "median" and M-value trimming is disabled (m_trim_prop = 0). It can be configured to perform TMM-style normalization by setting m_trim_prop and norm_mean="geometric"ornorm_mean="mod.geometric"`. Note that the weigthed mean for TMM is not available yet.

The normalization process is as follows:

Reference Selection: A reference expression profile is created from samples chosen via ref_type and ref_samples. Gene expression values are averaged using the ref_mean method.
Target Processing: For each target sample or group (norm_by), a target expression profile is created using tgt_mean.
M and A Vector Calculation:
- The A-vector (average expression) is used to filter out low-expression genes, which can be noisy.
- The M-vector (expression ratio: target/reference) is used to derive the normalization factor from its central tendency.
Trimming Process: A sequential trimming process refines the set of genes used for normalization:
- A-vector trimming: Genes with average expression below a_trim_value are removed.
- M-vector trimming: A proportion (m_trim_prop) of genes with the most extreme expression ratios are removed. This is disabled by default (m_trim_prop = 0).
- Extreme ratio trimming: If trim_extreme is TRUE, genes with infinite or zero ratios are removed. This is advised when norm_mean is not "median" or when m_trim_prop is too small to remove these values.
Factor Calculation: The final normalization factor is computed by applying norm_mean to the ratio (M-vector) of the remaining genes.
Normalization Scope (norm_scale): This parameter determines the scope and reference for normalization.
- design: Normalization is performed across all samples at once This is the generally recommended approach as it makes all samples comparable across the entire experiment.
- batch or group: Normalization is performed independently within each context. This can mitigate biases if a particular batch or group is compositionally very different. However, it renders data comparable only within that same context (e.g., within a batch), not across the entire design.

Usage

ExprData$compute_and_set_inter_norm_fact(
  norm_scale = "design",
  norm_by = "sample",
  ref_type = "all",
  ref_samples = NULL,
  ref_mean = "arithmetic",
  norm_mean = "median",
  tgt_mean = "arithmetic",
  a_mean = "arithmetic",
  a_trim_value = 1,
  m_trim_prop = 0,
  trim_extreme = FALSE
)

Arguments

norm_scale

Scale to apply the normalization:

"design" for all samples in one go
"batch" for applying norm_factors per batch
"group" for applying norm factors per batch per group. The scale will have an impact on the reference selection if ref type is "ctrl" or "all". In consequences the same sample can be associated with different scaling factor if it appears in different batch/group. Therefore data normalized at the "batch" or "group" level can not be analyzed at the design level. (and group scale not at the batch level either). Indeed at group/batch levels the inter_norm can only be applied at group/batch level.

norm_by

level by which M and A vector are computed followed by. the scaling factor for normalization.

ref_type

Type of reference samples to use for normalization.

"all" for using all samples as reference
"ctrl" for using only control samples as reference
"specified" for using specific samples ref_samples as reference

ref_samples

Samples to use as reference for normalization.

ref_mean

Method for averaging gene expression across reference samples. It is recommended to use the same method for ref_mean, tgt_mean, and a_mean.

"arithmetic": Recommended when using library size-scaled intra-normalization (e.g., "tpm", "fpkm", "fpm"). This preserves the sum of proportions.
"geometric": Recommended when intra-normalization does not account for library size (e.g., "none", "fpk"). The library size effect is then absorbed into the inter-sample normalization factor. This approach, with "none" intra-normalization, mirrors the default behavior in DESeq2. Note that this can be problematic if normalization is performed per group (norm_by = "group").
Other options: "median", "nz.geometric", "mod.geometric".

norm_mean

Method for the mean of ratios between the target and the reference. See ref_mean for possible values.

tgt_mean

Method for averaging gene expression across target samples. See ref_mean for recommended usage and available options.

a_mean

Method for averaging gene expression between target and reference samples to calculate the A-vector. See ref_mean for recommended usage and available options.

a_trim_value

Value for trimming the A vector.

m_trim_prop

Proportion of values to trim from the M vector.

trim_extreme

Whether to trim extreme values from the M vector, before calculating the mean. If the mean function norm_mean is not "median", extreme values will causes issues with the calculation of the mean.

Method `compute_and_set_intra_norm_fact()`

Set intra normalization factors. This function replaces any NaN values in the intra normalization factors with 1. NaN values may occur when the denominator in the calculations is 0. Replacing NaN values with 1 ensures that the normalization factors do not have missing or undefined values, which can cause issues in further analyses.

Usage

ExprData$compute_and_set_intra_norm_fact(method)

Arguments

method

Normalization method:

"none" for no normalization
"fpm" for Fragment per million mapped
"fpk" for Fragment per kilobase of transcript
"tpm" for Transcript per million
"fpkm" for Fragment per kilobase of transcript per million mapped

Method `reset()`

Reset object, this affects:

expression tags selection (as initially)
samples selection (as initially)
normalization (No norm)

Usage

ExprData$reset()

Returns

interger matrix with raw counts for expressed tags

Method `get_raw()`

Get raw count matrix

Usage

ExprData$get_raw()

Returns

interger matrix with raw counts for expressed tags

Method `filter_and_get_raw()`

Filter and get raw count matrix

Usage

ExprData$filter_and_get_raw(
  in_batch = NULL,
  in_group = NULL,
  include_ctrl = FALSE
)

Arguments

in_batch: (optional) A character vector specifying the batch(es) to include.
in_group: (optional) A character vector specifying the group(s) to include.
include_ctrl: when in_group is specified, will include batch ctrl

Returns

interger matrix with raw counts for expressed tags

Method `get_len()`

Get effective length matrix

Usage

ExprData$get_len()

Returns

numeric matrix with effective length for expressed tags

Method `filter_and_get_len()`

filter and get effective length matrix

Usage

ExprData$filter_and_get_len(in_batch = NULL, in_group = NULL)

Arguments

in_batch: (optional) A character vector specifying the batch(es) to include.
in_group: (optional) A character vector specifying the group(s) to include.

Returns

numeric matrix with effective length for expressed tags

Method `compute_norm_fact()`

Get normalization factors matrix

Usage

ExprData$compute_norm_fact(
  in_batch = NULL,
  in_group = NULL,
  inter_norm = FALSE,
  intra_norm = TRUE,
  include_ctrl = FALSE,
  rescale_inter_norm = TRUE
)

Arguments

in_batch: (optional) A character vector specifying the batch(es) to include.
in_group: (optional) A character vector specifying the group(s) to include.
inter_norm: A boolean indicating whether to apply inter-sample normalization.
intra_norm: A boolean indicating whether to apply intra-sample normalization.
include_ctrl: if TRUE and if in_batch and in_group are specified, control samples from the specified batch will be included.
rescale_inter_norm: Rescale inter-sample normalization factors so that their geometric mean is 1. Default is TRUE.

Returns

Numeric matrix with normalization factors for expressed tags

Method `get_intra_norm_fact_method()`

Get intra normalization method

Usage

ExprData$get_intra_norm_fact_method()

Returns

method name

Method `get_inter_norm_fact_opts()`

Get inter normalization methods

Usage

ExprData$get_inter_norm_fact_opts()

Returns

lists with all normalizations options

Method `compute_norm()`

Compute the normalized expression data from raw and norm matrices.

IMPORTANT: Default is no normalization. Please use the function below beforehand.

"compute_and_set_intra_norm_fact"
"compute_and_set_inter_norm_fact" Note that intra normalization is always applied, however inter norm is optional. Depending on the norm_scale used for inter normalization, the in_batch argument might be mandatory.

Usage

ExprData$compute_norm(
  in_batch = NULL,
  in_group = NULL,
  intra_norm = TRUE,
  inter_norm = FALSE,
  include_ctrl = FALSE,
  rescale_inter_norm = TRUE
)

Arguments

in_batch: (optional) A character vector specifying the batch(es) to include.
in_group: (optional) A character vector specifying the group(s) to include.
intra_norm: A boolean indicating whether to apply intra-sample normalization.
inter_norm: A boolean indicating whether to apply inter-sample normalization.
include_ctrl: include control samples in the normalization
rescale_inter_norm: Rescale inter-sample normalization factors so that their geometric mean is 1. Default is TRUE.

Returns

numeric matrix with norm counts for expressed tags

Method `is_with_fixed_length()`

Are the expression tags lengths fixed ?

Usage

ExprData$is_with_fixed_length()

Returns

numeric matrix with raw counts for expressed tags

Method `get_intra_norm_fact()`

Get the intra normalization factor

Usage

ExprData$get_intra_norm_fact(in_batch = NULL, in_group = NULL)

Arguments

in_batch: (optional) A character vector specifying the batch(es) to include.
in_group: (optional) A character vector specifying the group(s) to include.

Returns

numeric matrix with intra normalization factor

Method `get_inter_norm_fact()`

Get the inter normalization factor

Usage

ExprData$get_inter_norm_fact(in_batch = NULL, in_group = NULL, rescale = TRUE)

Arguments

in_batch: (optional) A character vector specifying the batch(es) to include.
in_group: (optional) A character vector specifying the group(s) to include.
rescale: Rescale the factors so that their geometric mean is 1.

Method `get_main_etag()`

Get the main expression tag id. The tag id corresponds to the unique id linked with a expression point. It can be tx_id (for transcript id) or "tgid" for "typed gene id". Why typed gene ID ? because some genes have transcripts from different types. As it would not be biologically relevant to aggregate different typse during the sum, a new id is create that is gene and type specific.

Usage

ExprData$get_main_etag()

Returns

chararacter representing the main espression tag id

Method `is_at_gene_level()`

Whether the expression data is at gene level or not.

Usage

ExprData$is_at_gene_level()

Returns

T or F

Method `get_design()`

Extract the PairwiseDesign instance that were used to build the expression data object.

Usage

ExprData$get_design()

Returns

PairwiseDesign object

Method `get_annotation()`

Extract the Annotation instance that were used to build the expression data object.

Usage

ExprData$get_annotation()

Returns

Annotation object

Method `plot_dist_per_sample()`

Plot the distribution of count or normalized values per RNA type for each sample.

Usage

ExprData$plot_dist_per_sample(
  intra_norm,
  inter_norm,
  include_ctrl = FALSE,
  rescale_inter_norm = TRUE,
  geoms = c("histo", "boxplot"),
  tr_fn = (function(x) log2(x + 2) - 1),
  mean_fun = NULL
)

Arguments

intra_norm

A boolean indicating whether to apply intra-sample normalization.

inter_norm

A boolean indicating whether to apply inter-sample normalization.

include_ctrl

A boolean indicating whether to include the control group. This argument is only valid when specifying only one argument for 'in_group' and 'in_batch'.

rescale_inter_norm

Rescale inter-sample normalization factors so that their geometric mean is 1. Default is TRUE.

geoms

Character vector, types of plot to draw, can be a combination of:

"boxplot": draw a box plot (fast)
"violin": draw a violin plot (slow)
"histo": draw an hiostogram (slow)

tr_fn

function to transform expression values before plot.

mean_fun

(Optional) Function to plot the mean per sample. Can be one of the following:

"median"
"geometric"
"nz.geometric" geometric without zero
"mod.geometric" modified geometric with epsilon = 1e-05 (see https://arxiv.org/abs/1806.06403)
"arithmetic"

...

Additional arguments passed to $compute_norm

Returns

ggplot2 graph

Method `extract_pairwise_data_with_design()`

Get formatted data for a group with its matching control within a batch

Usage

ExprData$extract_pairwise_data_with_design(
  in_batch,
  in_group,
  rescale_inter_norm = TRUE
)

Arguments

in_batch: (optional) A character vector specifying the batch(es) to include.
in_group: (optional) A character vector specifying the group(s) to include.
rescale_inter_norm: Rescale inter-sample normalization factors so that their geometric mean is 1. Default is TRUE.

Returns

list with selected attributes:

"raw" : matrix of raw values for test and control samples specified as column names
"len" : matrix of tag lenght values for test and control samples specified as column names
"intra_norm_fact" : matrix intra normalization factors
"inter_norm_fact" : vector of inter normalization factors
"norm_fact" : vector of inter normalization factors
"test_samples" : vector with test sample names
"ctrl_samples" : vector with control sample names
"design_table" : design table only for those samples
"ctrl_group" : the control group

Method `clean_id_versions()`

Clean version suffixes from expression tag IDs.

This method applies the remove_id_version_suffix utility to the row names of internal data matrices (raw, len, intra_norm_fact) and to selected_ids.

Usage

ExprData$clean_id_versions(suffix_pattern = "\\.\\d+$")

Arguments

suffix_pattern: (character) The regex pattern for the version suffix. Default is "-\\d+$". If NULL, FALSE, or an empty string, no cleaning is performed.

Method `plot_prcomp()`

Function to draw PCA plots

Usage

ExprData$plot_prcomp(
  in_batch = NULL,
  in_group = NULL,
  intra_norm = TRUE,
  inter_norm = TRUE,
  tr_fn = (function(x) log2(x + 2)),
  plot_scale = "group",
  ggplot_mod = NULL,
  color_palette = "Paired",
  prcomp_args = list(),
  include_ctrl_at_group_scale = FALSE,
  tags = NULL,
  tag_type = NULL,
  pca_plot_dims = c(1L, 2L),
  mshape = setNames("b_label", "Batch"),
  mcolor = setNames("g_label", "Group"),
  point_size = 5
)

Arguments

in_batch: (optional) A character vector specifying the batch(es) to include.
in_group: (optional) A character vector specifying the group(s) to include.
intra_norm: A boolean indicating whether to apply intra-sample normalization.
inter_norm: A boolean indicating whether to apply inter-sample normalization.
tr_fn: data transformation function
plot_scale: At which scale are the samples correlated.
ggplot_mod: ggplot modifier that will be added to the graph.
color_palette: name of the palette of color to use
prcomp_args: args to be used with prcomp.
include_ctrl_at_group_scale: whether to include the controls at group scale
tags: vector of tag ids to use for the plot
tag_type: name of the tag type to use
pca_plot_dims: integer id the the principal component to plot
mshape: Which variable to use for shape mapping
mcolor: Which variable to use for color mapping
point_size: point size for geom plot
prcomp_autoplot_args: list of argument that are used with autoplot.

Returns

ggplot2 graph

Method `plot_corr()`

Function to draw correlation plots

Usage

ExprData$plot_corr(
  in_batch = NULL,
  in_group = NULL,
  intra_norm = TRUE,
  inter_norm = TRUE,
  tr_fn = (function(x) log2(x + 2)),
  plot_scale = "group",
  ggplot_mod = NULL,
  include_ctrl_at_group_scale = FALSE,
  tags = NULL,
  tag_type = NULL
)

Arguments

in_batch: (optional) A character vector specifying the batch(es) to include.
in_group: (optional) A character vector specifying the group(s) to include.
intra_norm: A boolean indicating whether to apply intra-sample normalization.
inter_norm: A boolean indicating whether to apply inter-sample normalization.
tr_fn: data transformation function
plot_scale: At which scale are the samples correlated.
ggplot_mod: ggplot modifier that will be added to the graph.
include_ctrl_at_group_scale: whether to include the controls at group scale
tags: vector of tag ids to use for the plot
tag_type: name of the tag type to use

Returns

ggplot2 graph

Method `plot_hclust()`

Function to draw hierarchical clustering plots

Usage

ExprData$plot_hclust(
  in_batch = NULL,
  in_group = NULL,
  intra_norm = TRUE,
  inter_norm = TRUE,
  tr_fn = (function(x) log2(x + 2)),
  plot_scale = "group",
  ggplot_mod = NULL,
  color_palette = "BrBG",
  dist_method = "euclidean",
  hclust_method = "ward.D2",
  dim_reduce = NULL,
  clust_bar_var = c(),
  height_main = 10,
  width_main = 4,
  prcomp_args = list(),
  include_ctrl_at_group_scale = FALSE,
  tags = NULL,
  tag_type = NULL
)

Arguments

in_batch: (optional) A character vector specifying the batch(es) to include.
in_group: (optional) A character vector specifying the group(s) to include.
intra_norm: A boolean indicating whether to apply intra-sample normalization.
inter_norm: A boolean indicating whether to apply inter-sample normalization.
tr_fn: data transformation function
plot_scale: At which scale are the samples correlated.
ggplot_mod: ggplot modifier that will be added to the graph.
color_palette: name of the palette of color to use
dist_method: distance method
hclust_method: hierarchical clustering method
dim_reduce: reduction before clustering
clust_bar_var: list of variable to include as legend as a color bar
height_main: height value for main graph
width_main: width value for main graph
prcomp_args: args to be used with prcomp.
include_ctrl_at_group_scale: whether to include the controls at group scale
tags: vector of tag ids to use for the plot
tag_type: name of the tag type to use

Returns

ggplot2 graph

Method `clone()`

The objects of this class are cloneable with this method.

Usage

ExprData$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

An R6 class representing an RNA-Seq expression dataset.

Methods

Public methods

Method show_etags_summary()

Usage

Arguments

Returns

Method plot_etags_summary()

Usage

Arguments

Returns

Method filter_and_set_selected_ids()

Usage

Arguments

Method compute_and_set_inter_norm_fact()

Usage

Arguments

Method compute_and_set_intra_norm_fact()

Usage

Arguments

Method reset()

Usage

Returns

Method get_raw()

Usage

Returns

Method filter_and_get_raw()

Usage

Arguments

Returns

Method get_len()

Usage

Returns

Method filter_and_get_len()

Usage

Arguments

Returns

Method compute_norm_fact()

Usage

Arguments

Returns

Method get_intra_norm_fact_method()

Usage

Returns

Method get_inter_norm_fact_opts()

Usage

Returns

Method compute_norm()

Usage

Arguments

Returns

Method is_with_fixed_length()

Usage

Returns

Method get_intra_norm_fact()

Usage

Arguments

Returns

Method get_inter_norm_fact()

Usage

Arguments

Method get_main_etag()

Usage

Returns

Method is_at_gene_level()

Usage

Returns

Method get_design()

Usage

Returns

Method get_annotation()

Usage

Returns

Method plot_dist_per_sample()

Usage

Arguments

Returns

Method extract_pairwise_data_with_design()

Usage

Arguments

Method `show_etags_summary()`

Method `plot_etags_summary()`

Method `filter_and_set_selected_ids()`

Method `compute_and_set_inter_norm_fact()`

Method `compute_and_set_intra_norm_fact()`

Method `reset()`

Method `get_raw()`

Method `filter_and_get_raw()`

Method `get_len()`

Method `filter_and_get_len()`

Method `compute_norm_fact()`

Method `get_intra_norm_fact_method()`

Method `get_inter_norm_fact_opts()`

Method `compute_norm()`

Method `is_with_fixed_length()`

Method `get_intra_norm_fact()`

Method `get_inter_norm_fact()`

Method `get_main_etag()`

Method `is_at_gene_level()`

Method `get_design()`

Method `get_annotation()`

Method `plot_dist_per_sample()`

Method `extract_pairwise_data_with_design()`

Method `clean_id_versions()`

Method `plot_prcomp()`

Method `plot_corr()`

Method `plot_hclust()`

Method `clone()`