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

Excess-Return Index

Install and import#

bash
npm install fintech-algorithms
ts
import { calculate } from "fintech-algorithms/index-and-benchmark-engineering/return-variants/excess-return-index";

Signature#

calculate(data)

Total return less a cash return, giving the return over funding. This is what a futures or swap position on the index actually earns, which is why structured products quote it.

Parameters#

NameTypeNotes
data{ totalReturns: number[]; cashReturns: number[]; baseLevel: number }Both series must cover identical periods; mismatched compounding frequencies are a silent error. baseLevel is the index value at the start of the series; it scales the level but never the returns.

Returns#

{ excessReturns, levels, endingLevel }

Excess returns and the level series they generate.

Errors#

  • When the two return series differ in length — throws

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#

data
{
  "totalReturns": [0.005, -0.002, 0.008, 0.001, -0.004, 0.006],
  "cashReturns": [0.00015, 0.00015, 0.00016, 0.00016, 0.00016, 0.00017],
  "baseLevel": 1000
}

Call#

calculate(data)

Returns#

object with 3 fields: excessReturns, levels, endingLevel

{
  "excessReturns": [0.004849, -0.00215, 0.007839, 0.00084, -0.004159, 0.005829],
  "levels": [1000, 1004.849273, 1002.689171, 1010.548996, 1011.397722, 1007.19098],
  "endingLevel": 1013.061905
}

Diagrams#

Excess-Return Index — article hero
Excess-Return Index — failure guard
Excess-Return Index — worked example

Calculation flow#

Excess-Return Index calculation flow 
flowchart LR
    A["Point-in-time inputs"] --> B["Validate units and timing"]
    B --> C{"Contract feasible?"}
    C -->|No| D["Reject with reason"]
    C -->|Yes| E["Calculate Excess-Return Index"]
    E --> F["Recompute invariants"]
    F --> G{"Checks pass?"}
    G -->|No| D
    G -->|Yes| H["Publish audited output"]
Excess-Return Index methodology state 
stateDiagram-v2
    [*] --> FrozenInputs
    FrozenInputs --> Validated: contract passes
    FrozenInputs --> Rejected: missing or infeasible
    Validated --> Calculated: apply named rule
    Calculated --> Audited: invariants pass
    Calculated --> Rejected: invariant fails
    Audited --> Published: version and timestamp recorded
    Published --> Revised: approved correction
    Revised --> FrozenInputs: rebuild from retained source state

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 Return Variants family#