loadnls2 - Load Programs for function nls2


On to:
DESCRIPTION
USAGE
OPTIONAL-ARGUMENTS
VALUE
DETAILS
SIDE-EFFECTS
HOW TO GENERATE PROGRAMS
REFERENCES
SEE-ALSO
EXAMPLE





DESCRIPTION:
Load the programs required for function `nls2' or associated functions.

This function should be called before each different model study.


USAGE:
loadnls2(model="", psi=NULL, inv=NULL, lang="C", 
         libs=NULL, out=NULL, 
         tomyown="")

OPTIONAL ARGUMENTS:
model
- an empty string, if the model should be evaluated by syntax trees,
- the pathname of the file that contains the source or compiled programs, if the model should be evaluated by programs, (names separated by spaces if several files).
Suffixes .c, .f and .o are recognized,
- NULL, if no model need to be evaluated.
psi
same as the argument "model", regarding functions of parameters.
inv
same as the argument "model", regarding the inverse of a regression function.
lang
the programming language of the preceeding programs, if any: "C" if C language, and "F", if Fortran.
libs
same as the argument "model", regarding libraries and include-files used by the preceeding programs. character string.
Example: "-I/home/me/include -ltoto -L/home/me/toto"
out
the pathname of the library to be created, when model is evaluated by programmes.
A loadable library is created in the current directory which includes the compiled version of the programmes.
By default, the name of this library is the concatenation of 'libs', the name of the first file in the argument-list (without prefix and suffix) and a suffix.
Example: loadnls2("exmodel.c ex2.f") creates libexmodel.so.
You are adviced to unload the library using the dyn.unload function of R, once you have finished to study the model.
Example: dyn.unload("libexmodel.so")
tomyown
for advanced users.
The pathname of the file which contains the programs calculating the estimating equations (see the example nls2.ownmethod).

Sommaire


VALUE:

The name of what is loaded is returned, although it is not printed. (use 'print.default' to see it).
The users on Splus should invoke 'dyn.close' of the returned value before any subsequent call to 'loadnls2'.


DETAILS:

When the model is evaluated by programs, the library out is created, either by invoking the link-editor (Splus-version) or by invoking the R CMD SHLIB command (R-version).
This command needs a file called Makevars specifying the possible libs libraries. The Makevars file is created in a temporary directory in /tmp and deleted on exit of the function.

Sommaire




SIDE EFFECTS:

All the necessary programs are loaded.
When the model is evaluated by programmes, a file named out is created: do not invoke several loadnls2 with the same out value simultaneously.

Sommaire




HOW TO GENERATE PROGRAMS:

From the files that describe formally models or functions, C-programs can be automatically generated by using operating-system commands.

- analDer modelfile-name > outfile-name.c
to generate programs that evaluate an nls2 model,

- crPsi modelfile-name > outfile-name.c
to generate programs that evaluate functions of parameters,

- crInv modelfile-name > outfile-name.c
to generate programs that evaluate the inverse of a regression function.

- crCalib modelfile-name
to generate programs required by function `calib.nls2'.

Careful: analDer and crInv generate the programs on the standard output, --- here redirected respectively to the files outfile-name.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 modelfile-name.d.dc.c


REFERENCES:

`nls2 Reference Manual'.

Sommaire




SEE ALSO:

`nls2.model', `nls2.psi', `nls2.inv', `calib.nls2'.


EXAMPLE: An nls2 model is described in a file called "mymodel". Functions of parameters are described in a file called "myfunc".

Example 1: the model is evaluated by syntax trees. An S-session is opened with commands of the following pattern:

        loadnls2()
        nls2(data, model="mymodel", ...)

Example 2: the model is evaluated by programs.
1- The source of the programs is generated by:

        analDer mymodel > mymodel.c
2- Then, an S-session is opened with commands of the following pattern:
        loadnls2("mymodel.c")
        nls2(data, model="mymodel", ...)
A file libmymodel.so is created.
You can re-load it by dyn.load("libmymodel.so") and delete it when the model is not to be evaluated again.

Sommaire

Example 3: the model and functions of parameters are studied successively. Both are evaluated by syntax trees. An S-session is opened with commands of the following pattern:

        loadnls2(model="", psi="")
        # study of the model:
        r_nls2(data, model="mymodel", ...)
        # study of the functions:
        confidence(r, file="myfunc")

Example 4: only the functions of parameters are studied. They are evaluated by programs.
1- The source of the programs is generated by:

        crPsi myfunc
2- An S-session is opened with commands of the following pattern:
        loadnls2(model=NULL,psi="myfunc.c")
# No mind if the argument "model" is forgotten here,
# but fixing it to NULL prevents from extra loading
        # study of the functions:
        confidence(nls2.object, file="myfunc")

Sommaire

Example 5: the model is evaluated by a Fortran program. The file "mymodel" contains a Declaration Part only and a file named "myprog.f" is supposed to contain the required Fortran programs.
1- An S-session is opened with commands of the following pattern:

        loadnls2("myprog.f",lang="F")
        nls2(data, model="mymodel", ...)

Sommaire


Creation: 09/12/2001 -