\defmodule {swrite}

This module contains some functions used in writing statistical 
test results, inside the implementation of other modules.

Each testing function in the {\tt s} modules normally
writes a report (on standard output, by default) 
that contains the description of the generator being tested,
the name of the experiment, the name of the test and its parameters,
the values and significance levels of statistics,
and the CPU time used by each test.
This report may contain additional information specific to a given test.
More detailed results in the printouts can be obtained by setting 
the {\tt lebool} variables below to {\tt TRUE} before
calling the test. If all {\tt lebool} flags below are set to {\tt FALSE}, then
no output will be printed.


\bigskip\hrule
\code\hide
/* swrite.h for ANSI C */
#ifndef SWRITE_H
#define SWRITE_H
\endhide
#include "gdef.h"
#include "chrono.h"
#include "unif01.h"
#include "sres.h"
\endcode


%%%%%%%%%%%%%%%%%%%
\guisec{Environment variables}

\code

extern lebool swrite_Basic;           /* Prints basic results           */
extern lebool swrite_Parameters;      /* Prints details on parameters   */
extern lebool swrite_Collectors;      /* Prints statistical collectors  */
extern lebool swrite_Classes;         /* Prints classes for ChiSquare   */
extern lebool swrite_Counters;        /* Prints counters                */
\endcode
 \tab These environment variables (which are {\em boolean switches\/}) are used to 
  control the level of detail in the output printed by the tests. 
  By default, all are set to {\tt FALSE}, except for
  {\tt swrite\_Basic} which is set to {\tt TRUE}.
  When {\tt swrite\_Basic} is {\tt TRUE}, the test results are printed
  with a standard level of detail. 
  If it is {\tt FALSE}, then nothing from the  {\tt u} or  {\tt s}
  modules is printed.

  The other switches permit one to obtain more detailed information than 
  usual, in a selective way.  The details are printed when the 
  corresponding switch is set to {\tt TRUE}.
  This could be useful, for example, to examine more closely the kind of
  defect exhibited by a random number generator that fails a test.
  
  The switch {\tt swrite\_Parameters}  controls the printing of
  internal parameters that are specific to each test.
  The switch {\tt swrite\_Collectors} controls the printing of the 
  statistical collectors holding the $N$ values of the main statistics 
  $Y$ of the test.
  The switch {\tt swrite\_Classes} controls the printing of details 
  concerning the regroupings into classes (or categories),
  with the expected numbers of observations in each class,
  in the situations where such regrouping is performed in order 
  to apply a  chi-square test (see function  {\tt gofs\_MergeClasses}
  in module {\tt gofs} of library ProbDist).
  The switch {\tt swrite\_Counters} controls the printing of the different
  counters that hold the numbers of observations.
 \endtab
\code


extern lebool swrite_Host;
\endcode
 \tab If this variable is {\tt TRUE}, the name of the machine on which
the tests are run is printed before each test; otherwise it is not
printed.
 \endtab


\ifdetailed
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\guisec{Functions used for printouts}

\code

extern char swrite_ExperimentName[];
\endcode
 \tab This environment variable is the name of the current experiment
   (a series of tests). It is set by the procedure 
   {\tt swrite\_SetExperimentName} below.
 \endtab
\code


void swrite_SetExperimentName (char Name[]);
\endcode
 \tab Sets the name of an experiment to {\tt Name} (keeps the name in the
  global environment variable {\tt swrite\_ExperimentName}).
  This character string will be written at the beginning of the 
  report for each test.
\endtab
\code


void swrite_Head (unif01_Gen *gen, char *TestName, long N, long n, int r);
\endcode
 \tab
 Prints a header that contains the name of the current machine, 
 the name of the generator {\tt gen},
 the name of the experiment, the name of the test being applied, 
 and the values of $N$, $n$, and $r$.  Called at the beginning of each test.
\endtab
\code


void swrite_Final (unif01_Gen *gen, chrono_Chrono *Timer);
\endcode
\tab Prints the time in {\tt Timer} (total CPU time used by a test),
  and also the current state of generator {\tt gen}.
  Called at the end of each test.
\endtab
\code


void swrite_NormalSumTest (long N, sres_Basic *res);
\endcode
\tab  Writes the $s$-value and the $p$-value for the sample sum and the sample
  variance of all $N>1$ observations in the case of a {\em normal\/} distribution.
  For $N=1$, does nothing.
\endtab
\code


void swrite_AddStrChi (char S[], int len, long d);
\endcode
\tab Adds the number of degrees of freedom $d$ to string $S$,
  which has length {\tt len}.
\endtab
\code


void swrite_Chi2SumTest (long N, sres_Chi2 *res);
\endcode
\tab  Writes the $s$-value and the $p$-value for the sample sum
  of all $N>1$ observations in the case of a {\em chi-square\/} distribution.
  For $N=1$, does nothing.
\endtab
\code


void swrite_Chi2SumTestb (long N, double sval, double pval, long deg);
\endcode
\tab  Writes the $s$-value {\tt sval} and the $p$-value {\tt pval} for the 
  sample sum of all $N>1$ observations in the case of a {\em chi-square\/} 
  distribution with {\tt deg} degrees of freedom. For $N=1$, does nothing.
\endtab
\fi
\code\hide
#endif
\endhide\endcode
