data

Specify how to fetch and process the data used to fill the calendar

type DataRecord = Record<string, string | number>;
type DataGroupType = 'sum' | 'count' | 'min' | 'max' | 'average';

type DataOptions = {
  source: string | DataRecord[],
  type: 'json' | 'csv' | 'tsv' | 'txt',
  requestInit: object,
  x: string | ((datum: DataRecord) => number),
  y: string | ((datum: DataRecord) => number),
  groupY:
    | DataGroupType
    | ((values: (number | string | null)[]) => number | string | null),
  defaultValue: null | number | string,
};

The calendar is expecting an array of objects as input.
There is no expected pre-defined structure for the object, but it must at least have one or more property for the date, and another one for the value, which is usually a number, but string is also accepted

Classic object
[
  { date: '2012-01-01', value: 3 },
  { date: '2012-01-02', value: 6 },
  ...
];

Using timestamp
[
  { t: 1673388319933, p: 3, v: 'Asia' },
  { t: 1673388319934, p: 6, v: 'Europe' },
  ...
];

Using multiple properties to define a date
[
  { year: 2020, month: 1, day: 1, temperature: 38 },
  ...
];

More options are available below to instruct the calendar on how to fetch, read and extract the date and value from your dataset.

`source`

Data used to populate the calendar.

source: string | DataRecord[],

There are 2 ways to pass your data to the calendar:

Using a local object

const data = [
  { date: '2012-01-01', value: 3 },
  { date: '2012-01-02', value: 6 },
];

const cal = new CalHeatmap();
cal.paint({
  data: { source: data },
});

Fetching data from a remote source

A string value will be interpreted as an url, and the data will be retrieved via a GET request.

const cal = new CalHeatmap();
cal.paint({
  data: { source: 'https://your-api.com/data.json' },
});

Injecting dynamic date

2 special tokens are available to customize your url, in order to limit the data time range from your remote source.

{{start=XXX}} will be replaced by the start of the first subDomain of the calendar
{{end=XXX}} will be replaced by the end of the last subDomain of the calendar

XXX should be replaced by any dayjs format token (Advanced tokens are also accepted)

note

The start and end time range are both inclusive.

tip

The tokens' value will dynamically update on navigation.

Usage
const cal = new CalHeatmap();
cal.paint({
  date: { start: new Date('2020-01-01') },
  data: {
    source:
      'https://your-api.com/data?start={{start=YYYY-MM-DD}}&end={{end=[year-]YYYY}}',
  },
});

The above date.source will output something like:

https://your-api.com/data?start=2020-01-01&end=year-2020

If the remote source is behind authentication, or requires additional request customization, see requestInit.

caution

Fetch is used under the hood to load the remote resource. Ensure that your endpoint has CORS setup properly.

`type`

Parser used to interpret the data returned by your url source.

type: 'json' | 'csv' | 'tsv' | 'txt',

The parser will interpret the data, and convert it to an array of DataRecord.

Default: json

note

This option is used only when the source is an url.

`requestInit`

Additional requestInit options, send along your data request.

d3-fetch is used under the hood to handle all network requests. See their documentation for further information and usage.

Default: {}

note

This option is used only when the source is an url.

Usage
{
    method: 'POST', // *GET, POST, PUT, DELETE, etc.
    mode: 'cors', // no-cors, *cors, same-origin
    cache: 'no-cache', // *default, no-cache, reload, force-cache, only-if-cached
    credentials: 'same-origin', // include, *same-origin, omit
    headers: {
      'Content-Type': 'application/json'
      // 'Content-Type': 'application/x-www-form-urlencoded',
    },
    redirect: 'follow', // manual, *follow, error
    referrerPolicy: 'no-referrer', // no-referrer, *no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin, strict-origin, strict-origin-when-cross-origin, unsafe-url
  }

`x`

Property name of the date, or a function returning a timestamp.
Instruct the calendar how to extract the date property from your data.

x: string | ((datum: DataRecord) => number),

You can either pass a:

string: key name of the property holding the date, in your datum object. The date will be parsed using Date.parse.
function: function taking the datum as argument, and should return a timestamp

caution

If your date is a string (e.g. '2020-01-01T00:00:00'), ensure that its format is ISO 8601 compliant (YYYY-MM-DDTHH:mm:ss.sssZ), or it may lead to inconsistency/precision loss.

If possible, we recommend to always use timestamp, to avoid all timezone related issues.

Example

Extract date using property name
var data = [{ column1: '2012-01-01', column2: 3 }];

cal.paint({
  data: { source: data, x: 'column1' },
});

Extract date using a custom function
var data = [{ column1: '2012-01-01', column2: 3 }];

cal.paint({
  data: {
    source: data,
    x: datum => {
      return +new Date(datum['column1']);
    },
  },
});

Compute date from multiple properties
var data = [{ year: 2020, month: 1, value: 3 }];

cal.paint({
  data: {
    source: data,
    x: datum => {
      return +new Date(datum['year'], datum['month'] - 1, 1);
    },
  },
});

`y`

Property name of the the value, or a function returning the value.
Instruct the calendar how to extract the value property from your data.

y: string | ((datum: DataRecord) => number | string),

You can either pass a:

string: key name of the property holding the value, in your datum object. The value should be a number.
function: function taking the datum as argument, and should return the value, as a number or a string

Example

Extract value using property name
var data = [{ column1: '2012-01-01', column2: 3 }];

cal.paint({
  data: { source: data, y: 'column2' },
});

Extract value using a built-in function
var data = [{ date: '2012-01-01', high: '30', low: '16' }];

cal.paint({
  data: {
    source: data,
    y: datum => {
      // You can use the function to pre-process your values
      return +datum['high'] + +datum['low']) / 2;
    },
  },
});

caution

When using a source other than a local javascript object, there is no auto-casting, and all values will be parsed as string. If your value is a number, consider using a function to cast it properly, e.g.:

y: (datum) => +datum['key_name']

instead of just

y: 'key_name'

`groupY`

Aggregate function, to group all values from the same subDomain.

type DataGroupType = 'sum' | 'count' | 'min' | 'max' | 'average';

groupY:
  | DataGroupType
  | ((values: (number | string | null)[]) => number | string | null),

You can either pass a:

string: name of a built-in aggregate function (see DataGroupType), only available if your values are numeric
function: function taking an array of datum from the same subDomain, and should return a new aggregated value.

Default: sum

caution

If your values are non-numeric, you have to use count, or implement your own aggregation strategy

Example

data.js
var data = [
  { column1: '2012-01-01', column2: 3 },
  { column1: '2012-01-01', column2: 4 },
  { column1: '2012-01-02', column2: 5 },
];

Group using a built-in function
cal.paint({
  data: {
    source: data,
    x: 'column1',
    y: 'column2',
    groupY: 'sum',
  },
});

Group using a custom function
cal.paint({
  data: {
    source: data,
    x: 'column1',
    y: 'column2',
    groupY: data => {
      // data === [3, 4, 5]
      return data.reduce((a, b) => a + b, 0);
    },
  },
});

groupY also supports values with non-numeric type, such as

data.js
var data = [
  { column1: '2012-01-01', column2: 'Asia' },
  { column1: '2012-01-01', column2: 'Europe' },
  { column1: '2012-01-02', column2: 'Asia' },
];

In that case, only the count DataGroupType will be available, and you should implement your own groupY function if you are grouping your values by another strategy.

`defaultValue`

Default value to use when your dataset does not have a value for a date.

defaultValue: null | number | string,

Default: null

tip

The most common use case will be to set it to 0

This option used to be known as considerMissingDataAsZero in the previous versions

source​

Using a local object​

Fetching data from a remote source​

Injecting dynamic date​

type​

requestInit​

x​

Example​

y​

Example​

groupY​

Example​

defaultValue​

`source`

Using a local object

Fetching data from a remote source

Injecting dynamic date

`type`

`requestInit`

`x`

Example

`y`

Example

`groupY`

Example

`defaultValue`