Directional Persistence

Install and import#

npm install fintech-algorithms

import { directionalPersistence } from "fintech-algorithms/geometric-chart-patterns/market-structure-breakouts-and-regimes/directional-persistence";

Signature#

directionalPersistence(input)

Maps 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 absolute total divided by period. It measures one-sidedness without caring which side.

Parameters#

Returns#

TopicResult

series and latest carry a single value key, between 0 and 1. The warm-up is period bars, because the sign at index 0 is undefined and the rolling sum rejects windows containing it, so with the default ready_at is 20.

Warm-up#

The first period bars (20 by default) positions are null. The sign series is null at index 0, so the first complete window of period signs ends at index period.

Errors#

• When period is supplied as a non-integer or as a value below 2 — throws Error
• When a bar's 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#

directionalPersistence(input)

Returns#

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

{
  "topic_id": "D08-F07-A14",
  "title": "Directional Persistence",
  "state": "calculated",
  "ready": true,
  "ready_at": 20,
  "series": {
    "value": [null, null, null, null, null, null]
  },
  "latest": {
    "value": 0.1
  },
  "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 Directional Persistence 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…
• Trend/Range Regime ClassifierLabels each bar trend, range or uncertain by requiring two independent readings to agree: efficiency ratio at or above 0.…
• Volatility Regime ClassifierComputes realized volatility as the standard deviation of simple close returns over period bars, then ranks each reading agai…
• 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…