Hilbert Transform Trend/Cycle Mode

Install and import#

npm install fintech-algorithms

import { hilbertTransformTrendCycleMode } from "fintech-algorithms/statistical-time-series/hilbert-and-ehlers-cycle-analytics/hilbert-transform-trend-cycle-mode";

Signature#

hilbertTransformTrendCycleMode(input)

Labels each bar trend or cycle by asking whether the distance from close to its exponential trend exceeds 1.5 times the current Hilbert phasor amplitude. Any contract failure is rethrown as an Error whose message begins topic calculation failed: .

Parameters#

Returns#

TopicResult

Three series, each mirrored in latest: mode is the text trend or cycle, trend is the EMA of close over period, and amplitude is the Hilbert phasor magnitude. parameters echoes the supplied parameters and diagnostics reports causal and input_count. The series have different warm-ups and ready_at follows the earliest of them, 6.

Warm-up#

The first 6 nulls for `amplitude`, and `period - 1` nulls for `trend` and `mode` (19 at the default period of 20) positions are . amplitude needs the 4-bar EMA of close plus three bars of the quadrature filter, so it starts at index 6 and sets ready_at to 6. trend is an EMA seeded from the first full window of period closes, so it starts at index period - 1, and mode needs both, so it starts with trend.

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#

hilbertTransformTrendCycleMode(input)

Returns#

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

{
  "topic_id": "D09-F06-A05",
  "title": "Hilbert Transform Trend/Cycle Mode",
  "state": "calculated",
  "ready": true,
  "ready_at": 6,
  "series": {
    "mode": [null, null, null, null, null, null],
    "trend": [null, null, null, null, null, null],
    "amplitude": [null, null, null, null, null, null]
  },
  "latest": {
    "mode": "trend",
    "trend": 103.9546773984291,
    "amplitude": 0.8769323358697945
  },
  "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 Trend/Cycle Mode 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…
• 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…