qpcR (version 1.4-1)

modlist: Create nonlinear models from a dataframe and coerce them into a list

Description

Essential function to create a list of nonlinear models from the columns (runs) of a qPCR dataframe. This function houses different methods for curve transformation prior to fitting, such as normalization in [0, 1], smoothing, baseline subtraction etc. Runs that failed to fit or that have been identified as kinetic outliers (by default: lack of sigmoidal structure) can be removed automatically as well as their entries in an optionally supplied label vector.

Usage

modlist(x, cyc = 1, fluo = NULL, model = l4, check = "uni2", 
        checkPAR = parKOD(), remove = c("none", "fit", "KOD"), 
        exclude = NULL, labels = NULL, norm = FALSE, 
        baseline = c("none", "mean", "median", "lin", "quad", "parm"),
        basecyc = 1:8, basefac = 1, smooth = NULL, smoothPAR = NULL, 
        factor = 1, opt = FALSE, 
        optPAR = list(sig.level = 0.05, crit = "ftest"), verbose = TRUE, ...)

Arguments

x

a dataframe containing the qPCR data or a single qPCR run of class 'pcrfit'.

cyc

the column containing the cycle data. Defaults to first column.

fluo

the column(s) (runs) to be analyzed. If NULL, all runs will be considered.

model

the model to be used for all runs.

check

the method for kinetic outlier detection. Default is check for sigmoidal structure, see KOD. To turn off, use NULL.

checkPAR

parameters to be supplied to the check method, see KOD.

remove

which runs to remove. Either "none", those which failed to "fit" or from the "KOD" outlier method.

exclude

either "" for samples with missing column names or a regular expression defining columns (samples) to be excluded from modlist. See 'Details'.

labels

a vector containing labels, i.e. for defining replicate groups prior to ratiobatch.

norm

logical. Should the raw data be normalized within [0, 1] before model fitting?

baseline

type of baseline subtraction. See 'Details'.

basecyc

cycle range to be used for baseline subtraction, i.e. 1:5.

basefac

a factor for the baseline value, such as 0.95.

smooth

which curve smoothing method to use. See 'Details'.

smoothPAR

parameters to be supplied to the smoothing functions, supplied as a list. See 'Details'.

factor

a multiplication factor for the fluorescence response values (barely useful, but who knows...).

opt

logical. Should model selection be applied to each model?

optPAR

parameters to be supplied to mselect.

verbose

logical. If TRUE, fitting and tagging results will be displayed in the console.

...

other parameters to be passed to pcrfit.

Value

A list with each item containing the model from each column. A names item (which is tagged by *NAME*, if fitting failed) containing the column name is attached to each model as well as an item isFitted with either TRUE (fitting converged) or FALSE (a fitting error occured). This information is useful when ratiocalc is to be applied and unsuccessful fits should automatically removed from the given group definition. If kinetic outlier detection is selected, an item isOutlier is attached, defining the run as an outlier (TRUE) or not (FALSE).

Details

From version 1.4-0, the following baselining methods are available for the fluorescence values: baseline = numeric: a numeric value such as baseline = 0.2 for subtracting from each \(F_i\). "mean": subtracts the mean of all basecyc cycles from each \(F_i\). "median": subtracts the median of all basecyc cycles from each \(F_i\). "lin": creates a linear model of all basecyc cycles, predicts \(P_i\) over all cycles \(i\) from this model, and subtracts \(F_i - P_i\). "quad": creates a quadratic model of all basecyc cycles, predicts \(P_i\) over all cycles \(i\) from this model, and subtracts \(F_i - P_i\). "parm": extracts the \(c\) parameter from the fitted sigmoidal model and subtracts this value from all \(F_i\). It is switched off by default, but in case of data with a high baseline (such as in TaqMan PCR), it should be turned on as otherwise this will give highly underestimated efficiencies and hence wrong init2 values.

From version 1.3-8, the following smoothing methods are available for the fluorescence values: "lowess": Lowess smoothing, see lowess, parameter in smoothPAR: f. "supsmu": Friedman's SuperSmoother, see supsmu, parameter in smoothPAR: span. "spline": Smoothing spline, see smooth.spline, parameter in smoothPAR: spar. "savgol": Savitzky-Golay smoother, qpcR:::savgol, parameter in smoothPAR: none. "kalman": Kalman smoother, see arima, parameter in smoothPAR: none. "runmean": Running mean, see qpcR:::runmean, parameter in smoothPAR: wsize. "whit": Whittaker smoother, see qpcR:::whittaker, parameter in smoothPAR: lambda. "ema": Exponential moving average, see qpcR:::EMA, parameter in smoothPAR: alpha. The author of this package advocates the use of "spline", "savgol" or "whit" because these three smoothers have the least influence on overall curve structure.

In case of unsuccessful model fitting and if remove = "none" (default), the original data is included in the output, albeit with no fitting information. This is useful since using plot.pcrfit on the 'modlist' shows the non-fitted runs. If remove = "fit", the non-fitted runs are automatically removed and will thus not be displayed. If remove = "KOD", by default all runs without sigmoidal structure are removed likewise. If a labels vector lab is supplied, the labels from the failed fits are removed and a new label vector lab_mod is written to the global environment. This way, an initial labeling vector for all samples can be supplied, bad runs and their labels automatically removed and these transfered to downstream analysis (i.e. to ratiobatch) without giving errors. exclude offers an option to exclude samples from the modlist by some regular expression or by using "" for samples with empty column names. See 'Examples'.

See Also

pcrbatch for batch analysis using different methods.

Examples

# NOT RUN {
## Calculate efficiencies and ct values 
## for each run in the 'reps' data, 
## subtract baseline using mean of 
## first 8 cycles.
ml1 <- modlist(reps, model = l5, baseline = "mean")
getPar(ml1, type = "curve")

## 'Crossing points' for the first 3 runs (normalized)
##  and using best model from Akaike weights.
ml2 <- modlist(reps, 1, 2:5, model = l5, norm = TRUE, 
               opt = TRUE, optPAR = list(crit = "weights"))
sapply(ml2, function(x) efficiency(x, plot = FALSE)$cpD2)

## Convert a single run to a 'modlist'.
m <- pcrfit(reps, 1, 2, l5)
ml3 <- modlist(m)

## Using the 'testdat' set
## include failed fits.
ml4 <- modlist(testdat, 1, 2:9,  model = l5)
plot(ml4, which = "single")

## Remove failed fits and update a label vector.
GROUP <- c("g1s1", "g1s2", "g1s3", "g1s4", "g1c1", "g1c2", "g1c3", "g1c4") 
ml5 <- modlist(testdat, 1, 2:9,  model = l5, labels = GROUP, remove = "KOD")
plot(ml5, which = "single")

## Smoothing by EMA and alpha = 0.8.
ml6 <- modlist(reps, model = l5, smooth = "ema",
               smoothPAR = list(alpha = 0.5))
plot(ml6)

# }
# NOT RUN {
## Use one of the mechanistic models
## get D0 values.
ml7 <- modlist(reps, model = mak3)
sapply(ml7, function(x) coef(x)[1])

## Exclude first sample in each 
## replicate group of dataset 'reps'.
ml8 <- modlist(reps, exclude = ".1")
plot(ml8, which = "single")

## Using weighted fitting:
## weighted by inverse residuals.
ml9 <- modlist(reps, weights = "1/abs(resid)")
plot(ml9, which = "single")

## Use linear model of the first 10
## cycles for baselining.
ml10 <- modlist(reps, basecyc = 1:10, baseline = "lin")
plot(ml10)

## Use a single value for baselining.
ml11 <- modlist(reps, basecyc = 1:10, baseline = 0.5)
plot(ml11)
# }