calib.nls2 - Calibration of a Model Estimated by nls2


On to:
DESCRIPTION
USAGE
REQUIRED-ARGUMENTS
OPTIONAL-ARGUMENTS
VALUE
MORE ABOUT THE OUTPUT
HINTS
COMPUTATIONAL-CONSTRAINTS
STATISTICAL-CONSTRAINTS
SIDE-EFFECTS
DETAILS
NOTE
SEE-ALSO
REFERENCES
EXAMPLE-1 - Constant Variance
EXAMPLE-2 - Non-constant Variance and Expression Part in the model description
EXAMPLE-3 - Non-constant Variance and no model description



DESCRIPTION:

Calculates calibration confidence sets for the abscissa of a regression function studied by `nls2'.

The regression function, "f" is defined by:
y=f(x, theta)+epsilon
where y is the response, x the independent variable denoted by abscissa, theta the regression parameters and epsilon the errors.
Two confidence sets are calculated from values of the parameters previously estimated on a "standard" set of observations. The first one, denoted by S, is an interval. The second one, denoted by R, may not be an interval. Both consider that the asymptotic framework is a convenient one.


USAGE:
calib.nls2(nls2.object, file, ord,
                conf.level=0.95, 
                conf.bounds=c(qnorm((1-conf.level)/2, 0,1), 
                              qnorm((1+conf.level)/2, 0,1)),
                x.bounds=c(NA,NA), 
                check.points=20, 
                R.grid=20, 
	        R.max.size=20,
	        R.nsplit=0,
	        R.nx=(R.grid+1)**(R.nsplit+1))

Sommaire

REQUIRED ARGUMENTS:

nls2.object
object of class `nls2' that contains the values of the parameters estimated on the standard set of observations.
file
character string equal to the pathname of the operating-system file that contains the description of the inverse "f-1" of the regression function "f". (see the paragraph `COMPUTATIONAL-CONSTRAINTS', item 2).
ord
observed values of the response that correspond to the unknown value to be estimated. There may be replications, so ord may be a vector of length >=1.

Sommaire


OPTIONAL ARGUMENTS:

conf.level
confidence level restricted to lie between zero and one.
conf.bounds
vector of quantiles: conf.bounds[1] is the lower quantile, conf.bounds[2] is the upper one.
When this argument exists, it replaces the argument `conf.level'.
The default value are the normal 95quantiles.
x.bounds
bounds of the interval where x is restricted to lie: x.bounds[1] is the lower bound, x.bounds[2] is the upper bound.
The default settings are the values of the independent variable of the standard set of observations that correspond to the responses that are the nearest to the value of the argument `ord'.
NA value is accepted with the meaning: default value on the corresponding end.
check.points
number of regularly spaced points where "f" is calculated to verify its monotony (see the paragraph `STATISTICAL-CONSTRAINTS', item 1). If equal to zero, no verification.
R.grid
minimum number of regularly spaced points where the statistic "R" is calculated in the x.bounds interval. If equal to zero, "R" is not calculated.
R.max.size
maximum number of points returned in the R confidence set when it is not an interval. If more points are found, the "R.max.size-1" first points are returned and the last one.
R.nsplit
maximum number of times the grid of points is split when calculating "R" if a break is encountered (see the paragraph `DETAILS').
R.nx
maximum number of values returned in R.x and R.values (see the paragraph `VALUE').

Sommaire

VALUE:

An object of class "calibnls2", i.e a list with at most the following components:
- "x": least squares estimator of the abscissa.
- "S.conf.int": bounds of the S confidence interval.
- "S.message": comments about the S confidence interval.
- "R.conf.int": bounds of the R confidence interval. If it is not an interval, "R.conf.set" is returned instead. It may include NA values when R calculation does not run properly.
- "R.message": comments about the R confidence set of points.

In addition, the output contains:
- "ord, conf.bounds, x.bounds": actual values of the input arguments.
- "call": copy of the call.
- and, if required, "R.x" and "R.values": values of the abscissa and corresponding values of "R" that have been calculated to determine "R.conf.int" or "R.conf.set".


Sommaire

MORE ABOUT THE OUTPUT:

- The S interval is calculated only if the variance is constant.
- The R confidence set is calculated only if the variance is constant or the estimation method a maximum likelihood method.
- The "print" command prints only the most currently useful results. Use the command "names" to get the names of all the components and the command "print.default" to print them.


HINTS:

In case of errors:
- try to restrict the research interval by using the argument `x.bounds'.
- modify the statistical context by modifying `nls2.object', component `stat.ctx'.


Sommaire

COMPUTATIONAL-CONSTRAINTS:


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


2) "f" and "f-1" should be described in operating-system files:
"f" in a file whose name is given in the `nls2.object', component `model', and "f-1" in a file whose name is the value of the argument `file' (see the help-file `nls2.inv' to build it).


3)
- If the variance is constant or the R confidence set is not required, the function `loadnls2' should have been previously called with arguments "model" and "inv" set to non NULL values. Affect to them an empty string for an evaluation of the models by syntaxical trees and the name of files for evaluation by compiled programs.
- If the R confidence set is required and the variance is not constant, the function `loadnls2' must have been previously invoked as explained in the paragraph `EXAMPLE-2'.

  Variance constant Variance non constant
R model="", inv="" see example 2
No R model="", inv="" not possible



Sommaire

STATISTICAL-CONSTRAINTS:


1) "f" should be a continuous strictly monotone and univariate function.


2) "f" should not be defined by an ordinary differential equations system.


3) The variance of the observation whose abscissa is to be estimated and the variance of the "standard" set of observations are assumed to be identically defined.


4) The data must not include curves.


SIDE EFFECTS:

- When the argument `conf.bounds' is not provided, the side-effects of "qnorm()".
- If "f" or "f-1" are evaluated by syntax trees (see `loadnls2'), operating-system files are created. They contain the C-source programs that correspond to the formal descriptions. If these files already exist, they are replaced.


Sommaire

DETAILS:

Details about the argument `R.nsplit':
R.conf.set may not be an interval, so R is calculated on a grid of points regularly spaced in x.bounds.
By giving a positive value to R.nsplit, it is possible to make a more accurate determination of R.conf.set:
For each successive points x[i], x[i+1] of the grid, such as x[i] has been put into R.conf.set and not x[i+1] (or vice-versa), R is calculated again on a grid of R.grid points regularly spaced in the interval (x[i], x[i+1]). This new griding is repeated recursively R.nsplit times in each sub-interval.


Sommaire

NOTE:

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


SEE ALSO:

REFERENCES:

"Calibration with a nonlinear standard curve: how to do it.?", Gruet, M.A and Jolivet, E., Computational Statistics, Härdle, Berlin ,Germany, 1994.


Sommaire

EXAMPLE-1 - Constant Variance:

The description-file of the model, "Model.cst.d", is the following:

resp f; 
varind x; 
parresp n,d,a,b,g; 
pbisresp minf,pinf; 
subroutine;
begin 
f= if x <= minf then d else 
      if x >= pinf then n else 
      n+(d-n)*exp(-g*log(1+exp(a+b*x)))
    fi fi; 
end 


The description-file of the inverse of the regression function, "Inv.d", is the following:
abs x;
ord f;
paract n,d,a,b,g;
pbisabs minf,pinf;
subroutine;
begin
x = if f >= d then minf else
  if f <= n then pinf else
    (log(exp(log((f-n)/(d-n))/(-g)) -1)-a)/b
    fi fi;
end


The commands of the S-session are: ("f" and "f-1" are both evaluated by syntax trees)
  loadnls2(model="",inv="")
  model.cst <- list(file="Model.cst.d",
		gamf=c(-5,5), vari.type="CST") 
  nls2.out.cst  <- nls2(data, model.cst, stat.ctx) 
  calib.cst.out <- calib(nls2.out.cst,
                  file="Inv.d",
                  ord =c(1500,1600))

Sommaire

EXAMPLE-2 - Non-constant Variance and Expression Part in the model description:

The description-file of the model, "Model.d", is the following:

resp f; 
var v;
varind x; 
parresp n,d,a,b,g; 
pbisresp minf,pinf; 
pbisvar h;
subroutine;
begin 
f= if x <= minf then d else 
      if x >= pinf then n else 
      n+(d-n)*exp(-g*log(1+exp(a+b*x)))
    fi fi; 
v=exp(h*log(f));
end 


The description-file of the inverse of the regression function is the same file "Inv.d" as in the previous example.

The models cannot be evaluated by syntax trees. Therefore, we:
  1. - generate the programs by using the operating-system commands "analDer", "crInv" and "crCalib" (see `loadnls2', paragraph `REMARKS').
    analDer Model.d > Model.d.c
    crInv Inv.d     > Inv.d.c
    crCalib Model.d 
    
    Careful: analDer and crInv generate the programs on the standard output, --- here redirected respectively to the files Model.d.c and Inv.d.c ---, while crCalib generates the programs in a file, the name of which is the name of its argument, with the suffix dc.c. For example, here Model.d.dc.c

  2. - load them into the S-session by using the function `loadnls2':
    Splus
    loadnls2(model="Model.d.o Model.d.dc.o",  inv="Inv.d.o")
    
  3. - Now, we can study calibration by Splus:
    # nls2.object creation:
      model <- list(file="Model.d",	gamf=c(-5,5), gamv=2.3)
      nls2.out  <- nls2(data, model, stat.ctx) 
    # Invocation of nls2:
      calib.out <- calib(nls2.out, file="Inv.d",
                      ord =c(1500,1600))
    

Sommaire

EXAMPLE-3 - Non-constant Variance and no model description:

When the description-file of the model does not contain an Expression Part, the commands "analDer" and "crCalib" cannot be used to generate the C-programs. You have to write them by yourself. To write the programs that calculate the regression model, see the help `nls2.mymodel'. As to the programs that calculate the calibration model, write them in a very similar way. Their names are "calcfx_" and "calcvx_" (or "mycalcfx" and "mycalcvx" if Fortran programs). "calcfx_" is like the program "calcf_" that calculates the regression function and "calcvx_" is like the program "calcv_" that calculates the variance function except that the argument that contains the explicative variables and the argument that contains the parameters are inverted. The outputs containing the derivatives are the only arguments taken into account.
If the argument `file' does not contain an Expression Part either, the command "crInv" cannot be used to generate the C-programs that calculate the inverse of the regression function. You have to write them by yourself according with the instructions you will find in the help-file `nls2.myinv'.
To study the calibration model, see the paragraph `EXAMPLE-2' above.

Sommaire


Creation: 09/12/2001 -