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

Market-Depth Heatmap Aggregation

Install and import#

bash
npm install fintech-algorithms
ts
import { marketDepthHeatmap } from "fintech-algorithms/market-microstructure/market-depth-analytics/market-depth-heatmap-aggregation";

Signature#

marketDepthHeatmap(snapshotsRaw, tickRaw, binRaw, maxRaw)

Aggregates a sequence of book snapshots into a time-by-price grid — the data behind a depth heatmap, where persistent liquidity and fleeting quotes look completely different.

Parameters#

NameTypeNotes
snapshotsRawSnapshot[]Sequential book snapshots.
tickRawnumberTick size.
min: 0
binRawnumberPrice bin width in ticks.
min: 0
maxRawnumberMaximum distance from the touch to include.
min: 0

Returns#

{ grid, bins, snapshots, … }

The aggregated grid with its bin definitions.

Errors#

  • When tick or bin width is not positive — throws

Complexity: time O(snapshots × levels), space O(bins × snapshots).

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#

snapshotsRaw
[
  {
    "timestamp_seconds": 0,
    "bids": [
      {
        "price": 99.99,
        "quantity": 500
      },
      {
        "price": 99.98,
        "quantity": 700
      },
      {
        "price": 99.97,
        "quantity": 420
      }
    ],
    "asks": [
      {
        "price": 100.01,
        "quantity": 360
      },
      {
        "price": 100.02,
        "quantity": 620
      },
      {
        "price": 100.03,
        "quantity": 460
      }
    ]
  },
  {
    "timestamp_seconds": 10,
    "bids": [
      {
        "price": 99.99,
        "quantity": 520
      },
      {
        "price": 99.98,
        "quantity": 715
      },
      {
        "price": 99.97,
        "quantity": 430
      }
    ],
    "asks": [
      {
        "price": 100.01,
        "quantity": 375
      },
      {
        "price": 100.02,
        "quantity": 630
      },
      {
        "price": 100.03,
        "quantity": 468
      }
    ]
  },
  {
    "timestamp_seconds": 20,
    "bids": [
      {
        "price": 99.99,
        "quantity": 540
      },
      {
        "price": 99.98,
        "quantity": 730
      },
      {
        "price": 99.97,
        "quantity": 440
      }
    ],
    "asks": [
      {
        "price": 100.01,
        "quantity": 390
      },
      {
        "price": 100.02,
        "quantity": 640
      },
      {
        "price": 100.03,
        "quantity": 476
      }
    ]
  }
]

Showing 3 of 12 elements.

tickRaw
0.01
binRaw
30
maxRaw
2

Call#

marketDepthHeatmap(snapshotsRaw, tickRaw, binRaw, maxRaw)

Returns#

object with 9 fields: model, snapshot_interval_seconds, time_bin_seconds, max_distance_ticks, time_bin_count, book_coordinates, cells, peak_cell, …

{
  "model": "regular-snapshot-inside-relative-depth-heatmap",
  "snapshot_interval_seconds": 10,
  "time_bin_seconds": 30,
  "max_distance_ticks": 2,
  "time_bin_count": 4,
  "book_coordinates": [-3, -2, -1, 1, 2, 3],
  "cells": [
    {
      "time_bin_index": 0,
      "time_bin_start_seconds": 0,
      "book_coordinate": -3,
      "mean_quantity": 430,
      "max_quantity": 440,
      "observation_count": 3
    },
    {
      "time_bin_index": 0,
      "time_bin_start_seconds": 0,
      "book_coordinate": -2,
      "mean_quantity": 715,
      "max_quantity": 730,
      "observation_count": 3
    },
    {
      "time_bin_index": 0,
      "time_bin_start_seconds": 0,
      "book_coordinate": -1,
      "mean_quantity": 520,
      "max_quantity": 540,
      "observation_count": 3
    }
  ],
  "peak_cell": {
    "time_bin_index": 3,
    "time_bin_start_seconds": 90,
    "book_coordinate": -2,
    "mean_quantity": 850,
    "max_quantity": 865,
    "observation_count": 3
  },
  "state": "bid-peak"
}

Other exports#

This module also exports cumulativeDepth, topNDepthImbalance, depthAtDistanceProfile, expectedFillPrice, sweepCostAndSlippage, liquidityWallConcentration, depthDepletionReplenishment, calculate. 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#

Market-Depth Heatmap Aggregation — system map

Calculation flow#

Market-Depth Heatmap Aggregation calculation flow 
flowchart LR
    S1["Validate regular chronological snapshots"]
    S2["Reconstruct each uncrossed visible book"]
    S3["Map bids to negative and asks to positive inside coord"]
    S4["Zerofill absent included distances"]
    S5["Aggregate mean max count and peak by time bin"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"regular sampling and the unused zero coordinate"}
    D --> O["time_bin_count + diagnostics"]
    O --> A["Audit: Coordinate zero is never used"]

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 Market-Depth Analytics family#