align_me: Align time-course data based on an Mixed-Effects alignment...

In SeverinBang/blotIt3: Software set for alignment of biological replicate data

Align time-course data based on an Mixed-Effects alignment model

Description

The function deals primarily with time-course data of different targets which have been measured under different experimental conditions and whose measured values might be on a different scale, e.g. because of different amplification. The algorithm determines the different scaling and estimates the time-course on a common scale.

Usage

align_me(
  data,
  model = NULL,
  error_model = NULL,
  biological = NULL,
  scaling = NULL,
  error = NULL,
  parameter_fit_scale_log = TRUE,
  normalize = TRUE,
  average_techn_rep = FALSE,
  verbose = FALSE,
  names_as_factors = TRUE,
  normalize_input = TRUE,
  output_scale = "linear",
  iterlim = 100,
  ci_profiles = FALSE
)

Arguments

data	data.frame containing the the data to be scaled. Usualy the output of read_wide is used. Obligatory are the columns name, and value. In the case of time dependet data, a time column is also necessary. Additionally, data should have further columns, e.g. characterizing experimental conditions (the fixed effects) and sources of variance between data of the same experimental condition (the scaled variables).
model	character defining the model by which the values in data can be described, e.g. "yi/sj"
error_model	character defining a model for the standard deviation of a value, e.g. "sigma0 + value * sigmaR". This model can contain parameters, e.g. "sigma0" and "sigmaR", or numeric variables from data, e.g. "value" or "time".
biological	two-sided formula of the form par1+par2+... ~ name1+name2+... where "par1, par2, ..." are parameters contained in model, e.g. "yi", and "name1, ..." refers to variables in data, e.g. "condition". The parameters "par1, ..." are determined specific to the levels of "name1, ...".
scaling	two-sided formula of the form par1+par2+... ~ name1+name2+... where "par1, par2, ..." are parameters contained in model, e.g. "sj", and "name1, ..." refers to variables in data, e.g. "Experiment".
error	two-sided formula of the form par1+par2+... ~ name1+name2+... where "par1, par2, ..." are parameter contained in error, e.g. "sigma0" and "sigmaR", and "name1, ..." refers to variables in data. If the same values of "par1, ..." should be assumed for all data, the right hand side of ~ has to reffer to the "name" column of data.
parameter_fit_scale_log	logical, defining if the parameters are fitted on a log scale. Computational reasons.
normalize	logical indicating whether the biological effect parameter should be normalized to unit mean.
average_techn_rep	logical, indicates if the technical replicates should be averaged
verbose	logical, print out information about each fit
names_as_factors	logical, indicates if the name columns of the output should be parsed as factors instead of characters.
normalize_input	logical, if TRUE the input will be normalized before scaling, helpful if convergence fails because the data varies for to many orders of magnitude.
iterlim	numerical argument passed to trust.
ci_profiles	Logical, if TRUE, the confidence intervals (CI) are calculated based on the profile likelihood (PL). Default is FALSE, the CI will then be approximated by the Fisher information (FI). Calculation via PL is more exact but roughly 20times slower. The FI approximates the CI conservatively compared to the PL (FI leads to larger CI).

Details

Alignment of time-course data is achieved by an alignment model which explains the observed data by a function mixing fixed effects, usually parameters reflecting the "underlying" time-course, and latent variables, e.g. scaling parameters taking account for effects like different amplification or loading, etc. Depending on the measurement technique, the data has constant relative error, or constant absolute error or even a combination of those. This error is described by an error function. The error parameters are usually global, i.e. the same parameter values are assumed for all data points.

Value

Object of class aligned, i.e. a data frame of the alignment result containing an attribute "outputs": a list of data frames

aligned

data.frame with the original column names plus the column sigma. Each set of unique biological effects i.e. biological different condition (e.g. time point, target and treatment) has one set of value and sigma. The values are the estimated true values i.e. the determined biological parameters. The errors in the sigma column are estimated by employing the fisher information to quantify the uncertainty of the respective fit. Both, the value and its error are on the common scale.

scaled

The original measurements scaled to common scale by applying inverse model. The errors are the result of the evaluation of the error model and then also scaled to common scale by use of Gaussian error propagation.

prediction

Original data with value replaced by the prediction (evaluation of the model with the fitted parameters), and sigma from the evaluation of the error model. Both are on the original scale.

original

The original data as passed as data.

original_with_parameters

The original data but with added columns containing the estimated parameters

parameter

Parameter table with the columns: name: the name of the current target, level: the pasted unique set of effects (biological, scaling or error), parameter: the parameter identifier as defined in the (error) model, value and sigma containing the determined values and corresponding errors, nll: twice the negative log-likelihood of the fit, no_pars and no_data containing the number of parameters and data points for the respected fit. This list entry also has two attributes: value containing the final value (residual sum of squares) passed to trust::trust by the objective function and df the degrees of freedom of the fitting process.

biological

Names of the columns containing the biological effects

scaling

Names of the columns containing the scaling effects

error

Names of the columns containing the error effects

The estimated parameters are returned by the attribute "parameters".

See Also

read_wide to read data in a wide column format and get it in the right format for align_me.

Examples

## Get example dataset
example_data_file <- system.file(
  "extdata", "sim_data_wide.csv",
  package = "blotIt3"
)

## read in example data by use of 'read_wide()'
example_data <- read_wide(example_data_file, description = seq_len(3))

## execute align_me
out <- align_me(
  data = example_data,
  model = "yi / sj",
  error_model = "value * sigmaR",
  biological = yi ~ name + time + condition,
  scaling = sj ~ name + ID,
  error = sigmaR ~ name + 1,
  input_scale = "linear",
  normalize = TRUE,
  average_techn_rep = FALSE,
  verbose = FALSE,
  normalize_input = TRUE
)

SeverinBang/blotIt3 documentation built on April 4, 2022, 5 a.m.