Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 49 ยท Shapes and Combining

Joining and Splitting

Combine and cut NumPy arrays. Learn concatenate vs stack, vstack, hstack, column_stack, split, array_split, append, insert and delete, with runnable examples.

Data rarely arrives in the shape you need. Monthly files have to be glued into one table, a feature matrix needs one more column, a dataset must be cut into training and test parts. NumPy covers all of this with two families of functions: joining (concatenate, stack and friends) and splitting (split, array_split and friends).

There is one idea to hold on to: joining either extends an existing axis or creates a new one. concatenate extends, stack creates. Once that is clear, the many helper names (vstack, hstack, column_stack...) are only shortcuts. You should also know that NumPy arrays have a fixed size, so every "growing" function returns a brand new array. This lesson builds on reshaping.

concatenate: extend an existing axis

np.concatenate([a, b, ...], axis=0) joins arrays along an axis that already exists. All other dimensions must match exactly. With axis=0 you stack rows below each other; with axis=1 you put columns side by side. axis=None flattens everything first.

flowchart TB
    subgraph R["axis=0: more rows"]
        direction LR
        R1["a (2x2)"] --- R2["b (2x2)"] --> R3["result (4x2)"]
    end
    subgraph C["axis=1: more columns"]
        direction LR
        C1["a (2x2)"] --- C2["b (2x2)"] --> C3["result (2x4)"]
    end

concatenate keeps the number of dimensions and makes one of them longer.

stack: create a new axis

np.stack([a, b], axis=0) requires all arrays to have exactly the same shape and adds a new dimension. The axis argument says where the new axis goes in the result. Stacking three arrays of shape (2, 4) gives (3, 2, 4) for axis=0, (2, 3, 4) for axis=1 and (2, 4, 3) for axis=2.

Python concatenate versus stack

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Compare the last two lines of shapes: concatenate on the same three (2, 4) arrays gives (6, 4), while stack gives a three-dimensional array. A good rule: use stack when the arrays are "the same kind of thing" and you want a collection of them, such as a batch of images, and concatenate when you are making one longer piece out of several.

Both functions raise ValueError with a message that names the mismatch. When you read such a message, check the shapes of your inputs first.

Also note that joining arrays of different dtypes applies the usual promotion rules: joining integers with floats gives floats. See Converting and Casting Types.

The convenience functions

The shortcuts exist because "put these side by side" and "put these on top of each other" are so common. They also promote 1D inputs to a sensible 2D shape, which concatenate does not.

Function What it does
np.vstack Vertical stack: joins along axis 0. A 1D array of length n is treated as a row (1, n).
np.hstack Horizontal stack: joins along axis 1 for 2D, but along axis 0 for 1D arrays.
np.dstack Joins along a third axis (depth), turning (n,) into (1, n, 1) first.
np.column_stack Treats 1D arrays as columns, so each becomes one column of the result.
np.r_, np.c_ Index-style shortcuts: np.r_[1:4, 10, 20] joins pieces; np.c_[x, y] makes columns.
Python vstack, hstack and column_stack

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

hstack of two 1D arrays gives one longer 1D array, but column_stack gives a table with two columns. Mixing those up is a classic source of wrong shapes. The last line shows type promotion: integers joined with a float become float64.

Tip: When in doubt, use concatenate or stack with an explicit axis. The code documents your intent, and you avoid remembering which helper treats 1D input how.

split: cut an array into pieces

np.split(a, n) cuts an array into n equal parts along an axis (default 0) and returns a list of arrays. If the length is not divisible by n, it raises ValueError. Instead of a count, you can pass a list of cut indices: np.split(a, [2, 5]) cuts before index 2 and before index 5, giving three pieces.

np.array_split is the forgiving variant. When the division is not even, the first pieces get one extra element.

np.vsplit and np.hsplit are the splitting counterparts of vstack and hstack (axis 0 and axis 1), and np.dsplit splits along axis 2.

Python split, array_split, hsplit and vsplit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The pieces returned by the split functions are views of the original array, so writing into a piece changes the original. Call .copy() on a piece if you need to modify it independently, for example before shuffling a training set.

A typical use is a train/test split: shuffle the row indices, cut them at 80 percent with np.split(indices, [cut]), and select rows with those index arrays. You will see the shuffling part in Random Numbers with Generators.

append, insert and delete

Three functions mimic list operations, but remember that arrays cannot change size: every call allocates and fills a new array and leaves the input untouched.

  • np.append(a, values, axis=None) adds values at the end. Without axis it flattens both inputs first, which surprises people working with 2D data.
  • np.insert(a, index, values, axis=None) inserts before the given position(s).
  • np.delete(a, index, axis=None) removes the given positions. For boolean conditions, a mask like a[~mask] is often simpler.
Python append, insert and delete

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Look at the output for np.append(m, [9, 9]): without an axis, the 2D array is flattened into a 1D one. Always pass axis for tables.

Do not grow arrays in a loop

Calling np.append inside a loop copies the whole array every time, so the cost grows quadratically with the number of items. Collect pieces in a Python list and join once at the end:

Python
parts = []
for i in range(5):
    parts.append(np.full(2, i))
result = np.concatenate(parts)

Even better, when you know the final size, allocate it once with np.empty or np.zeros and fill it by slicing. See Writing Fast NumPy Code.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You have three arrays of shape (2, 4). What does np.stack([p, q, r]) return?

    stack creates a new axis, and with the default axis=0 the new axis is the first one. concatenate would give (6, 4).
  2. 2. What is the result shape of np.hstack([x, y]) for two 1D arrays of length 3?

    For 1D inputs hstack joins along the only axis and gives one longer 1D array. Use column_stack for a (3, 2) table or vstack for (2, 3).
  3. 3. Why does np.split(np.arange(10), 3) raise an error?

    split demands equal pieces. array_split allows unequal ones and gives the extra elements to the first pieces.
  4. 4. What does np.append(m, [9, 9]) do for a 2D array m when no axis is given?

    Without an axis, append flattens its inputs. Pass axis=0 or axis=1 and make the new data the matching shape to add rows or columns.
  5. 5. What is the best way to build an array from 10,000 small pieces produced in a loop?

    np.append copies the entire array on every call. One concatenate at the end copies each piece only once.

Summary

  • concatenate extends an existing axis; stack creates a new axis and needs equal shapes.
  • vstack, hstack, dstack, column_stack and np.r_/np.c_ are shortcuts that also promote 1D inputs. Prefer an explicit axis when clarity matters.
  • split needs equal parts, array_split does not; vsplit and hsplit cut along axes 0 and 1. The pieces are views.
  • append, insert and delete always return new arrays; pass axis for tables.
  • Never grow an array in a loop: collect a list and join once, or preallocate.

Next, put values in order and find them quickly in Sorting and Searching.