Scales

Overview

The timeline scale allows you to see when events occur and helps you navigate the timeline.

A linear scale is used by default, showing each individual time period, such as an hour, as the same width as any other.

Sometimes, however, events happen over multiple, separate intervals, in which case, a nonlinear scale, that condenses time periods without any events, can be useful.

This choice of scale, is referred to as the scale mode.

Similarly, sometimes, you might want to explore how events repeat over a period, such as a day or week. This is controlled using scale wrapping, sometimes referred to as "pattern of life" analysis.

Scale Mode

By default, KronoGraph spaces events along the timeline in relation to a linear scale. However, a dataset might have lots of events clustered closely together, followed by periods where no events occur. If this is the case, it can be useful to change the scaleMode to nonlinear to space the events proportionally, reduce the amount of empty space and allow for a larger time range to be seen at once.

The following timeline shows the dates of notable inventions and uses the nonlinear scale to stretch and compress time where needed, allowing more inventions to be shown in the same view. For example, there are more than 1500 years between the invention of paper and the printing press, but the nonlinear scale mode compresses the gap to make better use of the space in the timeline.

Default

Log in to view live examples

timeline.options({
  scales: {
      scaleMode: 'nonlinear'
  }
});

<Timeline
  options={{
    scales: {
      scaleMode: 'nonlinear'
    }
  }}
/>

By default, when an entity is focused, the timeline is rescaled for visible events. Disable this behavior by setting the rescale option to 'false'.

See the Nonlinear Scale Mode story to try it out.

The nonlinear scale is made up of an inner and outer scale. The outer scale gives context while the inner scale provides a more accurate indication of the date and time. Each vertical tick mark is drawn at a regular time interval, which shows how much time is compressed or expanded on the scale.

Customize the display of the scale with dateOrder and twelveHourClock. Currently, dateTimeFormats and dateTimeNames aren't supported using the nonlinear scale.

Note that when the scale mode is set to 'nonlinear', time series charts will be hidden.

Scale Wrapping

By default, the timeline shows time progressing, and displays events in the order in which they occurred, using a linear timescale (see also Scale Mode).

Sometimes, however, rather than seeing events sequentially, you might want to see how they occur by day of the week, or by date of the month. KronoGraph allows you to do this by using scale wrapping, enabling you to visualize and investigate repeating patterns, sometimes referred to as "pattern of life" analysis.

The following example shows how events occurring over many months can be visualized according to what time of the week they happened.

When wrapped by week, you can zoom in to see detail, but you can't zoom out any further than a week (as that's what your scale is being wrapped by).

Scale Wrapping

Log in to view live examples

You can change the timeline's scale wrapping by setting the wrapping option, for example:

options={{
  scales: {
    wrapping: 'week'
  }
}}

timeline.options({
  scales: {
    wrapping: 'week'
  }
});

KronoGraph provides the following scale wrapping options:

When scale wrapping is used:

• The scales show generic times, such as 'Monday', rather than specific dates and times. You can still zoom in to see details of events occurring over a part of the wrapping period. For example, if scale wrapping by week, you can zoom in to see activity for Fridays between 5 and 6pm.
• The timeline.fit() function fit() instance method fits the view to the whole wrapped interval (rather than to the range of time in which events occur).

Internally, scale wrapping uses a "base range" of times for each wrapping option, which it maps event times to. If you call timeline.range() If an onTimelineChange event containing a range object is invoked when the scale is wrapped, the times in the returned range event's range object are relative to this.

The base ranges for each wrapping option are:

So, for example, if wrapping by week, and zooming in to 'Tuesday', timeline.range() the TimeRange object returns a start date of 12 am, January 4, 2000, and an end date of 12 am, January 5, 2000 (which was a Tuesday). Conversely, if you call timeline.range() as a setter, pass a value to the range prop, the dates you provide should be relative to the base range.

Timestamps passed to event handlers for UI events such as click or hover onTimelineClick or onTimelineHover are also relative to the base range.

Check out the Scale Wrapping story to see an example of scale wrapping in action.

Note that if scale wrapping is applied, time series charts will be hidden.

Scale Localization

Dates and times are displayed in the scale in US English format by default. You can use the dateOrder and twelveHourClock options for basic adjustment of the US English format.

For further customization of the displayed date and time you can use:

• dateTimeFormats for different scale zoom levels and wrapping options. Each one is a string containing formatting codes and/or literal characters.
• dateTimeNames for months and days of the week, as well as the AM/PM symbols.

timeline.options({
  scales: {
    dateTimeFormats: {
      date: 'yyyy-MM-dd',
    },
  },
});

You can see some examples of date and time formatting for different locales in the Scales Options story.