Tensor Reduce

Shipping

tensor_reduce

Reduce an N-D array along chosen axes: sum, mean, min, max, product, variance, std

Signature

Inputs

aVector|Matrix|Tensorrequired— The array to reduce.

Outputs

resultScalar|Vector|Matrix|Tensor— The reduced array. Reducing every axis (empty `axes`, `keepdims` off) collapses to a Scalar; otherwise a lower-rank Array.

Parameters

Key	Type	Default	Notes
`reducer`	enum	sum	one of: sum, mean, min, max, prod, var, std
`axes`	text		Comma-separated axes to reduce, e.g. "0" or "-1, 0". Empty = reduce ALL axes (→ scalar). Negative axes count from the end.
`keepdims`	bool	false	Leave the reduced axes in the result as size-1 (numpy keepdims).
`ddof`	int	0	Delta degrees of freedom for var/std: 0 = population, 1 = sample. N−ddof ≤ 0 ⇒ NaN. Active only when reducer is var or std.

Description

Tensor Reduce collapses an array along one or more axes, mirroring numpy's arr.sum(axis=…, keepdims=…). Choose a reducer (sum, mean, min, max, prod, var, std) and the axes to fold over.

axes is a comma-separated list: "0" reduces the first axis, "-1, 0" reduces the last and first, and an empty string reduces all axes to a single value. Negative axes count from the end. With keepdims = true the reduced axes are retained as size-1 dimensions (handy for later broadcasting); with it off they vanish, lowering the rank. When every axis is reduced and dims are dropped, the rank-0 result becomes a plain Scalar.

For var and std, ddof (delta degrees of freedom) selects the normalization: $ddof = 0$ divides by $N$ (population), $ddof = 1$ divides by $N - 1$ (sample); if $N - ddof \leq 0$ the result is NaN.

Units follow the reducer. sum, mean, min, max, and std preserve the input unit. var (which would be unit²) and prod (unitⁿ) drop it, because the data model cannot encode those compound dimensions.

Mathematics

sum : y = \sum_{i \in axis} x_{i}, mean : y = \frac{1}{N} \sum_{i} x_{i}, prod : y = \prod_{i} x_{i}

var = \frac{1}{N - ddof} i \sum (x_{i} - \overset{x}{ˉ})^{2}, std = var

rank (result) = {rank (x) rank (x) - ∣ axes ∣ keepdims otherwise

Examples

Column sums of a matrix

Feed the $2 \times 3$ matrix [[1,2,3],[4,5,6]] with reducer = sum, axes = "0". Axis 0 (rows) folds away, leaving the per-column sums [5, 7, 9] — a length-3 vector. The unit (e.g. V) is preserved.

Grand total to a scalar

Leave axes empty on the same matrix with reducer = sum: all axes reduce and the rank-0 result collapses to the Scalar 21, still carrying the input unit.

Sample standard deviation

With reducer = std, ddof = 1 on the vector [1,2,3,4], the sample std divides by $N - 1 = 3$ : $\frac{1}{3} \sum (x_{i} - 2.5)^{2} = 5/3 \approx 1.29$ . Set ddof = 0 for the population value $\approx 1.118$ .

Applications

Marginalizing a multi-dimensional field — e.g. summing an image over its color axis or averaging a batch over the sample axis.
Per-axis statistics (mean, std) of a data cube without unpacking, with keepdims enabled for immediate broadcast back against the original.
Collapsing an entire array to a single scalar metric (total energy, peak value) for thresholding or logging.
Computing population vs sample variance/std on array data with an explicit degrees-of-freedom control.

Neat

The same `axes` string grammar (comma list, negative-from-end, empty=all) is shared verbatim with tensor_transpose's `order`, so axis addressing is consistent across the tensor toolkit.

var and prod are the only reducers that drop the unit — a principled consequence of the data model refusing to fake unit² or unitⁿ dimensions rather than silently mislabeling them.

ddof is exposed as an integer with a min of 0 and is UI-gated to appear only for var/std, keeping the panel uncluttered for the other five reducers.

Known issues

An axis index outside the array's rank (e.g. axis 3 on a rank-1 vector) is a hard error, not a clamp.

var and std return NaN when N − ddof ≤ 0 (too few elements for the chosen DOF), which can surface as NaN in downstream chains.

Because var/prod drop units, chaining a var result into a unit-checking additive op treats it as dimensionless.