Candlestick Pattern Occurrence Contract

Candlestick scanners become difficult to trust when a pattern name is the only evidence they return. This tutorial builds the missing contract around one question: What exact, point-in-time record proves that one detector matched one closed-bar window? By the end, you can normalize detector hits into reproducible occurrences with stable identity, causal timestamps, version, geometry score, and reason codes and verify the same result in Python and TypeScript.

Begin with the decision, not the chart decoration

A pattern label without its bar span, detector version, price basis, session, and availability time cannot be reproduced or safely deduplicated. TA-Lib’s official catalog demonstrates that many candlestick detectors can share an OHLC-array interface, while its API supports both whole-array and streaming execution (function catalog, core API). Our task is not to imitate undocumented vendor settings. It is to make the scanner boundary observable.

The selected formula is:

$$occurrence\_id=instrument\mid interval\mid end\_time\mid pattern\_id\mid start:end\mid version$$

The comparison is inclusive, the remaining tie-breaks are stable, and unavailable evidence never becomes a convenient zero. Those are implementation choices. They make behavior testable; they do not prove a market edge.

Follow the data contract

The canonical input and output tables live in the topic README. Preserve source-qualified instrument identity, interval and session, price basis, detector version, event time, availability time, and closed-bar state. Binance’s official kline stream shows why finality must be explicit: its payload distinguishes an updating bar from a closed one (provider schema). The exact fields differ across providers, so adapt at ingestion and keep the algorithm provider-neutral.

What to notice: validation and time eligibility happen before the decision. A plausible pattern found with later information is still invalid for a point-in-time scan.

Open the accessible full-size diagram. The guided lab lets you step through canonical, equality-boundary, and rejected states with reduced-motion support.

Recalculate the fixture

A two-bar bullish-engulfing hit on SYNTH:AAA ends at 10:05Z. The contract combines its instrument, interval, end time, pattern ID, span 10:11, and detector version v1. This is labeled synthetic teaching data. The stored expected values were frozen independently of either implementation; both languages must match them within 1e-9 for numbers and exactly for identifiers, arrays, booleans, reason codes, and states.

Implement one source of scanner semantics

The topic-specific Python and TypeScript entry points delegate to a shared D06-F05 family core. That architecture prevents nine packages from inventing nine versions of finite-number checks, inclusive boundaries, and error semantics. It does not hide the topic algorithm: each public wrapper names exactly one core function, and the canonical README freezes its behavior before derivatives.

Run the Python test with python tests/test_pattern_occurrence.py and the TypeScript test with node --test tests/pattern_occurrence.test.ts from the topic folder. The shared fixture is the cross-language oracle.

Interpret the result carefully

A detector can match geometry, the context can score highly, confirmation can occur, and the ranked alert can still lose money. Lo, Mamaysky, and Wang’s computational work is useful here because it separates systematic recognition from an empirical evaluation design (NBER Working Paper 7613). A production claim needs point-in-time universe membership, survivorship controls, costs, multiple-testing controls, out-of-sample data, and uncertainty. This tutorial claims only reproducible infrastructure behavior.

Failure checklist

• Reject provisional terminal bars and future-known levels.
• Do not mix raw and adjusted prices or incompatible session calendars.
• Preserve warm-up, zero-scale, invalid, suppressed, and expired states.
• Version definitions before changing thresholds or precedence.
• Keep ranking scores distinct from probabilities and expected returns.
• Retain reason codes so an operator can explain every accepted or rejected event.

What comes next

Continue through the related topics listed in the canonical package. Together the family moves from a stable detector registry to occurrence evidence, causal scanning, context, conflict handling, confirmation, and final ranked deduplicated output. Full sources and applicability boundaries are in REFERENCES.md.