Advanced Indexing

vindex

function vindex(
  a: NDArray,
  ...indices: (string | number[] | NDArray)[]
): NDArray

vindex closely corresponds to NumPy’s integer array indexing. It allows selection of arbitrary items in the array based on their N-dimensional index. Each integer array represents a number of indices into that dimension. Advanced indices always are broadcast and iterated as one:

x.vindex(ind_1, ..., ind_m)
// Equivalent to:
// result[i_1, ..., i_M] == x[ind_1[i_1, ..., i_M], ind_2[i_1, ..., i_M],
//                           ..., ind_N[i_1, ..., i_M]]

// Example
const m = np.array([
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9],
]);
m.vindex([0, 1, 2, 2], [0, 0, 1, 2]);
// [1, 4, 8, 9]

const ind = np.array([[0, 1], [1, 2]]);
m.vindex(ind);
// Equivalent to m.vindex(ind, ':')
// [[[1, 2, 3],
//   [4, 5, 6]],
//  [[4, 5, 6],
//   [7, 8, 9]]]

m.vindex(ind, ind);
// [[1, 5],
//  [5, 9]]

m.vindex('1:2', ind);
// [[[4], [5]], [[5, 6]]]
// shape (2, 2, 1)
// note the first dimension is now the last; NumPy would give shape (1, 2, 2)

Normally vindex is called with NDArray or number[] objects, but you can also freely mix in any of the arguments slice accepts. The order of dimensions in the result matches NumPy’s behaviour: if the advanced indices are contiguous, they replace in place; otherwise they are transposed to be the first dimensions.

take

Take elements from an array along an axis. The output preserves the shape of indices: indexing with a 2-D index array produces an output whose indexed-axis is replaced by the index array’s shape. A scalar index reduces rank by one along that axis (NumPy semantics). Legacy number[] callers are unchanged.

function take(
  a: ArrayLike,
  indices: ArrayLike,
  axis?: number
): NDArray

type ArrayLike = NDArrayCore | number | bigint | number[] | number[][] | number[][][];

|-|-|-|-|

Name	Type	Default	Description
`a`	`ArrayLike`	—	Source array.
`indices`	`ArrayLike`	—	Indices of the values to extract. Accepts NDArrays of any rank, nested `number[]`/`number[][]`/`number[][][]`, or a scalar.
`axis`	`number`	`undefined`	Axis along which to select values. When `undefined`, the input array is flattened before indexing.

Returns: NDArray — Array of values taken from a. Its shape is [...a.shape[:axis], ...indices.shape, ...a.shape[axis+1:]].

import * as np from 'numpy-ts';

const a = np.array([10, 20, 30, 40, 50]);
np.take(a, [0, 2, 4]);
// array([10, 30, 50])

const mat = np.array([[1, 2], [3, 4], [5, 6]]);
np.take(mat, [0, 2], 0);
// array([[1, 2],
//        [5, 6]])

// 2-D indices: output preserves the index shape along the indexed axis.
const src = np.array([10, 20, 30, 40, 50]);
const idx2D = np.array([[0, 2], [4, 1]]);
np.take(src, idx2D);
// array([[10, 30],
//        [50, 20]])
// shape [2, 2]

// Scalar index: rank reduces by one along the axis.
np.take(mat, 1, 0);
// array([3, 4])
// shape [2]

put

Replace specified elements of an array with given values.

function put(
  a: NDArray,
  indices: number[],
  values: ArrayLike
): void

Name	Type	Default	Description
`a`	`NDArray`	—	Target array. Modified in-place.
`indices`	`number[]`	—	Flat indices of elements to replace.
`values`	`ArrayLike`	—	Values to place at the target indices. If shorter than `indices`, values are repeated cyclically.

Returns: void — The array a is modified in-place.

import * as np from 'numpy-ts';

const a = np.array([0, 0, 0, 0, 0]);
np.put(a, [1, 3], [10, 20]);
// a is now array([0, 10, 0, 20, 0])

choose

Construct an array from an index array and a list of arrays to choose from.

function choose(a: ArrayLike, choices: ArrayLike[]): NDArray

Name	Type	Default	Description
`a`	`ArrayLike`	—	Index array. Each value selects which array in `choices` to take the corresponding element from.
`choices`	`ArrayLike[]`	—	List of arrays to choose from. All must be broadcastable to the same shape.

Returns: NDArray — Array formed by picking elements from choices according to a.

import * as np from 'numpy-ts';

const choices = [
  np.array([0, 1, 2, 3]),
  np.array([10, 11, 12, 13]),
  np.array([20, 21, 22, 23]),
];
const idx = np.array([0, 2, 1, 0]);

np.choose(idx, choices);
// array([0, 21, 12, 3])

compress

Return selected slices of an array along a given axis.

function compress(condition: ArrayLike, a: ArrayLike, axis?: number): NDArray

Name	Type	Default	Description
`condition`	`ArrayLike`	—	Boolean array selecting which entries to keep. Its length must match the size of `a` along the given axis.
`a`	`ArrayLike`	—	Array from which to extract.
`axis`	`number`	`undefined`	Axis along which to operate. When `undefined`, the array is flattened first.

Returns: NDArray — Array containing only the slices of a where condition is true.

import * as np from 'numpy-ts';

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

np.compress([true, false, true], a, 0);
// array([[1, 2],
//        [5, 6]])

np.compress([true, false], a, 1);
// array([[1],
//        [3],
//        [5]])

select

Return an array drawn from elements in choicelist depending on conditions.

function select(
  condlist: ArrayLike[],
  choicelist: ArrayLike[],
  defaultVal?: ArrayLike
): NDArray

Each element of condlist and choicelist is run through asarray, so plain number[], boolean[], nested arrays, and NDArrays are all accepted. defaultVal is broadcast to the output shape, allowing per-element fall-through values. Existing scalar/NDArray calls behave identically. |-|-|-|-|

Name	Type	Default	Description
`condlist`	`ArrayLike[]`	—	List of boolean array-likes. The first condition that is true determines which choice is used.
`choicelist`	`ArrayLike[]`	—	List of array-likes from which output elements are taken. Must be the same length as `condlist`.
`defaultVal`	`ArrayLike`	`0`	Value used when no condition is satisfied. Broadcasts to the output shape.

Returns: NDArray — Array where element i is taken from choicelist[j][i] for the first j where condlist[j][i] is true, or from defaultVal (broadcast) if no condition is true.

import * as np from 'numpy-ts';

const x = np.arange(6);
const result = np.select(
  [np.less(x, 2), np.greater(x, 3)],
  [x, np.multiply(x, 10)],
  -1
);
// array([0, 1, -1, -1, 40, 50])

// Plain number[] choice and an array defaultVal that broadcasts per-element.
const fallback = np.array([100, 200, 300, 400, 500, 600]);
np.select(
  [np.less(x, 2)],
  [[0, 10, 20, 30, 40, 50]],
  fallback
);
// array([0, 10, 300, 400, 500, 600])

place

Change elements of an array based on a boolean mask and replacement values.

function place(a: NDArray, mask: ArrayLike, vals: ArrayLike): void

Name	Type	Default	Description
`a`	`NDArray`	—	Array to modify in-place.
`mask`	`ArrayLike`	—	Boolean mask. Must be broadcastable to `a`.
`vals`	`ArrayLike`	—	Values to place into `a` where `mask` is true. Cycled if shorter than the number of true values.

Returns: void — The array arr is modified in-place.

import * as np from 'numpy-ts';

const a = np.array([0, 1, 2, 3, 4]);
np.place(a, np.greater(a, 2), [10, 20]);
// a is now array([0, 1, 2, 10, 20])

putmask

Change elements of an array based on a boolean mask.

function putmask(a: NDArray, mask: ArrayLike, values: ArrayLike): void

Name	Type	Default	Description
`a`	`NDArray`	—	Target array. Modified in-place.
`mask`	`ArrayLike`	—	Boolean mask. Where true, `a` is replaced by the corresponding element from `values`.
`values`	`ArrayLike`	—	Replacement values. Cycled if shorter than the number of true entries in `mask`.

Returns: void — The array a is modified in-place.

import * as np from 'numpy-ts';

const a = np.array([1, 2, 3, 4, 5]);
np.putmask(a, np.array([true, false, true, false, true]), [10, 20, 30]);
// a is now array([10, 2, 20, 4, 30])

take_along_axis

Take values from an array by matching indices along an axis.

function take_along_axis(arr: ArrayLike, indices: ArrayLike, axis: number): NDArray

Name	Type	Default	Description
`arr`	`ArrayLike`	—	Source array.
`indices`	`ArrayLike`	—	Indices to take along each slice of `arr`. Must have the same number of dimensions as `arr`.
`axis`	`number`	—	The axis to take along.

Returns: NDArray — Array of values gathered from arr at the given indices along axis.

import * as np from 'numpy-ts';

const a = np.array([[10, 30, 20], [60, 40, 50]]);
const idx = np.argsort(a, 1);

np.take_along_axis(a, idx, 1);
// array([[10, 20, 30],
//        [40, 50, 60]])

put_along_axis

Put values into an array by matching indices along an axis.

function put_along_axis(
  arr: NDArray,
  indices: ArrayLike,
  values: ArrayLike,
  axis: number
): void

Name	Type	Default	Description
`arr`	`NDArray`	—	Destination array. Modified in-place.
`indices`	`ArrayLike`	—	Indices along `axis` where values are placed.
`values`	`ArrayLike`	—	Values to insert. Must be broadcastable to `indices`.
`axis`	`number`	—	The axis along which to put values.

Returns: void — The array arr is modified in-place.

import * as np from 'numpy-ts';

const a = np.zeros([2, 3]);
const idx = np.array([[1], [2]]);
np.put_along_axis(a, idx, 99, 1);
// a is now array([[0, 99, 0],
//                 [0, 0, 99]])

copyto

Copy values from one array to another.

function copyto(dst: NDArray, src: ArrayLike | number | bigint): void

Name	Type	Default	Description
`dst`	`NDArray`	—	Destination array. Modified in-place.
`src`	`ArrayLike \| number \| bigint`	—	Source array or scalar. Must be broadcastable to `dst`.

Returns: void — The array dst is modified in-place.

import * as np from 'numpy-ts';

const dst = np.zeros([3]);
np.copyto(dst, np.array([1, 2, 3]));
// dst is now array([1, 2, 3])

broadcast_to

Broadcast an array to a new shape without copying data.

function broadcast_to(a: ArrayLike, shape: number[]): NDArray

Name	Type	Default	Description
`a`	`ArrayLike`	—	The array to broadcast.
`shape`	`number[]`	—	Target shape. Must be compatible with the input shape under NumPy broadcasting rules.

Returns: NDArray — A read-only view of the original array with the given shape.

import * as np from 'numpy-ts';

const a = np.array([1, 2, 3]);
const b = np.broadcast_to(a, [3, 3]);
// array([[1, 2, 3],
//        [1, 2, 3],
//        [1, 2, 3]])

broadcast_arrays

Broadcast any number of arrays against each other.

function broadcast_arrays(...arrays: ArrayLike[]): NDArray[]

Name	Type	Default	Description
`...arrays`	`ArrayLike[]`	—	Arrays to broadcast.

Returns: NDArray[] — List of arrays with the same shape, broadcast from the inputs.

import * as np from 'numpy-ts';

const a = np.array([[1], [2], [3]]);   // shape [3, 1]
const b = np.array([10, 20]);          // shape [2]

const [ba, bb] = np.broadcast_arrays(a, b);
// ba: array([[1, 1], [2, 2], [3, 3]])      -- shape [3, 2]
// bb: array([[10, 20], [10, 20], [10, 20]]) -- shape [3, 2]

broadcast_shapes

Compute the shape resulting from broadcasting the given shapes together.

function broadcast_shapes(...shapes: number[][]): number[]

Name	Type	Default	Description
`...shapes`	`number[][]`	—	Array shapes to broadcast together.

Returns: number[] — The broadcast shape. Throws: Error if the shapes are not compatible for broadcasting.

import * as np from 'numpy-ts';

np.broadcast_shapes([3, 1], [1, 4]);
// [3, 4]

np.broadcast_shapes([5], [3, 5], [1, 3, 5]);
// [1, 3, 5]

Overview

NDArray

Array Creation

Math

Array Manipulation

Reductions & Statistics

Linear Algebra

Logic & Comparison

Sorting & Searching

Set Operations

Bitwise

Indexing

Gradient & Differences

Polynomials

Random (np.random)

FFT (np.fft)

I/O

Utilities

Advanced Indexing

vindex

take

put

choose

compress

select

place

putmask

take_along_axis

put_along_axis

copyto

broadcast_to

broadcast_arrays

broadcast_shapes

​vindex

​take

​put

​choose

​compress

​select

​place

​putmask

​take_along_axis

​put_along_axis

​copyto

​broadcast_to

​broadcast_arrays

​broadcast_shapes

vindex

take

put

choose

compress

select

place

putmask

take_along_axis

put_along_axis

copyto

broadcast_to

broadcast_arrays

broadcast_shapes