Gap Classification

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

/** Transparent, repository-selected D06 candle and pattern contracts. */

type AnyMap = Record<string, any>;

const F02_TITLES: Record<string, string> = {
  "D06-F02-A01": "Doji", "D06-F02-A02": "Dragonfly Doji", "D06-F02-A03": "Gravestone Doji",
  "D06-F02-A04": "Marubozu", "D06-F02-A05": "Spinning Top", "D06-F02-A06": "Hammer",
  "D06-F02-A07": "Hanging Man", "D06-F02-A08": "Inverted Hammer", "D06-F02-A09": "Shooting Star",
};
const F03_TITLES: Record<string, string> = {
  "D06-F03-A01": "Bullish Engulfing", "D06-F03-A02": "Bearish Engulfing", "D06-F03-A03": "Bullish Harami",
  "D06-F03-A04": "Bearish Harami", "D06-F03-A05": "Piercing Line", "D06-F03-A06": "Dark Cloud Cover",
  "D06-F03-A07": "Tweezer Top", "D06-F03-A08": "Tweezer Bottom",
};

function finite(value: unknown, name: string): number {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${name} must be a finite number`);
  return value;
}
function positive(value: unknown, name: string): number { const n = finite(value, name); if (n <= 0) throw new RangeError(`${name} must be positive`); return n; }
function nonnegative(value: unknown, name: string): number { const n = finite(value, name); if (n < 0) throw new RangeError(`${name} must be non-negative`); return n; }
function candle(value: unknown, name: string): AnyMap {
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
  const source = value as AnyMap;
  const result = {open: finite(source.open, `${name}.open`), high: finite(source.high, `${name}.high`), low: finite(source.low, `${name}.low`), close: finite(source.close, `${name}.close`)};
  if (result.high < Math.max(result.open, result.close, result.low)) throw new RangeError(`${name}.high is below another OHLC value`);
  if (result.low > Math.min(result.open, result.close, result.high)) throw new RangeError(`${name}.low is above another OHLC value`);
  return result;
}
function anatomy(c: AnyMap): AnyMap {
  const bodyHigh = Math.max(c.open, c.close), bodyLow = Math.min(c.open, c.close);
  return {body_high: bodyHigh, body_low: bodyLow, body: bodyHigh-bodyLow, upper_shadow: c.high-bodyHigh, lower_shadow: bodyLow-c.low, range: c.high-c.low, direction: c.close>c.open?"bullish":c.close<c.open?"bearish":"neutral"};
}
function numberList(value: unknown, name: string): number[] {
  if (!Array.isArray(value)) throw new TypeError(`${name} must be an array`);
  return value.map((item,index)=>nonnegative(item, `${name}[${index}]`));
}
function median(values: number[]): number { const ordered=[...values].sort((a,b)=>a-b), n=ordered.length; return n%2?ordered[(n-1)/2]:(ordered[n/2-1]+ordered[n/2])/2; }
function referenceScales(data: AnyMap): [number|null,number|null,number] {
  const bodies=numberList(data.prior_bodies,"prior_bodies"), ranges=numberList(data.prior_ranges,"prior_ranges");
  if(bodies.length!==ranges.length) throw new RangeError("prior_bodies and prior_ranges must have equal length");
  if(bodies.some((body,index)=>body>ranges[index])) throw new RangeError("a prior body cannot exceed its range");
  if(bodies.length<5) return [null,null,bodies.length];
  return [median(bodies.slice(-10)),median(ranges.slice(-10)),Math.min(10,bodies.length)];
}
function context(data: AnyMap): string { if(!["uptrend","downtrend","sideways"].includes(data.trend_context)) throw new RangeError("trend_context must be uptrend, downtrend, or sideways"); return data.trend_context; }

function patternResult(args: AnyMap): AnyMap {
  let state:string, matched:boolean;
  if(args.bodyScale===null||args.rangeScale===null){state="warmup";matched=false;}
  else if(args.matchedGeometry&&args.requiredContext!==null&&args.actualContext!==args.requiredContext){state="wrong-context";matched=false;}
  else {matched=args.matchedGeometry;state=matched?"matched":"not-matched";}
  return {topic_id:args.topicId,pattern:args.title,matched,state,direction:args.a.direction,trend_context:args.actualContext,required_context:args.requiredContext,body:args.a.body,upper_shadow:args.a.upper_shadow,lower_shadow:args.a.lower_shadow,range:args.a.range,body_scale:args.bodyScale,range_scale:args.rangeScale,history_count:args.historyCount,geometry_score:args.geometryScore,checks:args.checks,failed_checks:Object.keys(args.checks).filter(key=>!args.checks[key])};
}

function shadowToBody(data: AnyMap): AnyMap {
  const c=candle(data.candle,"candle"), tick=positive(data.tick_size,"tick_size"), a=anatomy(c), body=a.body, effective=Math.max(body,tick);
  const upperRaw=body===0?null:a.upper_shadow/body, lowerRaw=body===0?null:a.lower_shadow/body, upperEffective=a.upper_shadow/effective, lowerEffective=a.lower_shadow/effective;
  const dominant=upperEffective>lowerEffective?"upper":lowerEffective>upperEffective?"lower":"balanced";
  return {state:body===0?"zero-body":"calculated",body,upper_shadow:a.upper_shadow,lower_shadow:a.lower_shadow,range:a.range,tick_size:tick,effective_body:effective,upper_to_body:upperRaw,lower_to_body:lowerRaw,upper_to_effective_body:upperEffective,lower_to_effective_body:lowerEffective,upper_to_range:a.range===0?null:a.upper_shadow/a.range,lower_to_range:a.range===0?null:a.lower_shadow/a.range,dominant_shadow:dominant,dominant_shadow_ratio:Math.max(upperEffective,lowerEffective)};
}

function gapClassification(data: AnyMap): AnyMap {
  const previous=candle(data.previous,"previous"), current=candle(data.current,"current"), tick=positive(data.tick_size,"tick_size"), minimumTicks=nonnegative(data.minimum_gap_ticks,"minimum_gap_ticks"), threshold=tick*minimumTicks;
  const pa=anatomy(previous), ca=anatomy(current);
  const candidates:AnyMap={up:{open:current.open-previous.close,body:ca.body_low-pa.body_high,"full-range":current.low-previous.high},down:{open:previous.close-current.open,body:pa.body_low-ca.body_high,"full-range":previous.low-current.high}};
  const qualifies=(distance:number)=>distance>0&&distance>=threshold;
  let direction="none", gapType="overlap", distance=0;
  outer: for(const candidateDirection of ["up","down"]) for(const candidateType of ["full-range","body","open"]){const d=candidates[candidateDirection][candidateType];if(qualifies(d)){direction=candidateDirection;gapType=candidateType;distance=d;break outer;}}
  return {state:direction!=="none"?"gap":"overlap",gap_direction:direction,gap_type:gapType,gap_distance:distance,threshold_distance:threshold,open_gap_up:qualifies(candidates.up.open),open_gap_down:qualifies(candidates.down.open),body_gap_up:qualifies(candidates.up.body),body_gap_down:qualifies(candidates.down.body),full_range_gap_up:qualifies(candidates.up["full-range"]),full_range_gap_down:qualifies(candidates.down["full-range"]),signed_open_gap:current.open-previous.close,previous_close:previous.close,current_open:current.open};
}

function trendContext(data: AnyMap): AnyMap {
  const closes=numberList(data.prior_closes,"prior_closes"), ranges=numberList(data.prior_ranges,"prior_ranges"), lookback=data.lookback;
  if(!Number.isInteger(lookback)||lookback<3) throw new RangeError("lookback must be an integer of at least 3");
  const efficiencyFloor=nonnegative(data.minimum_efficiency,"minimum_efficiency"), moveFloor=nonnegative(data.minimum_move_scale,"minimum_move_scale");
  if(efficiencyFloor>1) throw new RangeError("minimum_efficiency cannot exceed 1");
  if(closes.length!==ranges.length) throw new RangeError("prior_closes and prior_ranges must have equal length");
  if(closes.length<lookback) return {state:"warmup",trend_context:"warmup",history_count:closes.length,net_move:null,path_move:null,efficiency:null,range_scale:null,normalized_move:null};
  const sample=closes.slice(-lookback), rangeSample=ranges.slice(-lookback), net=sample.at(-1)!-sample[0];
  let path=0;for(let i=1;i<sample.length;i++)path+=Math.abs(sample[i]-sample[i-1]);
  const efficiency=path===0?0:Math.abs(net)/path, scale=median(rangeSample);
  if(scale===0)return {state:"zero-scale",trend_context:"sideways",history_count:lookback,net_move:net,path_move:path,efficiency,range_scale:scale,normalized_move:null};
  const normalized=net/scale, trend=efficiency>=efficiencyFloor&&normalized>=moveFloor?"uptrend":efficiency>=efficiencyFloor&&normalized<=-moveFloor?"downtrend":"sideways";
  return {state:"ready",trend_context:trend,history_count:lookback,net_move:net,path_move:path,efficiency,range_scale:scale,normalized_move:normalized};
}

function singlePattern(topicId:string,data:AnyMap):AnyMap{
  const c=candle(data.current,"current"),tick=positive(data.tick_size,"tick_size"),actualContext=context(data),[bodyScale,rangeScale,count]=referenceScales(data),a=anatomy(c);
  if(bodyScale===null||rangeScale===null)return patternResult({topicId,title:F02_TITLES[topicId],a,matchedGeometry:false,requiredContext:null,actualContext,bodyScale:null,rangeScale:null,historyCount:count,geometryScore:0,checks:{minimum_history:false}});
  const effectiveBody=Math.max(a.body,tick),dojiLimit=.10*rangeScale,shortShadowLimit=.05*rangeScale;let checks:Record<string,boolean>,requiredContext:string|null=null,score:number;
  switch(topicId){
    case"D06-F02-A01":checks={near_zero_body:a.body<=dojiLimit};score=1-a.body/Math.max(dojiLimit,tick);break;
    case"D06-F02-A02":checks={doji_body:a.body<=dojiLimit,short_upper_shadow:a.upper_shadow<=shortShadowLimit,long_lower_shadow:a.lower_shadow>=.60*rangeScale};score=a.lower_shadow/Math.max(rangeScale,tick);break;
    case"D06-F02-A03":checks={doji_body:a.body<=dojiLimit,long_upper_shadow:a.upper_shadow>=.60*rangeScale,short_lower_shadow:a.lower_shadow<=shortShadowLimit};score=a.upper_shadow/Math.max(rangeScale,tick);break;
    case"D06-F02-A04":checks={long_body:a.body>=1.20*bodyScale,short_upper_shadow:a.upper_shadow<=shortShadowLimit,short_lower_shadow:a.lower_shadow<=shortShadowLimit};score=a.body/Math.max(bodyScale,tick);break;
    case"D06-F02-A05":checks={short_body:a.body<=.60*bodyScale+1e-12,material_upper_shadow:a.upper_shadow+1e-12>=Math.max(a.body,.20*rangeScale),material_lower_shadow:a.lower_shadow+1e-12>=Math.max(a.body,.20*rangeScale)};score=Math.min(a.upper_shadow,a.lower_shadow)/effectiveBody;break;
    case"D06-F02-A06":case"D06-F02-A07":requiredContext=topicId.endsWith("A06")?"downtrend":"uptrend";checks={compact_body:a.body<=.75*bodyScale,long_lower_shadow:a.lower_shadow>=2*effectiveBody,short_upper_shadow:a.upper_shadow<=.25*effectiveBody,body_near_high:a.upper_shadow<=.25*Math.max(a.range,tick)};score=a.lower_shadow/effectiveBody;break;
    case"D06-F02-A08":case"D06-F02-A09":requiredContext=topicId.endsWith("A08")?"downtrend":"uptrend";checks={compact_body:a.body<=.75*bodyScale,long_upper_shadow:a.upper_shadow>=2*effectiveBody,short_lower_shadow:a.lower_shadow<=.25*effectiveBody,body_near_low:a.lower_shadow<=.25*Math.max(a.range,tick)};score=a.upper_shadow/effectiveBody;break;
    default:throw new RangeError(`unsupported single-candle topic ${topicId}`);
  }
  return patternResult({topicId,title:F02_TITLES[topicId],a,matchedGeometry:Object.values(checks).every(Boolean),requiredContext,actualContext,bodyScale,rangeScale,historyCount:count,geometryScore:score,checks});
}

function twoPattern(topicId:string,data:AnyMap):AnyMap{
  const first=candle(data.first,"first"),second=candle(data.second,"second"),tick=positive(data.tick_size,"tick_size"),tolerance=tick*nonnegative(data.price_tolerance_ticks,"price_tolerance_ticks"),actualContext=context(data),[bodyScale,rangeScale,count]=referenceScales(data),a=anatomy(first),b=anatomy(second);
  if(bodyScale===null||rangeScale===null){const result=patternResult({topicId,title:F03_TITLES[topicId],a:{body:b.body,upper_shadow:b.upper_shadow,lower_shadow:b.lower_shadow,range:b.range,direction:b.direction},matchedGeometry:false,requiredContext:null,actualContext,bodyScale:null,rangeScale:null,historyCount:count,geometryScore:0,checks:{minimum_history:false}});Object.assign(result,{first_direction:a.direction,second_direction:b.direction,first_body:a.body,second_body:b.body,price_tolerance:tolerance});return result;}
  const longFirst=a.body>=1.20*bodyScale,shortSecond=b.body<=.60*bodyScale,midpoint=(first.open+first.close)/2;let requiredContext:string,checks:Record<string,boolean>,score:number;
  switch(topicId){
    case"D06-F03-A01":requiredContext="downtrend";checks={first_bearish:a.direction==="bearish",second_bullish:b.direction==="bullish",lower_end_engulfed:b.body_low<=a.body_low,upper_end_engulfed:b.body_high>=a.body_high,strictly_larger_body:b.body>a.body};score=b.body/Math.max(a.body,tick);break;
    case"D06-F03-A02":requiredContext="uptrend";checks={first_bullish:a.direction==="bullish",second_bearish:b.direction==="bearish",lower_end_engulfed:b.body_low<=a.body_low,upper_end_engulfed:b.body_high>=a.body_high,strictly_larger_body:b.body>a.body};score=b.body/Math.max(a.body,tick);break;
    case"D06-F03-A03":requiredContext="downtrend";checks={first_bearish:a.direction==="bearish",long_first:longFirst,second_bullish:b.direction==="bullish",short_second:shortSecond,contained_low:b.body_low>=a.body_low,contained_high:b.body_high<=a.body_high,strict_containment:b.body_low>a.body_low||b.body_high<a.body_high};score=1-b.body/Math.max(a.body,tick);break;
    case"D06-F03-A04":requiredContext="uptrend";checks={first_bullish:a.direction==="bullish",long_first:longFirst,second_bearish:b.direction==="bearish",short_second:shortSecond,contained_low:b.body_low>=a.body_low,contained_high:b.body_high<=a.body_high,strict_containment:b.body_low>a.body_low||b.body_high<a.body_high};score=1-b.body/Math.max(a.body,tick);break;
    case"D06-F03-A05":requiredContext="downtrend";checks={first_bearish:a.direction==="bearish",long_first:longFirst,second_bullish:b.direction==="bullish",gap_below_first_low:second.open<=first.low-tick,close_above_midpoint:second.close>midpoint,close_below_first_open:second.close<first.open};score=(second.close-midpoint)/Math.max(a.body,tick);break;
    case"D06-F03-A06":requiredContext="uptrend";checks={first_bullish:a.direction==="bullish",long_first:longFirst,second_bearish:b.direction==="bearish",gap_above_first_high:second.open>=first.high+tick,close_below_midpoint:second.close<midpoint,close_above_first_open:second.close>first.open};score=(midpoint-second.close)/Math.max(a.body,tick);break;
    case"D06-F03-A07":requiredContext="uptrend";checks={first_bullish:a.direction==="bullish",second_bearish:b.direction==="bearish",highs_within_tolerance:Math.abs(first.high-second.high)<=tolerance,first_upper_rejection:a.upper_shadow>=.50*Math.max(a.body,tick),second_upper_rejection:b.upper_shadow>=.50*Math.max(b.body,tick)};score=Math.max(0,1-Math.abs(first.high-second.high)/Math.max(tolerance,tick));break;
    case"D06-F03-A08":requiredContext="downtrend";checks={first_bearish:a.direction==="bearish",second_bullish:b.direction==="bullish",lows_within_tolerance:Math.abs(first.low-second.low)<=tolerance,first_lower_rejection:a.lower_shadow>=.50*Math.max(a.body,tick),second_lower_rejection:b.lower_shadow>=.50*Math.max(b.body,tick)};score=Math.max(0,1-Math.abs(first.low-second.low)/Math.max(tolerance,tick));break;
    default:throw new RangeError(`unsupported two-candle topic ${topicId}`);
  }
  const result=patternResult({topicId,title:F03_TITLES[topicId],a:{body:b.body,upper_shadow:b.upper_shadow,lower_shadow:b.lower_shadow,range:b.range,direction:b.direction},matchedGeometry:Object.values(checks).every(Boolean),requiredContext,actualContext,bodyScale,rangeScale,historyCount:count,geometryScore:score,checks});
  Object.assign(result,{first_direction:a.direction,second_direction:b.direction,first_body:a.body,second_body:b.body,first_body_low:a.body_low,first_body_high:a.body_high,second_body_low:b.body_low,second_body_high:b.body_high,first_high:first.high,second_high:second.high,first_low:first.low,second_low:second.low,midpoint,price_tolerance:tolerance});return result;
}

export function calculate(topicId:string,inputs:AnyMap):AnyMap{
  if(!inputs||typeof inputs!=="object"||Array.isArray(inputs))throw new TypeError("inputs must be an object");
  if(topicId==="D06-F01-A03")return shadowToBody(inputs);
  if(topicId==="D06-F01-A04")return gapClassification(inputs);
  if(topicId==="D06-F01-A05")return trendContext(inputs);
  if(topicId in F02_TITLES)return singlePattern(topicId,inputs);
  if(topicId in F03_TITLES)return twoPattern(topicId,inputs);
  throw new RangeError(`unsupported topic id ${topicId}`);
}