fintech-algorithms

McClellan Volume Oscillator

Install and import

bash
npm install fintech-algorithms
ts
import { calculate } from "fintech-algorithms/market-breadth-and-internals/mcclellan-family/mcclellan-volume-oscillator";

Signature

calculate(records, cutoff)

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

records
[
  {
    "session_date": "2026-01-02",
    "session_sequence": 1,
    "effective_at": "2026-01-02T21:00:00Z",
    "available_at": "2026-01-02T21:20:00Z",
    "revision": 0,
    "event_type": "upsert",
    "source_evidence_state": "ready",
    "venue_id": "SYNTH-X",
    "universe_id": "SYNTH-STABLE-200",
    "methodology_id": "close-vs-comparable-prior-close-v1",
    "calendar_id": "SYNTH-WEEKDAY",
    "volume_unit": "shares",
    "volume_adjustment_basis": "reported-unadjusted",
    "advances": 100
  },
  {
    "session_date": "2026-01-05",
    "session_sequence": 2,
    "effective_at": "2026-01-05T21:00:00Z",
    "available_at": "2026-01-05T21:20:00Z",
    "revision": 0,
    "event_type": "upsert",
    "source_evidence_state": "ready",
    "venue_id": "SYNTH-X",
    "universe_id": "SYNTH-STABLE-200",
    "methodology_id": "close-vs-comparable-prior-close-v1",
    "calendar_id": "SYNTH-WEEKDAY",
    "volume_unit": "shares",
    "volume_adjustment_basis": "reported-unadjusted",
    "advances": 100
  },
  {
    "session_date": "2026-01-06",
    "session_sequence": 3,
    "effective_at": "2026-01-06T21:00:00Z",
    "available_at": "2026-01-06T21:20:00Z",
    "revision": 0,
    "event_type": "upsert",
    "source_evidence_state": "ready",
    "venue_id": "SYNTH-X",
    "universe_id": "SYNTH-STABLE-200",
    "methodology_id": "close-vs-comparable-prior-close-v1",
    "calendar_id": "SYNTH-WEEKDAY",
    "volume_unit": "shares",
    "volume_adjustment_basis": "reported-unadjusted",
    "advances": 100
  }
]

Showing 3 of 60 elements.

cutoff
"2026-04-01T00:00:00Z"

Call

calculate(records, cutoff)

Returns

object with 8 fields: status, reason_codes, points, latest_oscillator, latest_index_value, ignored_future_records, seed_policy, initial_index

{
  "status": "resolved",
  "reason_codes": [],
  "points": [
    {
      "observation": 1,
      "input_value": 0,
      "fast_ema": null,
      "slow_ema": null,
      "oscillator": null,
      "index_value": null,
      "status": "warming_fast",
      "session_date": "2026-01-02"
    },
    {
      "observation": 2,
      "input_value": 0,
      "fast_ema": null,
      "slow_ema": null,
      "oscillator": null,
      "index_value": null,
      "status": "warming_fast",
      "session_date": "2026-01-05"
    },
    {
      "observation": 3,
      "input_value": 0,
      "fast_ema": null,
      "slow_ema": null,
      "oscillator": null,
      "index_value": null,
      "status": "warming_fast",
      "session_date": "2026-01-06"
    }
  ],
  "latest_oscillator": 8658.494101161108,
  "latest_index_value": null,
  "ignored_future_records": 0,
  "seed_policy": "sma_19_39",
  "initial_index": null
}

Other exports

This module also exports transformRecord, calculateValues. 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

McClellan Volume Oscillator — family transform
McClellan Volume Oscillator — worked state

Calculation flow

McClellan Volume Oscillator calculation flow 
flowchart TD
    A["Records available at knowledge cutoff"] --> B{"Contiguous, unique, ready evidence?"}
    B -->|No| C["Withhold path and report reason"]
    B -->|Yes| D["Apply McClellan Volume Oscillator input transform"]
    D --> E["SMA-19 fast seed and 10% Trend"]
    D --> F["SMA-39 slow seed and 5% Trend"]
    E --> G{"Both states ready?"}
    F --> G
    G -->|No| H["Warm-up diagnostics"]
    G -->|Yes| I["Fast minus slow oscillator"]
    I --> J["Publish oscillator diagnostics"]
    J --> K["Provenance and current regime"]

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

  • Calculating the McClellan Oscillator — McClellan Financial Publications; Tom McClellan
  • A Subtle Message in the Volume Summation Index — McClellan Financial Publications; Tom McClellan
  • Understanding Oscillators and Other Indicators — McClellan Financial Publications
  • A-D definition — Nasdaq, Inc.
  • Evidence reconciliation