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

Ehlers Instantaneous Trendline

Install and import#

bash
npm install fintech-algorithms
ts
import { ehlersInstantaneousTrendline } from "fintech-algorithms/technical-indicators/trend-smoothing/ehlers-instantaneous-trendline";

Signature#

ehlersInstantaneousTrendline(input)

Splits close into a smoothed centre line and what is left over: the trendline is an EMA of max(4, period) and the detrended series is the bar's close minus that trendline.

Parameters#

NameTypeNotes
inputTopicInputbars is a non-empty array of OHLCV records with strictly increasing timestamp, finite open, high, low, close and non-negative volume, all sharing one adjustment basis. From parameters this topic reads only period, an integer of at least 2, default 14. The EMA length is max(4, period), so periods of 2 and 3 are both treated as 4.

Returns#

TopicResult

series and latest carry two keys, trendline and detrended. Both are null for the first max(4, period) - 1 bars while the EMA seeds, so with the default period ready_at is 13.

Warm-up#

The first max(4, period) - 1 bars (13 at the default period of 14) positions are null. The EMA seeds from the mean of its first max(4, period) closes, so the trendline first prints at index max(4, period) - 1, and detrended is null wherever the trendline is. ready_at is that index.

Errors#

  • When parameters.period is not an integer of at least 2 — throws Error
  • When bars is empty, or a bar has a non-finite price, a negative volume, or a timestamp that does not increase — 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#

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#

ehlersInstantaneousTrendline(input)

Returns#

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

{
  "topic_id": "D07-F01-A24",
  "title": "Ehlers Instantaneous Trendline",
  "state": "calculated",
  "ready": true,
  "ready_at": 13,
  "series": {
    "trendline": [null, null, null, null, null, null],
    "detrended": [null, null, null, null, null, null]
  },
  "latest": {
    "trendline": 103.6493158929627,
    "detrended": -3.6585014229627006
  },
  "parameters": {},
  "diagnostics": {
    "causal": true,
    "input_count": 96
  }
}

Diagrams#

Ehlers Instantaneous Trendline — article hero
Ehlers Instantaneous Trendline — concept map
Ehlers Instantaneous Trendline — decision comparison
Ehlers Instantaneous Trendline — worked example

Calculation flow#

Ehlers Instantaneous Trendline calculation flow 
flowchart LR
    A["an oldest-to-newest finite price series, declared price so"] --> B["Validate order, basis, and finite values"]
    B --> C["Apply the selected Ehlers Instantaneous Trendline 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"]
Ehlers Instantaneous Trendline readiness and evidence states 
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 Trend Smoothing family#