# Data collector functions

Statistics are calculated for each of the Data collector monitors. These statistics can be accessed via predefined functions for each data collector monitor. In the following, we assume that a data collector monitor with the ML name `DC` has been created.

The following functions can be used for data collector monitors that calculate either untimed or timed statistics. See Calculating statistics for more information about untimed and timed statistics.

`DC.count()`
returns the number times values have been added to the monitor
`DC.min()`
returns the minimum of the observed values
`DC.max()`
returns the maximum of the observed values
`DC.sum()`
returns the sum of the observed values
`DC.avrg()`
returns the average of the observed values
`DC.vari()`
returns the variance of the observed values
`DC.std()`
returns the standard deviation of the observed values
`DC.ss()`
returns the sum of the squares of the observed values
`DC.ssd()`
returns the sum of the squares of deviation of the observed values
`DC.ci(i)`
returns a record containing the `i%` confidence interval average of the observed values. `i` must be 90,95, or 99.
`DC.first()`
returns the value that was observed first
`DC.last()`
returns the most recently observed value
`DC.get_stat_strings()`
returns the ML name of the monitor together with a record with all of the statistics for the monitor as strings

The following functions are also available for data collector monitors that calculate timed statistics

`DC.starttime()`
returns the model time at which the first value was observed
`DC.lasttime()`
returns the model time at which the most recent value was observed
`DC.interval()`
returns the amount of model time that has elapsed since the monitor was first updated

## Return types

The type of the value that is returned by the functions above often depends on the type of the values returned by the observation function for the monitor.

Note that when an observation function returns integer values, the values are converted to infinite integers, i.e. `IntInf.int`, in order to avoid `Overflow` exceptions. This means that several of the functions mentioned above, such as `DC.min` and `DC.sum`, will return values of type `IntInf.int` rather than values of type `int`.

This table provides an overview of the types of the values returned by the functions above. The first row of the table indicates the type of the values returned by the observation function of the monitor.

real int or IntInf.int
`DC.avrg` real real
`DC.count` int int
`DC.first` real IntInf.int
`DC.last` real IntInf.int
`DC.max` real IntInf.int
`DC.min` real IntInf.int
`DC.ss` real IntInf.int
`DC.ssd` real real
`DC.std` real real
`DC.sum` real IntInf.int
`DC.vari` real real
`DC.ci` {avrg : real, {avrg : real,
half_length : real option, half_length : real option,
lower_endpoint : real option, lower_endpoint : real option,
percentage : int, percentage : int,
upper_endpoint : real option} upper_endpoint : real option}

## Examples of use

Suppose a Count Transition Occurrences Monitor has been defined for the Simple protocol example net.

The `count` function this data collector could be used in a predicate function for generic breakpoint monitor to stop a simulation when the `Receive_Packet` transition has occurred 5 times.

```fun pred (bindelem) =
let
fun predBindElem (Top'Receive_Packet (1, {k,n,p,str})) =
| predBindElem _ = false
in
predBindElem bindelem
end
```

The following can be used to access the 95% confidence interval for the `Queue_Delay` monitor for the example net of the Queue system example.

`Queue_Delay.ci(95)`

Here are examples of the kind of values that are returned by the `ci` function:

```  {avrg=55.5,half_length=SOME 705.183,lower_endpoint=SOME 760.683,
percentage=95,upper_endpoint=SOME ~649.683}

{avrg=0.0,half_length=NONE,lower_endpoint=NONE,percentage=95,
upper_endpoint=NONE}
```