> ## Documentation Index
> Fetch the complete documentation index at: https://numpyts.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Basic Reductions

> Core reduction functions: sum, prod, mean, std, variance, min, max, median, average, ptp, all, any.

# Basic Reductions

These functions reduce an array along one or more axes, returning either a scalar (when all axes are reduced) or an `NDArray` with fewer dimensions.

***

### ReductionOpts

The reductions `sum`, `prod`, `amax`/`max`, `amin`/`min`, `all`, and `any` accept an optional 4th argument `opts: ReductionOpts` for masked, seeded, or dtype-controlled reductions.

```typescript theme={null}
interface ReductionOpts {
  where?: ArrayLike;
  initial?: number | bigint | boolean;
  dtype?: DType;
}
```

| Field | Type | Description |
| - | - | - |
| `where` | `ArrayLike` | Boolean mask. Positions where `where` is `false` are replaced by the per-op identity before reducing (`0` for `sum`, `1` for `prod`, `-Infinity`/`+Infinity` for `max`/`min`, `true`/`false` for `all`/`any`). |
| `initial` | `number \| bigint \| boolean` | Starting value combined with the result via the op's combiner: `result + initial` for `sum`, `result * initial` for `prod`, `Math.max/min(result, initial)` for `max`/`min`, `result && Boolean(initial)` for `all`, `result \|\| Boolean(initial)` for `any`. |
| `dtype` | `DType` | Input is cast via `astype(dtype)` before the reduction. |

***

### sum

Compute the sum of array elements over the given axis.

```typescript theme={null}
function sum(
  a: NDArray,
  axis?: number | number[],
  keepdims?: boolean,
  opts?: ReductionOpts
): number | bigint | NDArray | Complex;
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `a` | `NDArray` | -- | Input array. |
| `axis` | `number \| number[]` | `undefined` | Axis or axes along which to sum. When `undefined`, sums over the flattened array. |
| `keepdims` | `boolean` | `false` | If `true`, reduced axes are kept as dimensions with size 1. |
| `opts` | `ReductionOpts` | `undefined` | Optional `where` mask, `initial` value, and/or `dtype` cast. See [ReductionOpts](#reductionopts). |

**Returns:** `number` when reducing all axes, `NDArray` when reducing along specific axes.

```typescript theme={null}
import { array, sum } from 'numpy-ts';

const a = array([[1, 2], [3, 4]]);

sum(a);          // 10
sum(a, 0);       // array([4, 6])
sum(a, 1);       // array([3, 7])
sum(a, 0, true); // array([[4, 6]])  -- shape [1, 2]

// Masked sum: only include elements where mask is true.
const mask = array([[true, false], [true, true]]);
sum(a, undefined, false, { where: mask }); // 8

// Seeded sum: start the accumulator at 100.
sum(a, undefined, false, { initial: 100 }); // 110
```

***

### prod

Compute the product of array elements over the given axis.

```typescript theme={null}
function prod(
  a: NDArray,
  axis?: number | number[],
  keepdims?: boolean,
  opts?: ReductionOpts
): number | bigint | NDArray | Complex;
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `a` | `NDArray` | -- | Input array. |
| `axis` | `number \| number[]` | `undefined` | Axis or axes along which to compute the product. When `undefined`, operates on the flattened array. |
| `keepdims` | `boolean` | `false` | If `true`, reduced axes are kept as dimensions with size 1. |
| `opts` | `ReductionOpts` | `undefined` | Optional `where` mask, `initial` value, and/or `dtype` cast. See [ReductionOpts](#reductionopts). |

**Returns:** `number` when reducing all axes, `NDArray` when reducing along specific axes.

```typescript theme={null}
import { array, prod } from 'numpy-ts';

const a = array([[1, 2], [3, 4]]);

prod(a);    // 24
prod(a, 0); // array([3, 8])
prod(a, 1); // array([2, 12])
```

***

### mean

Compute the arithmetic mean along the specified axis.

> [!NOTE]
>
> Integer inputs are automatically converted to `float64` for the result, matching NumPy behavior.

```typescript theme={null}
function mean(
  a: NDArray,
  axis?: number | number[],
  keepdims?: boolean
): number | NDArray | Complex | bigint;
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `a` | `NDArray` | -- | Input array. |
| `axis` | `number \| number[]` | `undefined` | Axis or axes along which to compute the mean. When `undefined`, operates on the flattened array. |
| `keepdims` | `boolean` | `false` | If `true`, reduced axes are kept as dimensions with size 1. |

**Returns:** `number` when reducing all axes, `NDArray` when reducing along specific axes.

```typescript theme={null}
import { array, mean } from 'numpy-ts';

const a = array([[1, 2], [3, 4]]);

mean(a);    // 2.5
mean(a, 0); // array([2, 3])
mean(a, 1); // array([1.5, 3.5])
```

***

### std

Compute the standard deviation along the specified axis.

```typescript theme={null}
function std(
  a: NDArray,
  axis?: number | number[],
  ddof?: number,
  keepdims?: boolean
): number | NDArray;
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `a` | `NDArray` | -- | Input array. |
| `axis` | `number \| number[]` | `undefined` | Axis or axes along which to compute the standard deviation. |
| `ddof` | `number` | `0` | Delta degrees of freedom. The divisor is `N - ddof`, where `N` is the number of elements. Use `ddof=1` for the sample standard deviation. |
| `keepdims` | `boolean` | `false` | If `true`, reduced axes are kept as dimensions with size 1. |

**Returns:** `number` when reducing all axes, `NDArray` when reducing along specific axes.

```typescript theme={null}
import { array, std } from 'numpy-ts';

const a = array([1, 2, 3, 4, 5]);

std(a);              // 1.4142135623730951  (population std)
std(a, undefined, 1); // 1.5811388300841898  (sample std)
```

***

### variance

Compute the variance along the specified axis.

> [!NOTE]
>
> `var` is a reserved word in JavaScript. This function is exported as both `variance` and `var_` (or accessed via the `var` alias if your bundler supports it). Use `variance` to avoid conflicts.

```typescript theme={null}
function variance(
  a: NDArray,
  axis?: number | number[],
  ddof?: number,
  keepdims?: boolean
): number | NDArray;
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `a` | `NDArray` | -- | Input array. |
| `axis` | `number \| number[]` | `undefined` | Axis or axes along which to compute the variance. |
| `ddof` | `number` | `0` | Delta degrees of freedom. The divisor is `N - ddof`. |
| `keepdims` | `boolean` | `false` | If `true`, reduced axes are kept as dimensions with size 1. |

**Returns:** `number` when reducing all axes, `NDArray` when reducing along specific axes.

```typescript theme={null}
import { array, variance } from 'numpy-ts';

const a = array([[1, 2], [3, 4]]);

variance(a);    // 1.25
variance(a, 0); // array([1, 1])
variance(a, 1); // array([0.25, 0.25])
```

***

### amin

Return the minimum of an array or minimum along an axis.

> [!NOTE]
>
> Also exported as `min`. Use `amin` to avoid shadowing `Math.min`.

```typescript theme={null}
function amin(
  a: NDArray,
  axis?: number | number[],
  keepdims?: boolean,
  opts?: ReductionOpts
): number | NDArray | Complex | bigint;
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `a` | `NDArray` | -- | Input array. |
| `axis` | `number \| number[]` | `undefined` | Axis or axes along which to find the minimum. |
| `keepdims` | `boolean` | `false` | If `true`, reduced axes are kept as dimensions with size 1. |
| `opts` | `ReductionOpts` | `undefined` | Optional `where` mask, `initial` value, and/or `dtype` cast. See [ReductionOpts](#reductionopts). |

**Returns:** `number` when reducing all axes, `NDArray` when reducing along specific axes.

```typescript theme={null}
import { array, amin } from 'numpy-ts';

const a = array([[3, 1], [4, 2]]);

amin(a);    // 1
amin(a, 0); // array([3, 1])
amin(a, 1); // array([1, 2])
```

***

### amax

Return the maximum of an array or maximum along an axis.

> [!NOTE]
>
> Also exported as `max`. Use `amax` to avoid shadowing `Math.max`.

```typescript theme={null}
function amax(
  a: NDArray,
  axis?: number | number[],
  keepdims?: boolean,
  opts?: ReductionOpts
): number | NDArray | Complex | bigint;
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `a` | `NDArray` | -- | Input array. |
| `axis` | `number \| number[]` | `undefined` | Axis or axes along which to find the maximum. |
| `keepdims` | `boolean` | `false` | If `true`, reduced axes are kept as dimensions with size 1. |
| `opts` | `ReductionOpts` | `undefined` | Optional `where` mask, `initial` value, and/or `dtype` cast. See [ReductionOpts](#reductionopts). |

**Returns:** `number` when reducing all axes, `NDArray` when reducing along specific axes.

```typescript theme={null}
import { array, amax } from 'numpy-ts';

const a = array([[3, 1], [4, 2]]);

amax(a);    // 4
amax(a, 0); // array([4, 2])
amax(a, 1); // array([3, 4])
```

***

### median

Compute the median along the specified axis.

```typescript theme={null}
function median(
  a: NDArray,
  axis?: number | number[],
  keepdims?: boolean
): number | NDArray;
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `a` | `NDArray` | -- | Input array. |
| `axis` | `number \| number[]` | `undefined` | Axis or axes along which to compute the median. |
| `keepdims` | `boolean` | `false` | If `true`, reduced axes are kept as dimensions with size 1. |

**Returns:** `number` when reducing all axes, `NDArray` when reducing along specific axes.

```typescript theme={null}
import { array, median } from 'numpy-ts';

median(array([3, 1, 4, 1, 5])); // 3
median(array([1, 2, 3, 4]));    // 2.5  (average of middle two)

const a = array([[3, 1], [4, 2]]);
median(a, 0); // array([3.5, 1.5])
```

***

### average

Compute the weighted average along the specified axis.

```typescript theme={null}
function average(
  a: NDArray,
  axis?: number,
  weights?: NDArray,
  keepdims?: boolean,
  returned?: boolean
): number | NDArray | Complex | bigint | [number | NDArray | Complex, number | NDArray];
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `a` | `NDArray` | -- | Input array. |
| `axis` | `number` | `undefined` | Axis along which to compute the average. |
| `weights` | `NDArray` | `undefined` | Weights associated with the values in `a`. If `undefined`, all weights are equal (equivalent to `mean`). |
| `keepdims` | `boolean` | `false` | If `true`, reduced axes are kept as dimensions with size 1. |
| `returned` | `boolean` | `false` | If `true`, returns a tuple `[avg, sum_of_weights]`. Without weights, `sum_of_weights` is the per-slice element count (matching NumPy). |

**Returns:** `number` when reducing all axes, `NDArray` when reducing along specific axes. When `returned=true`, a tuple `[avg, sum_of_weights]` instead.

```typescript theme={null}
import { array, average } from 'numpy-ts';

const a = array([1, 2, 3, 4]);

average(a);                             // 2.5
average(a, undefined, array([4, 3, 2, 1]));    // 2.0  (weighted)

// Return sum of weights alongside the average.
average(a, undefined, array([4, 3, 2, 1]), false, true); // [2.0, 10]
average(a, undefined, undefined, false, true);    // [2.5, 4]  -- element count
```

***

### ptp

Peak to peak (maximum - minimum) value along an axis.

```typescript theme={null}
function ptp(
  a: NDArray,
  axis?: number | number[],
  keepdims?: boolean
): number | NDArray | Complex | bigint;
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `a` | `NDArray` | -- | Input array. |
| `axis` | `number \| number[]` | `undefined` | Axis or axes along which to find the range. |
| `keepdims` | `boolean` | `false` | If `true`, reduced axes are kept as dimensions with size 1. |

**Returns:** `number` when reducing all axes, `NDArray` when reducing along specific axes.

```typescript theme={null}
import { array, ptp } from 'numpy-ts';

const a = array([[1, 5], [3, 2]]);

ptp(a);    // 4  (5 - 1)
ptp(a, 0); // array([2, 3])
ptp(a, 1); // array([4, 1])
```

***

### all

Test whether all array elements along a given axis evaluate to `true`.

```typescript theme={null}
function all(
  a: NDArray,
  axis?: number | number[],
  keepdims?: boolean,
  opts?: ReductionOpts
): boolean | NDArray;
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `a` | `NDArray` | -- | Input array. |
| `axis` | `number \| number[]` | `undefined` | Axis or axes along which to perform the logical AND. |
| `keepdims` | `boolean` | `false` | If `true`, reduced axes are kept as dimensions with size 1. |
| `opts` | `ReductionOpts` | `undefined` | Optional `where` mask, `initial` value, and/or `dtype` cast. See [ReductionOpts](#reductionopts). |

**Returns:** `boolean` when reducing all axes, `NDArray` (with boolean values) when reducing along specific axes.

```typescript theme={null}
import { array, all } from 'numpy-ts';

all(array([1, 2, 3]));    // true
all(array([1, 0, 3]));    // false

const a = array([[1, 0], [1, 1]]);
all(a, 0); // array([true, false])
all(a, 1); // array([false, true])
```

***

### any

Test whether any array element along a given axis evaluates to `true`.

```typescript theme={null}
function any(
  a: NDArray,
  axis?: number | number[],
  keepdims?: boolean,
  opts?: ReductionOpts
): boolean | NDArray;
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `a` | `NDArray` | -- | Input array. |
| `axis` | `number \| number[]` | `undefined` | Axis or axes along which to perform the logical OR. |
| `keepdims` | `boolean` | `false` | If `true`, reduced axes are kept as dimensions with size 1. |
| `opts` | `ReductionOpts` | `undefined` | Optional `where` mask, `initial` value, and/or `dtype` cast. See [ReductionOpts](#reductionopts). |

**Returns:** `boolean` when reducing all axes, `NDArray` (with boolean values) when reducing along specific axes.

```typescript theme={null}
import { array, any } from 'numpy-ts';

any(array([0, 0, 0]));    // false
any(array([0, 1, 0]));    // true

const a = array([[0, 0], [1, 0]]);
any(a, 0); // array([true, false])
any(a, 1); // array([false, true])
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.