MACD

Read the Spreads Before You Read the Signals

Install and import#

npm install fintech-algorithms

import { macd } from "fintech-algorithms/technical-indicators/trend-systems/macd";

Signature#

macd(values, fastSpan, slowSpan, signalSpan)

Moving average convergence/divergence: the gap between a fast and a slow EMA, its own EMA as a signal line, and the difference between them as a histogram.

Parameters#

Returns#

{ fast_ema, slow_ema, macd, signal, histogram }[] · length same-as-input

One record per position carrying both EMAs alongside the three published series.

Warm-up#

The first slowSpan − 1 for the MACD line, and slowSpan + signalSpan − 2 for the signal and histogram positions are null. The signal line is an average *of* the MACD line, so it is defined strictly later — plotting the two without allowing for that misaligns them.

Errors#

• When any span is < 1, is not an integer, or fastSpan ≥ slowSpan — throws RangeError

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

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#

[10, 11, 12, 13, 14, 15]

Showing 6 of 14 elements.

3

5

3

Call#

macd(values, fastSpan, slowSpan, signalSpan)

Returns#

object with 5 fields: 4, 6, 7, 9, 12

{
  "4": {
    "fastEma": 13,
    "slowEma": 12,
    "macd": 1,
    "signal": null,
    "histogram": null,
    "status": "warming_signal"
  },
  "6": {
    "fastEma": 15,
    "slowEma": 14,
    "macd": 1,
    "signal": 1,
    "histogram": 0,
    "status": "ready"
  },
  "7": {
    "fastEma": 15,
    "slowEma": 14.333333333333334,
    "macd": 0.6666666666666661,
    "signal": 0.833333333333333,
    "histogram": -0.16666666666666696,
    "status": "ready"
  },
  "9": {
    "macd": -0.06481481481481488,
    "signal": 0.24537037037037002,
    "histogram": -0.3101851851851849,
    "status": "ready"
  },
  "12": {
    "macd": 0.2088048696844993,
    "signal": 0.04260973936899856,
    "histogram": 0.16619513031550073,
    "status": "ready"
  }
}

Diagrams#

Calculation flow#

flowchart LR
    X["Ordered finite source values"] --> F["Fast SMA-seeded EMA"]
    X --> S["Slow SMA-seeded EMA"]
    F --> D{"Both EMAs ready?"}
    S --> D
    D -->|No| W["MACD unavailable"]
    D -->|Yes| M["MACD = fast EMA - slow EMA"]
    M --> G["Signal = SMA-seeded EMA of MACD"]
    M --> H["Histogram = MACD - signal"]
    G --> H
    H --> O["Aligned component row"]

stateDiagram-v2
    [*] --> WarmingPriceEMAs
    WarmingPriceEMAs --> WarmingSignal: "slow_span observations"
    WarmingSignal --> Ready: "signal_span MACD values"
    Ready --> Ready: "append one finalized observation"
    Ready --> RecomputedSuffix: "revise a historical observation"
    RecomputedSuffix --> Ready: "replace affected suffix"

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#

• Primary and authoritative sources
• Claims derived algebraically in this package
• Historical and interpretive caution
• Reproducibility
• Historical example decision

The rest of the Trend Systems family#

• Percentage Price Oscillator (PPO)MACD expressed as a percentage of the slow EMA rather than in price units, which makes readings comparable across instruments a…
• Aroon Up, Down, and OscillatorMeasures how recently the highest high and lowest low occurred within the lookback, expressed as 0–100.
• Directional MovementThe components beneath ADX: directional movement in each direction, Wilder-smoothed, divided by the average true range to give …
• Average Directional Index (ADX)Average directional index: the smoothed magnitude of the gap between +DI and −DI.
• Ichimoku CloudThe five Ichimoku lines.
• Parabolic SARStop-and-reverse: a trailing stop that accelerates toward price while a trend persists and flips side when price crosses it.
• SupertrendAn ATR-scaled band around the median price that ratchets in the direction of the trend and only flips when close crosses it.
• Average Directional Index Rating (ADXR)Runs the Wilder directional-movement system over the bars and returns the smoothed plus_di, minus_di and adx lines togeth…
• Vortex Indicator (+VI/−VI)Sums the upward and downward vortex movements over a rolling window and divides each by the summed true range, giving the paire…
• Choppiness IndexCompares the summed true range over a window against the window's own high-to-low span, on a base-10 log scale normalised by th…
• Trend Intensity IndexSplits each close into the part above and the part below a simple moving average, sums each part over a second window, and repo…
• QStickAverages the candle body, close minus open, over a rolling window, so a positive reading means the window closed above its open…
• Mass IndexTakes the ratio of a 9-period EMA of the high-low range to the 9-period EMA of that EMA, then sums the ratio over a longer wind…
• Vertical Horizontal FilterDivides the highest-to-lowest close span over a window by the sum of the absolute bar-to-bar close changes in that same window,…
• Random Walk Index (High/Low)Scores how far price has travelled against what a random walk would explain, by taking the largest displacement-over-expected-r…
• Trend Trigger FactorCompares the current window's high and low against the immediately prior window's, and reports the buy-minus-sell power as a pe…
• Directional Trend IndexWilder-smooths the net of the upward high moves against the downward low moves, and divides it by the smoothed total of both, g…
• Trend Strength IndexMeasures the absolute gap between a fast and a slow EMA of the close in units of average true range, so the spread is comparabl…