fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Queue Imbalance

Install and import#

bash
npm install fintech-algorithms
ts
import { queueImbalance } from "fintech-algorithms/market-microstructure/order-flow-and-impact/queue-imbalance";

Signature#

queueImbalance(inputRows, levels, decay)

The share of depth resting on the bid versus the ask. A simple, strongly predictive feature for the direction of the next price move at very short horizons.

Parameters#

NameTypeNotes
inputRowsRow[]Book observations with per-level sizes.
levelsnumberHow many levels deep to include. One level is the classic definition; more captures a broader picture and dilutes the signal.
min: 1 · integer: true
decaynumberWeight decay applied to deeper levels, so a size far from the touch counts for less.
min: 0

Returns#

{ imbalance, rows, levels, … }

Imbalance per observation, ranging from −1 (all ask) to +1 (all bid).

Errors#

  • When levels exceeds the depth supplied — throws

Complexity: time O(n × levels), 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#

inputRows
[
  {
    "id": "Q001",
    "event_time_ns": 0,
    "bid_sizes": [600, 900, 1100],
    "ask_sizes": [600, 900, 1100]
  },
  {
    "id": "Q002",
    "event_time_ns": 1000000,
    "bid_sizes": [680.3444, 862.918, 1124.7214],
    "ask_sizes": [519.6556, 937.082, 1075.2786]
  },
  {
    "id": "Q003",
    "event_time_ns": 2000000,
    "bid_sizes": [752.8242, 829.4658, 1147.0228],
    "ask_sizes": [447.1758, 970.5342, 1052.9772]
  }
]

Showing 3 of 60 elements.

levels
1
decay
1

Call#

queueImbalance(inputRows, levels, decay)

Returns#

object with 11 fields: model, state, levels, decay, observation_count, valid_count, unknown_count, mean_imbalance, …

{
  "model": "signed-queue-imbalance",
  "state": "estimated",
  "levels": 1,
  "decay": 1,
  "observation_count": 60,
  "valid_count": 60,
  "unknown_count": 0,
  "mean_imbalance": 0,
  "last_imbalance": -0.1339073333,
  "max_absolute_imbalance": 0.4333333333,
  "trace": [
    {
      "id": "Q001",
      "index": 0,
      "bid_depth": 600,
      "ask_depth": 600,
      "total_depth": 1200,
      "imbalance": 0,
      "side": "balanced",
      "reason": "normalized-depth"
    },
    {
      "id": "Q002",
      "index": 1,
      "bid_depth": 680.3444,
      "ask_depth": 519.6556,
      "total_depth": 1200,
      "imbalance": 0.1339073333,
      "side": "bid-heavy",
      "reason": "normalized-depth"
    },
    {
      "id": "Q003",
      "index": 2,
      "bid_depth": 752.8242,
      "ask_depth": 447.1758,
      "total_depth": 1200,
      "imbalance": 0.254707,
      "side": "bid-heavy",
      "reason": "normalized-depth"
    }
  ]
}

Other exports#

This module also exports orderFlowImbalance, kyleLambda, hasbrouckPriceImpact, pin, vpin, 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#

Queue Imbalance — calculation map
Queue Imbalance — decision boundary
Queue Imbalance — failure boundary
Queue Imbalance — scenario matrix
Queue Imbalance — worked example

Calculation flow#

Queue Imbalance Calculation Flow 
flowchart LR
    A["Point-in-time source records"] --> B["Validate clocks, sequence, and finality"]
    B --> C["Apply Queue Imbalance 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 →

References#

The rest of the Order-Flow and Impact family#

  • Order Flow ImbalanceNet signed change in depth at the touch — the quantity that best explains short-horizon price moves in the microstructure liter…
  • Kyle LambdaThe price-impact coefficient from regressing price change on signed order flow.
  • Hasbrouck Price ImpactDecomposes a trade's price effect into the permanent part — information — and the transient part that reverts.
  • PINProbability of informed trading, estimated by maximum likelihood on daily buy and sell counts.
  • VPINVolume-synchronised probability of informed trading: order imbalance measured in volume buckets rather than clock time.