colocate

DataFrame column reordering made simple. Works with pandas and polars.

Installation

uv add colocate

or

pip install colocate

Usage

Just import to register df.relocate():

import polars as pl
import colocate  # Registers df.relocate() and pl.between()

df = pl.DataFrame({
    "age": [25, 30, 35],
    "city": ["NYC", "LA", "Chicago"],
    "id": [1, 2, 3],
    "name": ["Alice", "Bob", "Charlie"],
    "score": [85, 90, 78],
})

Move to first (default)

df.relocate("id")
# ['id', 'age', 'city', 'name', 'score']

df.relocate(["id", "name"])
# ['id', 'name', 'age', 'city', 'score']

Move to last

df.relocate("score", to="last")
# ['age', 'city', 'id', 'name', 'score']

df.relocate(["score", "age"], to="last")
# ['city', 'id', 'name', 'score', 'age']

Move after anchor

df.relocate("name", after="id")
# ['age', 'city', 'id', 'name', 'score']

df.relocate(["name", "age"], after="id")
# ['city', 'id', 'name', 'age', 'score']

Chaining

For complex reordering, chain multiple calls:

(df
    .relocate("id")
    .relocate("name", after="id")
    .relocate("score", to="last")
)
# ['id', 'name', 'age', 'city', 'score']

Column Ranges with pl.between()

For sequential columns (common in survey data), use pl.between():

df = pl.DataFrame({
    "respondent_id": [1],
    "Q1_1": [1], "Q1_2": [2], "Q1_3": [3],
    "Q2_1": [4], "Q2_2": [5],
    "weight": [1.0],
})

df.relocate(pl.between("Q2_1", "Q2_2"))
# ['Q2_1', 'Q2_2', 'respondent_id', 'Q1_1', 'Q1_2', 'Q1_3', 'weight']

df.relocate(pl.between("Q2_1", "Q2_2"), after="respondent_id")
# ['respondent_id', 'Q2_1', 'Q2_2', 'Q1_1', 'Q1_2', 'Q1_3', 'weight']

df.relocate(pl.between("Q1_1", "Q1_3"), to="last")
# ['respondent_id', 'Q2_1', 'Q2_2', 'weight', 'Q1_1', 'Q1_2', 'Q1_3']

Polars Selectors

Full support for polars selectors:

import polars.selectors as cs

df.relocate(cs.last())                    # last column → first
df.relocate(cs.last(), after="id")        # last column → after id
df.relocate(cs.numeric(), to="last")      # all numeric → end
df.relocate(cs.string())                  # all string → first
df.relocate(cs.matches("^Q1_"))           # regex match → first
df.relocate(cs.starts_with("Q2"))         # prefix match → first
df.relocate(cs.by_name("score", "name"))  # specific cols → first

Works with pandas too

import pandas as pd
import colocate

df = pd.DataFrame({...})
df.relocate("id")
df.relocate(["score"], to="last")
df.relocate("name", after="id")

Note: pl.between() is polars-only. For pandas, use explicit column lists.

API

df.relocate(columns, after=None, to=None)

Note: after and to are mutually exclusive.

pl.between(start, end)  # Select columns from start to end (inclusive)

How it works

Under the hood, colocate simply:

1. Computes the new column order (pure list manipulation)
2. Calls df.select(new_order) via narwhals

That's it. Clean and simple.

License

MIT