Top-N Depth Imbalance

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213

export type JsonObject = Record<string, any>;

function numberValue(name: string, value: unknown, options: {positive?: boolean; nonnegative?: boolean} = {}): number {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${name} must be a finite number`);
  if (options.positive && value <= 0) throw new RangeError(`${name} must be positive`);
  if (options.nonnegative && value < 0) throw new RangeError(`${name} must be nonnegative`);
  return value;
}

function integerValue(name: string, value: unknown, positive = false): number {
  const result = numberValue(name, value);
  if (!Number.isInteger(result)) throw new RangeError(`${name} must be an integer`);
  if (positive && result <= 0) throw new RangeError(`${name} must be positive`);
  return result;
}

type Level = {price: number; quantity: number};

function levels(raw: unknown, side: "bid" | "ask"): Level[] {
  if (!Array.isArray(raw) || raw.length === 0) throw new RangeError(`${side}s must be a non-empty list`);
  const seen = new Set<number>();
  const result = raw.map((item, index) => {
    if (!item || typeof item !== "object") throw new TypeError(`${side}s[${index}] must be an object`);
    const row = item as JsonObject;
    const price = numberValue(`${side}s[${index}].price`, row.price, {positive: true});
    const quantity = numberValue(`${side}s[${index}].quantity`, row.quantity, {positive: true});
    if (seen.has(price)) throw new RangeError(`${side} prices must be unique aggregated levels`);
    seen.add(price);
    return {price, quantity};
  });
  for (let index = 1; index < result.length; index += 1) {
    if (side === "bid" && result[index - 1].price <= result[index].price) throw new RangeError("bids must be strictly descending from best price");
    if (side === "ask" && result[index - 1].price >= result[index].price) throw new RangeError("asks must be strictly ascending from best price");
  }
  return result;
}

function book(bidsRaw: unknown, asksRaw: unknown): [Level[], Level[]] {
  const bids = levels(bidsRaw, "bid"), asks = levels(asksRaw, "ask");
  if (bids[0].price >= asks[0].price) throw new RangeError("visible book must be uncrossed");
  return [bids, asks];
}

function tickDistance(price: number, best: number, tick: number, side: "bid" | "ask"): number {
  const raw = side === "bid" ? (best - price) / tick : (price - best) / tick;
  const rounded = Math.round(raw);
  if (Math.abs(raw - rounded) > 1e-7) throw new RangeError("price is not aligned to the declared tick grid");
  return rounded;
}

export function cumulativeDepth(bidsRaw: unknown, asksRaw: unknown, tickRaw: unknown): JsonObject {
  const [bids, asks] = book(bidsRaw, asksRaw);
  const tick = numberValue("tick_size", tickRaw, {positive: true});
  const rows = (sideLevels: Level[], side: "bid" | "ask") => {
    let cumulative = 0;
    const best = sideLevels[0].price;
    return sideLevels.map(level => {
      cumulative += level.quantity;
      return {price: level.price, quantity: level.quantity, distance_ticks: tickDistance(level.price, best, tick, side), cumulative_quantity: cumulative};
    });
  };
  const bidRows = rows(bids, "bid"), askRows = rows(asks, "ask");
  const spreadRaw = (asks[0].price - bids[0].price) / tick, spreadTicks = Math.round(spreadRaw);
  if (Math.abs(spreadRaw - spreadTicks) > 1e-7) throw new RangeError("spread is not aligned to the declared tick grid");
  const bidTotal = bidRows[bidRows.length - 1].cumulative_quantity, askTotal = askRows[askRows.length - 1].cumulative_quantity;
  return {model: "visible-cumulative-depth", best_bid: bids[0].price, best_ask: asks[0].price, tick_size: tick, spread_ticks: spreadTicks, bid_levels: bidRows, ask_levels: askRows, total_bid_depth: bidTotal, total_ask_depth: askTotal, state: bidTotal > askTotal ? "bid-deeper" : bidTotal < askTotal ? "ask-deeper" : "balanced"};
}

export function topNDepthImbalance(bidsRaw: unknown, asksRaw: unknown, nRaw: unknown, thresholdRaw: unknown = 0.1): JsonObject {
  const [bids, asks] = book(bidsRaw, asksRaw);
  const n = integerValue("n", nRaw, true), threshold = numberValue("threshold", thresholdRaw, {nonnegative: true});
  if (threshold > 1) throw new RangeError("threshold must not exceed one");
  if (bids.length < n || asks.length < n) throw new RangeError("both sides must contain at least n visible levels");
  const bidDepth = bids.slice(0, n).reduce((sum, row) => sum + row.quantity, 0);
  const askDepth = asks.slice(0, n).reduce((sum, row) => sum + row.quantity, 0);
  const total = bidDepth + askDepth, imbalance = (bidDepth - askDepth) / total;
  return {model: "top-n-visible-depth-imbalance", n, bid_depth: bidDepth, ask_depth: askDepth, total_depth: total, imbalance, threshold, state: imbalance > threshold ? "bid-heavy" : imbalance < -threshold ? "ask-heavy" : "balanced-band", complete_window: true};
}

export function depthAtDistanceProfile(bidsRaw: unknown, asksRaw: unknown, tickRaw: unknown, maxRaw: unknown): JsonObject {
  const [bids, asks] = book(bidsRaw, asksRaw);
  const tick = numberValue("tick_size", tickRaw, {positive: true}), maximum = integerValue("max_distance_ticks", maxRaw);
  if (maximum < 0) throw new RangeError("max_distance_ticks must be nonnegative");
  const profile = (sideLevels: Level[], side: "bid" | "ask") => {
    const best = sideLevels[0].price, byDistance = new Map<number, number>();
    sideLevels.forEach(level => byDistance.set(tickDistance(level.price, best, tick, side), level.quantity));
    let included = 0;
    for (let d = 0; d <= maximum; d += 1) included += byDistance.get(d) ?? 0;
    let cumulative = 0;
    return Array.from({length: maximum + 1}, (_, distance) => {
      const quantity = byDistance.get(distance) ?? 0; cumulative += quantity;
      return {distance_ticks: distance, quantity, cumulative_quantity: cumulative, depth_share: included ? quantity / included : 0};
    });
  };
  const bidProfile = profile(bids, "bid"), askProfile = profile(asks, "ask");
  const bidTotal = bidProfile[bidProfile.length - 1].cumulative_quantity, askTotal = askProfile[askProfile.length - 1].cumulative_quantity;
  return {model: "same-side-best-tick-distance-profile", tick_size: tick, max_distance_ticks: maximum, bid_profile: bidProfile, ask_profile: askProfile, included_bid_depth: bidTotal, included_ask_depth: askTotal, state: bidTotal > askTotal ? "bid-profile-heavier" : askTotal > bidTotal ? "ask-profile-heavier" : "profile-balanced"};
}

function sweep(bidsRaw: unknown, asksRaw: unknown, sideRaw: unknown, quantityRaw: unknown, limitRaw: unknown): JsonObject {
  const [bids, asks] = book(bidsRaw, asksRaw);
  if (sideRaw !== "buy" && sideRaw !== "sell") throw new RangeError("side must be buy or sell");
  const side = sideRaw, requested = numberValue("quantity", quantityRaw, {positive: true});
  const limit = limitRaw == null ? null : numberValue("limit_price", limitRaw, {positive: true});
  const sideLevels = side === "buy" ? asks : bids;
  let remaining = requested, notional = 0;
  const fills: JsonObject[] = [];
  for (let index = 0; index < sideLevels.length && remaining > 1e-12; index += 1) {
    const level = sideLevels[index];
    if (limit != null && (side === "buy" ? level.price > limit : level.price < limit)) break;
    const fillQuantity = Math.min(remaining, level.quantity);
    fills.push({level_index: index, price: level.price, quantity: fillQuantity, notional: fillQuantity * level.price});
    notional += fillQuantity * level.price; remaining -= fillQuantity;
  }
  if (remaining <= 1e-12) remaining = 0;
  const filled = requested - remaining, partialVwap = filled ? notional / filled : null;
  return {side, requested_quantity: requested, filled_quantity: filled, unfilled_quantity: remaining, full_fill: remaining === 0, fills, fill_notional: notional, partial_vwap: partialVwap, worst_fill_price: fills.length ? fills[fills.length - 1].price : null, best_bid: bids[0].price, best_ask: asks[0].price, midpoint: (bids[0].price + asks[0].price) / 2};
}

export function expectedFillPrice(bids: unknown, asks: unknown, side: unknown, quantity: unknown, limitPrice: unknown = null): JsonObject {
  const result = sweep(bids, asks, side, quantity, limitPrice);
  return {model: "deterministic-visible-book-fill-estimate", ...result, expected_fill_price: result.full_fill ? result.partial_vwap : null, state: result.full_fill ? "full-fill" : result.filled_quantity ? "partial-fill" : "unfilled"};
}

export function sweepCostAndSlippage(bids: unknown, asks: unknown, side: unknown, quantity: unknown, benchmarkRaw: unknown = "midpoint", benchmarkPriceRaw: unknown = null, limitPrice: unknown = null): JsonObject {
  const result = sweep(bids, asks, side, quantity, limitPrice);
  if (!["midpoint", "best-quote", "explicit"].includes(String(benchmarkRaw))) throw new RangeError("benchmark must be midpoint, best-quote, or explicit");
  const benchmark = String(benchmarkRaw);
  const reference = benchmark === "midpoint" ? result.midpoint : benchmark === "best-quote" ? (side === "buy" ? result.best_ask : result.best_bid) : numberValue("benchmark_price", benchmarkPriceRaw, {positive: true});
  const vwap = result.partial_vwap, direction = side === "buy" ? 1 : -1;
  const slippagePrice = vwap == null ? null : direction * (vwap - reference);
  const slippageBps = slippagePrice == null ? null : slippagePrice / reference * 10_000;
  return {model: "visible-book-sweep-cost", ...result, benchmark, benchmark_price: reference, sweep_vwap: vwap, signed_slippage_price: slippagePrice, signed_slippage_bps: slippageBps, total_slippage_cost: slippagePrice == null ? null : slippagePrice * result.filled_quantity, state: result.full_fill ? "full-sweep" : result.filled_quantity ? "partial-sweep" : "unfilled"};
}

function median(values: number[]): number {
  const sorted = [...values].sort((a, b) => a - b), middle = Math.floor(sorted.length / 2);
  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
}

export function liquidityWallConcentration(levelsRaw: unknown, multipleRaw: unknown = 2, minShareRaw: unknown = 0.25, thresholdRaw: unknown = 0.30): JsonObject {
  const parsed = levels(levelsRaw, "ask");
  const multiple = numberValue("wall_multiple", multipleRaw, {positive: true});
  const minShare = numberValue("minimum_share", minShareRaw, {nonnegative: true});
  const threshold = numberValue("concentration_threshold", thresholdRaw, {nonnegative: true});
  if (minShare > 1 || threshold > 1) throw new RangeError("share thresholds must not exceed one");
  const quantities = parsed.map(row => row.quantity), total = quantities.reduce((a, b) => a + b, 0), med = median(quantities);
  const shares = quantities.map(value => value / total), hhi = shares.reduce((sum, value) => sum + value * value, 0);
  const walls = parsed.map((level, index) => ({level_index: index, price: level.price, quantity: level.quantity, depth_share: shares[index], median_multiple: level.quantity / med})).filter(row => row.quantity >= multiple * med && row.depth_share >= minShare);
  let largestIndex = 0; quantities.forEach((value, index) => { if (value > quantities[largestIndex]) largestIndex = index; });
  return {model: "level-share-concentration-and-wall-screen", level_count: parsed.length, total_depth: total, median_level_quantity: med, hhi_fraction: hhi, effective_level_count: 1 / hhi, largest_level_index: largestIndex, largest_level_share: shares[largestIndex], walls, wall_multiple: multiple, minimum_share: minShare, concentration_threshold: threshold, state: walls.length ? "wall-detected" : hhi >= threshold ? "concentrated" : "distributed"};
}

export function depthDepletionReplenishment(seriesRaw: unknown): JsonObject {
  if (!Array.isArray(seriesRaw) || seriesRaw.length < 2) throw new RangeError("series must contain at least two snapshots");
  const parsed = seriesRaw.map((item, index) => {
    if (!item || typeof item !== "object") throw new TypeError(`series[${index}] must be an object`);
    const row = item as JsonObject;
    return {timestamp_seconds: numberValue(`series[${index}].timestamp_seconds`, row.timestamp_seconds, {nonnegative: true}), quantity: numberValue(`series[${index}].quantity`, row.quantity, {nonnegative: true})};
  });
  for (let i = 1; i < parsed.length; i += 1) if (parsed[i - 1].timestamp_seconds >= parsed[i].timestamp_seconds) throw new RangeError("timestamps must be strictly increasing");
  let depletion = 0, replenishment = 0;
  const changes = parsed.slice(1).map((current, index) => {
    const previous = parsed[index], delta = current.quantity - previous.quantity;
    replenishment += Math.max(delta, 0); depletion += Math.max(-delta, 0);
    return {timestamp_seconds: current.timestamp_seconds, previous_quantity: previous.quantity, quantity: current.quantity, delta_quantity: delta, classification: delta > 0 ? "replenishment" : delta < 0 ? "depletion" : "unchanged"};
  });
  const net = replenishment - depletion;
  return {model: "snapshot-visible-depth-change-decomposition", snapshot_count: parsed.length, start_quantity: parsed[0].quantity, end_quantity: parsed[parsed.length - 1].quantity, gross_depletion: depletion, gross_replenishment: replenishment, net_depth_change: net, replenishment_to_depletion: depletion ? replenishment / depletion : null, changes, state: net > 0 ? "net-replenishing" : net < 0 ? "net-depleting" : "net-flat"};
}

export function marketDepthHeatmap(snapshotsRaw: unknown, tickRaw: unknown, binRaw: unknown, maxRaw: unknown): JsonObject {
  if (!Array.isArray(snapshotsRaw) || snapshotsRaw.length < 2) throw new RangeError("snapshots must contain at least two regular observations");
  const snapshots = snapshotsRaw as JsonObject[], tick = numberValue("tick_size", tickRaw, {positive: true}), binSize = numberValue("time_bin_seconds", binRaw, {positive: true}), maximum = integerValue("max_distance_ticks", maxRaw);
  if (maximum < 0) throw new RangeError("max_distance_ticks must be nonnegative");
  const times = snapshots.map((item, index) => {
    if (!item || typeof item !== "object") throw new TypeError("each snapshot must be an object");
    return numberValue(`snapshots[${index}].timestamp_seconds`, item.timestamp_seconds, {nonnegative: true});
  });
  for (let i = 1; i < times.length; i += 1) if (times[i - 1] >= times[i]) throw new RangeError("snapshot timestamps must be strictly increasing");
  const intervals = times.slice(1).map((time, index) => time - times[index]);
  if (intervals.slice(1).some(interval => Math.abs(interval - intervals[0]) > 1e-9)) throw new RangeError("canonical heatmap requires regularly sampled snapshots");
  const origin = times[0], buckets = new Map<string, number[]>(), binSet = new Set<number>();
  snapshots.forEach((snapshot, snapshotIndex) => {
    const [bids, asks] = book(snapshot.bids, snapshot.asks), binIndex = Math.floor((times[snapshotIndex] - origin) / binSize);
    binSet.add(binIndex);
    const observed = new Map<number, number>();
    bids.forEach(level => { const d = tickDistance(level.price, bids[0].price, tick, "bid"); if (d <= maximum) observed.set(-(d + 1), level.quantity); });
    asks.forEach(level => { const d = tickDistance(level.price, asks[0].price, tick, "ask"); if (d <= maximum) observed.set(d + 1, level.quantity); });
    const coordinates = [...Array.from({length: maximum + 1}, (_, i) => -(maximum + 1) + i), ...Array.from({length: maximum + 1}, (_, i) => i + 1)];
    coordinates.forEach(coordinate => { const key = `${binIndex}|${coordinate}`, values = buckets.get(key) ?? []; values.push(observed.get(coordinate) ?? 0); buckets.set(key, values); });
  });
  const cells = [...buckets.entries()].map(([key, values]) => {
    const [binIndex, coordinate] = key.split("|").map(Number);
    return {time_bin_index: binIndex, time_bin_start_seconds: origin + binIndex * binSize, book_coordinate: coordinate, mean_quantity: values.reduce((a, b) => a + b, 0) / values.length, max_quantity: Math.max(...values), observation_count: values.length};
  }).sort((a, b) => a.time_bin_index - b.time_bin_index || a.book_coordinate - b.book_coordinate);
  const peak = cells.reduce((best, cell) => cell.mean_quantity > best.mean_quantity ? cell : best);
  return {model: "regular-snapshot-inside-relative-depth-heatmap", snapshot_interval_seconds: intervals[0], time_bin_seconds: binSize, max_distance_ticks: maximum, time_bin_count: binSet.size, book_coordinates: [...Array.from({length: maximum + 1}, (_, i) => -(maximum + 1) + i), ...Array.from({length: maximum + 1}, (_, i) => i + 1)], cells, peak_cell: peak, state: peak.book_coordinate < 0 ? "bid-peak" : "ask-peak"};
}

export function calculate(topicId: string, inputs: JsonObject): JsonObject {
  if (!inputs || typeof inputs !== "object" || Array.isArray(inputs)) throw new TypeError("inputs must be an object");
  if (topicId === "D11-F05-A01") return cumulativeDepth(inputs.bids, inputs.asks, inputs.tick_size);
  if (topicId === "D11-F05-A02") return topNDepthImbalance(inputs.bids, inputs.asks, inputs.n, inputs.threshold ?? 0.1);
  if (topicId === "D11-F05-A03") return depthAtDistanceProfile(inputs.bids, inputs.asks, inputs.tick_size, inputs.max_distance_ticks);
  if (topicId === "D11-F05-A04") return expectedFillPrice(inputs.bids, inputs.asks, inputs.side, inputs.quantity, inputs.limit_price);
  if (topicId === "D11-F05-A05") return sweepCostAndSlippage(inputs.bids, inputs.asks, inputs.side, inputs.quantity, inputs.benchmark ?? "midpoint", inputs.benchmark_price, inputs.limit_price);
  if (topicId === "D11-F05-A06") return liquidityWallConcentration(inputs.levels, inputs.wall_multiple ?? 2, inputs.minimum_share ?? 0.25, inputs.concentration_threshold ?? 0.30);
  if (topicId === "D11-F05-A07") return depthDepletionReplenishment(inputs.series);
  if (topicId === "D11-F05-A08") return marketDepthHeatmap(inputs.snapshots, inputs.tick_size, inputs.time_bin_seconds, inputs.max_distance_ticks);
  throw new RangeError(`unsupported topic_id: ${topicId}`);
}