# pypdevsbbl.generic.collectors module

Set of PythonPDEVS collectors for keeping track of all data.

The classes in this file will allow for obtaining some well required statistical data from your models.

class `pypdevsbbl.generic.collectors.``BaseCollector`(name: str)

  Bases: `pypdevs.DEVS.AtomicDEVS`

  Base class for all the collectors.

  This building block itself is not useful, but mainly acts as a root from which all collectors can inherit.

  Parameters: | name (str) – The name of the Collector.

  Input Ports:

  - input (any) – Obtains values.
  - clear (any) – Clears the contents of the block.

  `clearContents`()

    Clears the contents of the block.

  `plot`(axis, arg)

    Plots the data of the collector.

    Parameters:

    - axis – The `matplotlib` axis to plot on.
    - arg – Additional argument.

class `pypdevsbbl.generic.collectors.``Collector`(name: str, positive: bool = False)

  Bases: `pypdevsbbl.generic.collectors.BaseCollector`

  Collects base information about items that arrive on input.

  The Collector block keeps track of the basic information about all items that arrive. This includes minima, maxima, means, sums, sums of squares and the amount of items that it has seen.

  Using this data, the min, max, mean, variance, standard derivation and count of the passed items can be obtained. See their respective functions below.

  Note

  In order to do this, the items must be numeric and therefore have the `__lt__`, `__gt__`, `__add__`, `__pow__` and `__div__` operators available.

  Parameters:

  - name (str) – The name for the Collector.
  - positive (bool) – When `True`, only data from strict positive values will be captured. Defaults to `False`.

  State:

  - min (numeric) – The minimal value that arrived. When no items passed through, this will be INFINITY.
  - max (numeric) – The maximal value that arrived. When no items passed through, this will be -INFINITY.
  - n (int) – The amount of items that have arrived.
  - sum (numeric) – The sum of all values that have arrived.
  - squares (numeric) – The sum of the squares of all values that have arrived.

  Input Ports:

  - input (numeric) – Obtains values. Note that INFINITY inputs will shape the data in an undefined way.
  - clear (any) – Clears the contents of the block.

  `plot`(axis, cols=1)

    Plots the data of the collector.

    Parameters:

    - axis – The `matplotlib` axis to plot on.
    - cols – How many columns to split the info into. Defaults to 1.

  `extTransition`(inputs)
  `clearContents`()
  `min`()

    Conveniance method to obtain the minimal value.

    Returns: | The minimal value that arrived.

  `max`()

    Conveniance method to obtain the maximal value.

    Returns: | The maximal value that arrived.

  `count`()

    Conveniance method to obtain the amount of items.

    Returns: | The amount of items that have arrived.

  `sum`()

    Conveniance method to obtain the sum.

    Returns: | The sum of the items that have arrived.

  `sumOfSquares`()

    Conveniance method to obtain the sum of squares.

    Returns: | The sum of squares of the items that have arrived.

  `mean`()

    Get the mean of all values that have arrived.

    It is computed as \(\mu = \dfrac{\sum_i i}{n}\), with \(i\) an item that arrived.

    Returns: | The mean or 0 if no items have arrived.

  `variance`()

    Get the variance of all values that have arrived.

    It is computed as \(\sigma^2 = \dfrac{\sum_i i^2}{n} + \mu^2 - \dfrac{2\mu\sum_i i}{n}\), with \(i\) an item that arrived.

    Returns: | The variance or 0 if no items have arrived.

  `std`()

    Get the standard derivation of all values that have arrived.

    It is computed as \(\sigma = \sqrt{v}\), with \(v\) the result from the `variance()` function.

    Returns: | The standard derivation or 0 if no items have arrived.

class `pypdevsbbl.generic.collectors.``EstimateCollector`(name: str, b: int = 4)

  Bases: `pypdevsbbl.generic.collectors.BaseCollector`

  Collects information about items that arrive.

  The EstimateCollector block is a block that keeps track of everything that passes through, allowing it to yield important information.

  Whereas the `Collector` can collect general information data, this collector will use the P-squared Algorithm for Dynamic Calculation of Quantiles and Histograms without Scoring Observations.

  It has a `CollectorState` class, which is used to handle the information of passed-through items. Besides the `PythonPDEVS`-functionality, it also has a function that can obtain all boxplot- and histogram-data, called `CollectorState.histoplot()`.

  See also

  - `pypdevsbbl.extra.mathutils.histogram()`
  - `pypdevsbbl.extra.mathutils.histostep()`

  Parameters:

  - name (str) – The name of the EstimateCollector.
  - b (int) – The amount of cells you want for the histogram. 4 is often used, because it yields [min, Q1, median, Q3, max]. When 1 or less, the histogram will only keep track of the min and the max. Defaults to 4.

  State: | See `EstimateCollector.CollectorState`.

  Input Ports:

  - input (numeric) – Obtains values. Note that `INFINITY` inputs will shape the data in an undefined way.
  - clear (any) – Clears the contents of the block.

  class `CollectorState`(b=4)

    Bases: `object`

    Helperclass for the EstimateCollector.

    Note

    This class allows for the creation of boxplots and histogram, thanks to the `pypdevsbbl.extra.mathutils` module. This makes use of the `_hq`, `_hq0`, `_hn` and `_hn0` attributes. Changing these will make it so the histogram, min, max, median, Q1 and Q3 also changes, so please… DON’T.

    For the sake of the P^2 algorithm, b (number of cells) is chosen to be 4.

    Variables:

    - N (int) – The total number of items that have arrived.
    - N0 (int) – The total number of non-zero items that have arrived.
    - _b (int) – The amount of cells in the histogram.
    - _hq (list) – Datavalues of the bars in the histogram of all items. DON’T CHANGE THIS LIST!
    - _hq0 (list) – Datavalues of the bars in the histogram of all non-zero items. DON’T CHANGE THIS LIST!
    - _hn (list) – Positions of the bars in the histogram of all items. DON’T CHANGE THIS LIST!
    - _hn0 (list) – Positions of the bars in the histogram of all non-zero items. DON’T CHANGE THIS LIST!

    Parameters: | b (int) – The amount of cells you want for the histogram. When 1 or less, the histogram will only keep track of the min and the max. Defaults to 4.

    `_hstep`(val)

      Do the histostep function of the mathutils on this state.

      Additionally, this will do some size checks to make sure histostep can be executed correctly. The general histogram will change.

      See also

      `pypdevsbbl.extra.mathutils.histogram()`

      Warning

      Only use this function if you know what you’re doing.

      Parameters: | val (numeric) – A value that passes through and must update the histogram.

    `_hstep0`(val)

      Do the histostep function of the mathutils on this state.

      Additionally, this will do some size checks to make sure histostep can be executed correctly. The non-zero histogram will change.

      See also

      `pypdevsbbl.extra.mathutils.histogram()`

      Warning

      Only use this function if you know what you’re doing.

      Parameters: | val (numeric) – A non-zero value that passes through and must update the histogram.

    `min`()

      Get the smallest value that has arrived.

      Returns: | The smallest value, or INFINITY if no values have arrived yet.

    `min0`()

      Get the smallest non-zero value that has arrived.

      Returns: | The smallest non-zero value, or INFINITY if no values have arrived yet.

    `max`()

      Get the largest value that has arrived.

      Returns: | The largest value, or -INFINITY if no values have arrived yet.

    `max0`()

      Get the largest non-zero value that has arrived.

      Returns: | The largest non-zero value, or -INFINITY if no values have arrived yet.

    `histoplot`()

      Obtain all boxplot and histogram data from the state.

      This function is meant to be used as an unpacking of all data and only reads from the state. In fact, its result is a copy of the actual data, making sure it remains immutable.

      Returns:

      A 4-tuple (q, h, q0, h0), where
        - q (list): Datavalues of the bars in the histogram of all items.
        - h (list): Heights of the bars in the histogram, w.r.t. the item count.
        - q0 (list): Datavalues of the bars in the histogram of all non-zero items.
        - h0 (list): Heights of the bars in the histogram, w.r.t. the non-zero item count.

      Examples

      - To plot the histogram of all items, use q as x-values and h as its y-values.
      - To plot the histogram of all non-zero items, use q0 as x-values and h0 as its y-values.
      - To plot the boxplot of all items, unpack q and use it as input in the mathutils.draw_boxplot function (and plot it thereafter).
      - To plot the boxplot of all non-zero items, unpack q0 and use it as input in the mathutils.draw_boxplot function (and plot it thereafter).
  `plot`(axis, type='hist')

    Plots the data of the collector.

    Parameters:

    - axis – The `matplotlib` axis to plot on.
    - type –

      A string indicating which plot to create. Defaults to ‘hist’.

      For the histogram, use any of `['hist', 'histogram', 'bars', 'H', 'h', 0]`.

      For the boxplot, use any of `['bxpt', 'boxplot', 'box', 'B', 'b', 1]`

  `plot_boxplot`(axis)

    Plots the data of the collector as a boxplot.

    Parameters: | axis – The `matplotlib` axis to plot on.

  `plot_histogram`(axis)

    Plots the data of the collector as a histogram.

    Parameters: | axis – The `matplotlib` axis to plot on.

  `extTransition`(inputs)
  `clearContents`()

class `pypdevsbbl.generic.collectors.``TableCollector`(name: str)

  Bases: `pypdevsbbl.generic.collectors.BaseCollector`

  Builds a table of all collected data.

  Contrary to the other collectors, the TableCollector will create a table from ALL data that arrived. This implies that the usage of this component will allocate a lot of memory and, if you’re using mere numerical data, will be overkill. Nevertheless, if your data is not numerical, or you require to know when certain data arrived, this collector is the one you need.

  For every item that arrives, it will add another record in a table, which is accessible as a dictionary (see the `table()` method).

  Parameters: | name (str) – The name for the TableizeCollector.
  State: | table (list) – The table, as a pair/tuple of (elapsed time, item)

  Input Ports:

  - input (any) – Obtains values.
  - clear (any) – Clears the contents of the block.

  `clearContents`()
  `extTransition`(inputs)
  `plot`(axis, kwargs=None)

    Plots the data of the collector.

    Parameters:

    - axis – The `matplotlib` axis to plot on.
    - kwargs – Dictionary of keyword arguments to pass to the `matplotlib.axes.Axes.plot()` function. Defaults to `None` (= no arguments).

  `table`()

    Fetches the table that was built upto this point in time.

    This table will be returned as a dict, in the form of
      elapsed time -> item

    Returns: | The table.

class `pypdevsbbl.generic.collectors.``Counter`(name: str)

  Bases: `pypdevsbbl.generic.collectors.BaseCollector`

  Counts the amount of arrived messages.

  Parameters: | name (str) – The name of the block.

  State:

  - item (any) – The current item.
  - count (int) – The current count.

  Input Ports:

  - input (any) – The items that need to be counted.
  - clear (any) – Clears the contents of the block.

  Output Ports:

  - output (any) – The item that was counted.
  - count (int) – How many items have been counted, including the one outputted on the output port.

  `plot`(axis, pos=(0.5, 0.5))

    Plots the counted info

    Parameters:

    - axis – The `matplotlib` axis to plot on.
    - pos – The position to plot the data. Must be in [0, 1] for both x and y to be visible. Defaults to `(0.5, 0.5)`.

  `clearContents`()
  `timeAdvance`()
  `extTransition`(inputs)
  `outputFnc`()
  `intTransition`()