Hilbert Transform Dominant Cycle Phase

Install and import#

npm install fintech-algorithms

import { hilbertTransformDominantCyclePhase } from "fintech-algorithms/statistical-time-series/hilbert-and-ehlers-cycle-analytics/hilbert-transform-dominant-cycle-phase";

Signature#

hilbertTransformDominantCyclePhase(input)

Returns the instantaneous Hilbert phase angle in radians as atan2(quadrature, in_phase), where both components come from a four-tap filter over the residual of close against its 4-bar EMA. Any contract failure is rethrown as an Error whose message begins topic calculation failed: .

Parameters#

Returns#

TopicResult

One series, phase, mirrored as latest.phase, holding the angle in radians on the atan2 range. parameters echoes the supplied parameters and diagnostics reports causal and input_count. Warm-up is six leading nulls, so ready_at is 6.

Warm-up#

The first 6 positions are . The 4-bar EMA of close first resolves at index 3, and the quadrature filter reads the detrended value at the current bar plus the three before it, so the first defined phase and ready_at are at index 6.

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#

hilbertTransformDominantCyclePhase(input)

Returns#

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

{
  "topic_id": "D09-F06-A02",
  "title": "Hilbert Transform Dominant Cycle Phase",
  "state": "calculated",
  "ready": true,
  "ready_at": 6,
  "series": {
    "phase": [null, null, null, null, null, null]
  },
  "latest": {
    "phase": 2.9490866862859964
  },
  "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 Hilbert Transform Dominant Cycle Phase 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 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 Roofing FilterStacks the two halves of a roof: a two-pole high-pass filter tuned to period removes the slow drift, and an Ehlers Super Smoo…
• Ehlers DecyclerSubtracts a two-pole high-pass residual from close, leaving a trend line with the sub-period wiggle removed and far less la…