fitModel {TIMP}R Documentation

Driver for optimization of model parameters and output of results of fitting.

Description

Performs optimization of (possibly multidataset) models.

Usage

fitModel(data, model, modeldiffs = list(), 
                opt = list(linrange = 1, iter = 1, plot = TRUE))

Arguments

data list of data objects of class dat
model model of class dat describing the model as results from a call to the function initModel
modeldiffs list whose elements specify any dataset-specific model differences.
    dscal
    list of lists specifying linear scaling relations between datasets; each list has elements to, from, value. The index of the dataset to be scaled is given in to; the index of the dataset on which the scaling is to be based is given in from. The starting value parameterizing the relationship is given as value. For example, dscal = list(list(to=2,from=1,value=.457)).
    free
    list of lists specifying individual parameters to free for a given dataset. each sublist has named elements
      what
      character string naming parameter type, e.g., "kinpar"
      ind
      vector or numeric of indices into parameter vector or list, e.g., c(2,3) or 4
      dataset
      dataset index in which parameter is to be freed
      start
      starting value for freed parameter
    For example, free = list( list(what = "irfpar", ind = 1, dataset = 2, start=-.1932), list(what = "kinpar", ind = 5, dataset = 2, start=.0004), list(what = "kinpar", ind = 4, dataset = 2, start= .0159)).
    remove
    list of lists specifying individual parameters to remove from parameter groups for a given dataset. each sublist has named elements
      what
      character string naming parameter type, e.g., "kinpar"
      dataset
      dataset index in which parameter group is to be removed
      ind
      vector or numeric of indices into parameter vector or list, e.g., c(2,3) or 4 where parameter should be removed
    add
    list of lists specifying individual parameters to add to parameter groups for a given dataset. each sublist has named elements
      what
      character string naming parameter type, e.g., "kinpar"
      dataset
      dataset index in which parameter group is to change
      start
      starting value for added parameter
      ind
      vector or numeric of indices into parameter vector or list, e.g., c(2,3) or 4 where parameter should be added.
    change
    list of lists specifying entire parameter groups to change for a given dataset. each sublist has named elements
      what
      character string naming parameter type, e.g., "kinpar"
      dataset
      dataset index in which parameter group is to change
      spec
      new specification that in initModel would follow "what", e.g., for c(.1, .3) if what="kinpar"
    rel
    list of lists specifying parameters to relate between datasets each sublist has named elements
      what1
      character string naming parameter type to be determined in relation to some other parameter type , e.g., "kinpar"
      what2
      character string naming parameter type on which another parameter type is to depend, e.g., "kinpar"
      ind1
      vector or numeric of indices into parameter vector or list, e.g., c(2,3) or 4 of the dependent parameter.
    ind2
    vector or numeric of indices into parameter vector or list, e.g., c(2,3) or 4 of the parameter on which another parameter will depend
    dataset1
    dataset index of the dependent parameter
    dataset2
    dataset index of the parameter on which another parameter will depend
    rel
    optional character string describing functional relationship between parameters; defaults to "lin" for linear relationship
    start
    starting value or vector of values parameterizing relationship between parameters
opt list of options for fitting and display of results.
    iter
    integer number of iterations to optimize model parameters
    linrange
    numeric giving linear range of time axis for plotting; time will be plotted linearly from -linrange to linrange and plotted on a logarithmic (base 10) axis elsewhere
    plot
    Logical whose default value is TRUE; if FALSE then no plots or output files are written
    superimpose
    vector of dataset indices whose results should be superimposed in plots of traces
    selectedtraces
    vector of x indices for which traces are desired under a kinetic model
    notraces
    if length is non-zero, do not plot traces
    plotkinspec
    plot the spectra associated with the kinetics (leaving out the coherent artifact/scatter)
    breakdown
    vector of time indices for which the breakdown of contributions to the fit per-component is desired.
    xlabel
    character string label for x-axis, e.g., "nanoseconds" or "picoseconds"
    ylabel
    character string label for y-axis, e.g., "wavelength"
    title
    character string title for plots
    makeps
    character string prefix to plot files written to postscript; if present postscript will be written. Note that this string is also used as the preffix of txt output files
    writefit
    logical, if true then fit is written to a txt file; row and column labels are x and x2
    writecon
    logical, if true then concentrations are written to a txt file; row labels are x
    writespec
    logical, if true then spectra are written to a txt file; row labels are x2
    writenormspec
    logical, if true then normalized spectra are written to a txt file; row labels are x2
    FLIM
    list; if present FLIM plotting options used
    paropt
    list of graphical parameters in format par(...)
    to apply to plots. Defaults to par(omi = tit, mgp = c(2, 1, 0), mai = c(0.5, 0.5, 0.5, 0.25), mar=c(3,3,1,1)), where tit = c(0, 0, 1, 0) if a title is specified in the call to initModel, and tit = c(0, 0, 0, 0) otherwise.
    divrel
    if length is non-zero, plot traces and concentration profiles divided by the dataset scaling parameters where they apply; this allows for the fit of datasets having different intensities on the same scale.
    nospectra
    if length is non-zero, do not generate plots of data and fit under a spectral model
    selectedspectra
    vector of x2 indices for which plots of spectra are and model fit are desired under a spectral model
    residplot
    if length is non-zero, generate a plot of residuals in a separate window.

Details

This function applies the nls function internally to optimize nonlinear parameters and to solve for clp via the partitioned variable projection algorithm.

Value

list with elements toPlotter, final_res, onls, sumonls.

toPlotter is a list containing all arguments used by the plotting function; it is used to regenerate plots and other output by the examineFit function
final_res is the output of the last call to the residual function
onls is the output of the nls function used to fit nonlinear parameters
sumonls is the result of the call summary(onls)

normal-bracket162bracket-normal

Author(s)

Katharine M. Mullen, Ivo H. M. van Stokkum

See Also

readData, initModel, examineFit


[Package TIMP version 1.0 Index]