Loading tsb runtime…
← Back to playground index

diff & shift — discrete difference and value shifting

diffSeries / diffDataFrame compute the element-wise discrete difference (value[i] - value[i-periods]).
shiftSeries / shiftDataFrame shift values forward or backward by a given number of periods, filling with a configurable value.
Mirrors Series.diff(), Series.shift(), DataFrame.diff(), and DataFrame.shift() from pandas.

1 · Series diff — first discrete difference

Compute s[i] - s[i - periods] for each position. The first periods entries are null. Non-numeric values produce null.

Press ▶ Run to execute

💡 Tip: diffSeries is commonly used to compute returns, velocity, or changes over time.

2 · Series shift — lag and lead values

Shift values forward (positive periods) or backward (negative periods). Vacated positions are filled with fillValue (default null).

Press ▶ Run to execute

💡 Tip: combine shiftSeries with arithmetic to compute returns, lags, or leads.

3 · DataFrame diff — column-wise and row-wise

axis=0 (default): diff each column independently (rows over time).
axis=1: diff across columns within each row.

Press ▶ Run to execute

4 · DataFrame shift — lagging a DataFrame

Shift all columns by the same number of periods. Useful for creating lagged features in machine learning.

Press ▶ Run to execute

💡 Tip: creating multiple lagged columns is a common feature-engineering technique for time series forecasting.

API Reference

// Discrete difference
diffSeries(series: Series<Scalar>, options?: DiffOptions): Series<Scalar>
diffDataFrame(df: DataFrame, options?: DataFrameDiffOptions): DataFrame

interface DiffOptions {
  periods?: number;  // default 1; negative = look forward
}
interface DataFrameDiffOptions extends DiffOptions {
  axis?: 0 | 1 | "index" | "columns";  // default 0
}

// Value shifting
shiftSeries(series: Series<Scalar>, options?: ShiftOptions): Series<Scalar>
shiftDataFrame(df: DataFrame, options?: DataFrameShiftOptions): DataFrame

interface ShiftOptions {
  periods?:   number;  // default 1; negative = shift backward
  fillValue?: Scalar;  // default null
}
interface DataFrameShiftOptions extends ShiftOptions {
  axis?: 0 | 1 | "index" | "columns";  // default 0
}