Trend Analysis Module
Relevant source files
The following files were used as context for generating this wiki page:
The Trend Analysis Module is a core component of the Stolgo library, designed to facilitate Price Action Trading Analysis. It provides developers and traders with programmatic tools to identify market directions, price consolidation phases, and potential breakouts using historical price data. By automating rules based on support/resistance and price movement, the module allows for the backtesting of price action strategies.
Sources: README.md:1-12, lib/stolgo/trend.py:6-7
Architecture and Components
The module is structured around specialized classes that handle different aspects of price action. The Trend class focuses on identifying sustained directional movements, while the Breakout class identifies shifts from consolidation to new trends. These components rely on pandas.DataFrame inputs containing standard OHLC (Open, High, Low, Close) data.
Component Relationship
The following diagram illustrates how different analysis classes interact with market data to produce trend insights.
A flowchart showing the data flow from market DataFrames into analysis classes to determine trend results.
Sources: lib/stolgo/trend.py:6-7, lib/stolgo/breakout.py:4-5, lib/stolgo/candlestick.py:3-5
Trend Identification Logic
The module defines "giant" trends based on sequential candle colors and price progression over a specified period.
Uptrend Validation
A "giant uptrend" is identified when a series of candles meet two specific criteria:
- Every candle in the period must be "green" (Close > Open).
- Every candle's Close must be higher than the previous candle's Close.
Downtrend Validation
Conversely, a "giant downtrend" requires:
- Every candle in the period must be "red" (Close < Open).
- Every candle's Close must be lower than the previous candle's Close.
Sources: lib/stolgo/trend.py:10-75
Data Requirements
| Parameter | Type | Default | Description |
|---|---|---|---|
dfs | pandas.DataFrame | Required | Input candles containing 'Open' and 'Close' columns. |
periods | integer | 13 | The number of consecutive candles to analyze. |
percentage | float | 2 | Percentage range (used primarily for consolidation/breakout logic). |
Sources: lib/stolgo/trend.py:7-9, lib/stolgo/breakout.py:6-8
Consolidation and Breakout
The Breakout class provides the logic to detect when a market is moving sideways (consolidating) and when it exits that range.
Consolidation Detection
Consolidation is detected by calculating the range between the maximum and minimum closing prices over a period. If the min_close is greater than a specific percentage of the max_close, the price is considered to be within a consolidation range.
max_close = recent_dfs['Close'].max()
min_close = recent_dfs['Close'].min()
max_adjust = 1-(percentage/100)
if(min_close > max_close * max_adjust):
return True
Sources: lib/stolgo/breakout.py:27-33
Breakout Logic
The following sequence diagram shows the logic for determining a price breakout.
A sequence diagram depicting the internal logic for verifying a breakout after a period of consolidation.
Sources: lib/stolgo/breakout.py:44-59
Error Handling and Helpers
The module utilizes a custom exception and helper functions to ensure data integrity during analysis.
BadDataError: Raised when the input DataFrame does not contain enough rows to satisfy the requestedperiodsfor analysis.- Data Resampling: The
get_data_resamplehelper ensures that data is correctly formatted into OHLC dictionaries before analysis, which is critical for accurate trend detection.
Sources: lib/stolgo/exception.py:1-3, lib/stolgo/helper.py:79-82, lib/stolgo/trend.py:34-35
Summary
The Trend Analysis Module provides a structured approach to identifying market states—uptrends, downtrends, or consolidation—and detecting breakouts from those states. By utilizing standardized pandas DataFrames and configurable period/percentage parameters, it enables automated price action trading strategies within the Stolgo ecosystem.