Bullish Engulfing Pattern Detection
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Bullish Engulfing Pattern Detection is a core feature of the Stolgo library, a Price Action Trading Analysis Library designed to automate trading rules and facilitate backtesting based on price movement rather than just technical indicators. The detection logic identifies a specific two-candle reversal pattern where a small bearish candle is followed by a larger bullish candle that completely "engulfs" the price range of the previous candle's body.
Sources: README.md:1-13, lib/stolgo/candlestick.py:10-22
Within the Stolgo ecosystem, this feature works alongside other price action tools such as Breakout Detection and Trend Analysis to provide a comprehensive suite for algorithmic trading.
Sources: README.md:46-51, lib/stolgo/trend.py:6-7, lib/stolgo/breakout.py:4-5
Detection Logic and Architecture
The detection of the Bullish Engulfing pattern is encapsulated within the CandleStick class. It relies on comparing the Open and Close prices of two consecutive candles within a pandas DataFrame.
Pattern Requirements
For a pattern to be identified as Bullish Engulfing at a specific position (defaulting to the most recent candle), the following conditions must be met:
- Minimum Data: The input DataFrame must contain at least two candles.
- First Candle: The previous candle must be bearish (Close < Open).
- Second Candle: The current candle must engulf the previous one:
- The current Close must be greater than the previous Open.
- The current Open must be less than the previous Close.
Sources: lib/stolgo/candlestick.py:5-22
Component Relationship
The following diagram illustrates the logical flow of pattern validation:
The logic ensures that the second candle's body completely overlaps the first candle's body.
Sources: lib/stolgo/candlestick.py:11-21, lib/stolgo/exception.py:1-3
Technical Implementation
The implementation uses pandas.iloc for positional indexing, allowing users to check for patterns at any point in a historical dataset.
Class: CandleStick
The CandleStick class provides the primary API for pattern detection.
| Method | Parameters | Description |
|---|---|---|
is_bullish_engulfing | candles (DataFrame), pos (int, default -1) | Validates the Bullish Engulfing pattern at the specified index. |
is_bearish_candle | candle (Series) | Returns True if Close < Open. |
is_bullish_candle | candle (Series) | Returns True if Close > Open. |
Sources: lib/stolgo/candlestick.py:3-22
Pattern Detection Sequence
This sequence diagram shows how a user interacts with the CandleStick module to identify the pattern.
Supporting Infrastructure
The pattern detection is supported by common utilities for data handling and custom error reporting.
Data Preparation
Before pattern detection, data is typically resampled or formatted using helper functions to ensure consistency in OHLC (Open, High, Low, Close) columns. The get_data_resample function standardizes column casing and aggregates data into the required timeframe.
Sources: lib/stolgo/helper.py:83-86
Error Handling
The system employs a custom exception, BadDataError, when insufficient data is provided for analysis. This is critical for the is_bullish_engulfing method which requires a minimum of two candles.
if candles.shape[0] < 2:
raise BadDataError("Minimun two candles require")
Sources: lib/stolgo/candlestick.py:12-13, lib/stolgo/exception.py:1-3
Integration with Trend and Breakout
In a typical Stolgo implementation, Bullish Engulfing detection is often combined with trend identification to confirm reversals at support levels.
| Module | Functionality | Relevance to Engulfing |
|---|---|---|
Trend | is_giant_downtrend | Identifying if a Bullish Engulfing occurs at the bottom of a downtrend. |
Breakout | is_consolidating | Determining if the pattern emerges from a period of price consolidation. |
Helper | get_data_resample | Standardizing OHLC data for accurate pattern indexing. |
Sources: lib/stolgo/trend.py:65-71, lib/stolgo/breakout.py:12-25, lib/stolgo/helper.py:83-86
Summary
The Bullish Engulfing Pattern Detection in Stolgo provides a programmatic way to identify key price action reversals. By leveraging pandas DataFrames and strict price-comparison logic, it allows developers to automate a classic trading rule within backtesting or live execution environments. It serves as a foundational component alongside trend and breakout analysis modules.