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

# Advanced Indexing

> Take, put, compress, select, broadcast, and other advanced array indexing operations.

### vindex

```typescript theme={null}
function vindex(
  a: NDArray,
  ...indices: (string | number[] | NDArray)[]
): NDArray
```

`vindex` closely corresponds to [NumPy's integer array indexing](https://numpy.org/doc/stable/user/basics.indexing.html#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:

```typescript theme={null}
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](https://numpy.org/doc/stable/user/basics.indexing.html#combining-advanced-and-basic-indexing): 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.

```typescript theme={null}
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:]]`.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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`.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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`.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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]
```