This widget loads metric data for a period of time and displays points through lines, columns, or step charts.

Time Series Chart

Data Retrieval and Aggregation

You can specify the aggregation function to be used on all loaded metrics, you can select among RAW (means no aggregation), MIN, MAX, AVG, or DELTA. Optionally you can redefine on each metric a different aggregation. If unspecified on both levels, the default one is AVG.

MIN

Returns the minimum value computed in each time frame. If within the timeframe there are no values stored in the database, also the minimum is null.

MAX

Returns the maximum value computed in each time frame. If within the timeframe there are no values stored in the database, also the maximum is null.

AVG

Returns the average value computed in each time frame. If within the timeframe there are no values stored in the database, also the average is null.

DELTA

Returns the value variation computed in each time frame, considering the last value of the time frame and the last value of the previous time frame. If within the timeframe there are no values stored in the database, the resulting DELTA is zero.

By using the DELTA aggregation you can display the variation of metric in each time frame, for instance, the following chart loads twice the same metric (es. Energy), one using the DELTA aggregation and one using the MAX aggregation. So the first sub-chart displays the daily consumption, instead the second one displays the total consumption.

Aggregation Timeframes

Other than the aggregation function, there is also the timeframe defining the time aggregation unit (e.g. 1 Hour, 12 Hours, 1 Day, 1 Month).

For each aggregation function, you can use one of the following timeframes:

AUTO
MINUTES_5
MINUTES_10
MINUTES_30
HOURS_1
HOURS_6
HOURS_12
DAYS_1
MONTHS_1
YEARS_1

The default applied timeframe is AUTO, which means the widget requests data from the backend with aggregation based on a dynamic time frame (e.g., 1H, 6H, 12H, 1D...) depending on the requested period.
According to the timeframe, the requested period is divided into a maximum of 100 intervals and the aggregated value is calculated for each of them.
If there are more than 100 intervals, the timeframe is automatically increased until the result interval count is less or equals than 100.
For instance if you request a month of data aggregated by HOURS_1, the result will be resampled to HOURS_12, this means you will get 60 values for 30 days.

Grouping and Zooming

Once the data has been loaded, to keep browser performance smooth, the widget displays a maximum of 500 graphic points per series at a time; in case there are more points within the loaded period, the widget downsamples them, and if more detail is desired, the graph can be zoomed in. If the loaded period contains too many data points, summing all the metrics (max 40.000 points), the period is automatically truncated and a warning is shown to the user. Generally, this happens if you ask for RAW data over a long period. For instance, suppose to have two metrics, you can load, for each of them, up to 20.000 data points, but the chart will display a maximum of 500 graphic points at the time, where each graphic point corresponds, more or less, to 20.000/500 = 40 grouped data points.

On each metric, you can also specify the Value Grouping function (SUM, MAX, AVG) to be used to group data points when zooming out the chart. For instance, when zooming out you can display the SUM per month of the underlying daily values, instead of the average or maximum. For instance, for a temperature metric, in some cases, the maximum may be better than the average.

If you reduce the scroll bar or select an area of the graph, more data points may appear, and this depends on the limit of 500 graphic points displayed at a time. In this case, two icons appear on the right, the first allows you to reset the zoom level, while the second button reloads the data from the backend, focusing on the selected time window with the finest possible time aggregation (in the case of AUTO timeframe).

For example, suppose you have a temperature metric with a sample every 10 minutes and you want to load 12 months of data (6 * 24 * 365 = 52560 data points). By default, the widget will load the average temperature with an aggregation time interval of 12 hours (730 data points), so you can zoom in on March, for example, and by clicking on the Expand Selection button (the second one), you can reload the data for March only, which will be aggregated with a time interval of 1 hour, and in this case, you will only have 730 points to display.

Optionally you can enable the Timeframe and Aggregation selectors to change the aggregation and reload the data preserving the selected period.

The aggregation selected through the Aggregation selector affects only the metrics without an explicitly configured aggregation. For instance, a metric may always use AVG_DAYS_1.

Axis Management

For each metric, you can define the Y-axis title and whether to use the LEFT or RIGHT one.

For example, you can have a left and a right Y-axis with different scales.

Alternatively, you can select the Stacked Charts option; this will cause the widget to display one sub-chart for each metric. Metrics with the same Y-axis title are grouped together on the same sub-chart.

Chart Types

Each metric can be displayed with a different chart type, by choosing among:

Line: data points are directly interconnected through a line.
Column: for each data point a column is displayed.
Step: compared to the Line, which connects data points with direct lines creating an appearance of gradual change in data points, it sharply visualizes the changes between data points through steps.

Multiple Things Charting

The Time Series Chart can be placed also within the Location or Custom details, and display the metric of the location or of the underlying things, by displaying one series per thing.

On each metric, you can also specify whether the series must be stacked in order to see the totals among multiple metrics. For instance, suppose to have a metric providing the number of pieces produced every hour, you can stack the columns as follow.

The alternative to displaying the same metric for each thing, you can also choose the Collapsed rendering, which will show a single chart, whose values are given by the Value Grouping function (SUM, MAX, AVG) applied to the values between multiple things with the same timestamp.

Constant Lines

A constant line is a line marker that extends over the chart at a fixed Y value, giving the user information about which is, for instance, the minimum/maximum or median value.

Metric Min / Max

Yuo can display the minum and maximum value of a metric by enabling the Show Min Value Line or the Show Max Value Line options on a single metric element.

Chart Line

Alternatively, if you need to display a constant line on the graph independently of metrics, you can add a Chart Line element and configure whether the value should be read from a property accessible from the context of the thing or whether it is a static value.

You can also specify the label to be displayed on the line and the color.

Events

Along the data points of displayed metrics, you can show also the events occurred in the same time period.

In the Events section of the property panel, you can define a query on the events to be loaded (e.g. Event Severity = FAILURE).

For each found event, a marker is displayed under the x-axis, and by clicking on the marker, a tooltip displays the event details and the chart area corresponding to the event duration is highlighted according to the event severity.

Template Syntax

Below you can find some examples of how to use the component within a template.

Example 1

Time-series-chart displaying three metrics grouped into different sub-charts (Temperatures and Power).


<time-series-chart-widget class="flex-fill"
	                      [config]="{exportEnabled: true, filterEnabled: true, scrollbarEnabled: true, aggregationType: 'AVG', defaultPeriod: 'LAST_7_DAYS', legendPosition: 'center', stacked: true}">
	       
       <metric name="Temperature" filter="singleDecimalFormat" [chartOptions]="{yAxisTitle: 'Temperatures'}"></metric> 
       <metric name="TempSetpoint" [chartOptions]="{yAxisTitle: 'Temperatures'}"></metric> 
       <metric name="Power" filter="integerFormat" [chartOptions]="{yAxisTitle: 'Power', yAxisPosition: 'STACKED'}"></metric>
	       
</time-series-chart-widget>

Example 2

Time-series-chart into a location dashboard that displays a temperature chart for each underlying thing having such a metric.


<time-series-chart-widget class="flex-fill"
		                      [config]="{exportEnabled: true, filterEnabled: true, scrollbarEnabled: true, aggregationType: 'AVG', defaultPeriod: 'LAST_7_DAYS', legendPosition: 'center'}">
	
     <metric name="thing.Temperature" filter="singleDecimalFormat"></metric>
	         
</time-series-chart-widget>

Component Reference

Here is a comprehensive list of all the elements and properties that can be used to configure the component.

Time Series Chart <time-series-chart-widget>
PROPERTIES
Aggregation Selector Enabled	If enabled, the user can select the aggregation function between RAW, MIN, MAX, AVG (default), and DELTA. Type: BOOLEAN \| Optional \| Values: true false [config]="{aggregationsEnabled: true}"
Collapse / Expand	The flag indicating whether the widget is collaspible. Type: BOOLEAN \| Optional \| Values: true false [collapsible]="true"
CSS Class	The name(s) of the CSS class used to customize the widget layout. Type: STRING \| Optional class="my-custom-class"
Default Aggregation	The default aggregation used to all metrics. Type: ENUM \| Optional \| Values: RAW AVG DELTA MIN MAX [config]="{aggregationType: 'AVG'}"
Default Loading Period	The default date and time filtering period applied when entering the page. Type: ENUM \| Optional \| Values: TODAY YESTERDAY LAST_1_HOUR LAST_6_HOURS LAST_12_HOURS LAST_24_HOURS LAST_7_DAYS LAST_30_DAYS THIS_MONTH LAST_MONTH LAST_6_MONTHS LAST_12_MONTHS THIS_WEEK LAST_WEEK LAST_FULL_7_DAYS LAST_FULL_30_DAYS LAST_FULL_12_MONTHS [config]="{defaultPeriod: 'LAST_7_DAYS'}"
Enabled Periods	The list of periods which can be selected from the embedded period filter. Type: ENUM_ARRAY \| Optional \| Values: TODAY YESTERDAY LAST_1_HOUR LAST_6_HOURS LAST_12_HOURS LAST_24_HOURS LAST_7_DAYS LAST_30_DAYS THIS_MONTH LAST_MONTH LAST_6_MONTHS LAST_12_MONTHS THIS_WEEK LAST_WEEK LAST_FULL_7_DAYS LAST_FULL_30_DAYS LAST_FULL_12_MONTHS CUSTOM [config]="{enabledPeriods: ['V1', 'V2', 'VN']}"
Export Enabled	The boolean flag indicating whether the data export is enabled. Type: BOOLEAN \| Optional \| Values: true false [config]="{exportEnabled: true}"
Grid Background Color	The color used as grid background, default white. Type: STRING \| Optional [config]="{bgColor: 'fooBar'}"
Height	The height of the widget (e.g. 250px). Type: STRING \| Optional [config]="{height: '250px'}"
Label Provider	The filter providing labels for the chart metrics. Type: FILTER \| Optional [config]="{labelProvider: 'FILTER'}"
Legend Marker	The marker displayed for each element in the legend. CIRCLE: displays a colored circle. SQUARE: displays a colored square. Type: ENUM \| Optional \| Values: CIRCLE SQUARE [config]="{legendMarker: 'SQUARE'}"
Legend Position	The position of the legend in the chart. Type: ENUM \| Optional \| Values: none left center right [config]="{legendPosition: 'right'}"
Max Displayed Data Points	Indicates the maximum number of data points to be displayed for the selected date range, after which the widget starts grouping data points by using the Value Grouping function specified on the metric. Type: INTEGER \| Optional \| Default: 500 [config]="{groupCount: 123}"
Max Loaded Data Points	The maximum number of data points the widget can load among all metrics; use -1 to have unlimited data points. Be careful that this may affect browser performance. Type: INTEGER \| Optional \| Default: 40000 [config]="{maxDatapointCount: 123}"
Period Filter Enabled	The boolean flag indicating whether the embedded period filter is available. Type: BOOLEAN \| Optional \| Values: true false [config]="{filterEnabled: true}"
Period Variable	The id of the page's variable providing the date range filtering period, for instance the id of a <period-filter-field>. Type: STRING \| Optional [inputs]="{period: 'period'}"
Events Query	The array of conditions filtering out items. For instance: [config]="{eventQuery:[{'property': 'connectionStatus', 'predicate': 'eq', 'value': '1'}]” Predicates: eq, neq, beginsWith, like, notLike, isEmpty, isNotEmpty, gt, gte, lt, lte. Type: QUERY \| Optional
Query Variable	The id of the page's <things-filter-field> used for searching. Type: STRING \| Optional [inputs]="{query: 'query-1'}"
Scrollbar Enabled	The flag enabling the widget top scrolbar allowing the user to scroll and zoom data. Type: BOOLEAN \| Optional \| Values: true false [config]="{scrollbarEnabled: true}"
Show events	Flag indicating whether to enable events on charts. Type: BOOLEAN \| Optional \| Values: true false [config]="{showEventsOnChart: false}"
Stacked Charts	The flag enabling stacked charts grouping metrics having the same Y-Axis Title. Type: BOOLEAN \| Optional \| Values: true false [config]="{stacked: true}"
The file type to export.	The type of the file to generate when exporting data. Type: ENUM \| Optional \| Values: csv xlsx [config]="{exportFileType: 'xlsx'}"
Timeframe Selector Enabled	If enabled, the user can select the aggregation timeframe between 1 HOUR, 1 DAY, 1 MONTH. If not enabled, the timeframe is automatic according to the selected period. Type: BOOLEAN \| Optional \| Values: true false [config]="{timeframesEnabled: true}"
Title	The title displayed on the top part of the widget box. Type: STRING \| Optional [title]="'Details'"
Tooltip Date Format	String indicating the date format of the tooltip that appears when moving over the chart. Type: STRING \| Optional [config]="{tooltipDateFormat: 'yyyy-MM-dd'}"
Tooltip Enabled	Flag indicating whether to enable the tooltip that appears when moving over the chart. Type: BOOLEAN \| Optional \| Values: true false [config]="{tooltipEnabled: false}"
Y-Axis Trimmed	Flag indicating whether the Y-axis should be trimmed according to the minimum and maximum value of the loaded data. Type: BOOLEAN \| Optional \| Values: true false [config]="{yAxisTrimmed: true}"
End Date Variable	The <period-field>'s End Variable filtering data by end date. Type: STRING \| Optional [inputs]="{endDate: 'toDate'}" [DEPRECATED] Use the Period Variable property.
Start Date Variable	The <period-field>'s Start Variable filtering data by start date. Type: STRING \| Optional [inputs]="{startDate: 'fromDate'}" [DEPRECATED] Use the Period Variable property instead.
SUB-ELEMENTS
Metric	The metric whose values must be displayed within the chart. Multiple \| Required <metric name="Temperature"></metric>
Chart Line	The constant dashed line displayed on the graph data. Multiple \| Optional <property label='Max Temp' name='thingDefinition.properties.maxTemp'></property>

Metric <metric>
PROPERTIES
Bullet Size	The bullet size in pixels. Type: INTEGER \| Optional \| Default: 2 [chartOptions]="{bulletSize: 123}"
Bullet Type	Define the type of the bullets displayes along the line. Type: ENUM \| Optional \| Values: none circle square diamond up down [chartOptions]="{bulletType: 'square'}"
Chart Type	Defines how to display the metric values, wheter to use columns, lines or step lines. Type: ENUM \| Optional \| Values: line column step [chartOptions]="{chartType: 'column'}"
Color	The color used to render the chart for this metric. Type: STRING \| Optional [chartOptions]="{color: 'fooBar'}"
Column Width Percentage	The percentage of horizontal space occupied by each bar in case of column chart type. Type: INTEGER \| Optional \| Default: 90 [chartOptions]="{columnWidth: 50}"
Dashing	The line dashing style (e.g. '5' or '5,3'). Type: STRING \| Optional [chartOptions]="{dashing: '5,5'}"
Fill Opacity	The opacity (0 to 1) used to fill the chart area below the line or inside the columns. Type: INTEGER \| Optional [chartOptions]="{fillOpacity: 123}"
Filter	The name of the filter used to transform and display values. Type: FILTER \| Multiple value \| Optional filter="fooBarFilter"
Format Big Numbers	If true, big numbers are displayed using suffixes (e.g 1K, 1M, 1B). Type: BOOLEAN \| Optional \| Values: true false [chartOptions]="{formatBigNumbers: true}"
Initially Turned Off	The flag to turn off the metric when the graph is opened. If selected, the metric data is not loaded until you click on the metric in the legend. Type: BOOLEAN \| Optional \| Values: true false [chartOptions]="{hidden: true}"
Label	The metric alternative label. Type: STRING \| Optional label="Temperature"
Line Width	The width in pixel of the line. Type: INTEGER \| Optional \| Default: 1 [chartOptions]="{lineWidth: 123}"
Move Point Enabled	The flag enabling point vertical dragging to change the value. Type: BOOLEAN \| Optional \| Values: true false [chartOptions]="{movePointEnabled: true}"
Name	The metric whose value(s) must be loaded by the widget. Type: METRIC \| Required name="Temperature"
Rendering	The way the series is displayed in the graph. OVERLAID: all graphs are displayed in the same vertical space; column charts are displayed by grouping columns of different series, allowing them to be compared at the same date. STACKED: all graphs are arranged vertically, one on top of the other. It is useful for displaying total values. COLLAPSED: can be used only for child things, to display a single metric instead of one metric per thing. The values of the collapsed metrics are calculated using the Grouping Values function. Type: ENUM \| Optional \| Values: OVERLAID STACKED COLLAPSED [chartOptions]="{rendering: 'STACKED'}"
Show Boundary Datapoints	The flag to include values before and after the selected period in the chart. This option is valid only for Line and Step charts. Type: BOOLEAN \| Optional \| Values: true false [chartOptions]="{showBoundaryDatapoints: true}"
Show Max Value Line	The flag to turn on the red dashed line associated to the metric maximum value. The maximum value is the metric default minimum value if defined, else is computed among the loaded data. Type: BOOLEAN \| Optional \| Values: true false [chartOptions]="{showMaxLine: true}"
Show Min Value Line	The flag to turn on the blue dashed line associated to the metric minimum value. The minimum value is the metric default minimum value if defined, else is computed among the loaded data. Type: BOOLEAN \| Optional \| Values: true false [chartOptions]="{showMinLine: true}"
Unit	The unit of measurement to be displayed along the value. Type: STRING \| Optional unit="°C"
Value Grouping	The function to be applied to group values into the same timeframe in case of collapsed rendering or char zoom in/out. Type: ENUM \| Optional \| Values: SUM MAX AVG [chartOptions]="{valueGrouping: 'SUM'}"
Visibility Condition	The expression that allows you to reduce the visibility of the element. Type: STRING \| Optional *ngIf="getUser().organizationId != null"
Y-Axis Max	The value to be used as maximum value in the Y-Axis scale. Type: INTEGER \| Optional [chartOptions]="{yAxisMax: 100}"
Y-Axis Min	The value to be used as minimum value in the Y-Axis scale. Type: INTEGER \| Optional [chartOptions]="{yAxisMin: 0}"
Y-Axis Position	The position of the y-axis associated with the metric; within the same chart there can be a maximum of two y-axes, one on the left and one on the right. It is not possible to use subcharts and with Stacked Charts enabled. Type: ENUM \| Optional \| Values: LEFT RIGHT [chartOptions]="{yAxisPosition: 'RIGHT'}"
Y-Axis Title	The title displayed aside the Y-axis, when Y-Axis position is STACKED, similar metrics are grouped into sub charts (e.g. Temperatures, Power). Type: STRING \| Optional [chartOptions]="{yAxisTitle: 'Temperatures'}"

Chart Line <property>
PROPERTIES
Color	The color used to render the line in the chart. Type: STRING \| Optional \| Default: #3448DF [config]="{color: 'fooBar'}"
Label	The label displayed at above the line in the graph. Type: STRING \| Optional label="Temperature"
Value	The default Y value of the line. Type: INTEGER \| Optional [config]="{value: 123}"
Value Property	The property used to retrieve the constant Y value of the line. Type: PROPERTY \| Required name="serialNumber"
Y-Axis Title	In case of multiple Y-axis, you must specify the title of Y-axis where to display this line. Type: STRING \| Optional [config]="{yAxisTitle: 'Temperatures'}"

Limits

The load of metric data over multiple things works on a maximum of 500 things.