Candlestick Pattern Recognition

A primer on candlesticks

A candlestick shows four prices for a chosen time period: Open, High, Low, and Close (OHLC).

The real body is the segment between the Open and the Close. If the Close is above the Open the candle is bullish; otherwise it is bearish.

The upper shadow extends from the top of the real body to the High; the lower shadow extends from the bottom of the real body to the Low. Together the shadows show how far price moved beyond the Open-Close range.

Candlestick patterns are defined by comparing the size and position of bodies and shadows—within a single candle or across a sequence of consecutive candles.

Available patterns

The 61 pattern functions can be loosely grouped by how many candles they inspect:

Every function has a descriptive snake_case name and an uppercase alias matching the TA-Lib convention (doji / CDLDOJI, engulfing / CDLENGULFING, etc.).

Return values

All pattern functions require OHLC columns (~open + high + low + close) and return an integer matrix of the same length as the input:

• 1 — bullish pattern (or direction-neutral pattern) identified
• -1 — bearish pattern identified
• 0 — no pattern

x <- talib::doji(talib::BTC)
table(x)
#> CDLDOJI
#>   0   1 
#> 300  56

Some patterns are inherently directional (e.g., engulfing() returns both 1 and -1), while others are direction-neutral (e.g., doji() always returns 1 for identified patterns).

options(talib.normalize = FALSE)
table(talib::engulfing(talib::BTC))
#> CDLENGULFING
#> -100  -80    0   80  100 
#>   19   11  297   12   25

## Evening Star with 30% penetration
x <- talib::evening_star(talib::BTC, eps = 0.3)
sum(abs(x), na.rm = TRUE)
#> [1] 0

Lookback and NA values

Every pattern has a lookback period: the number of initial rows that are returned as NA because the algorithm needs historical context before it can evaluate. The lookback depends on two things: the number of candles in the pattern itself, and the N parameter that controls how many prior candles are used to compute reference values for body/shadow classification.

x <- talib::doji(talib::BTC)
attr(x, "lookback")
#> [1] 10

Tuning candlestick settings

Pattern recognition in {talib} relies on classifying each candle’s body and shadows as “long”, “short”, “doji-like”, etc. These classifications are controlled by two parameters per setting:

• N (lookback): How many prior candles to average when computing the reference value.
• alpha (sensitivity): A multiplier applied to the reference value. The current candle is tested against alpha * reference.

All settings are modified via options() and take effect on the next pattern function call.

## default N = 10
sum(abs(talib::doji(talib::BTC)), na.rm = TRUE)
#> [1] 56

## shorter lookback
options(talib.BodyDoji.N = 3)
sum(abs(talib::doji(talib::BTC)), na.rm = TRUE)
#> [1] 61

## default alpha = 0.1
sum(abs(talib::doji(talib::BTC)), na.rm = TRUE)
#> [1] 56

## more permissive: accept bodies up to 20% of the high-low range
options(talib.BodyDoji.alpha = 0.2)
sum(abs(talib::doji(talib::BTC)), na.rm = TRUE)
#> [1] 109

Charting patterns

Candlestick patterns integrate with the {talib} charting system. Bullish patterns are marked below the candle, bearish patterns above, and direction-neutral patterns use a neutral style:

{
    talib::chart(talib::BTC)
    talib::indicator(talib::doji)
    talib::indicator(talib::engulfing)
}

Multiple patterns can be layered on the same chart. Each call to indicator() adds its markers to the existing price chart.

Contributing and bug reports

The underlying library, TA-Lib, is a long-standing and well-known library but this R wrapper is still in its early stage. All contributions, suggestions, and bug reports are welcome.