Regular

Understanding Highcharts – Regular/Discrete Series Data

Jugal Thakkar

This is a part of the Understanding Highcharts – Series Data blog series

Let us first define what we mean by discrete or regular to set the context on this blog

  1. The x-axis (independent axis) is numerical
  2. The x-axis can be extended infinitely on either side, but sometimes can be bound by a mix & max
  3. Discrete: The x value of a points can’t be any number, but a certain (yet infinitely large) subset of the number system
  4. Regular: The difference between the x-values of any two given points is always an integral multiple of a fixed interval

Mathematically, all the x values can be formulated as follows

x = reference_x + N * fixed_interval

Where

reference_x

is the x value of a pre-defined reference point in the series, this can be the first point, last point or any other point in the series. N is an integer, can be positive or negative.

fixed_interval

is a fixed float. The values of

reference_x

&

fixed_interval

are static across all the points and only the N value varies from point to point. Integers & Natural numbers are classic examples of such series with

fixed_interval=1

Theoretically, for any series if we were to reduce the

fixed_interval

to a very small number, we would always be able fit all data points into the above formula. But in most cases we would not have y-values for all corresponding

N

values for such small

fixed_interval

Let’s say we are driving a car and wish to track the fuel consumption & time taken along our journey. For this experiment, we may choose a fixed interval after which we take a reading, let’s take a reading after every 50 kilometers. Initially, my odometer reads 10000 km and fuel tank is 90%. At the end of the journey I have the following readings

Odometer (km) Fuel Consumed (ltr.) Time Taken (mins.)
10050 7.2 110
10100 7.76 120
10150 8.96 115
10200 3.92 89
10250 7.76 122.6
10300 8.4 117

It can be easily inferred that

fixed_interval = 50 & reference_x = 10000

In fact the

reference_x

could have been any x value in the series, just that the value of

N

for points before it would be negative if we were to choose any point other than the start point. More importantly, Highcharts makes life easy if we choose the first point as reference, we will see how to do it next. Generally, although not always, there would be not more than one y value corresponding to each value of x.

Regular/Discrete Series Data in Highcharts

It is easy to notice the pattern of the x values in such series. Given the first point and the interval, the Nth x-value can be calculated & Highcharts offers doing this calculation for you! The series options of Highcharts has following two special properties
plotOptions.series.pointStart

If no x values are given for the points in a series, pointStart defines on what value to start. On a datetime X axis, the number will be given as milliseconds since 1970-01-01, for exampleDate.UTC(2011, 0, 1). Defaults to 0.

plotOptions.series.pointInterval

If no x values are given for the points in a series, pointInterval defines the interval of the x values in milliseconds. For example, if a series contains one value each day, set pointInterval to 24 * 3600 * 1000. Defaults to 1

If the above two properties are set in the series options, we can simply skip the x-values in the data and just provide the y values and let Highcharts take care of the rest.
series.data

1) A list of numerical values. In this case, the numerical values will be interpreted as y values, and x values will be automatically calculated, either starting at 0 and incrementing by 1, or from pointStart and pointInterval given in the plotOptions. This option is not available for series types with more than one value per point, like area range or OHLC.

Example:
data: [0, 5, 3, 5]

Let us see how to handle the above example in Highcharts

series: [{
    name: 'Fuel Consumed',
    pointStart: 10000,
    pointInterval: 100,
    tooltip: {
        valueSuffix: ' ltrs.'
    },
    data: [0, 7.2, 7.76, 8.96, 3.92, 7.76, 8.4]
}, {
    name: 'Time Taken',
    pointStart: 10000,
    pointInterval: 100,
    data: [0, 110, 120, 115, 89, 122.6, 117],
    tooltip: {
        valueSuffix: ' mins.'
    },
    yAxis: 1
}]

Limitations

In this approach we are forced to put one and only one value for each possible x value. Since Highcharts calculates the x values by itself, we have very limited control over it.

Say, we did not have valid data for one of the x values? Or one of the x-values is itself not valid? Had we specified the x-values ourselves, we could easily skip the particular data point. We do have an option to mark the y-value as

null

for missing points, but this will break the chart and may be undesired. If we just wish to skip the point but not break the chart, we would need to use the [x,y] approach.

data: [0, 7.2, 7.76, null, 3.92, 7.76, 8.4]

If we wanted to something more special, e.g. have multiple Y values for a given X, we may have to choose to treat the data as irregular and provide explicit x values for all points.

Read More @ Understanding Highcharts – Series Data blog series

Reference Links