@livefolio/sdk / returnSeries

Function: returnSeries()

returnSeries(series, period, mode?): Series

Defined in: features/indicators/return.ts:66

Computes a rolling period return over a price series.

Math definition:

// Percentage (default):
return[i] = (series[i] - series[i - period]) / series[i - period]

// Absolute:
return[i] = series[i] - series[i - period]

Warmup: the first period bars are consumed as the lookback window for the first output. The first output point corresponds to input index period. The output array is shorter than the input (no undefined placeholders).

Edge cases:

• period <= 0 — throws Error.
• series.length <= period — returns [] (needs strictly more than period bars).
• mode === 'pct' with prev === 0 — produces Infinity or NaN; callers should filter or guard against zero-price series.

Parameters

Parameter	Type	Default value	Description
series	Series	undefined	Input price series sorted in ascending timestamp order.
period	number	undefined	Lookback distance in bars. A value of 1 gives a single-bar (daily) return; larger values give multi-bar returns.
mode	ReturnMode	'pct'	Whether to return a percentage ratio or an absolute difference. Defaults to 'pct'.

Returns

Series

A Series of length max(0, series.length - period). Each point's timestamp t is taken from series[i] (the later of the two bars).

Example

import { returnSeries } from '@livefolio/sdk';

const prices = [
  { t: new Date('2023-01-02'), v: 100 },
  { t: new Date('2023-01-03'), v: 105 },
  { t: new Date('2023-01-04'), v: 110 },
];

const pct = returnSeries(prices, 1);
// pct[0] => { t: new Date('2023-01-03'), v: 0.05 }  // (105-100)/100
// pct[1] => { t: new Date('2023-01-04'), v: ~0.048 } // (110-105)/105

const abs = returnSeries(prices, 1, 'abs');
// abs[0] => { t: new Date('2023-01-03'), v: 5 }  // 105-100
// abs[1] => { t: new Date('2023-01-04'), v: 5 }  // 110-105

// Two-bar return
const twoBar = returnSeries(prices, 2);
// twoBar[0] => { t: new Date('2023-01-04'), v: 0.1 } // (110-100)/100