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

Advance/Decline Ratio

Advancing Issues per Declining Issue

Install and import#

bash
npm install fintech-algorithms
ts
import { calculateAdvanceDeclineRatio } from "fintech-algorithms/market-breadth-and-internals/advance-decline-breadth/advance-decline-ratio";

Signature#

calculateAdvanceDeclineRatio(snapshot)

Advances divided by declines. Scale-free where net advances is not, so readings stay comparable as the universe grows — the reason a raw A/D count from the 1960s cannot be compared with one from today.

Parameters#

NameTypeNotes
snapshotBreadthSnapshotOne session's counts with their evidence state and full identity — venue, calendar, session and universe.

Returns#

{ evidence_state, ratio_state, advance_decline_ratio, direction, observed_partition_ratio, observed }

The ratio plus a separate evidence_state and ratio_state, which distinguish a genuine reading from one the data could not support.

Errors#

  • When declines is zero, making the ratio undefined — reported as a ratio_state rather than thrown

Complexity: time O(1), space O(1).

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#

snapshot
{
  "series_id": "SYNTH-ADR",
  "record_id": "ADR-R1",
  "session_date": "2026-01-05",
  "effective_at": "2026-01-05T21:00:00Z",
  "available_at": "2026-01-05T21:05:00Z",
  "venue_id": "SYNTH-X",
  "calendar_id": "SYNTH-CAL",
  "session_id": "regular",
  "universe_id": "SYNTH-100",
  "universe_revision": "U1",
  "listing_id_scheme": "synthetic-listing-id",
  "security_type_policy": "common-equity",
  "comparison_basis": "comparable-prior-close",
  "corporate_action_policy": "provider-adjusted"
}

Showing 14 of 27 fields.

Call#

calculateAdvanceDeclineRatio(snapshot)

Returns#

object with 13 fields: evidence_state, ratio_state, advance_decline_ratio, direction, observed_partition_ratio, selected_record_id, selected_revision, excluded_count, …

{
  "evidence_state": "resolved",
  "ratio_state": "finite",
  "advance_decline_ratio": 2,
  "direction": "advances_dominant",
  "observed_partition_ratio": 2,
  "selected_record_id": "ADR-R1",
  "selected_revision": 1,
  "excluded_count": 0,
  "mover_count": 90,
  "classified_count": 100,
  "coverage_ratio": 1,
  "is_provisional": false,
  "reasons": []
}

Other exports#

This module also exports evaluateAdvanceDeclineRatioAsOf. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams#

Advance/Decline Ratio — ratio balance
Advance/Decline Ratio — same ratio different coverage

Calculation flow#

Evidence and ratio state flow 
flowchart TD
    Q["Declared as-of query"] --> F["Match identity, policy, and available time"]
    F --> N{"Eligible snapshot exists?"}
    N -->|"No"| U["unsupported; no metric"]
    N -->|"Yes"| C{"Revision chain unique, contiguous, linked?"}
    C -->|"No"| A["ambiguous; no metric"]
    C -->|"Yes"| P["Validate category partition and coverage"]
    P --> E{"Final with no exclusions?"}
    E -->|"No"| I["incomplete; observed diagnostic only"]
    E -->|"Yes"| R["resolved evidence"]
    R --> Z{"Universe or denominator edge?"}
    Z -->|"Empty universe"| Z1["empty_universe; null"]
    Z -->|"No movers"| Z2["no_movers; null"]
    Z -->|"No declines"| Z3["no_declines; null"]
    Z -->|"Declines positive"| O["finite A divided by D"]
Correction-aware snapshot lifecycle 
sequenceDiagram
    participant M as Point-in-time security master
    participant P as Comparable closing prices
    participant C as Corporate-action policy
    participant B as Breadth publisher
    participant Q as As-of evaluator

    M->>B: Stable listing roster and universe revision
    P->>B: Current and comparable prior closes
    C->>B: Adjustment and exclusion decisions
    B->>Q: Revision 1 with effective_at and available_at
    Q-->>Q: Use revision 1 before any later correction is available
    B->>Q: Revision 2 supersedes revision 1
    Q-->>Q: Use revision 2 only after its available_at
    B-xQ: Conflicting or broken chain
    Q-->>Q: Return ambiguous rather than guess

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#

  • R01 - Advance/Decline Ratio glossary
  • R02 - Daily Market Files landing page
  • R03 - 2026 Daily Market Statistics CSV
  • R04 - Daily TAQ catalog
  • R05 - TAQ NYSE Closing Prices Client Specification
  • R06 - NYSE Reference Data
  • R07 - NYSE Corporate Actions
  • Evidence boundary

The rest of the Advance/Decline Breadth family#