Skip to content

v0.70.0 - Add Shift Method for Time-Series Lag Calculations (2026-04-10)

What Changed?

This release adds the shift method to GroupedFrame, enabling time-series lag calculations within groups. Users can now easily reference previous or next row values for lag/lead analysis, period-over-period comparisons, and feature engineering in machine learning workflows. The feature maintains full backward compatibility with existing code.

What's New

Main Feature: Shift Method for GroupedFrame

What it does: Shifts column values within each group by a specified offset, returning all original rows with the specified column containing shifted values. Positive offset references previous rows (lag), negative offset references next rows (lead), and boundary rows are filled with null.

How to use it:

TypeScript
const df = BareFrame.fromColumns({
  dept: ["eng", "eng", "eng", "hr", "hr"],
  value: [10, 20, 30, 5, 15],
});

// Default: shift by 1 (get previous row's value)
df.groupBy(["dept"]).shift("value");
// dept | value
// eng  | null
// eng  | 10
// eng  | 20
// hr   | null
// hr   | 5

// Shift backward (get next row's value)
df.groupBy(["dept"]).shift("value", -1);
// dept | value
// eng  | 20
// eng  | 30
// eng  | null
// hr   | 15
// hr   | null

Code example:

TypeScript
// Lag: compare each row with previous row
const lag1 = df.groupBy(["dept"]).shift("sales", 1);

// Lead: peek at next row
const lead1 = df.groupBy(["dept"]).shift("sales", -1);

// Multi-lag: get value from 2 periods ago
const lag2 = df.groupBy(["dept"]).shift("sales", 2);

Added

  • GroupedFrame.shift(header: string, offset: number) - Shift values within each group

Changed

  • None

Fixed

  • None

Is It Safe to Upgrade?

  • Breaking Changes: No
  • Backward Compatible: Yes

All existing code continues to work unchanged. New method is purely additive.

Release Details

  • Date: 2026-04-10
  • Version: v0.70.0
  • gaslamp: 131
  • pilotlamp: 89
  • Files Changed: 2
  • Commits:
  • 82d00d1a feat(frame): add shift method to GroupedFrame
  • 0b113c96 docs(api): regenerate TypeDoc output
  • d21c975e bump: version 0.69.0 → 0.70.0

Known Issues

  • None

Next Steps

Consider adding window functions (rolling sum, rolling average) or cumulative functions to BareFrame if use cases emerge.