Chapter 5: Time Series Without Manual Labor

Populating a grid by hand is feasible for eight by eight cells. For a full year with 371 cells, mapping timestamps onto matrix coordinates is precisely the type of arithmetic where daylight saving time and start-of-week offsets cause silent errors that nobody catches.

That is what presets are for. They reside in a dedicated submodule so they are not loaded unless explicitly imported:

import { presets } from 'mlc-isometric-heatmap/presets';

const events = [
  { timestamp: new Date('2026-06-09T10:15:00Z'), value: 5 },
  { timestamp: new Date('2026-06-09T15:30:00Z'), value: 20 },
];

24 Hours Against Weekdays

const grid = presets.aggregate24h(events, { startOfWeek: 1 });

24 columns, 7 rows. startOfWeek: 1 begins on Monday — the Sunday default originates from US calendar conventions and is usually inappropriate for European contexts.

This is the ideal view for diurnal rhythms: when machinery runs, when periods of quiet occur, and how weekends differ from working hours.

Two measurement series as daily timelines.

A single day with four sample points — sparse data still yields a legible, informative picture.

One Month

const grid = presets.aggregateMonth(events, { year: 2026, month: 5 });

Weeks as columns, weekdays as rows. The monthly view is the granularity at which a human viewer can still easily inspect any individual day.

A single month with a height grid as a scale backdrop in the rear.

Monday to Friday only: where weekends contribute no data, showing them only wastes visual space.

Half a Year

A gap exists between a single month and an entire year: 26 weeks is too wide for a single monthly chart, yet too compact to form long-term seasonal textures in an annual grid. The six-month preset bridges this gap, optionally with monthly divider gaps.

Six months with month dividers: boundaries remain distinctly readable.

Two series across six months, paired with an isometric height grid.

One Year

const grid = presets.aggregateYear(events, { year: 2026 });

53 weeks against 7 weekdays — the geometry familiar from contribution graphs, elevated here with 3D height. At this density, row text can become visual clutter; showRowLabels: false turns them off cleanly.

A full year without row labels: the structural rhythm carries the visualization on its own.

The exact same year rendered as a continuous 3D relief instead of columns.

Multiple Groups Side by Side

When comparing quarters, semesters, or different facility locations, multiple grids can be merged into a single visualization rather than laid out in separate figures. The critical benefit is a unified vertical scale — independent graphs scale to their own local maxima, distorting comparative analysis.

Multiple monthly groups unified within a single graphic with a shared height scale.