Breakout Analysis Module
Relevant source files
The following files were used as context for generating this wiki page:
The Breakout Analysis Module is a core component of the Stolgo library designed to automate Price Action Trading rules. Its primary purpose is to identify periods of price consolidation and subsequent breakouts or breakdowns from those ranges. By providing programmatic checks for these market conditions, the module enables developers to build and backtest trading strategies that rely on price volatility and range escapes rather than traditional lagging technical indicators.
Sources: README.md:1-12, lib/stolgo/breakout.py:4-7
Architecture and Core Logic
The module is encapsulated within the Breakout class, which maintains state regarding the default lookback period and consolidation sensitivity. The logic relies on processing historical candle data, typically provided as a pandas DataFrame containing at least a 'Close' column.
Consolidation Detection
A "consolidation" is defined as a state where the price remains within a specific percentage range over a defined number of periods. The module calculates the maximum and minimum closing prices within the window and verifies if the minimum price is greater than a percentage-adjusted maximum.
The diagram above illustrates the logical flow for determining if a security is currently consolidating.
Sources: lib/stolgo/breakout.py:9-39
Breakout and Breakdown Identification
Breakouts and breakdowns are identified by first confirming that the preceding data (excluding the most recent candle) represents a consolidation phase. Once consolidation is confirmed, the module compares the most recent candle's closing price against the maximum or minimum of that range.
| Condition | Logic | Result |
|---|---|---|
| Breakout | Consolidation confirmed + Last Close > Range Max | True |
| Breakdown | Consolidation confirmed + Last Close < Range Min | True |
Sources: lib/stolgo/breakout.py:41-83
Key Components and API
The Breakout Class
The Breakout class provides the primary interface for technical analysis.
| Method | Parameters | Description |
|---|---|---|
__init__ | periods (int), percentage (float) | Initializes default lookback and range sensitivity. |
is_consolidating | dfs, periods, percentage | Determines if the price is within a tight range. |
is_breaking_out | dfs, periods, percentage | Checks if the current price has exceeded the consolidation ceiling. |
is_breaking_down | dfs, periods, percentage | Checks if the current price has fallen below the consolidation floor. |
Sources: lib/stolgo/breakout.py:4-83
Data Dependencies
The module expects dataframes formatted similarly to those returned by the Nasdaq or Samco data modules. These dataframes must contain price action data, specifically 'Close' values indexed by time.
This sequence shows the interaction between data acquisition modules and the Breakout analysis logic.
Sources: lib/stolgo/nasdaq.py:97-133, lib/stolgo/samco.py:127-167, lib/stolgo/breakout.py:41-61
Error Handling
The module utilizes a custom exception class, BadDataError, defined in lib/stolgo/exception.py. This error is raised specifically when the input DataFrame does not contain enough data points to satisfy the requested periods for analysis.
Sources: lib/stolgo/exception.py:1-3, lib/stolgo/breakout.py:27-28
Usage Example
The following snippet demonstrates how to initialize the module and perform a breakout check on data fetched from an external provider.
from stolgo.breakout import Breakout
from bandl.nasdaq import Nasdaq # External data dependency
# 1. Fetch data
nasdaq = Nasdaq()
dfs = nasdaq.get_data("AAPL", periods=90)
# 2. Analyze for breakout
breakout_test = Breakout(periods=13, percentage=2)
is_be = breakout_test.is_breaking_out(dfs)
Sources: README.md:54-61, lib/stolgo/breakout.py:5-8
Summary
The Breakout Analysis Module provides a robust mechanism for detecting range-bound price action and the emergence of new trends through breakouts and breakdowns. By integrating with the library's data acquisition and helper modules, it allows for seamless transition from data fetching to technical evaluation, serving as a foundational tool for automated price action trading strategies.
Sources: README.md:1-12, lib/stolgo/breakout.py:4-83