Range Efficiency Ratio

Install and import#

npm install fintech-algorithms

import { rangeEfficiencyRatio } from "fintech-algorithms/technical-indicators/range-and-volatility-indicators/range-efficiency-ratio";

Signature#

rangeEfficiencyRatio(input)

Range Efficiency Ratio: the absolute net close-to-close move across period bars divided by the sum of the high-low ranges over the same span.

Parameters#

Returns#

TopicResult

series holds a single key, value, a 0-1 efficiency reading; latest.value is its last value. The warm-up is period leading nulls, so ready_at is 14 at the default period.

Warm-up#

The first `period` bars (14 at the default period) positions are null. The numerator compares the close against the close period bars earlier, so it needs one more bar than the range window does. value is also null on any bar where the summed range is zero.

Errors#

• When parameters.period is not an integer >= 2 — throws Error
• When a bar is missing open, high, low, close, or volume, or one of them is not a finite number — throws Error
• When bars are not strictly ordered by timestamp, or a bar's high is below its open, low, or close — 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#

rangeEfficiencyRatio(input)

Returns#

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

{
  "topic_id": "D07-F06-A09",
  "title": "Range Efficiency Ratio",
  "state": "calculated",
  "ready": true,
  "ready_at": 14,
  "series": {
    "value": [null, null, null, null, null, null]
  },
  "latest": {
    "value": 0.07606679254426744
  },
  "parameters": {},
  "diagnostics": {
    "causal": true,
    "input_count": 96
  }
}

Diagrams#

Calculation flow#

flowchart LR
    A["ordered OHLC observations with session calendar, previous "] --> B["Validate order, basis, and finite values"]
    B --> C["Apply the selected Range Efficiency Ratio 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 function groups — see linked primary or authoritative record
• TA-Lib C/C++ API — 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 Range and Volatility Indicators family#

• Normalized ATR and ATR PercentageWilder's Average True Range over period bars, and the same figure restated as a percentage of that bar's close.
• Chaikin VolatilityChaikin Volatility: the percentage change, roc_period bars apart, in an exponential moving average of the bar's high-low range.
• Ulcer IndexUlcer Index: the root mean square of the percentage drawdown from the running peak close, measured across a window of period …
• Relative Volatility IndexRelative Volatility Index: an RSI-shaped 0-100 oscillator that grades the rolling standard deviation of close recorded on up ba…
• Volatility RatioVolatility Ratio: the standard deviation of close-to-close simple returns over a short window divided by the same measure over …
• Volatility Quality IndexVolatility Quality Index: accumulates each bar's true range signed by the direction of its close, then smooths the running tota…
• Average Daily RangeAverage Daily Range: the simple moving average of the bar's high-low range over period bars.
• Gap VolatilityGap Volatility: measures each bar's opening gap -- this open less the prior close -- and the rolling standard deviation of thos…
• High-Low Range PercentageExpresses the bar's high-low range as a percentage of its high-low midpoint: 200 * (high - low) / (high + low).
• Normalized Price RangePlaces the close inside the highest high and lowest low of the last period bars, scaled to a 0-1 position.
• Volatility StopVolatility Stop: a trailing long stop set multiplier ATRs below the highest close of the last period bars, and a short stop…