Documentation Vision Library+ Documentation

Box Plot+

Box Plot+ shows how a value is distributed. It groups the values of one or more data sources by period or by source and draws one box per group: the middle half of the values as a box, the median as a line, the spread as whiskers, and outliers and the mean as markers.

Overview

Box Plot+ with one box per hour, outliers and a mean marker for a reactor temperature

Watch the demo

See Box Plot+ in a practical PI Vision workflow.

Open video in a new tab Browse the complete demo gallery

When to use it

Use this symbol when you need to:

  • See whether a value stays steady from hour to hour, shift to shift or day to day, not only where its average lies.
  • Compare the spread of several data sources side by side.
  • Find unusual values (outliers) without scrolling through a trend.
  • Mark limits on the distribution, such as an operating window.

Choose Combo Chart+ to follow the individual values over time. Choose Histogram+ to see the full shape of one distribution.

Before you begin

  • Use PI Points or AF attributes with numeric values and enough values in each period. A box needs several values.
  • Choose a display time range that holds many periods, for example 8 hours for hourly boxes.
  • Configure PI Web API for Vision Library+. The symbol loads its own history.

Add and set up the symbol

  1. Select Box Plot+ in the PI Vision symbol gallery.
  2. Drag a numeric PI Point or AF attribute onto the display, for example a reactor temperature.
  3. Right-click the symbol and select Configure Box Plot....
  4. Under Scales > Category Scale, set Interval to MANUAL.
  5. Enter 1 and select Hour as the interval.
  6. Close the pane. The symbol shows one box per hour, with whiskers from the minimum to the maximum value.
Box Plot+ with hourly boxes over eight hours

With Interval on AUTO, the symbol picks an interval that fits the display time range and the symbol width.

Common tasks

Make each box cover a shift

Use this when the periods you compare are shifts or production days, not clock hours.

  1. Set the display time range to several days, for example two days.
  2. Under Scales > Category Scale, set Group By to TIME (1).
  3. Set Interval to MANUAL (2) and enter 8 and Hour (3).
  4. In Reference Time (4), enter the start of one shift as a PI time expression, such as T+6h for 06:00 today.
Category Scale group with Group By, Interval and Reference Time marked

Boxes start at the reference time and repeat every interval, forwards and backwards. With T+6h and 8 hours, the boxes start at 6:00 AM, 2:00 PM and 10:00 PM.

Six shift boxes over two days

For production days, use 1 and Day with the reference time of the day start.

Show the outliers and the mean

Use this to see which values fall outside the normal spread and where the average lies in each box.

  1. Right-click the symbol, select Configure Box Plot... and scroll to Trace Options.
  2. Select the data source in the list.
  3. Set Whisker Type to < 1.5 IQR (1). The whiskers then stop at the last value within 1.5 times the box height, and values beyond are outliers.
  4. In the Outliers group, check that Show is ON (2). The group appears only when Whisker Type is not Min / Max.
  5. In the Mean group, set Show to ON (3) and Labels to ON (4) to print the mean.
  6. Choose a Color and Size for each marker so they stand out.
Whisker Type, Outliers and Mean settings

Outliers appear as dots beyond the whiskers. The mean appears as a marker inside the box, with its value above it.

Boxes with red outliers and orange mean markers with values

Compare several data sources

Use this when you want to see which source varies most. Add the data sources to the symbol first.

  1. Under Scales > Value Scales, set Scale Type to Multiple (1) when the sources have different units. Each source then gets its own value axis, in the color of its boxes.
  2. Under Category Scale, set Group By to DATA SOURCE (2).
Scale Type Multiple and Group By Data Source

The symbol draws one box per data source for the whole time range. The legend shows each source with its latest value and unit.

One box per data source, each on its own value axis

Keep Group By on TIME to compare the sources inside each period instead: every period then holds one box per source.

Boxes per period, one for each data source

Use Single only when all sources share one unit, so the boxes sit on the same scale. Multiple is available only with vertical bars.

Mark limits on the chart

Use this to draw an operating window or alarm limits across the boxes.

  1. Right-click the symbol and select Add Multi-State....
  2. Select the data source and check Enable Multi-State (1).
  3. Set the upper limit of each level (2). Each level has a color.
  4. Set the lowest limit (3). Values below it are bad data and use the red color.
  5. Close the pane.
Multi-state editor with three levels and a lower limit

The chart draws a dashed line at every limit, in the color of its level. Here the red line is the lower limit at 130, the white line at 135, the orange line at 140 and the green line at 155. Once multi-state is on, the menu item reads Configure Multi-State....

Boxes with four dashed limit lines

To draw a line from data instead, drag another source onto the symbol and set its Type to Line under Trace Options.

Zoom into a period

Use this to look at part of a long range, for example the boxes of one afternoon.

  1. Under Interactivity, set Enable Zoom to ON (1).
  2. Choose the start Drag mode (2): PAN moves the window, BOX ZOOM zooms into a rectangle you draw.
  3. To zoom the whole display, set Apply to Display Time to ON (3). The row appears only when the argument axis is a timeline: Type is TIMELINE, Group By is TIME and the bars are vertical.
  4. Under Toolbar, set Show Toolbar to ON.
Interactivity section with Enable Zoom, Drag mode and Apply to Display Time marked

Select Zoom In (1) twice. The chart shows the middle quarter of the boxes. Select Reset Zoom (2) to return to the full range.

Zoomed chart with the toolbar

With Apply to Display Time on, Zoom In changes the time range of the whole display. Here the range halved to 12 hours (2), and the other symbols follow it.

Timeline chart after Zoom In with the display time halved

On a timeline, a box is drawn centered on the start of its interval, so a box at the edge of the window can be cut in half.

Use the symbol

Box Plot+ with numbered callouts and a tooltip
What it shows
(1)The box. Its lower edge is the first quartile (Q1) and its upper edge the third quartile (Q3), so it holds the middle half of the values.
(2)The median line: half of the values are lower, half are higher.
(3)The whiskers, which reach as far as Whisker Type says.
(4)An outlier: a value beyond the whiskers.
(5)The mean marker, when Mean is on. A mean far from the median means a skewed distribution.
(6)The toolbar: Pan, Box zoom, Zoom In, Zoom Out, Reset Zoom, Fullscreen and Download.

Interactions

  • Hover a box to see the period, the data source and its minimum, Q1, median, Q3 and maximum.
  • Zoom with the mouse wheel or Zoom In and Zoom Out. Drag to pan, or to zoom into a rectangle in Box zoom mode. Switch the mode from the toolbar. The chart returns to the Drag mode setting when the display is opened again.
  • Zoom Out doubles the visible window up to the loaded range. With Apply to Display Time on it widens the display time range instead. Reset Zoom returns to the full window and restores the display time range the chart left.
  • Fullscreen opens the chart in a large dialog. Download offers PNG, SVG, PDF, CSV, JSON and XLSX. The data formats are hidden when data export is disabled for the installation.
  • Toolbar visibility follows Reveal: with On Hover it fades in when the pointer is over the chart, with Always it stays visible. A touch device always shows it.
  • The zoom window stays while the data refreshes. It resets when the display time range changes or the time bar moves.
  • The shared Time Bar is available on this symbol.

No action in the chart writes data to the PI System.

Configure the symbol

The pane has these sections: Trend Options, Scales, Data Retrieval, Time Bar, Interactivity, Trace Options, Numbers and Export Data.

Trend Options

SettingWhat it does
TitleShows a title and a subtitle, with text, alignment and size.
StyleTheme, surface, container style, Foreground, Background, Border, Font Size. Sparkline hides the axes and borders for a minimal chart.
LegendEnabled, Position, Placement (outside or inside the plot), Alignment, the Text (name, value or both), Value placement, Size and Color (marker or text).
TooltipShow turns the hover panel on. Pointer is NONE, ARGUMENT (a line at the box) or CROSS (also a line at the value). Not offered for raw scatter traces.
Data LabelsChart-wide label switch, Value, Background and Font Size. Each trace chooses its own labels under Trace Options.
GridShow, Lines (None, Horizontal, Vertical, Both, named by direction on screen), Bands (shaded bands along the value axis) and Border (AXES, FRAME or NONE).
ToolbarShow Toolbar and Reveal (On Hover or Always). Always keeps a band of the plot free for the strip. See Zoom into a period.
BarsOrientation (HORIZONTAL or VERTICAL) and box Width in percent. Horizontal bars put the periods on the vertical axis, and TIMELINE and Multiple are not available.

Scales

SettingWhat it does
Value Scales: Label PositionDraws the value labels inside or outside the plot.
Scale TypeSingle, Multiple or Custom. Multiple gives each data source its own axis. Custom lets you define axes and assign sources to them. Align Ticks lines up the ticks of several axes. See Compare several data sources.
Single scale settingsShow, Position, Invert Scale, Transform (LINEAR or LOGARITHMIC), Scale Range (AUTO, DATABASE or CUSTOM with Minimum and Maximum), Title, Ticks (AUTO or CUSTOM) and Units. With Multiple, each source has the same settings under Trace Options > Axis Y.
Group ByTIME makes one box per period for each source. DATA SOURCE makes one box per source for the whole range.
Interval, Reference TimeAUTO or MANUAL period length. Reference Time anchors the grid and is available with MANUAL. See Make each box cover a shift.
TypeTIMELINE places boxes on a real time axis. DISCRETE places one label per box. TIMELINE is available with vertical bars and Group By TIME.
Category axis: Show, Position, Invert Scale, Title, Datetime FormatControl the argument axis. Datetime Format sets the label text.
Fit Data, FormatAvailable on a timeline. Fit Data fits the axis to the data and ignores the time range. Format is Timestamps, Relative or Offset from Start Time.

Data Retrieval

SettingWhat it does
ModeAuto loads a reduced set of values that is enough to draw the chart. Recorded loads every archived value. Summary loads a PI summary per Interval, so each box shows the distribution of those summaries. Interpolated loads one interpolated value per Interval.
Interval, Sync TimeSample spacing of Summary and Interpolated. Sync Time fixes the clock time the samples align to. This is not the box period.
Type, Basis, Conversion factorAvailable with Summary. Choose the calculation (for example Average) and Time Weighted or Event Weighted.
Start- and EndtimesDisplay time range, Custom time range or Duration and offset.

The symbol reads at most 30,000 values per request, shared among the data sources.

Time Bar and Interactivity

SettingWhat it does
Time BarAdds the shared Time Bar. Its interval choice is available with Summary and Interpolated.
Enable ZoomTurns on zoom, the drag modes and the zoom buttons. Off by default.
Drag modePAN or BOX ZOOM.
Apply to Display TimeZoom changes the display time range. Available on a timeline.
Show ScrollbarAdds a slider under the plot to drag the visible window. Available when Enable Zoom is on.

Trace Options

Select a data source in the list, then set its options.

SettingWhat it does
TypeBox Plot, Line, Area, Scatter or Scatter (raw data). Raw scatter draws every value as a semi-transparent dot, with Apply Jitter to spread overlapping dots.
AggregationFor Line, Area and Scatter: Average, Minimum or Maximum of the values in each period.
Median TypeINCLUSIVE keeps the overall median in both halves when Q1 and Q3 are calculated. EXCLUSIVE removes it from both.
Whisker TypeMin / Max reaches the lowest and highest value. < 1.5 IQR reaches the furthest values within 1.5 times the box height of Q1 and Q3. = 1.5 IQR fixes the whiskers at exactly that distance. Standard Deviation reaches a Threshold of 1 to 3 standard deviations around the mean. Custom takes a Lower Percentile and an Upper Percentile.
Color, LabelThe trace color and its legend name.
OutliersShow, Color, Size and shape. Available when Whisker Type is not Min / Max. A value is an outlier when it lies beyond the whiskers. See Show the outliers and the mean.
MeanShow, Color, Labels, Size and shape.
Data LabelsShow prints one statistic on each box. Value chooses Maximum, Q3, Median, Q1 or Minimum.
StrokeWidth and Dash of the box outline. The color is also offered for other trace types.
Axis YPer-source axis settings. Available with Multiple or Custom.
Add Multi-State...Opens the limit editor. See Mark limits on the chart.

Numbers and Export Data

SettingWhat it does
NumbersThe number format of labels and the tooltip.
Export DataFile Format (CSV, JSON, XLSX or PDF) and Download. The section is hidden when data export is disabled for the installation.

Troubleshooting and limitations

SymptomCauseWhat to do
A box is missing or flat.The period holds few or no values, or the values barely vary.Use a longer Interval, a longer time range, or Recorded mode.
The boxes are too narrow to read.Interval is AUTO over a long range, or the interval is short.Set Interval to MANUAL with a longer period.
No outliers are drawn.Whisker Type is Min / Max, which reaches every value.Choose another Whisker Type.
Apply to Display Time is missing.The argument axis is not a timeline.Set Type to TIMELINE with vertical bars and Group By TIME.
Multiple is missing.The bars are horizontal.Switch Orientation to VERTICAL.
The first box on a timeline is cut off.A timeline centers each box on the start of its interval.Use DISCRETE, or start the range before the first interval.
Loading is slow.A long range, a short interval or many sources.Shorten the range, use Summary mode, or remove sources.
  • Limitation: The symbol reads at most 30,000 values per request, shared among its data sources.
  • Limitation: Limit lines from multi-state are drawn at the latest limit value only.