Inverse Hammer Pattern Detection

Relevant source files

The following files were used as context for generating this wiki page:

• lib/stolgo/candlestick.py
• README.md
• lib/stolgo/helper.py
• lib/stolgo/samco.py
• lib/stolgo/nasdaq.py
• lib/stolgo/exception.py

Inverse Hammer Pattern Detection is a specific technical analysis feature within the Stolgo library used to identify a particular candlestick formation. Stolgo is a Price Action Trading Analysis Library designed to automate price action rules, such as support/resistance, trend, and candlestick patterns, facilitating backtesting for traders.

The detection of an inverted hammer is part of the CandleStick module, which provides APIs for common patterns like Bullish Engulfing and Hammer candles. This functionality relies on structured financial data (typically pandas DataFrames) fetched from external data providers like Samco, Nasdaq, or Yahoo Finance via the bandl library.

Sources: README.md:1-12, lib/stolgo/candlestick.py:53-72

Architectural Overview

The detection logic is encapsulated within the CandleStick class. It operates by analyzing OHLC (Open, High, Low, Close) data for a specific candle position in a time series.

Components and Data Flow

The detection process follows a structured flow from data acquisition to pattern validation:

1. Data Acquisition: Data is fetched using modules like Samco or Nasdaq and formatted into a pandas DataFrame.
2. Candle Identification: The user specifies a position (defaulting to the most recent candle) to analyze.
3. Pattern Calculation: The library calculates the ratios of the candle's body, upper wick, and lower wick relative to its total length.
4. Validation: If the ratios meet the threshold criteria for an inverse hammer, the function returns True.

The flow shows how raw financial data is processed through the detection API to determine the presence of a pattern.

Sources: lib/stolgo/candlestick.py:53-56, lib/stolgo/samco.py:129-135, lib/stolgo/nasdaq.py:90-100

Logic and Implementation

The detection logic differentiates between bullish and bearish candles while applying strict ratio requirements for the "Inverse Hammer" shape, which typically features a small body at the bottom and a long upper wick.

Detection Criteria

The function is_inverse_hammer_candle uses the following parameters to define the pattern:

Parameter	Type	Default Value	Description
candle	pd.DataFrame	Required	Input candle data series.
pos	int	-1	Index of the candle to analyze.
lower_wick	float	0.2	Maximum allowed ratio for the lower wick.
body	float	0.2	Maximum allowed ratio for the candle body.
upper_wick	float	0.6	Target ratio for the upper wick (implicit in validation).

Sources: lib/stolgo/candlestick.py:53-54

Computational Steps

For a candle at a given position, the total candle_length is defined as High - Low. The logic then branches based on the candle type:

• Bullish Candle (Close > Open):
  • candle_body = Close - Open
  • candle_upper_wick = High - Close
  • candle_lower_wick = Open - Low
• Bearish Candle (Close < Open):
  • candle_body = Open - Close
  • candle_upper_wick = Open - High (Note: Implementation shows Open - High, though typically calculated as High - Open)
  • candle_lower_wick = Close - Low

The pattern is confirmed if:

1. candle_body <= body * candle_length
2. candle_lower_wick <= lower_wick * candle_length

Sources: lib/stolgo/candlestick.py:53-72

This diagram illustrates the CandleStick class and its relationship with the custom exception module.

Sources: lib/stolgo/candlestick.py:3-72, lib/stolgo/exception.py:1-3

Usage Example

To detect an inverted hammer, the user first retrieves data and then calls the CandleStick detection method.

from stolgo.candlestick import CandleStick
# Assume 'dfs' is a pandas DataFrame with OHLC data
candle_test = CandleStick()
is_it = candle_test.is_inverse_hammer_candle(dfs)

Sources: README.md:54-58

Data Dependencies

Pattern detection relies on accurate data formatting. The helper.py module provides utilities to ensure DataFrames are correctly structured before analysis, such as resampling or date range formatting. If the data is insufficient (e.g., empty DataFrames), the system may raise a BadDataError.

Sources: lib/stolgo/helper.py:82-85, lib/stolgo/exception.py:1-3

Summary

Inverse Hammer Pattern Detection in Stolgo provides a programmatic way to identify potential trend reversals based on price action. By allowing configurable wick and body ratios, the library offers flexibility for different market conditions while abstracting the complex geometric calculations of candlestick charting. Sources: README.md:1-10, lib/stolgo/candlestick.py:53-72