Trend/Range Regime Classifier

Install and import#

npm install fintech-algorithms

import { trendRangeRegimeClassifier } from "fintech-algorithms/geometric-chart-patterns/market-structure-breakouts-and-regimes/trend-range-regime-classifier";

Signature#

trendRangeRegimeClassifier(input)

Labels each bar trend, range or uncertain by requiring two independent readings to agree: efficiency ratio at or above 0.55 with Choppiness at or below 45 gives trend, efficiency at or below 0.25 with Choppiness at or above 55 gives range, and anything else is uncertain.

Parameters#

Returns#

TopicResult

series and latest carry efficiency, choppiness and the string series regime. The warm-up is uneven: choppiness starts at period - 1 and efficiency at period, so ready_at is 19 with the default while the regime label itself stays null until index 20.

Warm-up#

The first period - 1 bars for choppiness, period bars for efficiency and regime positions are null. ready_at reports the earliest non-null across all series, which is choppiness at index period - 1. A caller reading regime should wait one bar longer, since the label is null whenever either input is.

Errors#

• When period is supplied as a non-integer or as a value below 2 — throws Error
• When a bar's high, low, or close is not a finite number — throws Error

Complexity: time O(n × period), 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#

trendRangeRegimeClassifier(input)

Returns#

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

{
  "topic_id": "D08-F07-A12",
  "title": "Trend/Range Regime Classifier",
  "state": "calculated",
  "ready": true,
  "ready_at": 19,
  "series": {
    "efficiency": [null, null, null, null, null, null],
    "choppiness": [null, null, null, null, null, null],
    "regime": [null, null, null, null, null, null]
  },
  "latest": {
    "efficiency": 0.08092573520497529,
    "choppiness": 58.89834097590164,
    "regime": "range"
  },
  "parameters": {},
  "diagnostics": {
    "causal": true,
    "input_count": 96
  }
}

Diagrams#

Calculation flow#

flowchart LR
    A["ordered OHLC observations, explicit lookbacks and threshol"] --> B["Validate order, basis, and finite values"]
    B --> C["Apply the selected Trend/Range Regime Classifier 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#

• CFA Institute technical-analysis overview — see linked primary or authoritative record
• TA-Lib maintained source — see linked primary or authoritative record
• Long-Term Storage Capacity of Reservoirs — see linked primary or authoritative record
• Evidence decision
• Level 1 evidence map

The rest of the Market Structure, Breakouts, and Regimes family#

• Highest-High and Lowest-Low PrimitivesThe two rolling extremes every breakout rule is built on: the highest high and lowest low over a window of period bars ending…
• Single-Asset New-High/New-Low SignalFlags whether a single instrument's close has cleared the highest high or undercut the lowest low of the preceding period bars.
• Breakout StrengthExpresses how far a close sits beyond its Donchian channel in units of ATR, so a two-tick break in a quiet market and a two-tic…
• Donchian BreakoutThe Donchian channel over the preceding period bars plus the two breakout booleans it implies.
• Opening Range BreakoutFixes the high and low of the session's first opening_bars bars and then tests every later close against that frozen range.
• Price Compression IndexCompares short-horizon volatility to long-horizon volatility as 100 × ATR(short_period) / ATR(long_period).
• Range Expansion IndexScores directional conviction as the signed sum of close-to-close changes over period bars divided by the sum of their absolu…
• Fractal Dimension IndexCompares the total path length walked by close over a window against the straight-line span of that window, on a log scale, and…
• Hurst ExponentA rolling rescaled-range estimate: over each window of period closes it takes the range of the mean-adjusted cumulative sum, …
• Efficiency RatioKaufman's ratio of net displacement to gross travel: the absolute change in close over period bars divided by the sum of the …
• Market Meanness IndexCounts how often close crosses the median of its own period-bar window and reports that as a percentage of the period - 1 o…
• Volatility Regime ClassifierComputes realized volatility as the standard deviation of simple close returns over period bars, then ranks each reading agai…
• Directional PersistenceMaps each bar to +1, -1 or 0 by the sign of its close-to-close change, sums those signs over period bars, and reports the abs…
• Swing Structure DetectorConfirms five-bar swing highs and lows and labels each one against the previous swing of the same kind - HH, LH, HL, LL…
• Higher-High/Lower-Low StructureReduces price to the higher-high / lower-low sequence traders read structure from, labelling each confirmed five-bar swing HH…
• Inside/Outside Bar StructureClassifies each bar against its immediate predecessor as inside (high not above and low not below), outside (high not below…
• Market EntropyTreats each bar as one of three states by the sign of its close change, then reports the Shannon entropy of the state distribut…