> ## 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: ArrayLike[], axis?: number | null): NDArray
```

| Name     | Type             | Default | Description                                                                                                                  |
| -------- | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `arrays` | `ArrayLike[]`    | --      | 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: ArrayLike[], axis?: number): NDArray
```

| Name     | Type          | Default | Description                                                  |
| -------- | ------------- | ------- | ------------------------------------------------------------ |
| `arrays` | `ArrayLike[]` | --      | 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: ArrayLike[]): NDArray
```

| Name     | Type          | Default | Description                                         |
| -------- | ------------- | ------- | --------------------------------------------------- |
| `arrays` | `ArrayLike[]` | --      | 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: ArrayLike[]): NDArray
```

| Name     | Type          | Default | Description                  |
| -------- | ------------- | ------- | ---------------------------- |
| `arrays` | `ArrayLike[]` | --      | 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: ArrayLike[]): NDArray
```

| Name     | Type          | Default | Description                  |
| -------- | ------------- | ------- | ---------------------------- |
| `arrays` | `ArrayLike[]` | --      | 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: ArrayLike[]): NDArray
```

| Name     | Type          | Default | Description                    |
| -------- | ------------- | ------- | ------------------------------ |
| `arrays` | `ArrayLike[]` | --      | 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: ArrayLike,
  values: ArrayLike | number | number[],
  axis?: number
): NDArray
```

| Name     | Type        | Default     | Description                                                                  |
| -------- | ----------- | ----------- | ---------------------------------------------------------------------------- |
| `arr`    | `ArrayLike` | --          | Base array.                                                                  |
| `values` | `ArrayLike` | --          | 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, [[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: ArrayLike,
  obj: number | number[],
  values: ArrayLike | number | number[],
  axis?: number
): NDArray
```

| Name     | Type                 | Default     | Description                                                           |
| -------- | -------------------- | ----------- | --------------------------------------------------------------------- |
| `arr`    | `ArrayLike`          | --          | Input array.                                                          |
| `obj`    | `number \| number[]` | --          | Index or indices before which to insert.                              |
| `values` | `ArrayLike`          | --          | 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]
```