drda {drda}R Documentation

Fit non-linear growth curves

Description

Use the Newton's with a trust-region method to fit non-linear growth curves to observed data.

Usage

drda(
  formula,
  data,
  subset,
  weights,
  na.action,
  mean_function = "logistic4",
  is_log = TRUE,
  lower_bound = NULL,
  upper_bound = NULL,
  start = NULL,
  max_iter = 10000
)

Arguments

formula

an object of class link[stats]{formula} (or one that can be coerced to that class): a symbolic description of the model to be fitted. Currently supports only formulas of the type y ~ x.

data

an optional data frame, list or environment (or object coercible by as.data.frame to a data frame) containing the variables in the model. If not found in data, the variables are taken from environment(formula), typically the environment from which drda is called.

subset

an optional vector specifying a subset of observations to be used in the fitting process.

weights

an optional vector of weights to be used in the fitting process. If provided, weighted least squares is used with weights weights (that is, minimizing sum(weights * residuals^2)), otherwise ordinary least squares is used.

na.action

a function which indicates what should happen when the data contain NAs. The default is set by the na.action setting of options, and is na.fail if that is unset. The ‘factory-fresh’ default is na.omit. Another possible value is NULL, no action. Value na.exclude can be useful.

mean_function

the model to be fitted. See details for available models.

is_log

a logical value indicating whether the predictor variable x is already log-transformed. Default to TRUE. Set to FALSE if x is on its natural scale, i.e. strictly positive.

lower_bound

numeric vector with the minimum admissible values of the parameters. Use -Inf to specify an unbounded parameter.

upper_bound

numeric vector with the maximum admissible values of the parameters. Use Inf to specify an unbounded parameter.

start

starting values for the parameters.

max_iter

maximum number of iterations in the optimization algorithm.

Details

Available models

Generalized logistic function

The most general model in this package is the generalized logistic function selected by setting mean_function = "logistic6". It is defined in this package as the 6-parameter function

alpha + (beta - alpha) / (xi + nu * exp(-eta * (x - phi)))^(1 / nu)

where eta != 0, nu > 0, and xi > 0. Although beta can be any real value, we use the convention beta > alpha to avoid identifiability problems: when beta < alpha it is always possible to adjust the other parameters to obtain the same exact curve. When beta > alpha and eta > 0 the curve is monotonically increasing. If beta > alpha and eta < 0 the curve is monotonically decreasing.

Parameter alpha represents the lower horizontal asymptote of the curve. Parameter beta is related to the upper horizontal asymptote of the curve. Parameter eta represents the steepness (growth rate) of the curve. Parameter phi is related to the value of the function at x = 0. Parameter nu affects near which asymptote maximum growth occurs. Parameter xi affects the value of the upper asymptote.

Note: the 6-parameter logistic function is non-identifiable from data and should not be used in real applications. It is available only for theoretical research convenience.

5-parameter logistic function

The 5-parameter logistic function can be selected by choosing mean_function = "logistic5". The function is obtained by setting xi = 1 in the generalized logistic function, that is

alpha + (beta - alpha) / (1 + nu * exp(-eta * (x - phi)))^(1 / nu)

Parameter alpha represents the lower horizontal asymptote of the curve. Parameter beta represents the upper horizontal asymptote of the curve. Parameter eta represents the steepness (growth rate) of the curve. Parameter phi is related to the value of the function at x = 0. Parameter nu affects near which asymptote maximum growth occurs.

4-parameter logistic function

The 4-parameter logistic function is the default model of drda. It can be explicitly selected by choosing mean_function = "logistic4". The function is obtained by setting xi = 1 and nu = 1 in the generalized logistic function, that is

alpha + (beta - alpha) / (1 + exp(-eta * (x - phi)))

Parameter alpha represents the lower horizontal asymptote of the curve. Parameter beta represents the upper horizontal asymptote of the curve. Parameter eta represents the steepness (growth rate) of the curve. Parameter phi represents the x value at which the curve is equal to its mid-point, i.e. ⁠f(phi; alpha, beta, eta, phi) = (alpha + beta) / 2⁠.

2-parameter logistic function

The 2-parameter logistic function can be selected by choosing mean_function = "logistic2". The function is obtained by setting xi = 1, nu = 1, beta = 1, and alpha = 0 in the generalized logistic function, that is

1 / (1 + exp(-eta * (x - phi)))

Parameter eta represents the steepness (growth rate) of the curve. Parameter phi represents the x value at which the curve is equal to its mid-point, i.e. ⁠f(phi; eta, phi) = 1 / 2⁠.

Gompertz function

The Gompertz function is the limit for nu -> 0 of the 5-parameter logistic function. It can be selected by choosing mean_function = "gompertz". The function is defined in this package as

alpha + (beta - alpha) * exp(-exp(-eta * (x - phi)))

where eta != 0.

Parameter alpha represents the lower horizontal asymptote of the curve. Parameter beta represents the upper horizontal asymptote of the curve. Parameter eta represents the steepness (growth rate) of the curve. Parameter phi is related to the value of the function at x = 0.

Constrained optimization

It is possible to search for the maximum likelihood estimates within pre-specified interval regions. Since the upper horizontal asymptote beta must be greater than the lower horizontal asymptote alpha, intervals are adjusted to satisfy this constraint.

Note: Hypothesis testing is not available for constrained estimates because asymptotic approximations might not be valid

Value

An object of class drda and model_fit, where model is the chosen mean function. It is a list containing the following components:

converged

boolean value assessing if the optimization algorithm converged or not.

iterations

total number of iterations performed by the optimization algorithm

constrained

boolean value set to TRUE if optimization was constrained.

estimated

boolean vector indicating which parameters were estimated from the data.

coefficients

maximum likelihood estimates of the model parameters.

rss

minimum value (found) of the residual sum of squares.

df.residuals

residual degrees of freedom.

fitted.values

fitted mean values.

residuals

residuals, that is response minus fitted values.

weights

(only for weighted fits) the specified weights.

mean_function

model that was used for fitting.

n

effective sample size.

sigma

corrected maximum likelihood estimate of the standard deviation.

loglik

maximum value (found) of the log-likelihood function.

fisher.info

observed Fisher information matrix evaluated at the maximum likelihood estimator.

vcov

approximate variance-covariance matrix of the model parameters.

call

the matched call.

terms

the terms object used.

model

the model frame used.

na.action

(where relevant) information returned by model.frame on the special handling of NAs.

is_log

boolean value. It is TRUE if the predictor variable was given on the log scale.


[Package drda version 1.0.0 Index]