@teakit/matrix

sum

Sums a matrix, optionally grouped by rows or cols, skipping "-" and undefined.

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

Matrix.sum({ "2024": [1, 2, 3], "2025": [4] }); // 10  (by: "all" default)
Matrix.sum({ "2024": [1, "-", 3, undefined] }); // 4   ("-"/undefined skipped)

Matrix.sum({ "2024": [1, 2], "2025": [3, 4] }, { by: "rows" });
// { "2024": [3], "2025": [7] }

Matrix.sum({ "2024": [1, 2], "2025": [3, 4] }, { by: "cols" });
// [4, 6]

// An empty bucket is "-".
Matrix.sum({ a: ["-", undefined] }); // "-"

// Plug in a custom numeric type via `using` (receives only valid values).
Matrix.sum(matrix, { using: (values) => Arith.sum(...values) });

API Reference

Signature

Matrix.sum<TCell, TKey extends string, TBy extends MatrixAggregateBy>(
  matrix: Matrix<TCell, TKey>,
  options?: MatrixAggregateOptions<TBy, MatrixValueOf<TCell>, TResult>,
): MatrixAggregateResult<TKey, TBy, TResult>;

Parameters

ParameterTypeRequiredNotes
options.by"all" | "rows" | "cols"NoDefaults to "all".
options.using(values) => TResultNoReceives only filtered valid values, no context. Defaults to numeric sum.

Returns

  • by: "all" → a single value (or "-").
  • by: "rows" → a matrix of length-1 rows, keys ascending.
  • by: "cols" → an array, one value per column.

Empty buckets are "-" and do not call using.

Throws

  • MATRIX_INVALID_AGGREGATE_OPTIONS — invalid by or non-function using.

Agent Contract

FieldValue
Kindstatic aggregation
Canonical namesum
AliasesNone (no sumRows/sumCols/sumMatrix)
Mutates inputsNo
ReturnsMatrixAggregateResult<TKey, TBy, TResult>

Agent Notes

  • Express direction with { by: "rows" | "cols" }, never a method-name alias.
  • The built-in default handles number; for Arith/Decimal pass using and keep summation semantics.
  • See also mean and median.