Cumulative Advance/Decline Line

Recompute History Without Looking Ahead

Install and import

bash

npm install fintech-algorithms

import { calculateCumulativeAdvanceDeclineLine } from "fintech-algorithms/market-breadth-and-internals/advance-decline-breadth/cumulative-advance-decline-line";

Signature

calculateCumulativeAdvanceDeclineLine(contract, events, knowledgeCutoff)

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

contract

{
  "metric": "cumulative_issue_count_advance_decline_line",
  "series_id": "SYNTH-ADL-001",
  "continuity_id": "CONTINUITY-ALPHA",
  "venue_id": "SYNTH-X",
  "universe_id": "SYNTH-COMMON-STOCK-V1",
  "calendar_id": "SYNTH-2026-WEEKDAYS",
  "session_type": "regular",
  "comparison_basis": "adjusted-prior-regular-close",
  "seed": 0,
  "seed_lineage_id": "SEED-ALPHA-0",
  "seed_effective_at": "2026-01-04T21:00:00Z",
  "seed_available_at": "2026-01-04T21:00:01Z",
  "expected_sessions": [
    {
      "session_sequence": 1,
      "session_date": "2026-01-05"
    },
    {
      "session_sequence": 2,
      "session_date": "2026-01-06"
    },
    {
      "session_sequence": 3,
      "session_date": "2026-01-07"
    }
  ]
}

events

[
  {
    "event_id": "EV-001-R1",
    "ingest_sequence": 1,
    "revision_number": 1,
    "supersedes_event_id": null,
    "action": "upsert",
    "session_sequence": 1,
    "session_date": "2026-01-05",
    "effective_at": "2026-01-05T21:00:00Z",
    "available_at": "2026-01-05T21:00:05Z",
    "series_id": "SYNTH-ADL-001",
    "continuity_id": "CONTINUITY-ALPHA",
    "venue_id": "SYNTH-X",
    "universe_id": "SYNTH-COMMON-STOCK-V1",
    "calendar_id": "SYNTH-2026-WEEKDAYS"
  },
  {
    "event_id": "EV-002-R1",
    "ingest_sequence": 2,
    "revision_number": 1,
    "supersedes_event_id": null,
    "action": "upsert",
    "session_sequence": 2,
    "session_date": "2026-01-06",
    "effective_at": "2026-01-06T21:00:00Z",
    "available_at": "2026-01-06T21:00:05Z",
    "series_id": "SYNTH-ADL-001",
    "continuity_id": "CONTINUITY-ALPHA",
    "venue_id": "SYNTH-X",
    "universe_id": "SYNTH-COMMON-STOCK-V1",
    "calendar_id": "SYNTH-2026-WEEKDAYS"
  },
  {
    "event_id": "EV-003-R1",
    "ingest_sequence": 3,
    "revision_number": 1,
    "supersedes_event_id": null,
    "action": "upsert",
    "session_sequence": 3,
    "session_date": "2026-01-07",
    "effective_at": "2026-01-07T21:00:00Z",
    "available_at": "2026-01-07T21:00:05Z",
    "series_id": "SYNTH-ADL-001",
    "continuity_id": "CONTINUITY-ALPHA",
    "venue_id": "SYNTH-X",
    "universe_id": "SYNTH-COMMON-STOCK-V1",
    "calendar_id": "SYNTH-2026-WEEKDAYS"
  }
]

Showing 3 of 5 elements.

knowledgeCutoff

"2026-01-11T00:00:00Z"

Call

calculateCumulativeAdvanceDeclineLine(contract, events, knowledgeCutoff)

Returns

object with 14 fields: status, reasons, knowledge_cutoff, seed, points, final_value, causal_prefix_diagnostic, missing_sessions, …

{
  "status": "resolved",
  "reasons": [],
  "knowledge_cutoff": "2026-01-11T00:00:00Z",
  "seed": 0,
  "points": [
    {
      "session_sequence": 1,
      "session_date": "2026-01-05",
      "event_id": "EV-001-R1",
      "revision_number": 1,
      "effective_at": "2026-01-05T21:00:00Z",
      "available_at": "2026-01-05T21:00:05Z",
      "advances": 60,
      "declines": 30,
      "unchanged": 8,
      "excluded": 2,
      "unclassified": 0,
      "universe_size": 100,
      "net_advances": 30,
      "cumulative_line": 30
    },
    {
      "session_sequence": 2,
      "session_date": "2026-01-06",
      "event_id": "EV-002-R1",
      "revision_number": 1,
      "effective_at": "2026-01-06T21:00:00Z",
      "available_at": "2026-01-06T21:00:05Z",
      "advances": 35,
      "declines": 55,
      "unchanged": 8,
      "excluded": 2,
      "unclassified": 0,
      "universe_size": 100,
      "net_advances": -20,
      "cumulative_line": 10
    },
    {
      "session_sequence": 3,
      "session_date": "2026-01-07",
      "event_id": "EV-003-R1",
      "revision_number": 1,
      "effective_at": "2026-01-07T21:00:00Z",
      "available_at": "2026-01-07T21:00:05Z",
      "advances": 40,
      "declines": 40,
      "unchanged": 18,
      "excluded": 2,
      "unclassified": 0,
      "universe_size": 100,
      "net_advances": 0,
      "cumulative_line": 10
    }
  ],
  "final_value": 20,
  "causal_prefix_diagnostic": [],
  "missing_sessions": [],
  "cancelled_sessions": [],
  "contains_provisional": false,
  "ignored_future_event_count": 0,
  "recompute_from_session": null,
  "blocked_from_session": null,
  "metric": "cumulative_issue_count_advance_decline_line"
}

Diagrams

Cumulative Advance/Decline Line — cumulative line staircase

Cumulative Advance/Decline Line — seed shift invariance

Calculation flow

Revision lineage and suffix recomputation

flowchart LR
    A["Session k revision 1"] --> B["Revision 2 names revision 1 as parent"]
    B --> C{"Revision 2 available by cutoff?"}
    C -- "No" --> D["Keep revision 1"]
    C -- "Yes" --> E["Select revision 2"]
    E --> F["Recompute session k"]
    F --> G["Recompute every later session"]
    G --> H["Publish new resolved suffix"]

Causal recurrence and publication flow

flowchart TD
    A["Continuity contract and knowledge cutoff"] --> B["Parse availability time"]
    B --> C{"Event known by cutoff?"}
    C -- "No" --> D["Ignore future event"]
    C -- "Yes" --> E["Validate visible order, identity, and daily evidence"]
    E --> F["Select one contiguous revision chain per session"]
    F --> G{"All expected sessions ready and final?"}
    G -- "No" --> H["Suppress main line and label diagnostic prefix"]
    G -- "Yes" --> I["Add Net Advances in declared calendar order"]
    I --> J["Publish resolved points and final value"]

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

Nasdaq Trader Daily Market Files
Nasdaq Trader Daily Market Summary Definitions
Fidelity advance/decline education
Nasdaq A-D glossary
Evidence boundary