confidence.nls2 - Confidence Interval for Parameters or Functions of Parameters Estimated by nls2


On to:
DESCRIPTION
USAGE
REQUIRED-ARGUMENTS
OPTIONAL-ARGUMENTS
VALUE
CONSTRAINTS
SIDE-EFFECTS
DETAILS
SEE-ALSO
EXAMPLE



DESCRIPTION:

Calculate confidence intervals for parameters estimated by `nls2' or for functions of such parameters.

Function `conflike.nls2' calculates a confidence interval based on the log-likelihood ratio for a parameter (To use it for a function of parameters, see example 4 in the paragraph `EXAMPLE').
Function `confidence.nls2' is similar to `conflike.nls2' when the argument `parameter' is set. When it is not set, two confidence intervals are calculated: the one is based on the quantiles of the asymptotic normal distribution and the other on the quantiles of the Student's t distribution.


USAGE:
confidence.nls2(nls2.object, conf.level=0.95,
     file=NULL, 
     pbispsi=c(nls2.object$model$gamf, nls2.object$model$gamv), 
     varpsi=NULL,
     parameter=NULL, n.values=NULL, eps=0.01,
     extends=3* coef(nls2.object)$std.error[parameter],
     step=extends/10)


conflike.nls2_function(nls2.object, parameter=NULL, n.values=NULL, eps=0.01, extends=3* coef(nls2.object)$std.error[parameter], step=extends/10, conf.level=0.95)

REQUIRED ARGUMENTS:
nls2.object
object of class `nls2'.

Sommaire

OPTIONAL ARGUMENTS:

conf.level
confidence level for the returned confidence intervals, restricted to lie between zero and one.
file
when confidence intervals are requested for functions of parameters, a character string equal to the pathname of the operating-system file which contains the description of the functions (see `nls2.psi').
pbispsi
when confidence intervals are requested for functions of parameters, the values of the second level parameters (i.e parameters not estimated), if any.
If it is a labelled vector, only the elements whose names are present in the `pbispsi' declaration of the formal description of the functions are taken into account. If it is not labelled, its values must be sorted according to this declaration.
By default if there is a `pbispsi' declaration in the formal description of the functions, the values of the second level parameters contained in the `nls2.object'.
varpsi
when confidence intervals are requested for a function of parameters that depends on variables, a vector or a matrix that contains the values of the variables declared by the `varpsi' declaration in the formal description of the function.
It is a matrix if there are several variables. If the columns are labelled, only those whose names are present in the `varpsi' declaration of the formal description are taken into account. If the columns are not labelled, they must be sorted according to this declaration.
parameter
the parameter for which a confidence interval based on the log-likelihood ratio is requested. When this argument is set and in function `conflike.nls2', only this type of confidence interval is returned.
Either character (the name of the parameter) or integer (a value from 1 to the total number of multiple parameters, the variance parameters been numbered after the regression parameters).
n.values
when the argument `parameter' is set and in function `conflike.nls2', the number of equally spaced values for which the log-likelihood ratio is calculated, at each side of the estimated value of the parameter. The confidence interval is then calculated by linear interpolation between the points where the ratio is the nearest to the criterion. When this argument is set, the argument `eps' is ignored.
eps
when the argument `parameter' is set and in function `conflike.nls2', the requested precision between the log-likelihood ratio and the criterion at the bounds of the confidence interval.
extends
when the argument `parameter' is set and in function `conflike.nls2', the distance from the estimated value of the parameter where the log-likelihood ratio is calculated.

Sommaire

VALUE:

A list with the following components, according to what has been requested:

psi:
the values of the functions or active parameters.
d.psi:
when confidence intervals are calculated for functions, the derivatives of the functions with respect to the active parameters.
std.error:
the standard error of the functions or parameters.
var.psi:
the asymptotic variance of the functions or parameters.
wald.statistic:
when confidence intervals are calculated for functions, the Wald statistic to test their nullity.
normal.conf.int:
the bounds of the confidence interval based on the quantiles of the normal distribution. A matrix with two columns: the first contains the lower bound and the second the upper bound. As many rows as number of values of the functions or parameters.
student.conf.int:
the bounds of the confidence interval based on the quantiles of the Student's t distribution. A matrix with two columns: the first contains the lower bound and the second the upper bound. As many rows as number of values of the functions or parameters.
like.conf.int:
when the argument `parameter' is set and in function `conflike.nls2', the bounds of the confidence interval based on the log-likelihood ratio.
In addition, when the argument `n.values' is set,
like.statistics:
the calculated values of the log-likelihood ratio.
p.values:
the corresponding values of the parameter.
And when the argument `n.values' is not set,
like.statistics:
the values of the log-likelihood ratio at the bounds of the confidence interval.
like.n.values:
the number of points where it has been calculated.



Sommaire

CONSTRAINTS:

- In the input argument `nls2.object', component `as.var' should exist.

- When the argument `parameter' is set and to call `conflike.nls2':
-- estimating method must be "MLTB" or "MLT",
-- function `loadnls2' must have been called,
-- the data frame containing the observations must be available, (its name is nls2.object$call$data). It is then assumed that this data frame has been neither deleted nor modified since the nls2.object was created.

- When confidence intervals are requested for functions, the function `loadnls2', argument `psi' not NULL, must have been previously called.


SIDE EFFECTS:

When confidence intervals are calculated for functions and when no program has been previously loaded to evaluate them (see `loadnls2'), an operating-system file is created which contains the C-program that corresponds to the formal description of the functions. If this file already exists, it is replaced.

See also the side-effects of "qnorm()".


DETAILS:

This function is a method for the generic function `confidence(conflike)' for class `nls2'. It can be invoked by calling `confidence(conflike)' for an object of the appropriate class, or directly by calling `confidence(conflike).nls2' regardless of the class of the object.


Sommaire

SEE ALSO:

EXAMPLE:
Example 1:
To calculate the confidence intervals based on the 
quantiles of the asymptotic normal distribution and 
the confidence intervals  based on the quantiles of 
the Student's t distribution:
  confidence.out_ confidence(nls2.out)


Example 2: To calculate a confidence interval based on the log-likelihood ratio for the second parameter: loadnls2() confidence.out_ confidence(pept.nl4, parameter=2) or: confidence.out_ conflike(pept.nl4, 2)

Example 3: To test "g=1, h=0", the description-file, named "mod", is: psi fg, fh; ppsi g, h; subroutine; begin fg = g -1; fh = h; end The commands of the S-session are: loadnls2(psi="") confidence.out_ confidence(nls2.out, file="mod")

Sommaire

Example 4: To calculate the three types of confidence intervals for a function of parameters. - The regression model is described in the file "elisa.mod1": resp OD; varind logd; aux a1; parresp p1,p2,p3,p4; subroutine; begin a1= 1+exp(p3*(logd-p4)); OD=p1+(p2-p1)/a1; end - The function to test depends on parameters of two curves. It is described in the file "elisa.ro": psi ro; ppsi p4_c1, p4_c2; subroutine; begin ro=10**(p4_c2-p4_c1); end

The parameters are estimated by using function `nls2'. Then the Normal and Student confidence intervals are calculated: loadnls2(psi="") elisa.conf1_ confidence(nls2.out1, file="elisa.ro")

It is not possible to calculate a confidence interval based on the log-likelihood ratio for a function of the parameters. So, the regression model is written again in such a way that the function is considered as a parameter. "ro" is declared as a parameter and the parameter "p4_c2" is replaced by: "log10(ro)+p4_c1".

resp OD; varind logd, courbe; aux a1,a2; parresp p1c1,p2c1,p3c1,p4c1, p1c2,p2c2, p3c2,ro; subroutine; begin a2 = if (ro <= 0) then 1 else log10(ro) fi; a1 = if (courbe==1) then 1+exp(p3c1*(logd-p4c1)) else 1+exp(p3c2 *(logd-(a2 + p4c1))) fi; OD = if (courbe==1) then (p1c1 + (p2c1-p1c1)/a1) else (p1c2 + (p2c2-p1c2)/a1) fi; end

In the data-frame which contains the experimental data the component "curves" is replaced by an independent variable called "courbe". Then function `nls2' is called on these new data and model. Finally, function `conflike.nls2' is applied: elisa.conf2<-conflike(elisa.nl2, "ro")


Sommaire


- Mon Sep 30 1996 -