ellips.nls2 - Confidence Ellipsoids 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:
Return what is necessary to plot
confidence ellipsoids in a two-dimensional space
for parameters that have been estimated by `nls2'
or for functions of such parameters.
Let p1, p2, be two active parameters or functions.
The returned structure contains the quantities
z(x,y),
x and y varying on a grid regularly spaced
around p1, p2.
The extends of the grid and the density of the points
can be different for x and y, and at each side of p1, p2.
From z, confidence ellipsoids can be defined and plotted:
a confidence ellipsoid is the set of points
for which the returned values are less or equal to the
quantile of a chi-square distribution.
The number of degrees of freedom is
equal to the number of active parameters when ellipsoids are defined for parameters,
and equal to the number of values of the functions
when ellipsoids are defined for functions.
USAGE:
ellips.nls2(nls2.object, axis,
file=NULL,
pbispsi= c(nls2.object$model$gamf,nls2.object$model$gamv),
varpsi=NULL,
extends=matrix(3, nrow = 2, ncol = 2),
density=matrix(12, nrow = 2, ncol = 2),
bounds=NULL)
REQUIRED ARGUMENTS:
- nls2.object
-
an object of class `nls2'.
- axis
-
the identification of the two-dimensional space (x,y). Vector of length 2, either
character
(when ellipsoids should be defined for functions,
"axis" contains names declared by
the `psi' declaration in the formal description-file
and when ellipsoids should be defined for parameters,
"axis" contains names of estimated parameters)
or integer (values from 1 to the length of
the `psi' declaration of the formal description-file or
to the length of the argument `varpsi',
or values from 1 to the total number of multiple parameters,
the variance parameters being numbered after the regression parameters).
OPTIONAL ARGUMENTS:
- file
-
when ellipsoids should be defined for functions,
a character string equal to the pathname
of the operating-system file that contains the description of the
functions (see `nls2.psi').
- pbispsi
-
when ellipsoids should be defined for functions,
the values of the second level parameters
of these functions, if any.
(i.e parameters not estimated by nls2).
If it is a labelled vector, only the elements whose names are present in the
`pbispsi' declaration of the formal description-file are taken into account.
If it is not labelled, its values must be sorted according to the
declaration.
By default if there is a `pbispsi' declaration in the formal description-file,
"pbispsi" is equal to
the second level parameters of the `nls2.object'.
- varpsi
-
when ellipsoids should be defined for a function
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-file.
It is a matrix if there are several variables.
If its columns are labelled, only those whose names are present in the
`varpsi' declaration of the formal description-file are taken into account.
If its columns are not labelled, they
must be sorted according to the declaration.
- extends
-
the extends of the projection space.
A matrix of 2 columns and 2 rows:
the lower bound of x is "p1-(extends[1,1]*se1)"
where se1 is the standard error of p1,
and its upper bound is "p1+(extends[2,1]*se1)".
Similarly, the lower and upper bounds of y are
"p2-(extends[1,2]*se2)"and "p2+(extends[2,2]*se2)",
se2 being the standard error of p2.
- density
-
A matrix of 2 columns and 2 rows:
density[1,1] is the number of points x at the left side
of p1
and density[2,1] is the number of points at its right.
Similarly, density[1,2] and density[2,2] are the number of points y at the
left and at the right sides of p2.
- bounds
-
The bounds of the projection space.
When this argument exists, it replaces the argument `extends'.
A matrix of 2 columns and 2 rows:
bounds[1,1] is the lower bound of x
and bounds[2,1] is its upper bound.
Similarly, bounds[1,2] and bounds[2,2] are the lower and upper bounds
of y.
VALUE:
A list with the following components:
"x": the coordinates of the points x.
Vector of length "density[1,1]+density[2,1]"
"y": the coordinates of the points y.
Vector of length "density[1,2]+density[2,2]".
"z": the criterion values.
Matrix of dimension (length(x), length(y)):
"z[i,j]" is the value at the point (x[i],y[j]).
CONSTRAINTS:
In the input argument `nls2.object', component `as.var' should exist.
The function `loadnls2', argument `psi' not NULL,
should have been previously called.
SIDE EFFECTS:
When ellipsoids are defined for functions and
no program has been previously loaded to calculate 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.
DETAILS:
This function is a method for the generic function `ellips'
for class `nls2'.
It can be invoked by calling `ellips' for an object of the appropriate
class, or directly by calling `ellips.nls2' regardless of the
class of the object.
SEE ALSO:
EXAMPLE:
Example 1:
---------
2 functions are described by the following file,
called "modelf":
ppsi n,d,a,b,g;
psi ps1, ps2;
subroutine;
begin
ps1=-1/b*(a+b*log10(g));
ps2=n+(d-n)*exp(g*log10(g/(1+g)));
end
The S-commands are:
loadnls2(psi="")
ellips.out_ ellips(nls2.out, axis=c("ps1","ps2"),
file="modelf")
X11()
contour(ellips.out,
levels=qchisq(c(0.50, 0.90, 0.99),2),
xlab="function ps1", ylab="function ps2")
Example 2:
---------
Ellipsoids are calculated for estimated parameters:
The S-commands are:
loadnls2()
ellips.out_ ellips(nls2.out,c("a","b"))
X11()
# Plot of ellipsoids for different probabilities:
# The levels are the quantiles of a chi-square distribution
# with number of degrees of freedom equal to five, because
# five parameters have been estimated in the nls2.object.
contour(ellips.out,
levels=qchisq(c(0.50, 0.90, 0.99),5),
xlab="a", ylab="b")
- Mon Sep 30 1996 -