|
|
|
|
||
|
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.
|
||
|
|
|