Percentage Volume Oscillator

Install and import#

npm install fintech-algorithms

import { percentageVolumeOscillator } from "fintech-algorithms/technical-indicators/volume-indicators/percentage-volume-oscillator";

Signature#

percentageVolumeOscillator(input)

Expresses the gap between a fast and a slow EMA of volume as a percentage of the slow EMA.

Parameters#

Returns#

TopicResult

series holds a single value, 100 times the fast EMA minus the slow EMA divided by the slow EMA, and latest its last element. A bar whose slow EMA is 0 yields null rather than a division result. The warm-up is set by the slow EMA seed.

Warm-up#

The first `slow_period` - 1 bars (9 with the default 10) positions are null. ready_at is 9 on default parameters.

Errors#

• When slow_period is not an integer greater than fast_period — throws Error
• When fast_period is not an integer of at least 2 — throws Error
• When a bar carries a negative volume — 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#

percentageVolumeOscillator(input)

Returns#

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

{
  "topic_id": "D07-F05-A15",
  "title": "Percentage Volume Oscillator",
  "state": "calculated",
  "ready": true,
  "ready_at": 9,
  "series": {
    "value": [null, null, null, null, null, null]
  },
  "latest": {
    "value": 2.367053666955535
  },
  "parameters": {},
  "diagnostics": {
    "causal": true,
    "input_count": 96
  }
}

Diagrams#

Calculation flow#

flowchart LR
    A["basis-consistent OHLCV observations with venue/session cov"] --> B["Validate order, basis, and finite values"]
    B --> C["Apply the selected Percentage Volume Oscillator 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 Volume Indicators family#

• On-Balance Volume (OBV)On-balance volume: a running total that adds the bar's volume when price closed up and subtracts it when price closed down.
• Accumulation/Distribution LineWeights each bar's volume by where the close sat within that bar's range, then accumulates.
• Chaikin Money FlowMoney-flow volume summed over a lookback and divided by total volume over the same window — the accumulation/distribution idea …
• Money Flow IndexRSI computed on typical price weighted by volume — commonly described as volume-weighted RSI, and read on the same 0–100 scale.
• Volume Price TrendLike OBV, but each bar contributes volume scaled by the size of the return rather than only its sign — so a 3% move counts for …
• Force IndexPrice change multiplied by volume, then smoothed.
• Chaikin A/D OscillatorBuilds the cumulative accumulation/distribution line from the money flow multiplier and volume, then returns the difference bet…
• Session VWAP IndicatorAccumulates typical price times volume divided by cumulative volume, restarting the accumulation at every new session.
• Anchored VWAPAccumulates typical price times volume divided by cumulative volume from a chosen anchor bar onward, with no session reset.
• Negative Volume IndexTracks a cumulative index seeded at 1000 that compounds the close-to-close return only on bars whose volume fell against the pr…
• Positive Volume IndexTracks a cumulative index seeded at 1000 that compounds the close-to-close return only on bars whose volume rose against the pr…
• Ease of MovementDivides the typical-price change by a box ratio built from scaled volume over the bar range, then smooths that raw reading with…
• Klinger Volume OscillatorSigns each bar's volume force by the direction of the high-low-close sum and weights it by where the close sits in the bar rang…
• Volume OscillatorReturns the difference between a fast and a slow simple moving average of raw volume.
• Volume Rate of ChangeMeasures the percentage change in volume against the bar period positions earlier.
• Relative VolumeDivides each bar's volume by the simple moving average of volume over the preceding window, giving a multiple of normal activity.
• Money Flow Multiplier and Money Flow VolumeReturns the per-bar money flow multiplier, the close's position within the bar range mapped to minus one through one, and that …
• Volume-Weighted MACDRuns the MACD construction on volume-weighted moving averages of close instead of exponential ones, and smooths the resulting l…
• Volume Zone OscillatorSigns each bar's volume by the direction of the close change, then expresses the EMA of that signed volume as a percentage of t…
• Twiggs Money FlowAccumulates volume weighted by where the close sits inside a range extended to include the prior close, then divides the EMA of…