tsb — resample()

Overview

resample groups a time-indexed Series or DataFrame into fixed-size time bins (seconds, minutes, hours, days, weeks, months, quarters, or years) and applies an aggregation function to each bin. Empty bins are automatically included in the output, filled with NaN for numeric aggregations or 0 for count/size.

Supported frequencies

Example 1 — Daily sum of a price Series

import { Series, resampleSeries } from "tsb";

const dates = [
  new Date("2024-01-01T09:00Z"),
  new Date("2024-01-01T15:00Z"),
  new Date("2024-01-02T10:00Z"),
  new Date("2024-01-02T16:00Z"),
  new Date("2024-01-04T09:00Z"), // note: Jan 3 is empty
];
const prices = new Series({ data: [100, 105, 98, 110, 120], index: dates, name: "price" });

const daily = resampleSeries(prices, "D").sum();
// Jan 1: 205   Jan 2: 208   Jan 3: NaN (empty)   Jan 4: 120
console.log(daily.index.values.map(d => d.toISOString().slice(0,10)));
console.log(daily.toArray());

Example 2 — Monthly mean with month-start labels

import { Series, resampleSeries } from "tsb";

const timestamps = [
  new Date("2024-01-05Z"), new Date("2024-01-20Z"),
  new Date("2024-02-10Z"), new Date("2024-02-25Z"),
  new Date("2024-03-15Z"),
];
const values = new Series({ data: [10, 20, 30, 40, 50], index: timestamps });

const monthly = resampleSeries(values, "MS").mean();
// Jan: 15   Feb: 35   Mar: 50
console.log(monthly.index.values.map(d => d.toISOString().slice(0,7)));
console.log(monthly.toArray());

Example 3 — OHLC (Open-High-Low-Close) aggregation

import { Series, resampleSeries } from "tsb";

const ticks = [
  new Date("2024-01-01T09:00Z"), new Date("2024-01-01T10:00Z"),
  new Date("2024-01-01T11:00Z"), new Date("2024-01-01T15:00Z"),
];
const px = new Series({ data: [100, 108, 95, 103], index: ticks, name: "AAPL" });

const ohlc = resampleSeries(px, "D").ohlc();
console.log("open :", ohlc.col("open").toArray());
console.log("high :", ohlc.col("high").toArray());
console.log("low  :", ohlc.col("low").toArray());
console.log("close:", ohlc.col("close").toArray());

Example 4 — DataFrame resample with per-column aggregations

import { DataFrame, Index, resampleDataFrame } from "tsb";

const idx = new Index([
  new Date("2024-01-01Z"), new Date("2024-01-01T12:00Z"),
  new Date("2024-01-02Z"), new Date("2024-01-02T18:00Z"),
]);
const df = DataFrame.fromColumns(
  { revenue: [100, 200, 150, 50], visits: [10, 20, 5, 15] },
  { index: idx },
);

// Different aggregation per column
const result = resampleDataFrame(df, "D").agg({
  revenue: "sum",
  visits: "mean",
});
console.log("revenue:", result.col("revenue").toArray()); // [300, 200]
console.log("visits :", result.col("visits").toArray());  // [15, 10]
console.log("index  :", result.index.values.map(d => d.toISOString().slice(0,10)));

Example 5 — Weekly resample (labeled by Sunday)

import { Series, resampleSeries } from "tsb";

// Jan 8 2024 = Monday, Jan 14 = Sunday
const dates = [
  new Date("2024-01-08Z"), new Date("2024-01-10Z"), new Date("2024-01-14Z"),
  new Date("2024-01-15Z"), new Date("2024-01-18Z"),
];
const s = new Series({ data: [1, 2, 3, 4, 5], index: dates });
const weekly = resampleSeries(s, "W").sum();

// Week 1 (ends Jan 14): 1+2+3=6   Week 2 (ends Jan 21): 4+5=9
console.log(weekly.index.values.map(d => d.toISOString().slice(0,10)));
console.log(weekly.toArray());

Example 6 — Custom aggregation function

import { Series, resampleSeries } from "tsb";

const dates = [
  new Date("2024-01-01Z"), new Date("2024-01-01T12:00Z"),
  new Date("2024-01-02Z"),
];
const s = new Series({ data: [2, 4, 8], index: dates });

// Product of each bin
const product = resampleSeries(s, "D").agg((vals) =>
  vals.reduce((acc, v) => (typeof v === "number" ? acc * v : acc), 1)
);
console.log(product.toArray()); // [8, 8]

API Reference

resampleSeries(series, freq, options?)

Returns a SeriesResampler with methods: .sum(), .mean(), .min(), .max(), .count(), .first(), .last(), .std(), .var(), .size(), .ohlc(), .agg(spec).

resampleDataFrame(df, freq, options?)

Returns a DataFrameResampler with the same numeric aggregation methods (each returning a DataFrame), plus .size() (returns a Series), and .agg(spec) where spec can be a per-column object.

options

See also

groupby — label-based grouping · rolling — rolling window · date_range — generate datetime indices