Ehlers Roofing Filter

Install and import#

npm install fintech-algorithms

import { ehlersRoofingFilter } from "fintech-algorithms/statistical-time-series/hilbert-and-ehlers-cycle-analytics/ehlers-roofing-filter";

Signature#

ehlersRoofingFilter(input)

Stacks the two halves of a roof: a two-pole high-pass filter tuned to period removes the slow drift, and an Ehlers Super Smoother run at half that span removes the fast noise, leaving the band in between. Any contract failure is rethrown as an Error whose message begins topic calculation failed: .

Parameters#

Returns#

TopicResult

Two series, both mirrored in latest: high_pass is the intermediate high-pass residual and value is that residual after the Super Smoother pass. parameters echoes the supplied parameters and diagnostics reports causal and input_count. There is no null prefix at all, so the warm-up is zero bars and ready_at is 0.

Warm-up#

The first 0 positions are no nulls are emitted. Both stages are seeded rather than gated. The high-pass recursion holds its first two outputs at zero, and the Super Smoother copies its input for its first two bars, so every index carries a number and ready_at is 0. The opening bars are seed values, not converged filter output.

Errors#

• When parameters.period is present but is not an integer of at least 4 — throws Error
• When bars is empty, a timestamp is missing or not strictly increasing, an OHLCV field is not finite, volume is negative, or high and low do not bracket open and close — 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#

ehlersRoofingFilter(input)

Returns#

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

{
  "topic_id": "D09-F06-A07",
  "title": "Ehlers Roofing Filter",
  "state": "calculated",
  "ready": true,
  "ready_at": 0,
  "series": {
    "high_pass": [
      0,
      0,
      -0.46270692883549364,
      -1.335377436005075,
      -2.201684726094235,
      -2.614761522250397
    ],
    "value": [
      0,
      0,
      -0.058577494525456325,
      -0.29546823437612796,
      -0.7658592036228475,
      -1.375141122806132
    ]
  },
  "latest": {
    "high_pass": -1.4080590702156108,
    "value": -1.0173197105824179
  },
  "parameters": {},
  "diagnostics": {
    "causal": true,
    "input_count": 96
  }
}

Diagrams#

Calculation flow#

flowchart LR
    A["uniformly sampled finite prices with declared prefilter, c"] --> B["Validate order, basis, and finite values"]
    B --> C["Apply the selected Ehlers Roofing Filter 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 cycle indicator group — see linked primary or authoritative record
• SciPy analytic-signal documentation — 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 Hilbert and Ehlers Cycle Analytics family#

• Hilbert Transform Dominant Cycle PeriodEstimates the dominant cycle length in bars from the bar-to-bar change in the Hilbert phase angle, clamping each raw estimate i…
• Hilbert Transform Dominant Cycle PhaseReturns the instantaneous Hilbert phase angle in radians as atan2(quadrature, in_phase), where both components come from a fo…
• Hilbert Transform Phasor ComponentsExposes the raw phasor behind the Hilbert cycle family: the in-phase component, its quadrature partner from the four-tap filter…
• Hilbert Transform SineWaveTurns the Hilbert phase angle into the classic sinewave pair, the sine of the phase and a lead sine shifted a quarter turn ahea…
• Hilbert Transform Trend/Cycle ModeLabels each bar trend or cycle by asking whether the distance from close to its exponential trend exceeds 1.5 times the c…
• Ehlers Cyber CycleRuns close through a two-pole high-pass filter tuned to period, then smooths the residual with an EMA of the same span, lea…
• Ehlers DecyclerSubtracts a two-pole high-pass residual from close, leaving a trend line with the sub-period wiggle removed and far less la…