VPIN

Install and import#

bash

npm install fintech-algorithms

import { vpin } from "fintech-algorithms/market-microstructure/order-flow-and-impact/vpin";

Signature#

vpin(inputRows, bucketVolume, windowBuckets, includePartial)

Volume-synchronised probability of informed trading: order imbalance measured in volume buckets rather than clock time. Proposed as a flash-crash early warning, and contested — its predictive claims are actively disputed in the literature.

Parameters#

Name	Type	Notes
`inputRows`	`Row[]`	Trades or volume bars with signed or classifiable volume.
`bucketVolume`	`number`	Volume that closes a bucket. The choice materially changes the series. min: 0
`windowBuckets`	`number`	Buckets averaged into each VPIN reading. min: 1 · integer: true
`includePartial`	`boolean`	Whether a final incomplete bucket is included.

Returns#

{ vpin, buckets, window_buckets, … }

The VPIN series with the buckets it was computed from.

Errors#

When bucketVolume is not positive — throws

Complexity: time O(n), space O(buckets).

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#

inputRows

[
  {
    "id": "V001",
    "event_time_ns": 0,
    "buy_volume": 50,
    "sell_volume": 50
  },
  {
    "id": "V002",
    "event_time_ns": 1000000,
    "buy_volume": 54.59220119,
    "sell_volume": 45.40779881
  },
  {
    "id": "V003",
    "event_time_ns": 2000000,
    "buy_volume": 58.48528137,
    "sell_volume": 41.51471863
  }
]

Showing 3 of 60 elements.

bucketVolume

windowBuckets

includePartial

false

Call#

vpin(inputRows, bucketVolume, windowBuckets, includePartial)

Returns#

object with 13 fields: model, state, bucket_volume, window_buckets, include_partial, input_event_count, bucket_count, dropped_partial_volume, …

{
  "model": "volume-synchronized-probability-of-informed-trading",
  "state": "estimated",
  "bucket_volume": 100,
  "window_buckets": 10,
  "include_partial": false,
  "input_event_count": 60,
  "bucket_count": 60,
  "dropped_partial_volume": 0,
  "valid_vpin_count": 51,
  "last_vpin": 0.1597998193,
  "mean_vpin": 0.3604789898,
  "max_vpin": 0.86,
  "trace": [
    {
      "id": "V001",
      "index": 0,
      "buy_volume": 50,
      "sell_volume": 50,
      "total_volume": 100,
      "absolute_imbalance": 0,
      "imbalance_fraction": 0,
      "source_event_index": 0,
      "vpin": null,
      "window_count": 1,
      "side": "warm-up",
      "reason": "insufficient-buckets"
    },
    {
      "id": "V002",
      "index": 1,
      "buy_volume": 54.59220119,
      "sell_volume": 45.40779881,
      "total_volume": 100,
      "absolute_imbalance": 9.18440238,
      "imbalance_fraction": 0.0918440238,
      "source_event_index": 1,
      "vpin": null,
      "window_count": 2,
      "side": "warm-up",
      "reason": "insufficient-buckets"
    },
    {
      "id": "V003",
      "index": 2,
      "buy_volume": 58.48528137,
      "sell_volume": 41.51471863,
      "total_volume": 100,
      "absolute_imbalance": 16.97056274,
      "imbalance_fraction": 0.1697056274,
      "source_event_index": 2,
      "vpin": null,
      "window_count": 3,
      "side": "warm-up",
      "reason": "insufficient-buckets"
    }
  ]
}

Other exports#

This module also exports orderFlowImbalance, queueImbalance, kyleLambda, hasbrouckPriceImpact, pin, runTopic. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams#

Calculation flow#

VPIN Calculation Flow

flowchart LR
    A["Point-in-time source records"] --> B["Validate clocks, sequence, and finality"]
    B --> C["Apply VPIN profile"]
    C --> D["Preserve trace and diagnostics"]
    D --> E["Report bounded output"]
    E --> F["Compare profiles"]
    F --> G["Reject unsupported inference"]

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 →

VPIN

Install and import#

Signature#

Parameters#

Returns#

Errors#

Worked example#

Input#

Call#

Returns#

Other exports#

Diagrams#

Calculation flow#

How it works#

References#

The rest of the Order-Flow and Impact family#