fitModel {TIMP}

Performs optimization of (possibly multidataset) models.

Description

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

Usage

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.

• linkclp list 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 constraints applicable to the clp will also be equated, and will be read from the model assigned to the first dataset in the group.

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

• thresh numeric 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.

• 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 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 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 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

  • 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 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

• weightlist List 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.

Value

A list is returned containing the following elements:

• currTheta is a list of objects of class theta whose elements contain the parameter estimates associated with each dataset modeled.

• currModel is an object of class multimodel containing the results of fitting as well as the model specification

• 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

• nlsprogress if lprogress = TRUE textual output of the fitting progress is returned as an array of strings

Author(s)

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

References

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

See Also

readData, initModel, examineFit

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