Heikin-Ashi Transform

Install and import#

npm install fintech-algorithms

import { heikinAshiTransform } from "fintech-algorithms/technical-indicators/price-transforms/heikin-ashi-transform";

Signature#

heikinAshiTransform(input)

Rebuilds each bar as a Heikin-Ashi candle, averaging OHLC into the smoothed close and carrying the smoothed open forward from the previous candle.

Parameters#

Returns#

TopicResult

series holds open, high, low and close, the four smoothed candle legs, and latest carries the last element of each. The smoothed close is (open + high + low + close) / 4; the smoothed open is the midpoint of the raw open and close on the first bar and thereafter the midpoint of the previous smoothed open and close; the smoothed high and low extend the raw ones to include both. Every bar produces values, so there is no positional warm-up.

Warm-up#

The first none positions are the first smoothed open is seeded from the first bar's own open and close. ready_at is 0, but the smoothed open is recursive, so the whole series depends on which bar the input starts at. Two runs over different slices of the same history do not agree exactly until the seed has decayed.

Errors#

• When a bar's open, high, low or close is not a finite number — throws Error
• When a high is below the bar's open, low or close — throws Error
• When timestamps are not strictly increasing — throws Error

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

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#

{
  "bars": [
    {
      "timestamp": "2024-01-02",
      "basis": "synthetic-unadjusted",
      "open": 100,
      "high": 101.45,
      "low": 98.695,
      "close": 100,
      "volume": 750000,
      "benchmark": 200
    },
    {
      "timestamp": "2024-01-03",
      "basis": "synthetic-unadjusted",
      "open": 101.49111452,
      "high": 103.38381693,
      "low": 100.05480022,
      "close": 101.78791214,
      "volume": 795117,
      "benchmark": 200.56326135
    },
    {
      "timestamp": "2024-01-04",
      "basis": "synthetic-unadjusted",
      "open": 102.45519048,
      "high": 104.6701838,
      "low": 100.91147007,
      "close": 102.9549389,
      "volume": 840234,
      "benchmark": 201.11020913
    }
  ],
  "parameters": {}
}

Call#

heikinAshiTransform(input)

Returns#

object with 9 fields: topic_id, title, state, ready, ready_at, series, latest, parameters, …

{
  "topic_id": "D07-F08-A05",
  "title": "Heikin-Ashi Transform",
  "state": "calculated",
  "ready": true,
  "ready_at": 0,
  "series": {
    "open": [
      100,
      100.018125,
      100.84876797625,
      101.798356894375,
      102.40147850843749,
      102.53449461546874
    ],
    "high": [101.45, 103.38381693, 104.6701838, 105.01857496, 104.62741155, 104.01164055],
    "low": [98.695, 100.018125, 100.84876797625, 101.0799399, 100.79741547, 100.54198995],
    "close": [
      100.03625,
      101.6794109525,
      102.7479458125,
      103.0046001225,
      102.6675107225,
      102.233242385
    ]
  },
  "latest": {
    "open": 102.4337036124137,
    "high": 102.4337036124137,
    "low": 98.68874251,
    "close": 100.21300550000001
  },
  "parameters": {},
  "diagnostics": {
    "causal": true,
    "input_count": 96
  }
}

Diagrams#

Calculation flow#

flowchart LR
    A["finite, basis-consistent OHLC observations and any require"] --> B["Validate order, basis, and finite values"]
    B --> C["Apply the selected Heikin-Ashi Transform convention"]
    C --> D["Emit value, readiness, and diagnostics"]
    D --> E["Interpret descriptively; test outcomes separately"]
    B -->|invalid or insufficient| X["Withhold output with a reason"]

stateDiagram-v2
    [*] --> Waiting
    Waiting --> Ready: enough valid causal observations
    Waiting --> Rejected: malformed or unsupported input
    Ready --> Calculated: selected formula applied
    Calculated --> Interpreted: diagnostic and limitation retained
    Interpreted --> Ready: next observation arrives
    Rejected --> Waiting: corrected input and deterministic reset

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#

• TA-Lib function groups — see linked primary or authoritative record
• TA-Lib C/C++ API — see linked primary or authoritative record
• TA-Lib maintained source — see linked primary or authoritative record
• Evidence decision
• Level 1 evidence map

The rest of the Price Transforms family#

• Typical PriceAverages each bar's high, low and close into a single representative price.
• Median Price TransformTakes the midpoint of each bar's high and low.
• Weighted CloseAverages high, low and a double-weighted close so the settlement price dominates the bar.
• Average Price TransformAverages all four OHLC prices into one value per bar.
• Log Price TransformTakes the natural logarithm of each close and the first difference of those logs.
• Price RelativeRebases the ratio of close to a benchmark level so the first bar equals base, producing a relative-strength line.
• Normalized Price TransformConverts close into a rolling z-score against its own moving average and standard deviation.