Candlestick Patterns Module
Relevant source files
The following files were used as context for generating this wiki page:
The Candlestick Patterns Module in the stolgo library provides essential utilities for Price Action Trading by identifying specific candle formations and market structures. It enables traders and developers to automate the detection of classic technical analysis patterns like Bullish Engulfing, Hammers, and Dojis within historical or real-time price data.
This module is designed to work with financial dataframes (typically OHLC format) to provide boolean indicators of price action rules. It serves as a core component of the broader stolgo ecosystem, which includes support for Trend and Breakout identification to facilitate algorithmic backtesting and strategy development.
Sources: README.md:3-12, lib/stolgo/candlestick.py:3
Module Architecture and Logic
The module is structured around the CandleStick class, which contains methods for individual candle classification (Bullish vs. Bearish) and complex multi-candle pattern recognition. The logic relies on comparing the relative positions of "Open", "High", "Low", and "Close" prices within a pandas.DataFrame.
Pattern Detection Flow
The following diagram illustrates the general logic used to determine a candle pattern, such as a Bullish Engulfing pattern, which requires a sequence of two candles.
The detection logic utilizes specific price thresholds and ratios to define candle shapes like the Hammer or Doji.
Sources: lib/stolgo/candlestick.py:3-19, lib/stolgo/exception.py:1-3
Key Pattern Indicators
The module identifies several primary candlestick patterns. Each detection method allows for custom sensitivity through parameters like body, upper_wick, and lower_wick ratios relative to the total candle length.
Candlestick Classification Table
| Pattern | Method | Description | Primary Requirements |
|---|---|---|---|
| Bearish Candle | is_bearish_candle | Basic price drop | Close < Open |
| Bullish Candle | is_bullish_candle | Basic price gain | Close > Open |
| Bullish Engulfing | is_bullish_engulfing | Reversal pattern | Prev is Bearish; Curr body "engulfs" Prev body |
| Hammer | is_hammer_candle | Trend reversal | Small upper wick, small body, long lower wick |
| Inverse Hammer | is_inverse_hammer_candle | Reversal/Warning | Long upper wick, small body, small lower wick |
| Doji | is_doji_candle | Indecision | Extremely small body, significant upper/lower wicks |
Sources: lib/stolgo/candlestick.py:5-84
Technical Implementation of Ratios
For complex candles like the Hammer or Doji, the module calculates candle_length (High - Low) and compares the components:
- Body: Absolute difference between Open and Close.
- Upper Wick: High minus the higher of Open/Close.
- Lower Wick: Lower of Open/Close minus Low.
# Example Hammer logic for a bullish candle
candle_upper_wick = curr_candle["High"] - curr_candle["Close"]
candle_body = curr_candle["Close"] - curr_candle["Open"]
if candle_body <= body * candle_length and candle_upper_wick <= upper_wick * candle_length:
return True
Sources: lib/stolgo/candlestick.py:25-30
Integration with Market Analysis
The Candlestick module is frequently used in conjunction with Trend and Breakout modules to provide context to the price action.
Related Analysis Modules
| Module | Purpose | Key Functions |
|---|---|---|
| Trend | Identifies directional momentum | is_giant_uptrend, is_giant_downtrend |
| Breakout | Detects price exits from ranges | is_consolidating, is_breaking_out |
Sources: lib/stolgo/trend.py:6-10, lib/stolgo/breakout.py:6-10
This relationship allows a developer to verify if a Bullish Engulfing pattern occurs specifically at a breakout point or during a specific trend.
Sources: lib/stolgo/trend.py:10-40, lib/stolgo/breakout.py:44-55
Error Handling
The module utilizes a custom exception, BadDataError, to handle scenarios where the provided data is insufficient for the requested analysis (e.g., requesting a two-candle pattern detection on a dataframe with only one row).
Sources: lib/stolgo/exception.py:1-3, lib/stolgo/candlestick.py:11
Conclusion
The Candlestick Patterns Module provides the low-level logic necessary for Price Action automation. By quantifying candle shapes and sequences into programmable rules, it allows for the objective identification of market sentiment and potential reversal points. When combined with the library's trend and breakout utilities, it forms a robust framework for technical analysis and algorithmic trading strategy development.