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.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib