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))
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".
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'.
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 |
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.
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.
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:
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
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
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))
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
analDer Model.d > Model.d.c crInv Inv.d > Inv.d.c crCalib Model.dCareful: 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
Splus loadnls2(model="Model.d.o Model.d.dc.o", inv="Inv.d.o")
# 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))
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.