welcome to nls2C Site Plan

Subroutines of nls2C

 

Available subroutines to:
estimate access results specific print global print create a file for SPlus/R
replicate data free memory cut the estimation process

See also:
how to write the calling program how to process series of non-linear regressions.


Estimation: subroutine nls2C

Syntax:
int nls2C(char *filein);
Argument:
filein is the name of an input-file containing data and options.
Return value: an integer value,
- 0: No error in the estimation process.
- a positive value: An error in the estimation process; see code in the help-file 'nls2.object' of nls2.
- a negative value: An error in your input-file.

Access the results:

Subroutines return results and input: See their syntax, list, an example of use.

You can also access intermediate results: See their syntax, list, an example of use.

Syntax of the access subroutines:
The name and syntax of the access subroutines depend on the type of the returned result, long int, character string or double, and on their structure, scalar or multidimensional.
In case of a multidimensional result, you do not have to allocate the target structure: a pointer to the internal data-structures of a nls2 is returned.

When values has not been calculated, for numerical or other reasons, they are arbitraly set to DBL_MAX, (generally 1.79E+308) a value you find in the standard C file "float.h" on your site.

In all of these subroutines:

See the help-file 'nls2.object' of nls2, as to the statistical meaning of the returned structure.

List of the access subroutines:
The access subroutines and the valid values for their first argument, *name, are:

long recup0L(char *name ,int step);
n.obst (number of observations, replications and null weights included), n.obs (number of observations, replications and null weights not included), n.curves, n.x (number of independant varaibles), n.theta, n.beta (number of parameters in the model description), is.odes (1 if the model is defined by an "odes", 0 otherwise), is.v (1 if the variance is modelised, 0 otherwise), n.steps, code, n.iters, nh, effic, max.iters.
When the model is described by an "odes":
ci.odes (1 if the initial conditions are parameters, 0 otherwise), x.odes (1 if the observations appear in the "odes" equations), n.times (number of time values, it is integration for), n.eq.odes (number of equations in the "odes"), n.theta.odes (number of parameters in the "odes"), lg.odes (length of the "odes").

double recup0D(char *name ,int step);
lambda.start, lambda.c1, lambda.c2, max.stop.crit, max.err.c2, max.err.c1, max.lambda, omega.c1, omega.c2, stat.crit, stop.crit, lambda, loglik, logfamily, norm, rss.un, rss, sigma, deviance .

char * recup1C(char *name ,int step);
file (the name of the model-description file), message (explanation about how the execution run), stat.crit.type, method, family, n.name, w.type, algo, mu.type, sigma2.type.

double * recup1D(char *name ,int step, int *n1);
y (observed values of the response), weights, theta, beta, fitted (fitted values of the response), variance (fitted values of the variance), y1, y2, s2, rep[lications], mu3, mu4, residuals, s.residuals, dev.residuals, eta, z.

double **recup2D(char *name ,int step,int *n1, int *n2);
x (values of the independant variables), as.var, d.resp, d.theta.vari, d.beta.vari, b.varz.b, correl, w, b, d.

Note: as.var and correl are returned in dimension multot x multot, multot been the total number of parameters.
b.varz.b and w are returned in dimension acttot x acttot, i.e the number of active parameters (the parameters set to a numerical constraint or equal to another one are not included).
b and d are returned in dimension number of sufficient statistics Z x acttot.

double ***recup3D(char *name ,int step, int *n1, int *n2, int *n3);
fodes, d.fodes.

Example of use of an access subroutine:

/* Declaration of the target structure: */
double statcrit;
...
        nls2C("myfile");
        statcrit=recup0D("stat.crit", 1);
	printf("\n*** stat.crit value: %g ***\n");

Access to intermediate structures

Syntax of the intermediate structures access subroutines:
The
intermediate saved structures have one dimension more: their first dimension is equal to the number of saved iterations, nitsv.

List of the intermediate structures access subroutines:
To access the intermediate structures, the subroutines are:

long int * recupIt1L(char *name, int step, int *nitsv);
iter.

double * recupIt1D(char *name, int step, int *nitsv);
lambda, omega, stop.crit, stat.crit, sigma2.

double ** recupIt2D(char *name, int step, int *nitsv, int *n1) ;
theta, beta, response, variance, eta, direc,

double *** recupIt3D(char *name, int step, int *nitsv, int *n1, int *n2);
d.resp, d.theta.vari, d.beta.vari, b, d.

double **** recupIt4D(char *name, int step, int *nitsv, int *n1, int *n2, int *n3);
fodes.

Example of use of an intermediate structures access subroutine:

/* Declaration of the target structure and subroutine argument: */
double *statcrit;
int nitsv;
...
        nls2C("myfile");
        statcrit=recupIt1D("stat.crit", 1, &nitsv);
	printf("\n*** stat.crit values ***\n");
	for (i=0; i< nitsv; i++)
	  {
	    printf(" Iteration %d: ", i);
	    printf("%10g ", statcrit[i]);
	  printf("\n");
	  }
	printf("\n");
      } 

Retour au début

Specific print:

Some subroutines are provided to print multi-dimensional results.
Syntax:
The names of the subroutines and their syntax depend on the type of structure to print, but for all of them:

List of the subroutines:

void pr1L(FILE *unit, long *vect, int nele);
void pr1D(FILE *unit, double *vect, int nele);
void pr1S(FILE *unit, short *vect, int nele);
void pr2S(FILE *unit, short **mat, int nlig, int ncol);
void pr2D(FILE *unit, double **mat, int nlig, int ncol);
void pr3D(FILE *unit, double ***mat, int nlig, int ncol, int n3);

Examples:

/* Declaration of the target structure and subroutines arguments: */
double **dresp;
int  n1, n2;

...

         dresp = recup2D("d.resp", 1, &n1, &n2);
         pr2D(stdout, dresp, n1, n2);

Retour au début

Global print:

Some subroutines print the whole of a nls2 structure.
Syntax
They have one input argument, only: a pointer to a file opened in write mode, the print unit.

List of these subroutines:

void ecrDonnees(FILE *fic);
display what is relative to the data (i.e the observations).
void ecrModele(FILE *fic);
display what is relative to the model.
void ecrCtxPuss(FILE *fic);
display what is relative to the statistical context.
void ecrCtxNum(FILE *fic);
display what is relative to the numerical contexts.
void ecrCrole(FILE *fic);
display what is relative to the control options.
void ecrCtxI(FILE *fic);
display what is relative to the integration context.

Retour au début

Create a file for SPlus/R:

Two subroutines generate files with SPlus (or R) commands.
- splus2C allows to create a structure which contains the results,
- splusData allows to create a data-frame which contains the observations.
The created structures are compatible with nls2.

Syntax:
int splus2C( char *name , char *dataname, FILE *file);
int splusData( char *name , FILE *file);

Arguments:

name
name of the nls2.object to create.
dataname
name of the SPlus (R) structure which contains the data;
file
pointer to a file opened in write or write-and-append mode: the SPlus (R) instructions creating the nls2.object will be written on it.
Then, in a Splus (R) session, type in: source("filename") where filename is the name of the file.

Example:

/* ------- Declarations  ------------ */
int code;
FILE *filesplus;

/* ------- Call  nls2C ------------ */
/* The name of the input-file is the first argument of the
   executable command */
if ( (code =nls2C(argv[1])) != 0)
  {
  fprintf(stderr,"Fatal error in nls2C, code %d \n", code);
  exit(code);
  }
/* Create a splus file for Splus */
if ( (int)(filesplus=fopen("SPLUSFILE", "w")) == NULL)
  {
    printf("Cannot open the output splus-file \n");
    return(ERRINPUT);
  }

/* ------- Call splus2C  ------------ */
if ((code= splus2C("mynls2.object" , filesplus)) != OK)
  {
    printf("Error in 'splus2C'\n");
    return(ERRINPUT);
  }
In a Splus (R) session, the command:
source("SPLUSFILE")
creates the nls2.object named mynls2.object.

Retour au début

Replicate data: subroutine rep2C

Function:
from a data-structure in dimension k (number of observations, replications not included), the subroutine rep2C returns a structure in dimension n (number of observations, replications included).
Syntaxe:
void rep2C(double * datak, double * datan);
Arguments:
- datak: pointer to the structure in dimension k (input argument).
- datan: pointer to the structure in dimension n (output argument).
Important note:
the output argument datan should be allocated before the call to rep2C.
Example:
The fitted values of the response are put in dimension n.
long int nobst;
int k;
double *fk, *fn;

... 
fk = recup1D("fitted",1, &k);
nobst= recup0L("n.obst", 1);

fn=(double *) calloc (nobst, sizeof (double));
rep2C(fk, fn);

Clean memory space: subroutine delnls2

Function:
nls2C allocates dynamically its data-structures. free the memory storage dynamically allocated by nls2C.
Syntaxe:
void delnls2();
Important note:
after a call to this subroutine, it is no more possible to access input or output.

Retour au début

Cut the estimation process

Instead of executing estimation in one "black box", you can process by steps: initialization of the nls2 structures, read input, estimate the parameters, and, eventually, clean memory.
  1. Initialization of the nls2 data-structures:
    int init2C();
    
  2. Read the input files:
    int lect2C(char *filein);
    
    filein is the pathname of the input file.

  3. Estimation:
    int go2C();
    
  4. Memory cleaning:
    void delnls2();
    

Each of the following subroutines returns 0 or an error code; A positive value means that there is an error in the estimation process (see code in the the help-file 'nls2.object' of nls2). A negative value means that there is an error in your input.

Example: The file simul.main.c.

Retour au début

 


© INRA, 2001-