Chart Annotations

Annotations draw lines and rich content on the graph, useful for indicating a value or event of interest on a LineChart.

Screenshot of component ChartAnnotation basic

Usage

Annotations are available in a few variants, but all have a similar API surface. They accept DataSource or Accessor guided control over their position, or manually set x or y values, as well as styling related properties.

Screenshot of component ChartAnnotation pointannotationcomplex

A ChartContainer allows any number of annotations to be added.

import {
ChartContainer,
LineChart,
RealTimeDomain,
TimeAxis,
VerticalAxis,
HorizontalAnnotation,
} from '@electricui/components-desktop-charts'
import { MessageDataSource } from '@electricui/core-timeseries'
const maxTempDS = new MessageDataSource('temp_max')
  1. <ChartContainer>
  2. <LineChart dataSource={tempDS} />
  3. <TimeAxis />
  4. <VerticalAxis />
  5. <RealTimeDomain window={10000} />
  6. <HorizontalAnnotation dataSource={maxTempDS} />
  7. </ChartContainer>
  1. <ChartContainer>
  2. <LineChart dataSource={tempDS} />
  3. <TimeAxis />
  4. <VerticalAxis />
  5. <RealTimeDomain window={10000} />
  6. <HorizontalAnnotation y={50} />
  7. </ChartContainer>

HorizontalAnnotation can help callout minimum or maximum values, or provide threshold indicators.

VerticalAnnotation are useful for indicating a statechange or event which has importance in time-domain.

PointAnnotation allows for rich markup with text, shapes and colours for painting additional information at a specific location in a LineChart.

Annotations are rendered as ordered in the source code; the last annotation component is drawn last and will be above other lines.

Datasource input

The default accessors of the HorizontalAnnotation and VerticalAnnotation take the data of the event as their y or x position, respectively.

The default accessor of the PointAnnotation assumes the data of the event is an object with keys x, y, (and optionally z).

Color

Use the color property to style the line.

Screenshot of component ChartAnnotation basic

Use a hex value #0066cc via string, or use enum driven color for consistency with other UI components.

import { Colors } from '@blueprintjs/core'
<HorizontalAnnotation color={Colors.BLUE3} />
<HorizontalAnnotation color="#0066cc" />

Line Width

The thickness of the line in pixels is developer configurable by setting lineWidth to any positive number.

The default is 2.

  1. <HorizontalAnnotation lineWidth={1} />
  2. <HorizontalAnnotation lineWidth={4} />

Horizontal Annotation

Screenshot of component ChartAnnotation horizontalannotation

A HorizontalAnnotation draws a straight line configurable in the y axis.

  1. <HorizontalAnnotation
  2. dataSource={powerMaxDataSource}
  3. accessor={event => event.powerMax}
  4. color={Colors.ORANGE3}
  5. />

Manually specify the position with the y property.

<HorizontalAnnotation y={230} color={Colors.ORANGE3} />

Props

PropTypeDefaultOptionalDescription
accessorEventDataAccessor

EventDataAccessor

Type: (eventData: any, time: number) => number

Yes

An accessor on the Events data to produce the y value of the line from the Event.

colorColor

Color

| string | number
Yes

The color of the line

dataSourceDataSourceReference

DataSourceReference

DataSources may be transformed by the mutator functions, this specifies if the function expects the 'original' reference or the transformed final DataSource.

Type: DataSource<T>

Yes

A reference to a DataSource for event injestion.

lineWidthnumberYes

The thickness of the line

ynumberYes

Fixed initial y axis line position

Vertical Annotation

Screenshot of component ChartAnnotation verticalannotation

A VerticalAnnotation draws a straight line, configurable in the x axis (time).

This will usually require a custom message processor to identify/filter a message and emit the relevant time.

// todo
  1. <VerticalAnnotation
  2. dataSource={highSpeedSource}
  3. accessor={event => event.over9000}
  4. color={Colors.RED3}
  5. />

Manually specify the position with the x property. This is most relevant when HorizontalAxis is being used, rather than a rolling TimeAxis.

<VerticalAnnotation x={1200} color={Colors.ORANGE3} />

Props

PropTypeDefaultOptionalDescription
accessorEventDataAccessor

EventDataAccessor

Type: (eventData: any, time: number) => number

Yes

An accessor on the Events data to produce the y value of the line from the Event.

colorColor

Color

| string | number
Yes

The color of the line

dataSourceDataSourceReference

DataSourceReference

DataSources may be transformed by the mutator functions, this specifies if the function expects the 'original' reference or the transformed final DataSource.

Type: DataSource<T>

Yes

A reference to a DataSource for event injestion.

lineWidthnumberYes

The thickness of the line

xnumberYes

Fixed initial x axis line position

Point Annotation

A PointAnnotation passes a developer specified layout into the ChartContainer context and bypasses normal rendering stages for higher performance. This allows any valid React function (or HTML) to be positioned in the Chart.

PointAnnotation does not accept color or lineWidth properties; styling responsibility is held by the child content.

Similar to line annotations, dynamic positioning is achieved with a datasource, and manual positions are supported through x and y properties.

Because the positioning of PointAnnotation is in 2D space, xAccessor and yAccessor are used to select the relevant fields from the annotation datasource. It's also possible to blindly return a value if this syntax is preferred over the straight x

  1. // Select the x value to be the event timestamp
  2. <PointAnnotation xAccessor={(event, time) => time} >
  1. // Just blindly return a number instead of using the 'y' prop
  2. <PointAnnotation yAccessor={event => 800} >

Dynamic and manual positioning is allowed at the same time, demonstrated in context:

Screenshot of component ChartAnnotation pointannotation
import { PointAnnotation } from '@electricui/components-desktop-charts'
import { MessageDataSource } from '@electricui/core-timeseries'
  1. <ChartContainer>
  2. <PointAnnotation
  3. dataSource={annotationDS}
  4. xAccessor={(event, time) => time}
  5. y={800}
  6. >
  7. <div
  8. style={{
  9. textAlign: 'left',
  10. color: 'black',
  11. width: '150px',
  12. }}
  13. >
  14. Put something interesting here
  15. </div>
  16. </PointAnnotation>
  17. </ChartContainer>

Any valid components can be embedded, though we recommend restricting these to display only components.

  1. <PointAnnotation>
  2. <Tag minimal intent={Intent.WARNING} icon="warning-sign">
  3. Oscillation Detected: <Printer accessor="dom_freq" />
  4. Hz
  5. </Tag>
  6. </PointAnnotation>

Interaction with components painted on a Chart is generally a poor UX choice.

Props

Failed to grab component information for PointAnnotation