src/lite/scale.ts

Functions

Imports

It imports no other module of this repo. Imported by src/lite/bar.ts, src/lite/series.ts.

Source

1/**
2 * The scales, ticks and tick labels the light charts need, written to give the same numbers as
3 * the Observable Plot renderer, so both draw the same chart.
4 *
5 * The tick, nice, band, log and UTC time algorithms are ports of d3-array, d3-scale, d3-time and
6 * d3-format (ISC License, Copyright 2010-2023 Mike Bostock), and the axis rules of Observable Plot
7 * (ISC License, Copyright 2020-2025 Observable, Inc.).
8 */
9
10const E10 = Math.sqrt(50);
11const E5 = Math.sqrt(10);
12const E2 = Math.sqrt(2);
13
14function tickSpec(start: number, stop: number, count: number): [number, number, number] {
15  const step = (stop - start) / Math.max(0, count);
16  const power = Math.floor(Math.log10(step));
17  const error = step / 10 ** power;
18  const factor = error >= E10 ? 10 : error >= E5 ? 5 : error >= E2 ? 2 : 1;
19  let i1: number;
20  let i2: number;
21  let inc: number;
22  if (power < 0) {
23    inc = 10 ** -power / factor;
24    i1 = Math.round(start * inc);
25    i2 = Math.round(stop * inc);
26    if (i1 / inc < start) ++i1;
27    if (i2 / inc > stop) --i2;
28    inc = -inc;
29  } else {
30    inc = 10 ** power * factor;
31    i1 = Math.round(start / inc);
32    i2 = Math.round(stop / inc);
33    if (i1 * inc < start) ++i1;
34    if (i2 * inc > stop) --i2;
35  }
36  if (i2 < i1 && 0.5 <= count && count < 2) return tickSpec(start, stop, count * 2);
37  return [i1, i2, inc];
38}
39
40/** About `count` round numbers from `start` to `stop`, as d3.ticks. */
41export function ticks(start: number, stop: number, count: number): number[] {
42  if (!(count > 0)) return [];
43  if (start === stop) return [start];
44  const reverse = stop < start;
45  const [i1, i2, inc] = reverse ? tickSpec(stop, start, count) : tickSpec(start, stop, count);
46  if (!(i2 >= i1)) return [];
47  const n = i2 - i1 + 1;
48  const out: number[] = [];
49  for (let i = 0; i < n; ++i) {
50    const k = reverse ? i2 - i : i1 + i;
51    out.push(inc < 0 ? k / -inc : k * inc);
52  }
53  return out;
54}
55
56function tickIncrement(start: number, stop: number, count: number): number {
57  return tickSpec(start, stop, count)[2];
58}
59
60function tickStep(start: number, stop: number, count: number): number {
61  const reverse = stop < start;
62  const inc = reverse ? tickIncrement(stop, start, count) : tickIncrement(start, stop, count);
63  return (reverse ? -1 : 1) * (inc < 0 ? 1 / -inc : inc);
64}
65
66/** A two-number domain or range. */
67export type Pair = readonly [number, number];
68
69/** A continuous position scale: linear, log or UTC time (as epoch milliseconds). */
70export interface Continuous {
71  readonly type: "linear" | "log" | "utc";
72  readonly domain: Pair;
73  readonly range: Pair;
74  (value: number): number;
75}
76
77/** A linear, log or time scale from a domain to a range. */
78export function continuous(type: Continuous["type"], domain: Pair, range: Pair): Continuous {
79  const t = type === "log" ? Math.log10 : (v: number) => v;
80  const d0 = t(domain[0]);
81  const span = t(domain[1]) - d0;
82  const [r0, r1] = range;
83  const scale = (value: number): number => {
84    const k = span === 0 ? 0.5 : (t(value) - d0) / span;
85    return r0 * (1 - k) + r1 * k;
86  };
87  return Object.assign(scale, { type, domain, range });
88}
89
90/** Widens a linear domain to round numbers, as d3's linear `nice()`. */
91export function niceLinear(domain: Pair, count = 10): Pair {
92  let [start, stop] = domain;
93  const reverse = stop < start;
94  if (reverse) [start, stop] = [stop, start];
95  let prestep: number | undefined;
96  for (let i = 0; i < 10; i++) {
97    const step = tickIncrement(start, stop, count);
98    if (step === prestep) return reverse ? [stop, start] : [start, stop];
99    if (step > 0) {
100      start = Math.floor(start / step) * step;
101      stop = Math.ceil(stop / step) * step;
102    } else if (step < 0) {
103      start = Math.ceil(start * step) / step;
104      stop = Math.floor(stop * step) / step;
105    } else break;
106    prestep = step;
107  }
108  return domain;
109}
110
111/** A power of ten, written so that 10 ** -3 is exactly 0.001. */
112const pow10 = (x: number): number => (Number.isFinite(x) ? Number(`1e${x}`) : x < 0 ? 0 : x);
113
114/** Widens a log domain to powers of ten. */
115export function niceLog(domain: Pair): Pair {
116  const [a, b] = domain;
117  const reverse = b < a;
118  const [lo, hi] = reverse ? [b, a] : [a, b];
119  const nice: Pair = [pow10(Math.floor(Math.log10(lo))), pow10(Math.ceil(Math.log10(hi)))];
120  return reverse ? [nice[1], nice[0]] : nice;
121}
122
123/** Log ticks: every whole multiple of each power of ten in the domain, when few enough. */
124export function logTicks(domain: Pair, count: number): number[] {
125  let [u, v] = domain;
126  const reverse = v < u;
127  if (reverse) [u, v] = [v, u];
128  let i = Math.log10(u);
129  let j = Math.log10(v);
130  let z: number[] = [];
131  if (j - i < count) {
132    i = Math.floor(i);
133    j = Math.ceil(j);
134    for (; i <= j; ++i) {
135      for (let k = 1; k < 10; ++k) {
136        const t = i < 0 ? k / pow10(-i) : k * pow10(i);
137        if (t < u) continue;
138        if (t > v) break;
139        z.push(t);
140      }
141    }
142    if (z.length * 2 < count) z = ticks(u, v, count);
143  } else {
144    z = ticks(i, j, Math.min(j - i, count)).map(pow10);
145  }
146  return reverse ? z.reverse() : z;
147}
148
149/** d3's minus sign. */
150const MINUS = "−";
151
152const group3 = (digits: string): string => digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
153
154/** `value` with `precision` decimals and thousands separators, as d3.format(",.{precision}f"). */
155function fixed(value: number, precision: number): string {
156  let negative = value < 0 || 1 / value < 0;
157  const text = Math.abs(value).toFixed(precision);
158  if (negative && Number(text) === 0) negative = false;
159  const [whole = "", fraction] = text.split(".");
160  return `${negative ? MINUS : ""}${group3(whole)}${fraction === undefined ? "" : `.${fraction}`}`;
161}
162
163/** The decimal exponent of a number, as d3-format reads it: NaN for zero or a non-finite number. */
164const exponentOf = (value: number): number =>
165  Number.isFinite(value) && value !== 0
166    ? Number(Math.abs(value).toExponential().split("e")[1])
167    : Number.NaN;
168
169/** The tick labels of a linear scale: as many decimals as the tick step needs. */
170export function linearTickFormat(domain: Pair, count: number): (value: number) => string {
171  const step = tickStep(domain[0], domain[1], count);
172  // d3-format reads a missing precision as 6 and holds a fixed precision to 0 through 20.
173  const precision = Math.min(20, Math.max(0, -exponentOf(step)));
174  return (value) => fixed(value, Number.isNaN(precision) ? 6 : precision);
175}
176
177const PREFIXES = [
178  "y",
179  "z",
180  "a",
181  "f",
182  "p",
183  "n",
184  "µ",
185  "m",
186  "",
187  "k",
188  "M",
189  "G",
190  "T",
191  "P",
192  "E",
193  "Z",
194  "Y",
195];
196
197/** A number with an SI prefix and no trailing zeros, as d3.format("~s"). */
198function si(value: number): string {
199  if (value === 0) return "0";
200  const [digits = "", exp = "0"] = Math.abs(value).toExponential(5).split("e");
201  const coefficient = digits.replace(".", "");
202  const exponent = Number(exp);
203  const prefix = Math.max(-8, Math.min(8, Math.floor(exponent / 3)));
204  const i = exponent - prefix * 3 + 1;
205  const n = coefficient.length;
206  let out =
207    i === n
208      ? coefficient
209      : i > n
210        ? coefficient + "0".repeat(i - n)
211        : i > 0
212          ? `${coefficient.slice(0, i)}.${coefficient.slice(i)}`
213          : `0.${"0".repeat(-i)}${coefficient}`;
214  if (out.includes(".")) out = out.replace(/\.?0+$/, "");
215  return `${value < 0 ? MINUS : ""}${out}${PREFIXES[8 + prefix]}`;
216}
217
218/** The tick labels of a log scale: SI numbers, blank between powers of ten when crowded. */
219export function logTickFormat(domain: Pair, count: number): (value: number) => string {
220  const k = Math.max(1, (10 * count) / logTicks(domain, 10).length);
221  return (d) => {
222    let i = d / pow10(Math.round(Math.log10(d)));
223    if (i * 10 < 10 - 0.5) i *= 10;
224    return i <= k ? si(d) : "";
225  };
226}
227
228/** A band scale: equal slots across a range, as d3.scaleBand with Plot's rounding rule. */
229export interface Band {
230  readonly step: number;
231  readonly bandwidth: number;
232  /** The start of slot `i`. */
233  at(i: number): number;
234}
235
236/**
237 * Slots for `n` categories across `range`. Rounded to whole pixels when that wastes no more than
238 * 30 pixels, as Plot does.
239 */
240export function band(n: number, range: Pair, paddingInner: number, paddingOuter: number): Band {
241  const [r0, r1] = range;
242  const length = Math.abs(r1 - r0);
243  const m = n - paddingInner;
244  const raw = length / Math.max(1, m + paddingOuter * 2);
245  const round = (raw - Math.floor(raw)) * m <= 30;
246  const step = round ? Math.floor(raw) : raw;
247  let start = Math.min(r0, r1) + (length - step * m) * 0.5;
248  let bandwidth = step * (1 - paddingInner);
249  if (round) {
250    start = Math.round(start);
251    bandwidth = Math.round(bandwidth);
252  }
253  return { step, bandwidth, at: (i) => start + step * i };
254}
255
256const SECOND = 1000;
257const MINUTE = 60 * SECOND;
258const HOUR = 60 * MINUTE;
259const DAY = 24 * HOUR;
260const WEEK = 7 * DAY;
261const MONTH = 30 * DAY;
262const YEAR = 365 * DAY;
263
264/** A UTC time interval on epoch milliseconds, as d3-time's. */
265interface Interval {
266  floor(t: number): number;
267  offset(t: number, step: number): number;
268}
269
270const date = (t: number): Date => new Date(t);
271
272/**
273 * Midnight UTC on the first of a month, for any year. Date.UTC reads years 0 to 99 as 1900 to
274 * 1999, so the year is set on its own, as d3-time does.
275 */
276function utcStart(year: number, month: number): number {
277  const d = new Date(0);
278  d.setUTCFullYear(year, month, 1);
279  return d.getTime();
280}
281
282function every(base: Interval, test: (t: number) => boolean): Interval {
283  return {
284    floor(t) {
285      let d = base.floor(t);
286      while (!test(d)) d = base.floor(d - 1);
287      return d;
288    },
289    offset(t, step) {
290      let d = t;
291      for (let i = 0; i < step; i++) {
292        do d = base.offset(d, 1);
293        while (!test(d));
294      }
295      return d;
296    },
297  };
298}
299
300const fixedInterval = (ms: number): Interval => ({
301  floor: (t) => Math.floor(t / ms) * ms,
302  offset: (t, step) => t + step * ms,
303});
304
305const utcSecond = fixedInterval(SECOND);
306const utcMinute = fixedInterval(MINUTE);
307const utcHour = fixedInterval(HOUR);
308const unixDay = fixedInterval(DAY);
309const utcSunday: Interval = {
310  floor: (t) => {
311    const day = Math.floor(t / DAY) * DAY;
312    return day - date(day).getUTCDay() * DAY;
313  },
314  offset: (t, step) => t + step * WEEK,
315};
316const utcMonth: Interval = {
317  floor: (t) => utcStart(date(t).getUTCFullYear(), date(t).getUTCMonth()),
318  offset: (t, step) => {
319    const d = date(t);
320    d.setUTCMonth(d.getUTCMonth() + step);
321    return d.getTime();
322  },
323};
324const utcYear: Interval = {
325  floor: (t) => utcStart(date(t).getUTCFullYear(), 0),
326  offset: (t, step) => {
327    const d = date(t);
328    d.setUTCFullYear(d.getUTCFullYear() + step);
329    return d.getTime();
330  },
331};
332
333function yearsEvery(k: number): Interval {
334  return {
335    floor: (t) => utcStart(Math.floor(date(t).getUTCFullYear() / k) * k, 0),
336    offset: (t, step) => {
337      const d = date(t);
338      d.setUTCFullYear(d.getUTCFullYear() + step * k);
339      return d.getTime();
340    },
341  };
342}
343
344/** Every `k`th unit of an interval, counted by a calendar field (seconds, hours, months). */
345function fieldEvery(base: Interval, field: (t: number) => number, k: number): Interval {
346  return k === 1 ? base : every(base, (t) => field(t) % k === 0);
347}
348
349const TICK_INTERVALS: [string, number, number][] = [
350  ["second", 1, SECOND],
351  ["second", 5, 5 * SECOND],
352  ["second", 15, 15 * SECOND],
353  ["second", 30, 30 * SECOND],
354  ["minute", 1, MINUTE],
355  ["minute", 5, 5 * MINUTE],
356  ["minute", 15, 15 * MINUTE],
357  ["minute", 30, 30 * MINUTE],
358  ["hour", 1, HOUR],
359  ["hour", 3, 3 * HOUR],
360  ["hour", 6, 6 * HOUR],
361  ["hour", 12, 12 * HOUR],
362  ["day", 1, DAY],
363  ["day", 2, 2 * DAY],
364  ["week", 1, WEEK],
365  ["month", 1, MONTH],
366  ["month", 3, 3 * MONTH],
367  ["year", 1, YEAR],
368];
369
370function tickInterval(start: number, stop: number, count: number): Interval {
371  const target = Math.abs(stop - start) / count;
372  let i = TICK_INTERVALS.findIndex(([, , step]) => step > target);
373  if (i === -1) i = TICK_INTERVALS.length;
374  if (i === TICK_INTERVALS.length) {
375    return yearsEvery(tickStep(start / YEAR, stop / YEAR, count));
376  }
377  if (i === 0) {
378    const k = Math.max(tickStep(start, stop, count), 1);
379    return fixedInterval(k);
380  }
381  const before = TICK_INTERVALS[i - 1] as [string, number, number];
382  const after = TICK_INTERVALS[i] as [string, number, number];
383  const [name, k] = target / before[2] < after[2] / target ? before : after;
384  switch (name) {
385    case "second":
386      return fieldEvery(utcSecond, (t) => date(t).getUTCSeconds(), k);
387    case "minute":
388      return fieldEvery(utcMinute, (t) => date(t).getUTCMinutes(), k);
389    case "hour":
390      return fieldEvery(utcHour, (t) => date(t).getUTCHours(), k);
391    case "day":
392      return fieldEvery(unixDay, (t) => t / DAY, k);
393    case "week":
394      return utcSunday;
395    case "month":
396      return fieldEvery(utcMonth, (t) => date(t).getUTCMonth(), k);
397    default:
398      return utcYear;
399  }
400}
401
402/** UTC time ticks from `start` to `stop` (epoch milliseconds), about `count` of them. */
403export function timeTicks(start: number, stop: number, count: number): number[] {
404  const reverse = stop < start;
405  const [lo, hi] = reverse ? [stop, start] : [start, stop];
406  const interval = tickInterval(lo, hi, count);
407  const out: number[] = [];
408  const end = hi + 1;
409  let t = interval.offset(interval.floor(lo - 1), 1);
410  t = interval.floor(t);
411  while (t < end) {
412    out.push(t);
413    const next = interval.floor(interval.offset(t, 1));
414    if (!(next > t)) break;
415    t = next;
416  }
417  return reverse ? out.reverse() : out;
418}
419
420const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
421/** Zero-padded, with the sign ahead of the zeros, as d3-time-format pads. */
422const pad = (n: number, width = 2): string =>
423  `${n < 0 ? "-" : ""}${String(Math.abs(n)).padStart(width, "0")}`;
424
425/** The parts of d3.utcFormat that time axes use. */
426const part = {
427  year: (t: number) => pad(date(t).getUTCFullYear() % 10000, 4),
428  month: (t: number) => MONTHS[date(t).getUTCMonth()] ?? "",
429  day: (t: number) => String(date(t).getUTCDate()),
430  hour12: (t: number) => String(date(t).getUTCHours() % 12 || 12),
431  ampm: (t: number) => (date(t).getUTCHours() >= 12 ? "PM" : "AM"),
432  minute: (t: number) => pad(date(t).getUTCMinutes()),
433  second: (t: number) => pad(date(t).getUTCSeconds()),
434  milli: (t: number) => pad(date(t).getUTCMilliseconds(), 3),
435};
436
437type Format = (t: number) => string;
438
439/** The two-level formats Plot puts on time axes: a fine label, and a coarse one when it changes. */
440const TIME_FORMATS: Record<string, [Format, Format]> = {
441  millisecond: [(t) => `.${part.milli(t)}`, (t) => `:${part.minute(t)}:${part.second(t)}`],
442  second: [(t) => `:${part.second(t)}`, (t) => `${part.hour12(t)}:${part.minute(t)}`],
443  minute: [(t) => `${part.hour12(t)}:${part.minute(t)}`, part.ampm],
444  hour: [(t) => `${part.hour12(t)} ${part.ampm(t)}`, (t) => `${part.month(t)} ${part.day(t)}`],
445  day: [part.day, part.month],
446  month: [part.month, part.year],
447};
448
449/** An instant as ISO 8601, as the isoformat package writes it. */
450function isoFormat(t: number): string {
451  const d = date(t);
452  const year = d.getUTCFullYear();
453  const [h, m, s, ms] = [
454    d.getUTCHours(),
455    d.getUTCMinutes(),
456    d.getUTCSeconds(),
457    d.getUTCMilliseconds(),
458  ];
459  const y = year < 0 ? `-${pad(-year, 6)}` : year > 9999 ? `+${pad(year, 6)}` : pad(year, 4);
460  const time =
461    h || m || s || ms
462      ? `T${pad(h)}:${pad(m)}${s || ms ? `:${pad(s)}${ms ? `.${pad(ms, 3)}` : ""}` : ""}Z`
463      : "";
464  return `${y}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}${time}`;
465}
466
467const FORMAT_INTERVALS: [string, Interval, number][] = [
468  ["year", utcYear, Number.POSITIVE_INFINITY],
469  ["month", utcMonth, Number.POSITIVE_INFINITY],
470  ["day", unixDay, 6 * MONTH],
471  ["hour", utcHour, 3 * DAY],
472  ["minute", utcMinute, 6 * HOUR],
473  ["second", utcSecond, 30 * MINUTE],
474];
475
476/**
477 * The labels of time ticks on a bottom axis, each a line or two: the finest unit every tick is
478 * aligned to, with the coarser unit beneath where it changes ("Jan" over "2026").
479 */
480export function timeTickLabels(ticks: readonly number[]): string[] {
481  let step: number | undefined;
482  for (let i = 1; i < ticks.length; i++) {
483    const gap = Math.abs((ticks[i] as number) - (ticks[i - 1] as number));
484    if (step === undefined || gap > step) step = gap;
485  }
486  let name: string | undefined;
487  if (step !== undefined && step < 1000) name = "millisecond";
488  else {
489    for (const [n, interval, maxStep] of FORMAT_INTERVALS) {
490      if (step !== undefined && step > maxStep) break;
491      if (n === "hour" && !step) break;
492      if (ticks.every((t) => interval.floor(t) >= t)) {
493        name = n;
494        break;
495      }
496    }
497  }
498  if (name === undefined) return ticks.map(isoFormat);
499  if (name === "year") return ticks.map(part.year);
500  const [fine, coarse] = TIME_FORMATS[name] as [Format, Format];
501  return ticks.map((t, i) => {
502    const previous = ticks[i - 1];
503    const f1 = fine(t);
504    const f2 = coarse(t);
505    return previous !== undefined && f2 === coarse(previous) ? f1 : `${f1}\n${f2}`;
506  });
507}