Top-N Index Contribution
Install and import#
npm install fintech-algorithmsimport { calculate } from "fintech-algorithms/market-breadth-and-internals/concentration-and-diffusion/top-n-index-contribution";Signature#
calculate(rows, topN)How much of an index's move came from its largest N members. This is the arithmetic behind 'seven stocks are holding up the market' — a claim that is usually asserted and rarely measured.
Parameters#
| Name | Type | Notes |
|---|---|---|
rows | Row[] | Constituents with weight, return and sector. Rows carry a ready flag; a row that is not ready is excluded rather than treated as zero, because a missing count and a count of zero mean opposite things about market breadth. |
topN | number | How many leading contributors to attribute separately. min: 1 · integer: true |
Returns#
{ status, top_n, top_contribution, total_contribution, share, leaders }
The leaders' contribution, the total, and the share — plus the leaders themselves, so the claim can be named rather than gestured at.
Errors#
- When topN exceeds the number of ready constituents — reported as a status rather than thrown
Complexity: time O(n log n),
space O(n).
Worked example#
executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.
Input#
[
{
"security_id": "S01",
"weight": 0.17821782178217824,
"return": 0.065,
"sector": "Tech",
"ready": true
},
{
"security_id": "S02",
"weight": 0.13861386138613863,
"return": 0.041,
"sector": "Financials",
"ready": true
},
{
"security_id": "S03",
"weight": 0.10891089108910892,
"return": 0.028,
"sector": "Industrials",
"ready": true
}
]Showing 3 of 24 elements.
5Call#
calculate(rows, topN)Returns#
object with 6 fields: status, top_n, top_contribution, total_contribution, share, leaders
{
"status": "resolved",
"top_n": 5,
"top_contribution": 0.02225742574257426,
"total_contribution": 0.021676237623762376,
"share": 1.0268122230850045,
"leaders": [
{
"security_id": "S01",
"contribution": 0.011584158415841586
},
{
"security_id": "S02",
"contribution": 0.005683168316831684
},
{
"security_id": "S03",
"contribution": 0.00304950495049505
}
]
}Diagrams#
Calculation flow#
Calculation Flow — Top-N Index Contribution
flowchart LR
A["Point-in-time component snapshot"] --> B{"Complete, unique, finite?"}
B -->|"No"| X["Incomplete — withhold value"]
B -->|"Yes"| C["Apply Top-N Index Contribution contract"]
C --> D["Retain component audit trace"]
D --> E["Publish value, unit, parameter, and as-of"]
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.
References#
- Claim-to-source map
- S&P Dow Jones Indices: Index Mathematics Methodology — S&P Dow Jones Indices