Handling Units of Time

Overview

There are a number of formats to represent time, which means that each dataset you load into KronoGraph may need to be handled differently. You will need to convert your time into a Date object or a millisecond number. Standard JavaScript handles time down to millisecond resolution, which is one thousandth of a second.

const date1 = new Date(2022, 11, 14); // year, month, day
const date2 = Date.UTC(2022, 11, 14); // 1670976000000 milliseconds

KronoGraph will always return dates as Date objects. You can then convert them into the format that suits you best.

const isoDate1 = date1.toISOString(); // 2022-12-14T00:00:00.000Z

Higher Resolution Time

For the majority of applications, milliseconds show sufficient time resolution to display your data. However, in some cases, milliseconds just aren't granular enough.

KronoGraph allows for the use of nanoseconds (¹⁄_1000000000 of a second, or 10⁻⁹ seconds) by accepting and returning an extra value in addition to standard date values to account for these smaller fractions of seconds.

Depending on how time is recorded in your data, it is possible to break date strings into a Date object and a number of nanoseconds, shown in the following example:

  const str = "Sep 24, 2019 17:56:40.563420880";

  // split the date string at the decimal point into a date and a fraction of a second
  const [dateText, fractionText] = str.split(".");

  // convert "Sep 24, 2019 17:56:40" to a Date object
  const time = new Date(dateText);

  // make sure that the nanosecond portion of the date string has nine decimal places
  // by adding zeros if needed
  const nanosecondsText = fractionText.padEnd(9, "0");

  // convert the nanoseconds text string to a number
  const nanoseconds = Number(nanosecondsText);

See the MDN docs for more information about manipulating strings.

You can then assign the values to the appropriate time properties, in this case to time and timeNanoseconds. Depending on the Scale Localization options you are using, the timeline could appear as below:

Time Nanoseconds

Log in to view live examples

const timelineData = {
  entities: {
    ent1: { label: 'Entity 1', },
    ent2: { label: 'Entity 2', },
  },
  events: {
    evt1: {
      entityIds: ['ent1', 'ent2'],
      time: new Date('Sep 24, 2019 17:56:40'),
      timeNanoseconds: 563420880,
      color: '#FF8838',
    },
  },
};

Take a look at the Higher Resolution Time story for an example.

Range Limits

If you use a timeNanoseconds value, KronoGraph will select a resolution to display the data depending on the values supplied. There are three levels of resolution available:

• Milliseconds (10^-3 seconds)
• Microseconds (10^-6 seconds)
• Nanoseconds (10^-9 seconds)

KronoGraph will use the resolution required, so long as the time range of your data does not exceed the range limits for that resolution. The range limits are as follows:

If the time range exceeds these limits, KronoGraph will use the next best resolution. A warning message will appear in the developer console unless the showWarnings option is set to false.