@teakit/matrix

mean

Averages a matrix, optionally grouped by rows or cols, dividing only by the count of valid values.

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

// Only the valid values count toward the denominator.
Matrix.mean({ "2024": [10, 20, "-", 40, "-", 60, 70, 80, 90, 100, 110, 120] });
// 70  ((10+20+40+60+70+80+90+100+110+120) / 10)

Matrix.mean({ a: [2, 4], b: [10, 20] }, { by: "rows" }); // { a: [3], b: [15] }
Matrix.mean({ a: [2, 4], b: [4, 8] }, { by: "cols" }); // [3, 6]

Matrix.mean({}); // "-"  (no valid values)

// `using` may override the averaging semantics entirely.
Matrix.mean({ a: [1, 2, 3] }, { using: (values) => values.length }); // 3

API Reference

Signature

Matrix.mean<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 valid values. Defaults to arithmetic mean.

Returns

Same shape as sum: a value, a matrix of length-1 rows, or an array, depending on by. Empty buckets are "-".

Throws

  • MATRIX_INVALID_AGGREGATE_OPTIONS — invalid by or non-function using.

Agent Contract

FieldValue
Kindstatic aggregation
Canonical namemean
AliasesNone
Mutates inputsNo
ReturnsMatrixAggregateResult<TKey, TBy, TResult>

Agent Notes

  • The denominator is the count of valid values only; "-" and undefined are excluded, not treated as zero.
  • Unlike sum, a using override is not expected to preserve averaging semantics — it can compute anything from the valid values.