Arms Index (TRIN)

The hidden decision

Two sessions can have the same upside/downside volume ratio and still tell different pressure stories once issue participation is counted.

Arms Index (TRIN) answers one bounded question: is volume more concentrated in advancing or declining issues after controlling for their counts? Its value is not a prediction. Its value is an auditable state whose inputs, time, units, and failure conditions are visible.

By the end, you will be able to calculate the method, reproduce its synthetic case, inspect its implementation trace, and decide when the output must be withheld.

Build the mental model

Build two ratios from the same universe: advancing issues per declining issue and advancing volume per declining-volume share. Divide the first by the second only when all four legs are positive.

Upside/Downside Volume Ratio owns only the volume denominator. TRIN adds an issue-count normalization, so identical volume ratios can produce different TRIN values.

The highlighted family card is a scope boundary. Count breadth, volume composition, recursive pressure, intraday sampling, and causal divergence can all produce lines, but their units and state memories are not interchangeable.

Freeze the contract before calculating

The selected formulation is:

Publish only when all four count and volume legs are strictly positive. Publication invariant: Zero count or zero volume creates an incomplete denominator topology; the package never manufactures infinity or a neutral 1.

The input table in the canonical README defines row fields and units. The parameter table distinguishes a sourced method from package choices such as equality behavior, seed, zero policy, sampling grid, normalized breadth scale, and event timestamp.

Arms Index (TRIN) supports this bounded source role: trin divides the advancing/declining issue ratio by the advancing/declining volume ratio. It does not override the limitations recorded in REFERENCES.md, and it does not establish historical performance.

Reproduce the synthetic result

Every observation below is synthetic. The arithmetic is author-derived:

Both denominators and both numerators are positive. The output is therefore finite and resolved.

The expected output is:

{
  "status": "resolved",
  "value": 0.75
}

The SVG is not a decorative output card. It isolates the algorithm's actual learning obstacle: one displayed number hides two different ratios and four denominator-sensitive legs. Notice the labels and dashed or branched boundaries; color is supplementary.

Calculation flow

The Mermaid diagram renders from visuals/mermaid/calculation-flow.md and follows this pseudocode:

validate four synchronized positive legs
issue_ratio = advances / declines
volume_ratio = advancing_volume / declining_volume
return issue_ratio / volume_ratio with both diagnostics

Validation comes first so bad evidence cannot mutate later state. That rule is especially important for recursive lines, timestamp grids, arming clocks, and right-side pivot confirmation.

Read the implementation

Python and TypeScript both:

1. validate finite inputs and the topic's identity/clock rules;
2. compute the named intermediate values;
3. preserve the trace needed to audit the result; and
4. return a numeric value or typed event only when the publication boundary passes.

They share datasets/canonical-fixture.json, including expected output and parameters. The code avoids provider SDKs and hidden network calls so the teaching arithmetic is fully inspectable.

Use the guided lab

Open visuals/animated/playground.html. Its objective is to change issue participation separately from volume concentration and observe which ratio moves.

The initial screen is the completed canonical state. Back and Step reveal one observation at a time; Play uses the same transition function; Pause stops it; Reset restores the scenario and parameter. Comparison isolates a nearby outcome, while Failure / boundary demonstrates a reason code rather than a persuasive fake value. Reduced-motion Play advances one deterministic step without starting a timer.

The diagnostic panel and audit table should be read together. A smooth chart alone cannot prove denominator topology, chronological completeness, sampling continuity, or causal confirmation.

Operational interpretation

Use the decomposed issue and volume ratios to diagnose whether the headline TRIN value came from counts, volume concentration, or both.

Do not misuse it: Do not interpret a zero leg as neutral, infinity, or 1.0, and do not mix count and volume legs from different exchanges or cutoffs.

Passing the implementation checks proves definition fidelity. It does not prove reversal prediction, causal market explanation, trading profitability, transferability to another universe, or performance after costs.

Edge cases worth testing

• Any zero leg makes the two-ratio topology incomplete in this package.
• TRIN equals 1 only when the issue ratio equals the volume ratio; it is not a default.
• Multiplying both volume legs by the same scale leaves TRIN unchanged.
• Smoothing TRIN is a separate derived series with its own warm-up and identity.

Provider corrections require recomputing the affected tail or event set. A corrected observation that becomes available later must not leak into an earlier point-in-time result.

Evidence and historical boundary

A named historical reconstruction remains deferred. Publication would require a licensed point-in-time universe, exact classification rules, synchronized observations, session and sampling policy, correction lineage, the selected calculation convention, a knowledge cutoff, and redistribution rights.

Using a famous chart without that bundle would make the story stronger and the evidence weaker. The labelled synthetic fixture is therefore the responsible public example.

Summary and handoff

You can now calculate TRIN_t = (A_t/D_t)/(V^+_t/V^-_t), interpret dimensionless ratio, audit the method-specific boundary, and reproduce matching Python and TypeScript behavior. Review Upside/Downside Volume Ratio and Advance/Decline Ratio for the immediate input concept. Continue with Zweig Breadth Thrust in the dependency path.