fitFunction {CornerstoneR}

Fit Function to Data via Nonlinear Regression

Description

Fit predefined functions to data via nonlinear least squares using Levenberg-Marquardt algorithm via nlsLM.

Usage

fitFunction(
  dataset = cs.in.dataset(),
  preds = cs.in.predictors(),
  resps = cs.in.responses(),
  groups = cs.in.groupvars(),
  auxs = cs.in.auxiliaries(),
  scriptvars = cs.in.scriptvars(),
  return.results = FALSE,
  ...
)

Arguments

dataset

[data.frame]
Dataset with named columns. The names correspond to predictors and responses.

preds

[character]
Character vector of predictor variables.

resps

[character]
Character vector of response variables.

groups

[character]
Character vector of group variables.

auxs

[character]
Character vector of auxiliary variables.

scriptvars

[list]
Named list of script variables set via the Cornerstone "Script Variables" menu. For details see below.

return.results

[logical(1)]
If FALSE the function returns TRUE invisibly. If TRUE, it returns a list of results. Default is FALSE.

...

[ANY]
Additional arguments to be passed to nls . Please consider possible script variables (scriptvars) to prevent duplicates.

Details

The following script variables are summarized in scriptvars list:

math.fun

[character(1)]
Function selection for fitting data. It is possible to choose a predefined model, or compose a model manually by selecting User Defined.
Default is User Defined

preds.frml

[character(1)]
Required if math.fun is set to User Defined. Valid R formula for the right hand side (predictors) of the model equation.

resp.frml

[character(1)]
Required if math.fun is set to User Defined. Valid R formula for the left hand side (response) of the model equation.

limits

[character(1)]
Optional if math.fun is set to User Defined. Specifies minimum and maximum value for function math.fun as a comma separated list of min and max. It is possible to assign variables, e.g. min=a, which need start values in start.vals, as well as real numbers, e.g. min=4.5, with a period as decimal separator.

start.vals

[character(1)]
Required if math.fun is set to User Defined. Specify starting values for all terms of the right hand side as a comma separated list with a period as decimal separator.

weights

[character(1)]
Select a weighting variable from the auxiliary variables.

max.iter

Maximum number of iterations. For details see link[minpack.lm]{nls.lm.control}

max.ftol

Maximum relative error desired in the sum of squares. If 0, the default is used. For details see link[minpack.lm]{nls.lm.control}

Value

Logical [TRUE] invisibly and outputs to Cornerstone or, if return.results = TRUE, list of resulting data.frame objects:

coeff

Estimated coefficients and standard errors for each group. Convergence information is available for every group (for details see link[minpack.lm]{nls.lm}).

vcov

Variance-Covariance matrix of the main coefficients for the fitted model of each group (for details see link[stats]{vcov}).

predictions

Dataset to brush with predictions and residuals added to original values and groups, if available.

Examples

# Generate data from logistic function:
fun = function(x, a, b, c, d, sigma = 1) {
  a+(b-a) / (1+exp(-d*(x-c))) + rnorm(length(x), sd = sigma)
  }
library(data.table)
dt = data.table(  x1 = sample(seq(-10, 10, length.out = 100))
                  , group1 = sample(x = c("A", "B"), replace = TRUE, size = 100)
                  )
dt[group1 == "A", y1 := fun(x1, 1, 10, 1, 0.6, 0.1)]
dt[group1 == "B", y1 := fun(x1, 8, 2, -1, 0.3, 0.1)]
# Set script variables
scriptvars = list(math.fun = "Logistic", resp.frml = "", preds.frml = "", limits = ""
                  , start.vals = "", weights = "", max.iter = 50, max.ftol = 0
                  )
# Fit the logistic function:
res = fitFunction(dt, "x1", "y1", "group1", character(0), scriptvars, TRUE)
# Show estimated coefficients:
res$coeff
# Variance-Covariance matrix:
res$vcov
# Plot fitted vs. residuals:
plot(res$predictions$Fitted, res$predictions$Residuals)