fintech-algorithms

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

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