Index-of-Indices

Install and import#

bash

npm install fintech-algorithms

import { calculate } from "fintech-algorithms/index-and-benchmark-engineering/strategy-indices/index-of-indices";

Signature#

calculate(data)

Combines several index return streams into one under fixed weights. Straightforward, with one thing to get right: the component returns must be the same variant — mixing a price-return component with a total-return one biases the blend.

Parameters#

Name	Type	Notes
`data`	`{ componentIds: string[]; weights: number[]; componentReturns: number[][]; baseLevel: number }`	`componentReturns` is one series per component, all covering the same periods. `baseLevel` is the index value at the start of the series; it scales the level but never the returns.

Returns#

{ componentIds, portfolioReturns, levels, endingLevel }

The blended return series and level.

Errors#

When the weights and components differ in length, or the return series are ragged — throws

Complexity: time O(n × components), 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

{
  "componentIds": ["Equity", "Bond", "Commodity"],
  "weights": [0.5, 0.3, 0.2],
  "componentReturns": [
    [0.01, 0.002, -0.004],
    [-0.006, 0.003, 0.008],
    [0.004, -0.001, 0.002]
  ],
  "baseLevel": 1000
}

Call#

calculate(data)

Returns#

object with 4 fields: componentIds, portfolioReturns, levels, endingLevel

{
  "componentIds": ["Equity", "Bond", "Commodity"],
  "portfolioReturns": [0.0048, -0.0005, 0.0021, 0.0035, 0],
  "levels": [1000, 1004.8, 1004.2976, 1006.406625, 1009.929048, 1009.929048],
  "endingLevel": 1009.929048
}

Diagrams#

Calculation flow#

Index-of-Indices 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 Index-of-Indices"]
    E --> F["Recompute invariants"]
    F --> G{"Checks pass?"}
    G -->|No| D
    G -->|Yes| H["Publish audited output"]

Index-of-Indices 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#

S&P Dow Jones Indices Index Mathematics Methodology — S&P Dow Jones Indices
S&P DJI Equity Indices Policies & Practices — S&P Dow Jones Indices
FTSE Russell Capping Methodology — FTSE Russell, LSEG
FTSE Russell Index Policy and Methodology Library — FTSE Russell, LSEG
MSCI Global Investable Market Indexes Methodology Library — MSCI
MSCI Minimum Volatility Indexes Methodology — MSCI
S&P Risk Control 2.0 Indices Methodology — S&P Dow Jones Indices
Principles for Financial Benchmarks — International Organization of Securities Commissions
Regulation (EU) 2016/1011 — European Union
Portfolio Selection — Harry Markowitz
On the Properties of Equally-Weighted Risk Contributions Portfolios — Sébastien Maillard, Thierry Roncalli, and Jérôme Teïletche
Fundamental Indexation — Robert Arnott, Jason Hsu, and Philip Moore
FTSE Currency Hedging Methodology Overview — FTSE Russell, LSEG

Index-of-Indices

Install and import#

Signature#

Parameters#

Returns#

Errors#

Worked example#

Input#

Call#

Returns#

Diagrams#

Calculation flow#

How it works#

References#

The rest of the Strategy Indices family#