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

# Joining Arrays

> Concatenate, stack, and assemble arrays together.

### concatenate

Join a sequence of arrays along an existing axis. All arrays must have the same shape except along the concatenation axis.

`concat` is an alias for `concatenate`.

```typescript theme={null}
function concatenate(arrays: NDArray[], axis?: number | null): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `arrays` | `NDArray[]` | -- | Sequence of arrays to join. |
| `axis` | `number \| null` | `0` | Axis along which to concatenate. If `null`, each input is raveled (flattened) and the results are concatenated along axis 0. |

**Returns:** `NDArray` -- The concatenated array.

```typescript theme={null}
import * as np from 'numpy-ts';

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

// Concatenate along rows (axis 0)
const c = np.concatenate([a, b], 0);
console.log(c.toArray());
// [[1, 2], [3, 4], [5, 6]]

// Concatenate along columns (axis 1)
const d = np.concatenate([a, a], 1);
console.log(d.toArray());
// [[1, 2, 1, 2], [3, 4, 3, 4]]

// axis=null: ravel inputs and concatenate along axis 0
const f = np.concatenate([a, b], null);
console.log(f.toArray());  // [1, 2, 3, 4, 5, 6]

// Using the alias
const e = np.concat([a, b], 0);
```

***

### stack

Join a sequence of arrays along a **new** axis. All input arrays must have the same shape.

```typescript theme={null}
function stack(arrays: NDArray[], axis?: number): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `arrays` | `NDArray[]` | -- | Sequence of arrays with identical shapes. |
| `axis` | `number` | `0` | Axis in the result along which the input arrays are stacked. |

**Returns:** `NDArray` -- The stacked array with one additional dimension.

```typescript theme={null}
import * as np from 'numpy-ts';

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

// Stack along new axis 0 (default)
const c = np.stack([a, b]);
console.log(c.shape);     // [2, 3]
console.log(c.toArray());  // [[1, 2, 3], [4, 5, 6]]

// Stack along new axis 1
const d = np.stack([a, b], 1);
console.log(d.shape);     // [3, 2]
console.log(d.toArray());  // [[1, 4], [2, 5], [3, 6]]
```

***

### vstack

Stack arrays vertically (row-wise). 1-D arrays of shape `(N,)` are first reshaped to `(1, N)`. Equivalent to `concatenate` along axis 0 after that reshape.

`row_stack` is an alias for `vstack`.

```typescript theme={null}
function vstack(arrays: NDArray[]): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `arrays` | `NDArray[]` | -- | Sequence of arrays. 1-D arrays are promoted to 2-D. |

**Returns:** `NDArray` -- The vertically stacked array.

```typescript theme={null}
import * as np from 'numpy-ts';

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

const c = np.vstack([a, b]);
console.log(c.shape);     // [2, 3]
console.log(c.toArray());  // [[1, 2, 3], [4, 5, 6]]

// Works the same via the alias
const d = np.row_stack([a, b]);
```

***

### hstack

Stack arrays horizontally (column-wise). For 1-D arrays, concatenates along axis 0. For 2-D and higher arrays, concatenates along axis 1.

```typescript theme={null}
function hstack(arrays: NDArray[]): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `arrays` | `NDArray[]` | -- | Sequence of arrays to stack. |

**Returns:** `NDArray` -- The horizontally stacked array.

```typescript theme={null}
import * as np from 'numpy-ts';

// 1-D arrays: simple concatenation
const a = np.array([1, 2, 3]);
const b = np.array([4, 5, 6]);
console.log(np.hstack([a, b]).toArray());  // [1, 2, 3, 4, 5, 6]

// 2-D arrays: concatenate along axis 1
const c = np.array([[1], [2]]);
const d = np.array([[3], [4]]);
console.log(np.hstack([c, d]).toArray());  // [[1, 3], [2, 4]]
```

***

### dstack

Stack arrays depth-wise (along the third axis). 1-D arrays `(N,)` are reshaped to `(1, N, 1)` and 2-D arrays `(M, N)` to `(M, N, 1)` before stacking.

```typescript theme={null}
function dstack(arrays: NDArray[]): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `arrays` | `NDArray[]` | -- | Sequence of arrays to stack. |

**Returns:** `NDArray` -- The depth-stacked array (at least 3-D).

```typescript theme={null}
import * as np from 'numpy-ts';

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

const c = np.dstack([a, b]);
console.log(c.shape);     // [1, 3, 2]
console.log(c.toArray());  // [[[1, 4], [2, 5], [3, 6]]]
```

***

### column\_stack

Stack 1-D arrays as columns into a 2-D array. 1-D inputs are first reshaped to column vectors `(N, 1)`, then horizontally stacked. 2-D and higher arrays are passed through to `hstack` unchanged.

```typescript theme={null}
function column_stack(arrays: NDArray[]): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `arrays` | `NDArray[]` | -- | Sequence of 1-D or 2-D arrays. |

**Returns:** `NDArray` -- 2-D array with each 1-D input as a column.

```typescript theme={null}
import * as np from 'numpy-ts';

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

const c = np.column_stack([a, b]);
console.log(c.shape);     // [3, 2]
console.log(c.toArray());
// [[1, 4],
//  [2, 5],
//  [3, 6]]
```

***

### block

Assemble an array from nested sequences of blocks. Each level of nesting concatenates along a different axis: the innermost list concatenates along axis `-1`, the next level along axis `-2`, and so on outward (matching NumPy's semantics).

```typescript theme={null}
function block(arrays: NestedNDArrays[]): NDArray

type NestedNDArrays = NDArrayCore | NestedNDArrays[];
```

| Name | Type | Default | Description |
| - | - | - | - |
| `arrays` | `NestedNDArrays[]` | -- | Nested list of arrays. Innermost lists are concatenated along axis `-1`, the next level along axis `-2`, etc. A flat list `[a, b]` concatenates along the last axis. |

**Returns:** `NDArray` -- The assembled array.

```typescript theme={null}
import * as np from 'numpy-ts';

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

// Flat list: concatenate along the last axis
const c = np.block([a, b]);
console.log(c.toArray());
// [[1, 2, 5, 6],
//  [3, 4, 7, 8]]

// Nested list: inner along axis -1, outer along axis -2
const d = np.array([[ 9, 10], [11, 12]]);
const e = np.array([[13, 14], [15, 16]]);
const f = np.block([[a, b], [d, e]]);
console.log(f.toArray());
// [[ 1,  2,  5,  6],
//  [ 3,  4,  7,  8],
//  [ 9, 10, 13, 14],
//  [11, 12, 15, 16]]
```

***

### append

Append values to the end of an array. When no axis is given, both arrays are flattened before concatenation.

```typescript theme={null}
function append(
  arr: NDArray,
  values: NDArray | number | number[],
  axis?: number
): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `arr` | `NDArray` | -- | Base array. |
| `values` | `NDArray` | -- | Values to append. |
| `axis` | `number` | `undefined` | Axis along which to append. If `undefined`, both inputs are flattened first. |

**Returns:** `NDArray` -- A copy of `arr` with `values` appended.

```typescript theme={null}
import * as np from 'numpy-ts';

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

// Append without axis: flattens and concatenates
const b = np.append(a, [4, 5, 6]);
console.log(b.toArray());  // [1, 2, 3, 4, 5, 6]

// Append along an axis
const c = np.array([[1, 2], [3, 4]]);
const d = np.append(c, np.array([[5, 6]]), 0);
console.log(d.toArray());
// [[1, 2], [3, 4], [5, 6]]
```

***

### insert

Insert values into an array before specified indices.

```typescript theme={null}
function insert(
  arr: NDArray,
  obj: number | number[],
  values: NDArray | number | number[],
  axis?: number
): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `arr` | `NDArray` | -- | Input array. |
| `obj` | `number \| number[]` | -- | Index or indices before which to insert. |
| `values` | `NDArray` | -- | Values to insert. |
| `axis` | `number` | `undefined` | Axis along which to insert. If `undefined`, `arr` is flattened first. |

**Returns:** `NDArray` -- A copy of `arr` with `values` inserted.

```typescript theme={null}
import * as np from 'numpy-ts';

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

// Insert a single value
const b = np.insert(a, 2, 99);
console.log(b.toArray());  // [1, 2, 99, 3, 4, 5]

// Insert multiple values
const c = np.insert(a, [1, 3], [10, 20]);
console.log(c.toArray());  // [1, 10, 2, 3, 20, 4, 5]
```


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