Tick-Run Bars: Count the Dominant Side Without Confusing a Run With a Streak

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

/** Causal Tick-Run Bars under this package's disclosed EMA convention. */
export type Trade = {
  tradeId: string; timestamp: string; session: string; symbol: string;
  price: number; volume: number; currency: string; sequence?: number;
};

export type Config = {
  closePartial: boolean; initialTickSign: -1 | 1; initialExpectedTicks: number;
  initialBuyProbability: number; alphaTicks: number; alphaBuyProbability: number;
  thresholdFloorTicks: number; thresholdMultiplier: number;
};

export type Bar = {
  barIndex: number; session: string; startTime: string; endTime: string;
  lastTradeTime: string; open: number; high: number; low: number; close: number;
  volume: number; dollarValue: number; tickCount: number; firstTradeId: string;
  lastTradeId: string; closeReason: "threshold" | "session_end" | "stream_end";
  buyTicks: number; sellTicks: number; dominantCount: number;
  dominantSide: "buy" | "sell" | "tie"; thresholdTicks: number;
  overshootTicks: number; thresholdMet: boolean; isComplete: boolean;
  frozenExpectedTicks: number; frozenBuyProbability: number;
};

function timestamp(value: unknown): number {
  if (typeof value !== "string" || !value.endsWith("Z")) {
    throw new Error("timestamp must be an ISO-8601 UTC string ending in Z");
  }
  const parsed = Date.parse(value);
  if (!Number.isFinite(parsed)) throw new Error("timestamp must be valid ISO-8601");
  return parsed;
}
function finite(value: unknown, name: string): number {
  if (typeof value !== "number" || !Number.isFinite(value)) {
    throw new Error(`${name} must be a finite number`);
  }
  return value;
}
function positive(value: unknown, name: string): number {
  const parsed = finite(value, name);
  if (parsed <= 0) throw new Error(`${name} must be positive`);
  return parsed;
}
function rounded(value: number): number { return Number(value.toFixed(8)); }

function validate(trades: Trade[], config: Config): void {
  if (!Array.isArray(trades)) throw new Error("trades must be an array");
  if (!config || typeof config !== "object") throw new Error("config must be an object");
  if (typeof config.closePartial !== "boolean") throw new Error("closePartial must be boolean");
  if (config.initialTickSign !== -1 && config.initialTickSign !== 1) {
    throw new Error("initialTickSign must be -1 or +1");
  }
  positive(config.initialExpectedTicks, "initialExpectedTicks");
  const probability = finite(config.initialBuyProbability, "initialBuyProbability");
  if (probability < 0 || probability > 1) throw new Error("initialBuyProbability must be in [0, 1]");
  for (const [name, value] of [
    ["alphaTicks", config.alphaTicks], ["alphaBuyProbability", config.alphaBuyProbability],
  ] as const) {
    const alpha = finite(value, name);
    if (alpha <= 0 || alpha > 1) throw new Error(`${name} must be in (0, 1]`);
  }
  positive(config.thresholdFloorTicks, "thresholdFloorTicks");
  positive(config.thresholdMultiplier, "thresholdMultiplier");

  const ids = new Set<string>(); const closedSessions = new Set<string>();
  let activeSession: string | null = null; let priorTime: number | null = null;
  let priorSequence: number | null = null; let symbol: string | null = null;
  let currency: string | null = null;
  for (const trade of trades) {
    if (!trade || typeof trade !== "object") throw new Error("each trade must be an object");
    for (const name of ["tradeId", "timestamp", "session", "symbol", "currency"] as const) {
      if (typeof trade[name] !== "string" || !trade[name].trim()) throw new Error(`${name} must be a non-empty string`);
    }
    if (ids.has(trade.tradeId)) throw new Error("tradeId must be unique");
    ids.add(trade.tradeId);
    const currentTime = timestamp(trade.timestamp);
    if (priorTime !== null && currentTime < priorTime) throw new Error("trades must be chronological");
    if (priorTime !== null && currentTime === priorTime) {
      if (!Number.isInteger(trade.sequence) || priorSequence === null || trade.sequence! <= priorSequence) {
        throw new Error("equal timestamps require strictly increasing integer sequence values");
      }
    }
    priorTime = currentTime; priorSequence = Number.isInteger(trade.sequence) ? trade.sequence! : null;
    positive(trade.price, "price"); positive(trade.volume, "volume");
    if (symbol === null) { symbol = trade.symbol; currency = trade.currency; }
    else if (trade.symbol !== symbol || trade.currency !== currency) {
      throw new Error("one symbol and one currency are allowed per call");
    }
    if (activeSession === null) activeSession = trade.session;
    else if (trade.session !== activeSession) {
      closedSessions.add(activeSession);
      if (closedSessions.has(trade.session)) throw new Error("a session may not reappear after another session begins");
      activeSession = trade.session;
    }
  }
}

export function constructBars(trades: Trade[], config: Config): Bar[] {
  validate(trades, config);
  if (trades.length === 0) return [];
  const result: Bar[] = []; let current: Trade[] = []; let activeSession: string | null = null;
  let previousPrice: number | null = null; let tickSign = config.initialTickSign;
  let expectedTicks = config.initialExpectedTicks;
  let expectedBuyProbability = config.initialBuyProbability;
  let buyTicks = 0; let sellTicks = 0; let threshold = 0;
  let frozenExpectedTicks = 0; let frozenBuyProbability = 0;

  const beginBar = (): void => {
    current = []; buyTicks = 0; sellTicks = 0;
    frozenExpectedTicks = expectedTicks; frozenBuyProbability = expectedBuyProbability;
    threshold = Math.max(
      config.thresholdFloorTicks,
      config.thresholdMultiplier * frozenExpectedTicks
        * Math.max(frozenBuyProbability, 1 - frozenBuyProbability),
    );
  };
  const resetSessionState = (): void => {
    previousPrice = null; tickSign = config.initialTickSign;
    expectedTicks = config.initialExpectedTicks;
    expectedBuyProbability = config.initialBuyProbability;
  };
  const emit = (reason: Bar["closeReason"]): void => {
    if (!current.length) return;
    const prices = current.map(trade => trade.price);
    const volumes = current.map(trade => trade.volume);
    const dominantCount = Math.max(buyTicks, sellTicks);
    const dominantSide = buyTicks > sellTicks ? "buy" : sellTicks > buyTicks ? "sell" : "tie";
    const isComplete = reason === "threshold";
    result.push({
      barIndex: result.length, session: current[0].session,
      startTime: current[0].timestamp, endTime: current.at(-1)!.timestamp,
      lastTradeTime: current.at(-1)!.timestamp,
      open: rounded(prices[0]), high: rounded(Math.max(...prices)),
      low: rounded(Math.min(...prices)), close: rounded(prices.at(-1)!),
      volume: rounded(volumes.reduce((sum, value) => sum + value, 0)),
      dollarValue: rounded(current.reduce((sum, trade) => sum + trade.price * trade.volume, 0)),
      tickCount: current.length, firstTradeId: current[0].tradeId,
      lastTradeId: current.at(-1)!.tradeId, closeReason: reason,
      buyTicks, sellTicks, dominantCount, dominantSide,
      thresholdTicks: rounded(threshold),
      overshootTicks: isComplete ? rounded(Math.max(0, dominantCount - threshold)) : 0,
      thresholdMet: isComplete, isComplete,
      frozenExpectedTicks: rounded(frozenExpectedTicks),
      frozenBuyProbability: rounded(frozenBuyProbability),
    });
    if (isComplete) {
      const observedTicks = current.length;
      const observedBuyProbability = buyTicks / observedTicks;
      expectedTicks = (1 - config.alphaTicks) * expectedTicks + config.alphaTicks * observedTicks;
      expectedBuyProbability = (1 - config.alphaBuyProbability) * expectedBuyProbability
        + config.alphaBuyProbability * observedBuyProbability;
    }
    beginBar();
  };

  beginBar();
  for (const trade of trades) {
    if (activeSession !== null && trade.session !== activeSession) {
      if (current.length && config.closePartial) emit("session_end"); else beginBar();
      resetSessionState(); beginBar();
    }
    activeSession = trade.session;
    if (previousPrice !== null) {
      if (trade.price > previousPrice) tickSign = 1;
      else if (trade.price < previousPrice) tickSign = -1;
    }
    previousPrice = trade.price; current.push(trade);
    buyTicks += Number(tickSign === 1); sellTicks += Number(tickSign === -1);
    if (Math.max(buyTicks, sellTicks) >= threshold) emit("threshold");
  }
  if (current.length && config.closePartial) emit("stream_end");
  return result;
}