ETHZ_Logo RAMSES_Logo_Right   RAMSES   RAMSES_Logo_Left Systems Ecology  
Start    search button      Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

DEFINITION MODULE StochStat;

  (*******************************************************************

    Module  StochStat     (Version 1.1)

      Copyright (c) 1990-2006 by Thomas Nemecek, Andreas Fischlin and
      ETH Zurich.

    Purpose   Statistical analysis and visualization of results
              from stochastic simulation runs.

    Remarks   Calculates means, standard deviation and confidence
              intervals of n  arrays with m observations of a
              monitorable variable and allows to display the
              means and the confidence intervals in the graph
              window, using the module SimGraphUtils.


    Programming

      o Design
        Thomas Nemecek            19/04/1990

      o Implementation
        Thomas Nemecek            24/04/1990
        Andreas Fischlin          10/05/1996


    ETH Zurich
    Systems Ecology
    CHN E 35.1
    Universitaetstrasse 16
    8092 Zurich
    SWITZERLAND

    URLs:
        <mailto:RAMSES@env.ethz.ch>
        <http://www.sysecol.ethz.ch>
        <http://www.sysecol.ethz.ch/SimSoftware/RAMSES>


    Last revision of definition:  05/06/2002  AF

  *******************************************************************)


  (*
    FROM StochStat IMPORT
      StatArray, StatArrayExists, Prob2Tail, Str31,
      notExistingStatArray, DeclStatArray, RemoveStatArray,
      RemoveAllStatArrays, ClearStatArray, ClearAllStatArrays,
      SetStatArray, SetUndefValue, GetUndefValue, SetTolerance,
      GetTolerance, PutValue, GetValue, GetSingleStatistics,
      GetStatistics, DeclDispMV, DisplayArray, DisplayAllArrays,
      RealFileFormat, n, dec, FileOutFormat, indepsFormat,
      meansFormat, sumsYFormat, sumsYSquareFormat,
      stdDevsYFormat, confIntsYFormat, confProb, meansOnly,
      meansSDCI, allVals, DumpStatArray, DumpStatArrays;
  *)

  FROM SYSTEM           IMPORT BYTE;
  FROM DMFiles          IMPORT TextFile;
  FROM DMConversions    IMPORT RealFormat;
  FROM SimBase          IMPORT Model;


  TYPE
    StatArray;
    Prob2Tail = (prob999, prob990, prob950, prob900, prob800);
      (* 2-tailed probablility for confidence intervals the values mean
         promilles. *)
    Str31 = ARRAY [0..31] OF CHAR;

  VAR
    notExistingStatArray:       StatArray; (* read only *)


  (**************************************)
  (*#####   StatArray management   #####*)
  (**************************************)

  PROCEDURE StatArrayExists(statArray: StatArray): BOOLEAN;

  PROCEDURE DeclStatArray(VAR statArray: StatArray; length: INTEGER);
    (* declares an array of data with n=length observation per run.
       Implicitly calls ClearStatArray! *)

  PROCEDURE RemoveStatArray(VAR statArray: StatArray);

  PROCEDURE RemoveAllStatArrays;

  PROCEDURE ClearStatArray(statArray: StatArray);
    (* fills all columns of the array of data with 0.0,
       except the column with the independent variables, which
       is initialized to the undefined value.
       Resets the array to the initial state. *)

  PROCEDURE ClearAllStatArrays;

  PROCEDURE SetStatArray(statArray: StatArray;
                         VAR N, X, sumY, sumYSquare: ARRAY OF REAL);
    (* an initial state of the statArray can be set (var parameters
       only for speed-up reasons).  Can be used e.g.  to continue an
       experiment, which had to be aborted.
       CAUTION: If any of the values are not known, set undefVal
                for the independent, and 0 for all N, sumY and
                sumYSquare! *)



  (******************************)
  (*#####   Data storage   #####*)
  (******************************)

  PROCEDURE SetUndefValue(    undefVal: REAL);
    (* has only an effect, if no array are currently delrared
       for reasons of consistency*)
  PROCEDURE GetUndefValue(VAR undefVal: REAL);
    (* undefVal is assigned to any statistical value, which can not
       be calculated, because the number of observations is not sufficient,
       e.g. means if n=0, of stDevs is n=1.
       This value is also used to display values in the graph,
       that could not be calculated, e.g. mean if the number
       of observations is 0. You should use an undefVal,
       that does not occur in your data
       The default undefVal is -1.0E30; *)


  PROCEDURE SetTolerance(    tol: REAL);
  PROCEDURE GetTolerance(VAR tol: REAL);
    (* tol is the maximal tolerance in which values of the
       independent varible are accepted. The value of the independent
       variable has to lie within the interval [x-tol,x+tol], where x is
       the first value given as independent.
       The default tolerance is 10E-4 *)

  PROCEDURE PutValue(statArray: StatArray; index: INTEGER; x, y: REAL);
    (* adds a value y to the stat array *)

  PROCEDURE GetValue(statArray: StatArray; index: INTEGER;
    VAR count, x, sumY, sumYSquare: REAL);

  (****************************)
  (*#####   Statistics   #####*)
  (****************************)

  PROCEDURE GetSingleStatistics(statArray: StatArray; index: INTEGER;
    VAR count, x, sumY, sumYSquare, meansY, stdDevsY, confIntsY: REAL;
    confProb: Prob2Tail);
    (* gives statistical values describing a single observation point.
       count = number of observations at any observation point
       x = independent variable
       stdDevsY = standard deviation
       confIntsY  =  half confidence interval for confProb
       of any observation point in the array. The true mean lies within the
       interval [mean-confIntervalY, mean+confIntervalY] with
       a probability confProb.

       The statistics are given as follows for any observation point:
         if N = 0 ==>   at any observation point, sumY, sumYSquare = 0,
                        all other statistical values are = undefVal
         if N = 1 ==>   the mean,sumY & sumYSquare are the single value resp. its
                        square and all other values are = undefVal
         if N ≥ 2 ==>   all values are calculated
         *)


  PROCEDURE GetStatistics(statArray: StatArray;
    VAR N, X, sumY, sumYSquare, meansY, stdDevsY, confIntsY: ARRAY OF REAL;
    confProb: Prob2Tail; VAR length: INTEGER);

    (* gives statistical values describing the data.
       N = number of observations at any observation point
       X = independet variable

       For further explanations see text of PROC GetSingleStatistics
         *)


  (***********************************)
  (*#####   Graphical display   #####*)
  (***********************************)

  PROCEDURE DeclDispMV(statArray: StatArray;
                       mDepVar: Model;   VAR mvDepVar: REAL;
                       mIndepVar: Model; VAR mvIndepVar: REAL);
    (* Each data array to be displayed in the graph window must be associated
       with a dependent and and independent variable, which should both be declared
       as MVs in the client model. If time should be the independent variable,
       then SimGraphUtils.timeIsIndep can be given as parameter.
       See SimGraphUtils.DEF for description of the monitoring mechanism. *)

  PROCEDURE DisplayArray(statArray:     StatArray;
                         withErrBars:   BOOLEAN;
                         confProb:      Prob2Tail);
    (* The data are displayed in the graph if the following conditions are met:
         1. the associated MV must be set as isY
         2. the associated indepVar must be set as isX, respectively if the
            simulation time is chosen, none of the MVs must be set as isX.

       error bars with probability confProb are displayed, if withErrBars=TRUE
       and all observation points have an N ≥ 2.
       If no values have been stored at any observation point, these values are
       displayed as undefVal. Make sure that undefVal lies outside your
       scaling range. *)

  PROCEDURE DisplayAllArrays(withErrBars:   BOOLEAN;
                             confProb:      Prob2Tail);
    (* The data of all array are displayed. You can select the variables you
       want to display as isY.  *)

  (*****************************)
  (*#####   File output   #####*)
  (*****************************)

  (*  supports the file output of StatArray data together with labels,
      written on the top of the data and the independent variable values,
      written in the leftmost column. The data are written from the
      current position of the file f, which should be open.  *)
  TYPE
    RealFileFormat = RECORD
                        rf:         RealFormat;
                        n, dec:     CARDINAL;
                     END;
    FileOutFormat = RECORD
                      means, counts, sumsY, sumsYSquare,
                      stdDevsY, confIntsY:
                        BOOLEAN;
                      indepsFormat,meansFormat, sumsYFormat, sumsYSquareFormat,
                      stdDevsYFormat, confIntsYFormat:
                        RealFileFormat;
                      confProb:      Prob2Tail;
                    END;
 (* The labels are written with the following suffixes:
      mean                 -ø
      count                -N'
      sum Y                -ΣY
      standard deviation   -stdev
      condifence intervals -CIL resp. -CIH for low and high limit *)

    VAR (*  read only!  *)
      meansOnly,
        (* writes only means *)
      meansSDCI,
        (* writes means, standard deviations and confidnce intervals *)
      allVals:              FileOutFormat;
        (* writes all stored and calculated values *)
        (*  default RealFormat:
            rf  = ScientificNotation;
            n   = 10
            dec = 5
            default confProb = prob950*)

  PROCEDURE DumpStatArray (VAR f:           TextFile;
                               label:       Str31;
                               statArray:   StatArray;
                               fof:         FileOutFormat);
  PROCEDURE DumpStatArrays(VAR f:           TextFile;
                               labels:      ARRAY OF Str31;
  (* IF VERSION_STONYBROOK *) (*.
                               statArrays:  ARRAY OF BYTE; (* StatArray *)
  .*) (* ENDIF VERSION_STONYBROOK *)
  (* IF VERSION_MacMETH *)
                               statArrays:  ARRAY OF StatArray;
  (* ENDIF VERSION_MacMETH *)

  (* IF VERSION_EPC *) (*.
                               statArrays:  ARRAY OF StatArray;
  .*) (* ENDIF VERSION_EPC *)

  (* IF VERSION_P1 *) (*.
                               statArrays:  ARRAY OF StatArray;
  .*) (* ENDIF VERSION_P1 *)
                               fof:         FileOutFormat;
                               nArs:        INTEGER);
 (* The independent values of the first StatArray are written in the
    leftmost column. In case the arrays have not the same length, the
    length of the first array determines the number of values written.
    A character "N" is written in the positions where data are missing.
    Only the first nArs statArrays are dumped to the file. *)


END StochStat.

  Contact RAMSES@env.ethz.ch Last updated: 25-Jul-2011 [Top of page]