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'.
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.
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.
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.
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")
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")
- Mon Sep 30 1996 -