Skip to content

Category: Experiment

simulation run outcomes and results

syOutcome

Collects data during simulation and at the end provides raw values and statistics about specific cell in the model.

Syntax

syOutcome(SimulationCell, TimeNow, [View], [ResultsCell], [TableDescriptions], [ResultsTableTitle], [OutcomeTitle], [Realization])

The syOutcome function syntax has the following arguments:

  • SimulationCell: required. Reference to a cell that should be observed during simulation.
  • TimeNow: required. Reference to a cell with syClock().
  • View: optional. Type of report: 1 - table of raw data for each timestep in each realization, 2 - table of percentiles for each timestep, 3 - line chart and table of raw data for each timestep in each realization, 4 - line chart and table of percentiles for each timestep, 5 - descriptive statistics of final values (last timestep), 6 - histogram and descriptive statistics of final values (last timestep), 1 if ommited.
  • ResultsCell: optional. Reference to upper-left cell of results table, a cell just below the syOutcome formula if ommited.
  • TableDescriptions: optional. Row and column descriptions of results table: 0 - without, 1 - row descriptions, 2 - column destriptions, 3 - both, 0 if ommited.
  • ResultsTableTitle: optional. Title for results table.
  • OutcomeTitle: optional. Title for cell with syOutcome formula, SimulationCell address or name in double braces if ommited.
  • Realization: optional. Realization for which the results should be collected and presented if View is 1 or 3. Data for all realizations are shown if 0 or ommited.

Return value is the cell address or name of the observed cell in double braces, e.g. {{A1}} or {{PeopleWaiting}}.

Remarks

syOutcome element observes SimulationCell from the beginning to the end of simulation time for all the realizations. It saves the value of obvserved cell for each timestep in each realization. Depending from View argument, it writes the results as raw values, percentiles by each timestep, or descriptive statistics in a range of cells. The results are written statically as values (similar to "paste as values") so that you can analyse them without worrying that they will change if the model gets recalculated (for instance because of random number generators).

View argument defines the type of output. By default the values are given as a table where rows represent sequential timesteps and columns are model realizations. If you choose percentiles, these are calculated by each timestep. Output gives 0.0, 0.2, 0.4, 0.5 (mode), 0.6, 0.8 and 1.0 percentile. To get percentiles, you have to run more than one realization so that the sample is representative. If you choose descriptives, these are calculated for the final value of the observed cell (at the end of simulation time), and average, standard deviation, median, mode, minimum, maximum, kurtosis and skewness are displayed.

All of the above Viev options also have a chart counterpart - raw values and percentiles can be accompanied by line chart, and histogram is prepared together with descriptives. Charts are positioned near the upper-left cell of the results table.

If you set the ResultsCell, the outcome table is presented in this cell (the cell becomes the upper-left corner of the output table). The ResultsCell can point to another spreadsheet or even to another opened workbook. In this case, the chart is preserved during simulation runs for you convenience, so that a comparisson between different simulation runs is easy.

TableDescriptions controls the display of table headers - besides the result values, the sequential numbers of timesteps and realizations can be displayed as row and column descriptions. With percentiles, their designations are denoted as column names. Values of descriptive statistics are given in one column which can be accompanied by explanations when you set TableDescriptions to non-zero value.

ResultsTableTitle sets the title of the results table which is displayed in the upper leftmost cell above the table.

If OutcomeTitle is not set, the syOutcome formula displays mustached SimulationCell address or range name, for instance as {{A3}} or {{PopulationSize}}, otherwise it displays outcome title as set by this argument.

If syOutcome displays raw values (View = 1 or View = 3), Realization can limit the output to just one realization, as set by this argument.

If the simulation is run again, Spry asks you if you are sure to overwrite the results from the previous run, including charts. If you would like to preserve results, you can copy and paste the values to a different location, or you can change the ResultsCell argument to some other cell. However, if you change the simulation parameters (e.g. the number of realizations, timesteps) or syOutcome arguments, the information about the dimension of the former results table gets lost and it is advisable to manually Clear the results before changing these parameters.

syOutcome preserves the format of the observed cell - the format of SimulationCell is applied in results table.

NOTE: When the observed SimulationCell returns error value (like #N/A), syOutcome presents this by empty cell as a value for the problematic timestep and realization. If this is a case, percentiles and descriptives are not calculated properly, which is also presented by zero values for these outcomes.

Examples

  • =syOutcome(A2,A1) - The simplest possible results table which gives the raw values of the cell A2. The number of rows in the table equals the number of all timesteps, and the number of columns is the number of realizations. If simulation is static (time is frozen, when TimeStart equals TimeEnd in syClock()), there is only one row of data.
  • =syOutcome(A2,A1,6,Sheet2!A1) - Descriptives table with the names of statistics is prepared as a table on Sheet2 in the same workbook as our model resides. Histogram of final values is also presented.