# LGF_Boxplot_DInt (FB / V3.0.1)

Author: Siemens Digital Industry

## Short description

If you want to get an overview of existing data, you can use a Boxplot diagram. A Boxplot shows you in which area the data is located and how it is distributed over this area. A Boxplot consists of the following parameters:

- Minimum (smallest occurring value of the sample)
- Lower or first quartile (below this value are 25% of the sample values)
- Median or second quartile (below this value are 50% of the sample values)
- Upper or third quartile (below this value are 75% of the sample values)
- Maximum (largest occurring value of the sample)

Figure: Boxplot

###### WinCC-Control

To visualize the Boxplot, the Siemens Industry Online Support offers you a Net-Control, which you can use in conjunction with WinCC Runtime Professional. You can find the controls in the `UserFiles` folder of this library.

Figure: .Net Control "Boxplot"

### Block Interface

| LGF_Boxplot_DInt (FB) |
--- | --- | ---
Bool |  |  | execute |  | error |  |  | Bool
LReal |  |  | rangeOutlier |  | status |  |  | Word
|  |  |  |  | subfunctionStatus |  |  | Word
|  |  |  |  | outlierMax |  |  | LReal
|  |  |  |  | max |  |  | DInt
|  |  |  |  | q75 |  |  | LReal
|  |  |  |  | median |  |  | LReal
|  |  |  |  | q25 |  |  | LReal
|  |  |  |  | min |  |  | DInt
|  |  |  |  | outlierMin |  |  | LReal
|  |  |  |  | skewness |  |  | LReal
Array[*] of DInt |  |  | values |  |  | Array[*] of DInt

### Input parameter

Identifier | Data type | Default value | Description
--- | --- | --- | ---
execute | Bool | FALSE | Activation of the calculation with each positive edge.
rangeOutlier | LReal | 1.5 | Outlier detection: * 0: Outlier detection is deactivated * 0-1: Invalid value * >1: Outlier detection is activated.

### Output parameter

Identifier | Data type | Description
--- | --- | ---
error | Bool | FALSE: No error TRUE: An error occurred during the execution of the FB
status | Word | 16#0000-16#7FFF: Status of the FB 16#8000-16#FFFF: Error identification (see following Table)
subfunctionStatus | Word | Status or return value of called FB's, FC's and system blocks
outlierMax | LReal | Upper outliers in %.
max | DInt | Maximum Value, not an outlier.
q75 | LReal | 3rd quartile or Q75 of the data series.
median | LReal | 2nd quartile or Median of the data series.
q25 | LReal | 1st quartile or Q25 of the data series.
min | DInt | Minimum Value, not an outlier.
outlierMin | LReal | Lower outliers in %.
skewness | LReal | Skewness of the data series.

### In/Out parameter

Identifier | Data type | Description
--- | --- | ---
values | Array[*] of DInt | The array containing the data series that is to be used for the calculation

### Status & Error codes

Code / Value | Identifier / Description
--- | ---
16#0000 | STATUS_EXECUTION_FINISHED Status: Execution finished without errors
16#7000 | STATUS_NO_CALL Status: No call of FB. The block waits for activation through the parameter `enable`.
16#7001 | STATUS_FIRST_CALL Status: First call of FB after enabling
16#8200 | ERR_NEG_ARR_BOUND Error: Negative array boundary not allowed. Check the array at the input `values`.
16#8600 | ERR_SHELL_SORT Error: Error in command `LGF_ShellSort_DInt`. Check `subFunctionStatus` code
16#9101 | ERR_RANGE_NOT_OK Error: The parameter `rangeOutlier` type is invalid. Enter a valid `rangeOutlier` value for the parameter: * 0: Outlier detection is deactivated * >1 Valid value.

## Functional description

The block sorts the data series and then calculates the so-called “five-point summary”:

Table: Five-point summary

Characteristic value of the five-point summary | Output parameter of the block
--- | ---
Minimum (smallest occurring value of the sample) | `min`
Lower or first quartile (below this value are 25% of the sample values) | `q25`
Median or second quartile (below this value are 50% of the sample values) | `median`
Upper or third quartile (below this value are 75% of the sample values) | `q75`
Maximum (largest occurring value of the sample) | `max`

If outlier detection is activated, the block first calculates the limits. From these limit values, the values are recognized as outliers:

Bound^{upper} = q_{75} + rangeOutlier \cdot (q_{75} - q_{25})

Bound_{lower} = q_{25} - rangeOutlier \cdot (q_{75} - q_{25})

The block then calculates new values for the parameters `max` and `min`, which lie within the outlier limits. The outliers are counted and output as a percentage.

To make it easier to judge how the data is distributed, the block also calculates the skew. The skewness lies between the values `-1` and `1` with the following meaning:

- `-1`: extremely left skewed distribution
- `0`: symmetrical distribution
- `1`: extreme right-skew distribution

The elements of the passed array are sorted in ascending order by the block. The `LGF_Shellsort_DInt` block is used for sorting.

The parameters are calculated as follows:

Table: Boxplot formulas Parameters Formula

Parameters | Formula
--- | ---
q25 (1st quartile) | q_{25} = x_{(k)} \qquad with \qquad k = \frac{\left[ \frac{1}{2} (n+1) \right] + 1}{2} = \frac{n + 3}{4}
q50 (2nd quartile) median | q_{50} = x_{(\frac{n+1}{2})}
q75 (3rd quartile) | q_{75} = x_{(n+1-k)} \qquad with \qquad (n + 1 - k) = \frac{3n+1}{4} n := number of samples (size of array) If the result of the element to be determined (from which the quartiles can be derived) is not an integer, the quartile is calculated from the linear fraction between the two adjacent samples.
skewness | skewness= \frac{(q_{75} + q_{25}) - 2 \cdot q_{50}}{q_{75} - q_{25}} Note: This is just an approximation.

## Change log

Version & Date | Change description
--- | ---
| 01.00.00 | Siemens Industry Online Support
| 23.11.2018 | First released version
| 01.00.01 | Simatic Systems Support
| 05.11.2019 | Code reworked, regions, comments and constants are added
| 03.00.00 | Simatic Systems Support
| 23.04.2020 | Set version to V3.0.0, harmonize the version of the whole library
| 03.00.01 | Simatic Systems Support
| 06.04.2021 | Insert documentation