@teakit/matrix

rollup

Rolls a finer period matrix up to a coarser one, detecting the input period from its shape (no from argument).

import { Matrix } from "@teakit/matrix";

Matrix.rollup({ "2024": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] }, { to: "year" });
// { "2024": [78] }  (default aggregation is sum; "-"/undefined skipped)

Matrix.rollup({ "2024": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] }, { to: "quarter" });
// { "2024": [6, 15, 24, 33] }

Matrix.rollup({ "2024": [10, 20, 30, 40] }, { to: "year" }); // { "2024": [100] }

// Empty target buckets are "-": only January is present here.
Matrix.rollup({ "2024-01": Array(31).fill(1) }, { to: "month" });
// { "2024": [31, "-", "-", "-", "-", "-", "-", "-", "-", "-", "-", "-"] }

// Override the per-bucket aggregation (receives only valid values).
Matrix.rollup(monthMatrix, { to: "year", using: (values) => Arith.sum(...values) });

API Reference

Signature

Matrix.rollup<TCell, TTo extends MatrixRollupTo, TResult>(
  matrix: Matrix<TCell>,
  options: MatrixRollupOptions<TTo, MatrixValueOf<TCell>, TResult>,
): MatrixRollupResult<TTo, TResult>;

Parameters

ParameterTypeRequiredNotes
options.to"year" | "quarter" | "month"YesMust be strictly coarser than the input.
options.using(values) => TResultNoPer-bucket aggregation over valid values, no context. Defaults to sum.

Supported directions: day → month/quarter/year, month → quarter/year, quarter → year.

Returns

A fixed-shape target period matrix, keys ascending, no auto-filled gap years; buckets with no source period or no valid value are "-".

Throws

  • MATRIX_INVALID_ROLLUP_OPTIONS — invalid to or non-function using.
  • MATRIX_UNRECOGNIZED_PERIOD_MATRIX — input is not a recognizable period matrix (mixed or unknown shape).
  • MATRIX_UNSUPPORTED_ROLLUP — same-or-finer target.

Agent Contract

FieldValue
Kindstatic period transform
Canonical namerollup
AliasesNone
Mutates inputsNo
ReturnsMatrixRollupResult<TTo, TResult>

Agent Notes

  • Do not pass from; the input period is detected from key format + row length (see period-shapes).
  • using receives only valid values (no "-"/undefined) and no context.
  • For the opposite direction (coarser → finer) use rolldown.