fitModel() R function from [TIMP]

Performs optimization of (possibly multidataset) models.

Performs optimization of (possibly multidataset) models and outputs plots and files representing the fit of the model to the data.


fitModel(data, modspec=list(), datasetind = vector(),
modeldiffs = list(), opt = opt(),lprogress=FALSE )

Arguments

data: list of objects of class dat containing the data to be modeled
modspec: list whose elements are models of class dat

describing the models as results from a call to the function initModel
datasetind: vector that has the same length as data; for each dataset in data specify the model it should have as an index into modspec; default mapping is that all datasets use the first model given in modspec
modeldiffs: list whose elements specify any dataset-specific model differences.
- linkclplist of vectors containing the indices of datasets. If the two dataset indices are in the same vector, their conditionally linear parameters will be equated if they represent the same condition (e.g., a wavelength) within thresh. For example, linkclp = list(1:10, 11:15) will let datasets 1-10 and 11-15 have the same clp. Note that if linkclp is not given, it will default to list{1:length(data)}, so that the clp from all datasets are equated when they represent conditions within thresh of each other.
  
  Consider the situation where the clp from many different datasets are equated. Then it is important to note that the specification of constraintsapplicable to the clp will also be equated, and will be read from themodel assigned to the first dataset in the group.
- dscallist 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)).
- threshnumeric describing the tolerance with which clp from different datasets are to be considered as equal. For instance, for two datasets containing data at 750 and 751 nm, respectively, thresh=1.5 will equate the clp at 750 and 751 between datasets. Specify a negative value of thresh to estimate clp per-dataset. See Section 2.2 of the paper in the references for the model equations.
- freelist 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 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)).
- removelist of lists specifying individual parameters to remove from parameter groups for a given dataset. each sublist has named elements
  - whatcharacter string naming parameter type, e.g., "kinpar"
  - datasetdataset index in which parameter group is to be removed
  - indvector of indices into parameter vector or list, e.g., c(2,3) or 4 where parameter should be removed
- addlist of lists specifying individual parameters to add to parameter groups for a given dataset. each sublist has named elements
  - whatcharacter string naming parameter type, e.g., "kinpar"
  - datasetdataset index in which parameter group is to change
  - startstarting value for added parameter
  - indvector of indices into parameter vector or list, e.g., c(2,3) or 4 where parameter should be added.
- changelist of lists specifying entire parameter groups to change for a given dataset. each sublist has named elements
  - whatcharacter string naming parameter type, e.g., "kinpar"
  - datasetdataset index in which parameter group is to change
  - specnew specification that in initModel would follow "what", e.g., for c(.1, .3) if what="kinpar"
- rellist of lists specifying parameters to relate between datasets each sublist has named elements
  - what1character string naming parameter type to be determined in relation to some other parameter type , e.g., "kinpar"
  - what2character string naming parameter type on which another parameter type is to depend, e.g., "kinpar"
  - ind1vector of indices into parameter vector or list, e.g., c(2,3) or 4 of the dependent parameter.
  - ind2vector 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
  - dataset1dataset index of the dependent parameter
  - dataset2dataset index of the parameter on which another parameter will depend
  - reloptional character string describing functional relationship between parameters; defaults to "lin" for linear relationship
  - startstarting value or vector of values parameterizing relationship between parameters
- weightlistList of new weights for the datasets returned by the function outlierCorrs (as the element weightList of the list that is the return value of this function).
opt: Object of class kinopt or specopt specifying fitting and plotting options.
lprogress: Logical specifying whether textual output of fitting progress is returned

Details

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

Returns

A list is returned containing the following elements:

currThetais a list of objects of class theta whose elements contain the parameter estimates associated with each dataset modeled.
currModelis an object of class multimodel

containing the results of fitting as well as the model specification
toPlotteris a list containing all arguments used by the plotting function; it is used to regenerate plots and other output by the examineFit function
nlsprogressif lprogress = TRUE textual output of the fitting progress is returned as an array of strings

References

Mullen KM, van Stokkum IHM (2007). ``TIMP: an R package for modeling multi-way spectroscopic measurements.'' Journal of Statistical Software, 18(3). tools:::Rd_expr_doi("10.18637/jss.v018.i03")

Author(s)

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

Examples


## 2 simulated concentration profiles in time
C <- matrix(nrow = 51, ncol = 2)
k <- c(.5, 1)
t <- seq(0, 2, by = 2/50)
C[, 1] <- exp( - k[1] * t)
C[, 2] <- exp( - k[2] * t)

## 2 simulated spectra in wavelength
E <- matrix(nrow = 51, ncol = 2)
wavenum <- seq(18000,28000, by=200)
location <- c(25000, 20000)
delta <- c(5000, 7000)
amp <- c(1, 2)
E[, 1] <- amp[1] * exp( - log(2) * (2 * (wavenum - location[1])/delta[1])^2)
E[, 2] <- amp[2] * exp( - log(2) * (2 * (wavenum - location[2])/delta[2])^2)

## simulated time-resolved spectra
sigma <- .001
Psi_q  <- C %*% t(E) + sigma * rnorm(nrow(C) * nrow(E))

## as an object of class dat
Psi_q_data <- dat(psi.df = Psi_q, x = t, nt = length(t), x2 = wavenum, nl =
length(wavenum))

## model for the data in the time-domain
kinetic_model <- initModel(mod_type = "kin", seqmod = FALSE,
kinpar = c(.1, 2))

## fit the model
kinetic_fit <- fitModel(data = list(Psi_q_data),
modspec = list(kinetic_model), opt = kinopt(iter=4, plot=FALSE))

fitModel function