← tsb playground

insertColumn / popColumn

Column insertion and removal for DataFrames — mirrors pandas.DataFrame.insert() and pandas.DataFrame.pop().

Because tsb DataFrames are immutable, both functions return a new DataFrame rather than mutating the original. popColumn returns both the extracted Series and the resulting DataFrame.

API summary

Example 1 — insertColumn

import { DataFrame, insertColumn } from "tsb";

const df = DataFrame.fromColumns({
  name: ["Alice", "Bob", "Carol"],
  age:  [30, 25, 35],
});
// columns: ["name", "age"]

// Insert "city" between "name" and "age"
const df2 = insertColumn(df, 1, "city", ["NY", "LA", "SF"]);
// df2.columns.values → ["name", "city", "age"]
// df2.col("city").values → ["NY", "LA", "SF"]

// Original is unchanged
// df.columns.values → ["name", "age"]

Example 2 — Insert with a Series

import { DataFrame, Series, insertColumn } from "tsb";

const df = DataFrame.fromColumns({ a: [1, 2, 3], b: [4, 5, 6] });
const salary = new Series({ data: [100_000, 90_000, 120_000], name: "salary" });

const df2 = insertColumn(df, 0, "salary", salary);
// df2.columns.values → ["salary", "a", "b"]

Example 3 — popColumn

import { DataFrame, popColumn } from "tsb";

const df = DataFrame.fromColumns({
  id:   [1, 2, 3],
  name: ["Alice", "Bob", "Carol"],
  age:  [30, 25, 35],
});

// Remove "age" and keep the Series
const { series: ageSeries, df: df2 } = popColumn(df, "age");
// ageSeries.values       → [30, 25, 35]
// df2.columns.values     → ["id", "name"]
// df.columns.values      → ["id", "name", "age"]  ← original unchanged

Example 4 — reorderColumns

import { DataFrame, reorderColumns } from "tsb";

const df = DataFrame.fromColumns({ a: [1], b: [2], c: [3], d: [4] });

// Reverse the column order
const df2 = reorderColumns(df, ["d", "c", "b", "a"]);
// df2.columns.values → ["d", "c", "b", "a"]

// Select a subset (drops columns not listed)
const df3 = reorderColumns(df, ["a", "c"]);
// df3.columns.values → ["a", "c"]   (b and d are dropped)

Example 5 — moveColumn

import { DataFrame, moveColumn } from "tsb";

const df = DataFrame.fromColumns({
  year:  [2020, 2021, 2022],
  value: [10, 20, 30],
  label: ["a", "b", "c"],
});
// columns: ["year", "value", "label"]

// Move "label" to the front
const df2 = moveColumn(df, "label", 0);
// df2.columns.values → ["label", "year", "value"]

Error cases

// Duplicate column name (default: not allowed)
insertColumn(df, 1, "a", [1, 2, 3]);
// → RangeError: Column "a" already exists. Use allowDuplicates=true to permit...

// Out-of-range loc
insertColumn(df, 99, "x", [1, 2, 3]);
// → RangeError: loc=99 is out of range [0, 2].

// Wrong number of values
insertColumn(df, 0, "x", [1]);  // df has 3 rows
// → RangeError: values length 1 does not match DataFrame row count 3.

// Column not found
popColumn(df, "missing");
// → RangeError: Column "missing" not found in DataFrame.

pandas equivalence table