Factor Diffusion Index

The operational question

Market breadth is not one idea. A headline move can be driven by a few constituents, a weight vector can be concentrated before any return occurs, and a signal can spread across sectors or factor sleeves without those components being independent. Factor Diffusion Index owns one precise question: how broadly is a declared signal improving across a fixed set of factor sleeves?

Several factor sleeves can improve together because they share holdings. This diagnostic counts participation while keeping that overlap limitation visible. That is a diagnostic and governance outcome, not a forecast, recommendation, legal classification, or promise of diversification.

Intuition before notation

Treat each factor sleeve as one component of a breadth panel; the output describes cross-factor participation, not a provider factor index. Sector diffusion spans industry groups; factor diffusion spans systematic strategy sleeves whose holdings may overlap heavily.

The family map prevents a category error. Contribution combines beginning weight and realized return. HHI and effective N inspect the weight vector before returns. Diffusion scores direction across a fixed component panel. Choosing the wrong branch may produce valid arithmetic that answers the wrong question.

Freeze the series identity

The selected formula is:

Apply the declared signal, horizon, direction convention, and tolerance to each factor sleeve, then average 1/0.5/0 scores. Factor identities, construction methods, return basis, currency, horizon, availability time, and tolerance are part of the series identity. The relevant primary source establishes the underlying convention; the exact diagnostic, translated universe, and parameters remain package choices where stated.

The snapshot needs unique identifiers, finite values, complete coverage, and one point-in-time methodology. as_of is not enough in production: retain observation, availability, and knowledge times plus source owner, revision, and finality. A later corrected roster or classification must not overwrite what was knowable at the earlier cutoff.

Required input

Output and refusal behavior

Return value from 0 to 100 and class counts. The score describes equal-sleeve directional participation only; it is not a provider factor index, diversification ratio, or independence statistic.

The reference API deliberately matches sector-diffusion arithmetic while enforcing factor-sleeve identity in the data contract. The lab changes tolerance and scenarios without pretending the votes are independent.

Read the mathematics, not only the score

The 1/0.5/0 transform is identical to sector diffusion, but the component identity is a fixed factor-sleeve methodology. Exact tolerance equality is unchanged, and every sleeve receives one vote regardless of assets or holdings overlap.

• 0 <= D_factor <= 100 and class counts sum to the fixed sleeve count.
• Exact +tolerance and -tolerance observations are unchanged.
• Replacing a provider methodology, factor definition, currency, horizon, or signal creates a new series.
• A high score does not imply independent exposures: Value, Quality, Momentum, and other sleeves may own many of the same securities.

The output must travel with its series identity and diagnostic trace. A bare number strips away the universe, methodology, horizon, tolerance, and evidence status needed to interpret it.

Work the synthetic example

The following is labelled synthetic and all arithmetic is author-derived:

The exact expected result is:

{
  "status": "resolved",
  "value": 62.5,
  "improving": 4,
  "unchanged": 2,
  "deteriorating": 2,
  "total": 8
}

The visual keeps the distribution beside the aggregate. That matters because two identical aggregate values can conceal different component states. The values are synthetic teaching inputs; the displayed result is author-derived arithmetic.

Compare nearby methods

The comparison is part of the contract. A different numerator, denominator, component universe, weighting rule, tolerance, or signal horizon is not a cosmetic option—it defines a different series.

Implementation walkthrough

The reference algorithm validates before aggregating:

validate a fixed set of provider/methodology-identified factor sleeves
validate synchronized signal, return basis, currency, horizon, and tolerance
classify each sleeve with strict tolerance boundaries
assign scores 1, 0.5, or 0 and average equal votes
return value, class counts, and sleeve-level trace

Validate provider and methodology identity before arithmetic, preserve sleeve-level classes, and route independence questions to covariance rather than the diffusion score.

Python and TypeScript consume the same JSON fixture and return the same resolved fields. Invalid or incomplete input raises rather than being repaired. The playground deliberately translates its failure fixture into a visible withheld state because its job is to teach the refusal boundary.

Guided lab

Open the guided playground. Start from the informative canonical state, switch to Comparison, then Failure / boundary. Use Back and Step to inspect how each component enters the result. Change the tolerance and compare broad factor participation, a split panel, and an incomplete sleeve set. Reset restores the exact canonical state, and reduced-motion Play advances one deterministic observation without starting a timer.

The calculation flow shows why point-in-time validation precedes aggregation.

Put the diagnostic into an operating workflow

Use the panel to ask whether a declared signal is improving across the same strategy sleeves. Pair it with holdings-overlap or covariance analysis before making any statement about diversification.

A robust dashboard retains the input snapshot, formula version, parameters, component trace, and refusal reason. It should make methodology or taxonomy changes visible as breaks in series identity rather than quietly splicing them into history.

Edge cases and misuse boundaries

Do not imply independence among factors, mix provider constructions, or call a high reading a forecast of aggregate market return. Missing components are neither zero nor unchanged. A different roster, taxonomy, factor provider, share-class policy, currency, return basis, horizon, or tolerance defines a different series.

Main takeaway: Cross-factor participation is useful, but equal votes across overlapping sleeves are not independent bets.

Passing implementation tests proves that the code matches the selected definition. It does not prove association with future returns, usefulness after costs, causation, or suitability for an investment decision.

Evidence and historical boundary

The source records in REFERENCES.md establish only the claims mapped to them. They do not establish the synthetic numbers or silently define this package's translated universe and parameters.

A named historical case is deferred until fixed licensed factor-sleeve methodologies, complete same-basis signals, availability timestamps, holdings-overlap evidence, revisions, and redistribution permission. Deferral is a publication boundary, not a missing-data invitation: the public tutorial uses a transparent synthetic case rather than an irreproducible observed value.

Summary and handoff

You can now calculate D_{\mathrm{factor}}=100\frac{N_+ + 0.5N_0}{N}, identify the series-defining choices, interpret its edge regimes, preserve the audit trace, and reject incomplete snapshots. Continue with Covariance.

Primary sources and exact limitations are recorded in REFERENCES.md.