modlist: Create nonlinear models from a dataframe and coerce them into...
In qpcR: Modelling and Analysis of Real-Time PCR Data

Description Usage Arguments Details Value Author(s) See Also Examples

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.

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, ...)

`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`.

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'.

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).

Andrej-Nikolai Spiess

pcrbatch for batch analysis using different methods.

## 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)

## End(Not run)