fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Levels, Changes, Differences, and Returns

Install and import#

bash
npm install fintech-algorithms
ts
import { levelsChangesDifferencesAndReturns } from "fintech-algorithms/foundations/financial-time-series-foundations/levels-changes-differences-and-returns";

Signature#

levelsChangesDifferencesAndReturns(input)

Converts a level series into its period-over-period differences and its simple returns, keeping the original levels alongside them.

Parameters#

NameTypeNotes
inputD00InputReads values, a non-empty list of finite levels, and timestamps, a list of parseable date-time strings of the same length.

Returns#

D00Output

levels echoes the input series. changes and differences are the same list of consecutive first differences, one shorter than the input. returns divides each level by its predecessor and subtracts one.

Errors#

  • When values is absent, empty, or holds a non-finite number — throws RangeError
  • When timestamps and values have different lengths — throws RangeError
  • When the series holds fewer than two observations — throws RangeError
  • When any level other than the last one is zero, which would leave a return undefined — throws RangeError

Complexity: time O(n), space O(n).

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

input
{
  "timestamps": [
    "2025-01-01T00:00:00Z",
    "2025-01-02T00:00:00Z",
    "2025-01-03T00:00:00Z",
    "2025-01-04T00:00:00Z",
    "2025-01-05T00:00:00Z",
    "2025-01-06T00:00:00Z"
  ],
  "values": [100, 102, 101, 104, 106, 105],
  "lag": 1,
  "window": 3,
  "resampleSize": 2,
  "period": 3,
  "stationarityTolerance": 3,
  "alpha": 0.4,
  "splitIndex": 4
}

Call#

levelsChangesDifferencesAndReturns(input)

Returns#

object with 2 fields: levels, changes

{
  "levels": [100, 102, 101, 104, 106, 105],
  "changes": [2, -1, 3, 2, -1]
}

Diagrams#

Levels, Changes, Differences, and Returns — article hero
Levels, Changes, Differences, and Returns — calculation ledger
Levels, Changes, Differences, and Returns — concept anatomy
Levels, Changes, Differences, and Returns — failure boundary
Levels, Changes, Differences, and Returns — method map
Levels, Changes, Differences, and Returns — scenario contrast

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

The rest of the Financial Time-Series Foundations family#