ChartAnnotation

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

Usage

Annotations are available with different 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.

A ChartContainer can render an unbounded number of annotations. Each annotation only displays one point of data.

import { 
  ChartContainer, 
  LineChart, 
  RealTimeDomain, 
  TimeAxis,  
  VerticalAxis,
  HorizontalLineAnnotation 
} from '@electricui/components-desktop-charts'
import { useMessageDataSource } from '@electricui/core-timeseries'
 
const OverviewPage = () => {
  const tempDS = useMessageDataSource('temp_ptc')
  const maxTempDS = useMessageDataSource('temp_max')
 
  return (
    <React.Fragment>
      <ChartContainer>
        <LineChart dataSource={tempDS} />
        <TimeAxis />
        <VerticalAxis />
        <RealTimeDomain window={10000} />
        <HorizontalLineAnnotation dataSource={maxTempDS} />
        <HorizontalLineAnnotation y={50} />
      </ChartContainer>
    </React.Fragment>
  )
}

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

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

PointAnnotation are useful for highlighting single points of information.

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

Annotations render as ordered in the source code; the last annotation component renders last and will be above other lines.

Datasource input

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

The default accessor of the ElementAnnotation assumes the data of the event is an object with keys x and y.

A null can be passed as the data to hide the annotation.

Color

Use the color property to style the line.

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

import { Colors } from '@blueprintjs/core'
 
<HorizontalLineAnnotation color={Colors.BLUE3} />

<HorizontalLineAnnotation 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.

<HorizontalLineAnnotation lineWidth={1} />

<HorizontalLineAnnotation lineWidth={4} />

Horizontal Annotation

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

import { HorizontalLineAnnotation } from '@electricui/components-desktop-charts'
 
<HorizontalLineAnnotation
  dataSource={powerMaxDataSource}
  color={Colors.ORANGE3}
/>

Manually specify the position with the y property.

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

Vertical Annotation

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

This typically requires a custom DataFlow to identify/filter a message and emit the relevant time.

In this example, the highSpeedSource emits events at certain times, and the accessor on the VerticalLineAnnotation draws its line at the time of the latest event. The default accessor places the line at the time of the event, instead of the data.

import { VerticalLineAnnotation } from '@electricui/components-desktop-charts'
 
<VerticalLineAnnotation
  dataSource={highSpeedSource}
  accessor={(data, time) => time}
  color={Colors.RED3}
/>

Manually specify the position with the x property.

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

Y Axis Annotation

A YAxisAnnotation provides side-lined annotations which track a datasource.

This can display the numeric value of a signal alongside the plot, or callout specific values by using a custom message processor to identify/filter a message and emit specific events to the datasource.

import { YAxisAnnotation } from '@electricui/components-desktop-charts'
 
<YAxisAnnotation dataSource={signalSource} />

Styling control over the annotation and the dashed gridline is also exposed. Labels and tick formattting properties are also exposed.

 <YAxisAnnotation
  dataSource={temperature_thresholds}
  accessor={event => event.minimum}
  color={Colors.BLUE2}
  gridColor={Colors.BLUE5}
  tickFormat={(tick: number) => tick.toFixed(2) + '°C'}
/>
 
<YAxisAnnotation
  dataSource={temperature_thresholds}
  accessor={event => event.maximum}
  color={Colors.RED2}
  gridColor={Colors.RED5}
  tickFormat={(tick: number) => tick.toFixed(0) + '°C'}
/>

Point Annotation

A 2D 'dot' which can be positioned with typical DataSource and accessor syntax. Internally, this uses the same functionality as ScatterPlot.

The accessor must return an object of the form {x: number, y: number} to specify the position on the chart for the annotation, or a null to specify that the annotation should hide.

import { PointAnnotation } from '@electricui/components-desktop-charts'
 
<PointAnnotation
  dataSource={dataSource}
  accessor={(data, time) => ({x: time, y: data})}
  color={Colors.BLUE3}
/>

The colour can be specified as a string or number.

<PointAnnotation color={Colors.BLUE3} />
<PointAnnotation color="blue" />
<PointAnnotation color="#0066CC" />

As with other charts and annotations, colorAccessor is available for dynamic control. This example uses a Three color and changes based on the underlying data.

import { Color } from 'three'
 
const col = new Color()

<PointAnnotation 
  dataSource={dataSource}
  color="#FFF"
  colorAccessor={(data, time) => {
    col.setHSL(0.4, 0.6, 0.5)
 
    if (data < 500 ) {
      col.setHSL(0.0, 0.5, 0.5)
    }
 
    return col.getHex()
  }}
 />

Size is controllable by providing a number to the size property. Use the sizeAccessor to dynamically control the annotation's size.

<PointAnnotation size={1} />
<PointAnnotation size={8} />
<PointAnnotation size={32} />

Element Annotation

A ElementAnnotation passes a developer specified component into the ChartContainer context and moves it to stay aligned to a point on the Chart.

ElementAnnotation does not accept color or lineWidth properties; the child content must handle styling.

Dynamic positioning relies on a DataSource with the same syntax as a normal LineChart. Manual positions control properties x and y are available.

The accessor must return an object of the form {x: number, y: number} to specify the position on the chart for the annotation, or a null to specify that the annotation should hide.

import { ElementAnnotation } from '@electricui/components-desktop-charts'
 
// Select the x value to be the event timestamp
<ElementAnnotation 
  dataSource={annotationDS} 
  accessor={(data, time) => ({x: time, y: data})}
>
  <span>Useful notes?</span>
</ElementAnnotation>

If the annotation has both a manually set position and an accessor and dataSource, the annotation will start at the manually set position and move when an event is received.

<ChartContainer>
  <ElementAnnotation
    dataSource={annotationDS}
    accessor={(data, time) => ({x: time, y: data})}
    x={100}
    y={800}
  >
    <div
      style={{
        textAlign: 'left',
        color: 'black',
        width: '150px',
      }}
    >
      Put something interesting here
    </div>
  </ElementAnnotation>
</ChartContainer>

Any valid components are embeddable, though we recommend restricting these to display/output focussed components.

<ElementAnnotation>
  <Tag minimal intent={Intent.WARNING} icon="warning-sign">
    Oscillation Detected: <Printer accessor="dom_freq" /> Hz
  </Tag>
</ElementAnnotation>

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