\defmodule {fres}

This module defines common structures used to keep the results of tests
in the {\tt f} modules when the statistics of the test obey a
simple distribution. Some tests require more specialized structures for
the results and those are defined in the appropriate {\tt f} modules.

The argument {\tt res} of each testing function is a structure 
 that can keep the tables of $p$-values and other results.
This is useful if one wishes to do something else with the tables of
results after the tests are ended. In that case, one 
{\it must} call the appropriate {\tt Create} function to create the
 {\tt res} structure. Simply declaring a variable  {\tt
res} and passing its address as the argument will not work.
That structure must also be deleted when no longer needed. If one does not
want to post-process or use the tables of results after a {\tt f} test,
it suffices to set the {\tt res} argument of the testing function
to the {\tt NULL} pointer.
Then, the structure is created and deleted automatically inside the 
testing function. In any case, the tables of results will be printed on 
standard output.

\bigskip
\hrule
\code
\hide
/* fres.h for ANSI C */
#ifndef FRES_H
#define FRES_H
\endhide
#include "gofw.h"
#include "ftab.h"
#include "ffam.h"
#include "bitset.h"
\endcode



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\guisec{Common structure for test results (continuous distribution)}

The tables of $p$-values for tests in the {\tt f} modules, based on simple
continuous distributions can be recovered in the structure defined below.
Tests which produces many tables of different results use more complicated
structures and are defined in the appropriate {\tt f} module.

\code


typedef struct {
   ftab_Table *PVal [gofw_NTestTypes];
   bitset_BitSet Active;
   char *name;
} fres_Cont;
\endcode
 \tab
  The tables in this structure contain the $p$-values resulting from
  the tests applied to a whole family of generators.
  When the number of replications $N$ is equal to 1, the $p$-values
  are returned in {\tt PVal2[gofw\_Mean]}. When $N > 1$, the relevant
  $p$-values are returned in {\tt PVal [$j$]}, where  $j$ is a member
  of the set {\tt Active}. The active statistics are usually those
  in {\tt gofw\_ActiveTests} (see module {\tt gofw} in library
  ProbDist). Using the non-active {\tt PVal [$j$]} is illegal and will
  give unpredictable results. The variable 
 {\tt name} gives the name of the test which produced the above results.
 \endtab
\code


fres_Cont *fres_CreateCont (void);
\endcode
 \tab 
  Creates and returns a structure that will hold the tables of $p$-values
  above. 
 \endtab
\code


void fres_DeleteCont (fres_Cont *res);
\endcode
 \tab 
  Frees the memory allocated to {\tt res} by {\tt fres\_CreateCont}.
 \endtab
\code
\hide

void fres_InitCont (ffam_Fam *fam, fres_Cont *res, int N,
                    int Nr, int j1, int j2, int jstep, char *nam);
\endcode
 \tab 
   Initializes the {\tt res} structure, ensures that it can keep results
   for the first {\tt Nr} generators of family {\tt fam}, with sample sizes
   varying from {\tt j1} to {\tt j2} by step of {\tt jstep} for a given
   generator, and sets its {\tt name} field to {\tt nam}.  {\tt N}
   is the number of replications of the base test. This function
   must not be called directly by the user. It has been made public because
   it is called internally by the tests in the {\tt f} modules.
 \endtab
\code
\endhide

void fres_PrintCont (fres_Cont *res);
\endcode
 \tab Prints the tables in {\tt res}.
 \endtab
\code


void fres_FillTableEntryC (fres_Cont *res, gofw_TestArray pval, int N,
                           int irow, int icol);
\endcode
 \tab This function fills the entry in row {\tt irow} and column {\tt icol}
  of the active tables in {\tt res} with the values in {\tt pval}. {\tt N}
  is the number of replications of the base test.
 \endtab




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\guisec{Common structure for test results (discrete distribution)}

The tables of $p$-values for tests in the {\tt f} modules, based on simple
discrete distributions can be recovered in the structure defined below.
Tests which produces many tables of different results use more complicated
structures and are defined in the appropriate {\tt f} module.

\code

typedef struct {
   ftab_Table *PLeft;
   ftab_Table *PRight;
   ftab_Table *PVal2;
   char *name;
} fres_Disc;
\endcode
 \tab
  The tables in this structure contain the left $p$-values,
  the right $p$-values, and the resulting
  $p$-values (as computed in function {\tt gofw\_pDisc} of library
   ProbDist) for a statistic taking discrete values. The variable 
  {\tt name} gives the name of the test which produced the above results.
 \endtab
\code


fres_Disc * fres_CreateDisc (void);
\endcode
 \tab 
  Creates and returns a structure that will hold the results
  of a simple test based on a discrete distribution. 
 \endtab
\code


void fres_DeleteDisc (fres_Disc *res);
\endcode
 \tab 
  Frees the memory allocated to {\tt res} by {\tt fres\_CreateDisc}.
 \endtab
\code
\hide

void fres_InitDisc (ffam_Fam *fam, fres_Disc *res,
                    int Nr, int j1, int j2, int jstep, char *nam);
\endcode
 \tab 
   Initializes the {\tt res} structure, ensures that it can keep results
   for the first {\tt Nr} generators of family {\tt fam}, with sample sizes
   varying from {\tt j1} to {\tt j2} by step of {\tt jstep} for a given
   generator, and sets its {\tt name} field to {\tt nam}. This function
   must not be called directly by the user. It has been made public because
   it is called internally by the tests in the {\tt f} modules.
 \endtab
\code
\endhide

void fres_PrintDisc (fres_Disc *res, lebool LR);
\endcode
 \tab Prints the tables in {\tt res}. If {\tt LR} is {\tt TRUE}, prints the
   tables {\tt PLeft} and {\tt PRight}; otherwise, 
   prints only the {\tt PVal2} table.
 \endtab
\code


void fres_FillTableEntryD (fres_Disc *res, double pLeft, double pRight,
                           double pVal2, int irow, int icol);
\endcode
 \tab This function fills the entry in row {\tt irow} and column {\tt icol}
  of the tables in {\tt res} with the values  {\tt pLeft}, {\tt pRight}
  and {\tt pVal2}.
 \endtab




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\guisec{Structure for Poisson test results}

The tables of $p$-values for tests in the {\tt f} modules based on a
Poisson distribution can be recovered in the structure defined below.

\code

typedef struct {
   ftab_Table *Exp;
   ftab_Table *Obs;
   ftab_Table *PLeft;
   ftab_Table *PRight;
   ftab_Table *PVal2;
   char *name;
} fres_Poisson;
\endcode
 \tab
  The tables in this structure contain the expected numbers, the observed
  numbers, the left $p$-values, the right $p$-values, and the resulting
  $p$-values (as computed in function {\tt gofw\_pDisc} of library
   ProbDist) for a statistic obeying the Poisson law. The variable 
  {\tt name} gives the name of the test which produced the above results.
 \endtab
\code


fres_Poisson * fres_CreatePoisson (void);
\endcode
 \tab 
  Creates and returns a structure that will hold the results
  of a test based on the Poisson distribution. 
 \endtab
\code


void fres_DeletePoisson (fres_Poisson *res);
\endcode
 \tab 
  Frees the memory allocated to {\tt res} by {\tt fres\_CreatePoisson}.
 \endtab
\code
\hide

void fres_InitPoisson (ffam_Fam *fam, fres_Poisson *res,
                       int Nr, int j1, int j2, int jstep, char *nam);
\endcode
 \tab 
   Initializes the {\tt res} structure, ensures that it can keep results
   for the first {\tt Nr} generators of family {\tt fam}, with sample sizes
   varying from {\tt j1} to {\tt j2} by step of {\tt jstep} for a given
   generator, and sets its {\tt name} field to {\tt nam}. This function
   must not be called directly by the user. It has been made public because
   it is called internally by the tests in the {\tt f} modules.
 \endtab
\code
\endhide

void fres_PrintPoisson (fres_Poisson *res, lebool LR, lebool Ratio);
\endcode
 \tab Prints the tables in {\tt res}. If {\tt LR} is {\tt TRUE}, prints the
   tables {\tt PLeft} and {\tt PRight}; otherwise does not print them.
   If {\tt Ratio} is {\tt TRUE}, prints the observed numbers in {\tt Obs} as
   a ratio over the corresponding numbers in  {\tt Exp}, otherwise prints
   them as themselves.
 \endtab
\code


void fres_FillTableEntryPoisson (fres_Poisson *res, double Exp, double Obs, 
                                 double pLeft, double pRight, double pVal2,
                                 int irow, int icol);
\endcode
 \tab This function fills the entry in row {\tt irow} and column {\tt icol}
  of the tables in {\tt res} with the expected number {\tt Exp},
  the observed number {\tt Obs}, the left $p$-value {\tt pLeft}, 
  the right $p$-value {\tt pRight}, and the resulting
  $p$-value {\tt pVal2}.
 \endtab

\code
\hide
#endif
\endhide
\endcode
