Volatility Quality Index

Install and import#

npm install fintech-algorithms

import { volatilityQualityIndex } from "fintech-algorithms/technical-indicators/range-and-volatility-indicators/volatility-quality-index";

Signature#

volatilityQualityIndex(input)

Volatility Quality Index: accumulates each bar's true range signed by the direction of its close, then smooths the running total with an exponential moving average.

Parameters#

Returns#

TopicResult

series holds raw, the signed true range contributed by each bar, and value, the EMA of the running total of raw. latest carries the last of each. raw has no warm-up at all -- it is zero on the first bar and populated from there on -- which is why ready_at is 0; value carries period - 1 leading nulls.

Warm-up#

The first 0 bars for `raw`, `period - 1` bars for `value` (13 at the default period) positions are null. raw is defined from the first bar, so the result reports ready at index 0 even though value is still null there. Callers reading latest.value on a short history must check for null themselves.

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), 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#

volatilityQualityIndex(input)

Returns#

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

{
  "topic_id": "D07-F06-A06",
  "title": "Volatility Quality Index",
  "state": "calculated",
  "ready": true,
  "ready_at": 0,
  "series": {
    "raw": [
      0,
      3.3838169299999947,
      3.758713730000011,
      3.9386350599999957,
      -3.829996080000001,
      -3.4696505999999943
    ],
    "value": [null, null, null, null, null, null]
  },
  "latest": {
    "raw": -3.1208633100000043,
    "value": 12.394917882563625
  },
  "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 Volatility Quality Index 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 …
• 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…
• Range Efficiency RatioRange Efficiency Ratio: the absolute net close-to-close move across period bars divided by the sum of the high-low ranges ove…
• 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…