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

Depth Depletion and Replenishment

Install and import#

bash
npm install fintech-algorithms
ts
import { depthDepletionReplenishment } from "fintech-algorithms/market-microstructure/market-depth-analytics/depth-depletion-and-replenishment";

Signature#

depthDepletionReplenishment(seriesRaw)

Tracks depth being consumed and refilled over a sequence of snapshots. The pairing matters: depletion without replenishment is a book emptying out, which is the condition preceding a dislocation.

Parameters#

NameTypeNotes
seriesRawSnapshot[]Sequential book snapshots with per-side depth.

Returns#

{ events, depletion_total, replenishment_total, net, … }

Depletion and replenishment events with their net effect.

Errors#

  • When fewer than two snapshots are supplied — throws

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

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#

seriesRaw
[
  {
    "timestamp_seconds": 0,
    "quantity": 500
  },
  {
    "timestamp_seconds": 1,
    "quantity": 380
  },
  {
    "timestamp_seconds": 2,
    "quantity": 440
  }
]

Showing 3 of 6 elements.

Call#

depthDepletionReplenishment(seriesRaw)

Returns#

object with 10 fields: model, snapshot_count, start_quantity, end_quantity, gross_depletion, gross_replenishment, net_depth_change, replenishment_to_depletion, …

{
  "model": "snapshot-visible-depth-change-decomposition",
  "snapshot_count": 6,
  "start_quantity": 500,
  "end_quantity": 420,
  "gross_depletion": 300,
  "gross_replenishment": 220,
  "net_depth_change": -80,
  "replenishment_to_depletion": 0.7333333333333333,
  "changes": [
    {
      "timestamp_seconds": 1,
      "previous_quantity": 500,
      "quantity": 380,
      "delta_quantity": -120,
      "classification": "depletion"
    },
    {
      "timestamp_seconds": 2,
      "previous_quantity": 380,
      "quantity": 440,
      "delta_quantity": 60,
      "classification": "replenishment"
    },
    {
      "timestamp_seconds": 3,
      "previous_quantity": 440,
      "quantity": 300,
      "delta_quantity": -140,
      "classification": "depletion"
    }
  ],
  "state": "net-depleting"
}

Other exports#

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

Depth Depletion and Replenishment — system map

Calculation flow#

Depth Depletion and Replenishment calculation flow 
flowchart LR
    S1["Validate chronological snapshots"]
    S2["Subtract each prior visible quantity"]
    S3["Accumulate negative magnitudes as depletion"]
    S4["Accumulate positive changes as replenishment"]
    S5["Return gross net ratio and event audit"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"zerodepletion null ratio and stable bucket identity"}
    D --> O["replenishment_to_depletion + diagnostics"]
    O --> A["Audit: Net change equals end quantity minus start quantity"]

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#