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.


Sommaire

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).

Sommaire

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.

Sommaire


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.


Sommaire

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:

Sommaire

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")

Sommaire


- Mon Sep 30 1996 -