Candlestick patterns

The 61 classic candlestick patterns — doji, hammer, engulfing, morning star, three black crows — recognized directly from OHLC bars. Every pattern is a single pl.Expr, so detection runs vectorized alongside the rest of your feature pipeline.

The pattern definitions follow TA-Lib, the de-facto reference for this family. The implementation is a Polars rewrite, not a port: TA-Lib walks one bar at a time carrying running sums and mutable state, while these compile to shifts and rolling windows over columns.

What a pattern returns

Value	Meaning
100	Bullish occurrence
-100	Bearish occurrence
0	Pattern not present on this bar
null	Warm-up — not enough history to decide

Patterns that are inherently one-sided (a hammer is always bullish) return 100/0. Patterns that occur in both directions — engulfing, harami, marubozu — return the signed value, taken from candle color or from which side the setup formed on.

Warm-up is null, not zero

This is the one deliberate divergence from TA-Lib, which reports 0 for bars it could not evaluate. Here a 0 always means "I checked, no pattern" and null means "not enough history to check" — so a warm-up bar can never be mistaken for a genuine negative when these become model features.

Quick start

Every function defaults to the conventional open/high/low/close column names, so the common case needs no arguments:

import polars as pl
from polars_ta import candles

df.with_columns(
    candles.cdl_engulfing().alias("engulfing"),
    candles.cdl_hammer().alias("hammer"),
    candles.cdl_morning_star().alias("morning_star"),
)

Custom column names, the expression namespace, and per-symbol frames all behave as they do everywhere else in the library:

candles.cdl_doji("o", "h", "l", "c")     # custom column names
pl.col("open").ta.cdl_doji()             # namespace (binds to `open`)
df.with_columns(candles.cdl_harami().over("symbol"))   # multi-asset

Computing all 61 at once

ALL_PATTERNS maps each name to its function, which makes the whole family one with_columns call:

df.with_columns(fn().alias(name) for name, fn in candles.ALL_PATTERNS.items())

To collapse them into a single score — how many bullish patterns fired minus how many bearish ones, a common feature-engineering shortcut:

score = pl.sum_horizontal(
    [fn().fill_null(0) for fn in candles.ALL_PATTERNS.values()]
) / 100
df.with_columns(score.alias("candle_score"))

How thresholds are decided

A pattern like "hammer" is not a crisp predicate — it needs a notion of "short body" and "long lower shadow", and those only mean something relative to recent candles. TA-Lib solves this with a settings table mapping each qualitative term to a (range type, average period, factor) triple, and this library keeps that idea:

Term	Measured against	Period	Factor
BodyLong	real body	10	1.0
BodyVeryLong	real body	10	3.0
BodyShort	real body	10	1.0
BodyDoji	high-low range	10	0.1
ShadowLong	real body	0	1.0
ShadowVeryLong	real body	0	2.0
ShadowShort	both shadows	10	1.0
ShadowVeryShort	high-low range	10	0.1
Near	high-low range	5	0.2
Far	high-low range	5	0.6
Equal	high-low range	5	0.05

So BodyDoji means "body no larger than 10% of the average high-low range of the previous 10 candles". Because the thresholds are relative, a pattern means the same thing on a $3 stock and a $3,000 one, and adapts as volatility regimes shift. A period of 0 means "compare against this same candle" — used by the shadow terms, which judge a shadow against its own body.

Two details are load-bearing:

• The average excludes the candle being judged. The threshold at bar i is built from bars [i-period, i-1], so a candle never helps set the bar it is measured against. (A naive rolling_mean gets this wrong, and it matters most on exactly the outlier candles the patterns care about.)
• The Shadows range type is halved, since it sums two shadows.

Thresholds live in polars_ta._candle_internal.CANDLE_SETTINGS. Adjusting a value there retunes every pattern that uses that term coherently — which is the main reason to keep a table instead of scattering constants across 61 functions.

Patterns are not signals

The frequency chart above is a useful reality check. Over 5,000 real BTCUSDT 5-minute bars, belt hold fires on over a thousand of them while thrusting fires once. Common patterns are mostly noise at this timeframe; rare ones give you too few observations to fit anything on.

Treat these as features, not trading signals

Candlestick patterns are weak, noisy predictors on their own, and the literature on their standalone edge is not encouraging. They are most useful as conditioning features — combined with trend, volatility, or volume context, or as inputs to a model that can learn when they matter. Nothing in this library validates that a pattern has predictive value on your data; measure that yourself before trading it.

A reasonable way to use them is as context-gated features — for example, only treating a bullish reversal pattern as interesting when the market is already oversold:

from polars_ta import candles, momentum

df.with_columns(
    (
        (candles.cdl_hammer() == 100) & (momentum.rsi("close", 14) < 30)
    ).alias("hammer_in_oversold")
)

Pattern reference

The 61 patterns, grouped by how many candles they inspect:

Candles	Patterns
1	cdl_doji, cdl_dragonfly_doji, cdl_gravestone_doji, cdl_long_legged_doji, cdl_rickshaw_man, cdl_takuri, cdl_marubozu, cdl_closing_marubozu, cdl_long_line, cdl_short_line, cdl_spinning_top, cdl_high_wave, cdl_belt_hold
2	cdl_doji_star, cdl_hammer, cdl_hanging_man, cdl_inverted_hammer, cdl_shooting_star, cdl_engulfing, cdl_harami, cdl_harami_cross, cdl_piercing, cdl_dark_cloud_cover, cdl_counterattack, cdl_separating_lines, cdl_on_neck, cdl_in_neck, cdl_thrusting, cdl_homing_pigeon, cdl_matching_low, cdl_kicking, cdl_kicking_by_length
3	cdl_morning_star, cdl_evening_star, cdl_morning_doji_star, cdl_evening_doji_star, cdl_abandoned_baby, cdl_tristar, cdl_3_white_soldiers, cdl_3_black_crows, cdl_identical_3_crows, cdl_2_crows, cdl_upside_gap_2_crows, cdl_3_inside, cdl_3_outside, cdl_3_stars_in_south, cdl_advance_block, cdl_stalled_pattern, cdl_unique_3_river, cdl_stick_sandwich, cdl_tasuki_gap, cdl_gap_side_side_white, cdl_xside_gap_3_methods, cdl_hikkake
4–5	cdl_concealing_baby_swallow, cdl_3_line_strike, cdl_rise_fall_3_methods, cdl_mat_hold, cdl_breakaway, cdl_ladder_bottom, cdl_hikkake_mod

Seven patterns take a penetration argument controlling how far one candle must close into another: cdl_morning_star, cdl_evening_star, cdl_morning_doji_star, cdl_evening_doji_star, cdl_abandoned_baby, cdl_mat_hold (default 0.3, 0.5 for mat hold), and cdl_dark_cloud_cover (default 0.5). Raising it makes the pattern stricter.

---

polars_ta.candles

Candlestick pattern recognition — 61 patterns, as pure Polars expressions.

Rewritten for Polars, inspired by TA-Lib

The pattern definitions here — which candles must be black or white, how far a gap must reach, what counts as a "long" body — follow TA-Lib's C implementations, which are the de-facto reference for these patterns and encode decades of accumulated convention. Nothing is ported line-by-line: TA-Lib walks one bar at a time with running trailing sums and mutable state, whereas every function here compiles to a single vectorized pl.Expr built from shifts and rolling windows. The output is designed to match TA-Lib's, so you can diff against talib directly.

Ideas worth keeping from TA-Lib

Two of its design choices carried over because they are genuinely good, and both live in :mod:polars_ta._candle_internal:

• A global settings table instead of magic numbers. "Long body" means "bigger than 1.0x the average body of the last 10 candles" — a relative threshold, so a pattern means the same thing on a $3 stock and a $3,000 one, and adapts as volatility regimes change. Retuning CANDLE_SETTINGS retunes every pattern coherently.
• The average excludes the candle being judged, so a candle never helps set the threshold it is measured against. See the _candle_internal docstring.

What the output means

Each function returns an Int32 expression:

Value	Meaning
100	Bullish occurrence
-100	Bearish occurrence
0	Pattern not present
null	Warm-up — not enough history to decide

The null warm-up is the one deliberate divergence from TA-Lib, which reports 0 for bars it could not evaluate. This library's convention is that warm-up is null and never faked, so a "no pattern here" is never confused with a "could not tell" — which matters when these become model features.

Patterns that are inherently one-sided (a hammer is always bullish) return 100/0; patterns that come in both directions (engulfing, harami) return the signed value.

These are features, not signals

Candlestick patterns are weak, noisy predictors on their own, and most fire far too often to trade unfiltered. They are most useful as conditioning features — combined with trend, volatility, or volume context. Nothing here validates that a pattern has predictive value on your data.

Usage

Every function defaults to the conventional column names, so the common case is a bare call:

import polars as pl
from polars_ta import candles

df.with_columns(
    candles.cdl_engulfing().alias("engulfing"),
    candles.cdl_hammer().alias("hammer"),
    candles.cdl_morning_star(penetration=0.3).alias("morning_star"),
)

Custom column names, an expression namespace call, and per-symbol frames all work the way they do everywhere else in the library:

candles.cdl_doji("o", "h", "l", "c")
pl.col("open").ta.cdl_doji()
df.with_columns(candles.cdl_harami().over("symbol"))

ALL_PATTERNS maps every pattern name to its function, for computing the whole family at once:

df.with_columns(fn().alias(name) for name, fn in candles.ALL_PATTERNS.items())

cdl_doji

cdl_doji(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Doji — open and close virtually equal.

A body smaller than 10% of the recent high-low range. Signals indecision: buyers and sellers finished the bar where they started.

Source code in polars_ta/candles.py

def cdl_doji(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Doji — open and close virtually equal.

    A body smaller than 10% of the recent high-low range. Signals indecision:
    buyers and sellers finished the bar where they started.
    """
    c = make_candles(open_, high, low, close)
    cond = c.body() <= c.average("BodyDoji")
    return signal(cond, 1, warmup=_settings_warmup(c, 0, "BodyDoji"))

cdl_doji_star

cdl_doji_star(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Doji Star — a long candle, then a doji gapping away from it.

Bearish (-100) after a long white candle that gaps up, bullish (100) after a long black candle that gaps down: momentum has stalled.

Source code in polars_ta/candles.py

def cdl_doji_star(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Doji Star — a long candle, then a doji gapping away from it.

    Bearish (`-100`) after a long white candle that gaps up, bullish (`100`)
    after a long black candle that gaps down: momentum has stalled.
    """
    c = make_candles(open_, high, low, close)
    long_first = c.body(1) > c.average("BodyLong", 1)
    doji = c.body(0) <= c.average("BodyDoji", 0)
    gap_up = c.is_white(1) & (c.body_bottom(0) > c.body_top(1))
    gap_down = c.is_black(1) & (c.body_top(0) < c.body_bottom(1))
    cond = long_first & doji & (gap_up | gap_down)
    direction = pl.when(c.is_white(1)).then(-1).otherwise(1)
    return signal(cond, direction, warmup=_settings_warmup(c, 1, "BodyLong"))

cdl_dragonfly_doji

cdl_dragonfly_doji(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Dragonfly Doji — doji with a long lower shadow and no upper shadow.

Price sold off hard and recovered entirely by the close.

Source code in polars_ta/candles.py

def cdl_dragonfly_doji(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Dragonfly Doji — doji with a long lower shadow and no upper shadow.

    Price sold off hard and recovered entirely by the close.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body() <= c.average("BodyDoji"))
        & (c.upper_shadow() < c.average("ShadowVeryShort"))
        & (c.lower_shadow() > c.average("ShadowLong"))
    )
    return signal(
        cond, 1, warmup=_settings_warmup(c, 0, "BodyDoji", "ShadowVeryShort")
    )

cdl_gravestone_doji

cdl_gravestone_doji(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Gravestone Doji — doji with a long upper shadow and no lower shadow.

The mirror of the dragonfly: a rally that gave everything back.

Source code in polars_ta/candles.py

def cdl_gravestone_doji(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Gravestone Doji — doji with a long upper shadow and no lower shadow.

    The mirror of the dragonfly: a rally that gave everything back.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body() <= c.average("BodyDoji"))
        & (c.lower_shadow() < c.average("ShadowVeryShort"))
        & (c.upper_shadow() > c.average("ShadowLong"))
    )
    return signal(
        cond, 1, warmup=_settings_warmup(c, 0, "BodyDoji", "ShadowVeryShort")
    )

cdl_long_legged_doji

cdl_long_legged_doji(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Long Legged Doji — doji with at least one very long shadow.

Wide-ranging indecision: the bar covered a lot of ground and settled flat.

Source code in polars_ta/candles.py

def cdl_long_legged_doji(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Long Legged Doji — doji with at least one very long shadow.

    Wide-ranging indecision: the bar covered a lot of ground and settled flat.
    """
    c = make_candles(open_, high, low, close)
    cond = (c.body() <= c.average("BodyDoji")) & (
        (c.lower_shadow() > c.average("ShadowLong"))
        | (c.upper_shadow() > c.average("ShadowLong"))
    )
    return signal(cond, 1, warmup=_settings_warmup(c, 0, "BodyDoji"))

cdl_rickshaw_man

cdl_rickshaw_man(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Rickshaw Man — long-legged doji whose body sits near the range midpoint.

Source code in polars_ta/candles.py

def cdl_rickshaw_man(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Rickshaw Man — long-legged doji whose body sits near the range midpoint."""
    c = make_candles(open_, high, low, close)
    hl_mid_lo = c.low_() + c.high_low_range() / 2 - c.average("Near")
    hl_mid_hi = c.low_() + c.high_low_range() / 2 + c.average("Near")
    cond = (
        (c.body() <= c.average("BodyDoji"))
        & (c.lower_shadow() > c.average("ShadowLong"))
        & (c.upper_shadow() > c.average("ShadowLong"))
        & (c.body_bottom() <= hl_mid_hi)
        & (c.body_top() >= hl_mid_lo)
    )
    return signal(cond, 1, warmup=_settings_warmup(c, 0, "BodyDoji", "Near"))

cdl_takuri

cdl_takuri(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Takuri — a dragonfly doji with an exceptionally long lower shadow.

Source code in polars_ta/candles.py

def cdl_takuri(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Takuri — a dragonfly doji with an exceptionally long lower shadow."""
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body() <= c.average("BodyDoji"))
        & (c.upper_shadow() < c.average("ShadowVeryShort"))
        & (c.lower_shadow() > c.average("ShadowVeryLong"))
    )
    return signal(
        cond, 1, warmup=_settings_warmup(c, 0, "BodyDoji", "ShadowVeryShort")
    )

cdl_marubozu

cdl_marubozu(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Marubozu — a long candle with essentially no shadows.

One side controlled the entire bar: the open and close are the extremes. Signed by candle color.

Source code in polars_ta/candles.py

def cdl_marubozu(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Marubozu — a long candle with essentially no shadows.

    One side controlled the entire bar: the open and close *are* the extremes.
    Signed by candle color.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body() > c.average("BodyLong"))
        & (c.upper_shadow() < c.average("ShadowVeryShort"))
        & (c.lower_shadow() < c.average("ShadowVeryShort"))
    )
    return signal(
        cond,
        c.color(),
        warmup=_settings_warmup(c, 0, "BodyLong", "ShadowVeryShort"),
    )

cdl_closing_marubozu

cdl_closing_marubozu(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Closing Marubozu — long candle with no shadow on the closing end.

The close finished at the extreme of the bar; the opening end may have a shadow. Signed by candle color.

Source code in polars_ta/candles.py

def cdl_closing_marubozu(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Closing Marubozu — long candle with no shadow on the *closing* end.

    The close finished at the extreme of the bar; the opening end may have a
    shadow. Signed by candle color.
    """
    c = make_candles(open_, high, low, close)
    very_short = c.average("ShadowVeryShort")
    white_ok = c.is_white() & (c.upper_shadow() < very_short)
    black_ok = c.is_black() & (c.lower_shadow() < very_short)
    cond = (c.body() > c.average("BodyLong")) & (white_ok | black_ok)
    return signal(
        cond,
        c.color(),
        warmup=_settings_warmup(c, 0, "BodyLong", "ShadowVeryShort"),
    )

cdl_long_line

cdl_long_line(open_: str | Expr = _L" backlink-type="used-by" backlink-anchor="polars_ta.candles.cdl_long_line" optional>_L, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Long Line Candle — a long body with short shadows. Signed by color.

Source code in polars_ta/candles.py

def cdl_long_line(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Long Line Candle — a long body with short shadows. Signed by color."""
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body() > c.average("BodyLong"))
        & (c.upper_shadow() < c.average("ShadowShort"))
        & (c.lower_shadow() < c.average("ShadowShort"))
    )
    return signal(
        cond, c.color(), warmup=_settings_warmup(c, 0, "BodyLong", "ShadowShort")
    )

cdl_short_line

cdl_short_line(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Short Line Candle — a short body with short shadows. Signed by color.

Source code in polars_ta/candles.py

def cdl_short_line(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Short Line Candle — a short body with short shadows. Signed by color."""
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body() < c.average("BodyShort"))
        & (c.upper_shadow() < c.average("ShadowShort"))
        & (c.lower_shadow() < c.average("ShadowShort"))
    )
    return signal(
        cond, c.color(), warmup=_settings_warmup(c, 0, "BodyShort", "ShadowShort")
    )

cdl_spinning_top

cdl_spinning_top(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Spinning Top — small body with both shadows longer than it.

Indecision, but with more range than a doji. Signed by color.

Source code in polars_ta/candles.py

def cdl_spinning_top(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Spinning Top — small body with both shadows longer than it.

    Indecision, but with more range than a doji. Signed by color.
    """
    c = make_candles(open_, high, low, close)
    body = c.body()
    cond = (
        (body < c.average("BodyShort"))
        & (c.upper_shadow() > body)
        & (c.lower_shadow() > body)
    )
    return signal(cond, c.color(), warmup=_settings_warmup(c, 0, "BodyShort"))

cdl_high_wave

cdl_high_wave(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

High-Wave Candle — small body with very long shadows on both sides.

Extreme volatility with no resolution. Signed by color.

Source code in polars_ta/candles.py

def cdl_high_wave(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """High-Wave Candle — small body with *very* long shadows on both sides.

    Extreme volatility with no resolution. Signed by color.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body() < c.average("BodyShort"))
        & (c.upper_shadow() > c.average("ShadowVeryLong"))
        & (c.lower_shadow() > c.average("ShadowVeryLong"))
    )
    return signal(cond, c.color(), warmup=_settings_warmup(c, 0, "BodyShort"))

cdl_belt_hold

cdl_belt_hold(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Belt-hold — a long candle that opens at its own extreme.

Bullish when a long white candle opens at its low, bearish when a long black candle opens at its high.

Source code in polars_ta/candles.py

def cdl_belt_hold(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Belt-hold — a long candle that opens at its own extreme.

    Bullish when a long white candle opens at its low, bearish when a long
    black candle opens at its high.
    """
    c = make_candles(open_, high, low, close)
    very_short = c.average("ShadowVeryShort")
    long_body = c.body() > c.average("BodyLong")
    bullish = c.is_white() & (c.lower_shadow() < very_short)
    bearish = c.is_black() & (c.upper_shadow() < very_short)
    cond = long_body & (bullish | bearish)
    return signal(
        cond,
        c.color(),
        warmup=_settings_warmup(c, 0, "BodyLong", "ShadowVeryShort"),
    )

cdl_hammer

cdl_hammer(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Hammer — small body at the top, long lower shadow, after a decline.

Bullish reversal: sellers pushed price down and were fully rejected. The body must also sit near the prior candle's low, which is what ties it to a downtrend rather than firing anywhere.

Source code in polars_ta/candles.py

def cdl_hammer(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Hammer — small body at the top, long lower shadow, after a decline.

    Bullish reversal: sellers pushed price down and were fully rejected. The
    body must also sit near the prior candle's low, which is what ties it to a
    downtrend rather than firing anywhere.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body() < c.average("BodyShort"))
        & (c.lower_shadow() > c.average("ShadowLong"))
        & (c.upper_shadow() < c.average("ShadowVeryShort"))
        & (c.body_bottom() <= c.low_(1) + c.average("Near", 1))
    )
    return signal(
        cond,
        1,
        warmup=_settings_warmup(c, 1, "BodyShort", "ShadowVeryShort", "Near"),
    )

cdl_hanging_man

cdl_hanging_man(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Hanging Man — hammer shape, but occurring after an advance.

Same geometry as the hammer; bearish because of where it appears — the body sits near the prior candle's high.

Source code in polars_ta/candles.py

def cdl_hanging_man(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Hanging Man — hammer shape, but occurring after an advance.

    Same geometry as the hammer; bearish because of where it appears — the body
    sits near the prior candle's *high*.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body() < c.average("BodyShort"))
        & (c.lower_shadow() > c.average("ShadowLong"))
        & (c.upper_shadow() < c.average("ShadowVeryShort"))
        & (c.body_bottom() >= c.h(1) - c.average("Near", 1))
    )
    return signal(
        cond,
        -1,
        warmup=_settings_warmup(c, 1, "BodyShort", "ShadowVeryShort", "Near"),
    )

cdl_inverted_hammer

cdl_inverted_hammer(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Inverted Hammer — small body, long upper shadow, gapping down after a fall.

Bullish reversal: an intrabar rally attempt after a gap down.

Source code in polars_ta/candles.py

def cdl_inverted_hammer(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Inverted Hammer — small body, long upper shadow, gapping down after a fall.

    Bullish reversal: an intrabar rally attempt after a gap down.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body() < c.average("BodyShort"))
        & (c.upper_shadow() > c.average("ShadowLong"))
        & (c.lower_shadow() < c.average("ShadowVeryShort"))
        & (c.body_top() < c.body_bottom(1))
    )
    return signal(
        cond, 1, warmup=_settings_warmup(c, 1, "BodyShort", "ShadowVeryShort")
    )

cdl_shooting_star

cdl_shooting_star(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Shooting Star — small body, long upper shadow, gapping up after a rally.

Bearish reversal: the mirror of the inverted hammer.

Source code in polars_ta/candles.py

def cdl_shooting_star(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Shooting Star — small body, long upper shadow, gapping up after a rally.

    Bearish reversal: the mirror of the inverted hammer.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body() < c.average("BodyShort"))
        & (c.upper_shadow() > c.average("ShadowLong"))
        & (c.lower_shadow() < c.average("ShadowVeryShort"))
        & (c.body_bottom() > c.body_top(1))
    )
    return signal(
        cond, -1, warmup=_settings_warmup(c, 1, "BodyShort", "ShadowVeryShort")
    )

cdl_engulfing

cdl_engulfing(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Engulfing Pattern — a body that completely swallows the previous one.

Bullish when a white candle engulfs a prior black body, bearish for the reverse. One of the few patterns with no threshold tuning at all: it is pure geometry.

Source code in polars_ta/candles.py

def cdl_engulfing(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Engulfing Pattern — a body that completely swallows the previous one.

    Bullish when a white candle engulfs a prior black body, bearish for the
    reverse. One of the few patterns with no threshold tuning at all: it is
    pure geometry.
    """
    c = make_candles(open_, high, low, close)
    bullish = (
        c.is_white(0) & c.is_black(1) & (c.c(0) >= c.o(1)) & (c.o(0) <= c.c(1))
    )
    bearish = (
        c.is_black(0) & c.is_white(1) & (c.o(0) >= c.c(1)) & (c.c(0) <= c.o(1))
    )
    direction = pl.when(bullish).then(1).otherwise(-1)
    return signal(bullish | bearish, direction, warmup=_warmup(c, 1))

cdl_harami

cdl_harami(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Harami Pattern — a small body contained within the previous long body.

The inverse of engulfing: momentum compressed rather than reversed. Bullish after a long black candle, bearish after a long white one.

Source code in polars_ta/candles.py

def cdl_harami(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Harami Pattern — a small body contained within the previous long body.

    The inverse of engulfing: momentum compressed rather than reversed.
    Bullish after a long black candle, bearish after a long white one.
    """
    c = make_candles(open_, high, low, close)
    contained = (
        (c.body(1) > c.average("BodyLong", 1))
        & (c.body(0) < c.average("BodyShort", 0))
        & (c.body_top(0) <= c.body_top(1))
        & (c.body_bottom(0) >= c.body_bottom(1))
    )
    bullish = contained & c.is_black(1)
    bearish = contained & c.is_white(1)
    direction = pl.when(c.is_black(1)).then(1).otherwise(-1)
    return signal(
        bullish | bearish,
        direction,
        warmup=_settings_warmup(c, 1, "BodyLong", "BodyShort"),
    )

cdl_harami_cross

cdl_harami_cross(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Harami Cross — a harami whose second candle is a doji.

Considered a stronger signal than a plain harami: total indecision inside the prior body.

Source code in polars_ta/candles.py

def cdl_harami_cross(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Harami Cross — a harami whose second candle is a doji.

    Considered a stronger signal than a plain harami: total indecision inside
    the prior body.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body(1) > c.average("BodyLong", 1))
        & (c.body(0) <= c.average("BodyDoji", 0))
        & (c.body_top(0) <= c.body_top(1))
        & (c.body_bottom(0) >= c.body_bottom(1))
    )
    direction = pl.when(c.is_black(1)).then(1).otherwise(-1)
    return signal(
        cond, direction, warmup=_settings_warmup(c, 1, "BodyLong", "BodyDoji")
    )

cdl_piercing

cdl_piercing(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Piercing Pattern — a white candle closing above the midpoint of a black one.

Bullish reversal: price gapped down, then bought back more than half of the previous day's loss.

Source code in polars_ta/candles.py

def cdl_piercing(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Piercing Pattern — a white candle closing above the midpoint of a black one.

    Bullish reversal: price gapped down, then bought back more than half of the
    previous day's loss.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_black(1)
        & (c.body(1) > c.average("BodyLong", 1))
        & c.is_white(0)
        & (c.o(0) < c.low_(1))
        & (c.c(0) > c.c(1) + c.body(1) * 0.5)
        & (c.c(0) < c.o(1))
    )
    return signal(cond, 1, warmup=_settings_warmup(c, 1, "BodyLong"))

cdl_dark_cloud_cover

cdl_dark_cloud_cover(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C, penetration: float = 0.5) -> Expr

Dark Cloud Cover — a black candle closing well into a prior white body.

The bearish mirror of piercing.

Parameters:

Name	Type	Description	Default
penetration	float	How far the black body must close into the white one, as a fraction of that body. TA-Lib's default is 0.5.	0.5

Source code in polars_ta/candles.py

def cdl_dark_cloud_cover(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
    penetration: float = 0.5,
) -> pl.Expr:
    """Dark Cloud Cover — a black candle closing well into a prior white body.

    The bearish mirror of piercing.

    Args:
        penetration: How far the black body must close into the white one, as a
            fraction of that body. TA-Lib's default is `0.5`.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_white(1)
        & (c.body(1) > c.average("BodyLong", 1))
        & c.is_black(0)
        & (c.o(0) > c.h(1))
        & (c.c(0) > c.o(1))
        & (c.c(0) < c.c(1) - c.body(1) * penetration)
    )
    return signal(cond, -1, warmup=_settings_warmup(c, 1, "BodyLong"))

cdl_counterattack

cdl_counterattack(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Counterattack — two long opposite-colored candles closing at the same level.

A gap in the trend direction that is completely erased by the close.

Source code in polars_ta/candles.py

def cdl_counterattack(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Counterattack — two long opposite-colored candles closing at the same level.

    A gap in the trend direction that is completely erased by the close.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.color(0) == -c.color(1))
        & (c.body(0) > c.average("BodyLong", 0))
        & (c.body(1) > c.average("BodyLong", 1))
        & ((c.c(0) - c.c(1)).abs() <= c.average("Equal", 1))
    )
    return signal(
        cond, c.color(), warmup=_settings_warmup(c, 1, "BodyLong", "Equal")
    )

cdl_separating_lines

cdl_separating_lines(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Separating Lines — opposite-colored candles sharing the same open.

A continuation pattern: the counter-trend candle's move is immediately given back from the identical opening price.

Source code in polars_ta/candles.py

def cdl_separating_lines(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Separating Lines — opposite-colored candles sharing the same open.

    A continuation pattern: the counter-trend candle's move is immediately
    given back from the identical opening price.
    """
    c = make_candles(open_, high, low, close)
    very_short = c.average("ShadowVeryShort", 0)
    same_open = (c.o(0) - c.o(1)).abs() <= c.average("Equal", 1)
    white_cont = c.is_black(1) & c.is_white(0) & (c.lower_shadow(0) < very_short)
    black_cont = c.is_white(1) & c.is_black(0) & (c.upper_shadow(0) < very_short)
    cond = (
        (c.color(0) == -c.color(1))
        & same_open
        & (c.body(0) > c.average("BodyLong", 0))
        & (white_cont | black_cont)
    )
    return signal(
        cond,
        c.color(),
        warmup=_settings_warmup(c, 1, "BodyLong", "Equal", "ShadowVeryShort"),
    )

cdl_on_neck

cdl_on_neck(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

On-Neck Pattern — a white candle closing exactly at the prior black low.

Bearish continuation: the bounce stalled precisely at the previous low.

Source code in polars_ta/candles.py

def cdl_on_neck(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """On-Neck Pattern — a white candle closing exactly at the prior black low.

    Bearish continuation: the bounce stalled precisely at the previous low.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_black(1)
        & (c.body(1) > c.average("BodyLong", 1))
        & c.is_white(0)
        & (c.o(0) < c.c(1))
        & ((c.c(0) - c.low_(1)).abs() <= c.average("Equal", 1))
    )
    return signal(
        cond, -1, warmup=_settings_warmup(c, 1, "BodyLong", "Equal")
    )

cdl_in_neck

cdl_in_neck(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

In-Neck Pattern — a white candle closing just barely into the black body.

Bearish continuation, slightly weaker penetration than thrusting.

Source code in polars_ta/candles.py

def cdl_in_neck(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """In-Neck Pattern — a white candle closing just barely into the black body.

    Bearish continuation, slightly weaker penetration than thrusting.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_black(1)
        & (c.body(1) > c.average("BodyLong", 1))
        & c.is_white(0)
        & (c.o(0) < c.low_(1))
        & (c.c(0) >= c.c(1))
        & (c.c(0) <= c.c(1) + c.average("Equal", 1))
    )
    return signal(cond, -1, warmup=_settings_warmup(c, 1, "BodyLong", "Equal"))

cdl_thrusting

cdl_thrusting(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Thrusting Pattern — a white candle closing into but below the black midpoint.

A failed piercing: not enough recovery to flip the bias, so bearish.

Source code in polars_ta/candles.py

def cdl_thrusting(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Thrusting Pattern — a white candle closing into but below the black midpoint.

    A failed piercing: not enough recovery to flip the bias, so bearish.
    """
    c = make_candles(open_, high, low, close)
    # Distinguished from piercing by requiring the close to stay *below* the
    # midpoint of the black body — the recovery falls short.
    cond = (
        c.is_black(1)
        & (c.body(1) > c.average("BodyLong", 1))
        & c.is_white(0)
        & (c.o(0) < c.low_(1))
        & (c.c(0) > c.c(1))
        & (c.c(0) <= c.c(1) + c.body(1) * 0.5)
    )
    return signal(cond, -1, warmup=_settings_warmup(c, 1, "BodyLong"))

cdl_homing_pigeon

cdl_homing_pigeon(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Homing Pigeon — a small black candle inside a prior long black body.

Bullish reversal: selling pressure visibly shrinking.

Source code in polars_ta/candles.py

def cdl_homing_pigeon(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Homing Pigeon — a small black candle inside a prior long black body.

    Bullish reversal: selling pressure visibly shrinking.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_black(1)
        & c.is_black(0)
        & (c.body(1) > c.average("BodyLong", 1))
        & (c.body(0) < c.average("BodyShort", 0))
        & (c.o(0) < c.o(1))
        & (c.c(0) > c.c(1))
    )
    return signal(
        cond, 1, warmup=_settings_warmup(c, 1, "BodyLong", "BodyShort")
    )

cdl_matching_low

cdl_matching_low(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Matching Low — two black candles closing at an identical level.

Bullish: a support level that held twice.

Source code in polars_ta/candles.py

def cdl_matching_low(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Matching Low — two black candles closing at an identical level.

    Bullish: a support level that held twice.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_black(1)
        & c.is_black(0)
        & ((c.c(0) - c.c(1)).abs() <= c.average("Equal", 1))
    )
    return signal(cond, 1, warmup=_settings_warmup(c, 1, "Equal"))

cdl_kicking

cdl_kicking(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Kicking — two opposite marubozu separated by a gap.

A violent sentiment flip with no overlap between the two candles at all.

Source code in polars_ta/candles.py

def cdl_kicking(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Kicking — two opposite marubozu separated by a gap.

    A violent sentiment flip with no overlap between the two candles at all.
    """
    c = make_candles(open_, high, low, close)
    very_short_0 = c.average("ShadowVeryShort", 0)
    very_short_1 = c.average("ShadowVeryShort", 1)
    marubozu_1 = (
        (c.body(1) > c.average("BodyLong", 1))
        & (c.upper_shadow(1) < very_short_1)
        & (c.lower_shadow(1) < very_short_1)
    )
    marubozu_0 = (
        (c.body(0) > c.average("BodyLong", 0))
        & (c.upper_shadow(0) < very_short_0)
        & (c.lower_shadow(0) < very_short_0)
    )
    gap_up = c.is_black(1) & c.is_white(0) & (c.low_(0) > c.h(1))
    gap_down = c.is_white(1) & c.is_black(0) & (c.h(0) < c.low_(1))
    cond = marubozu_1 & marubozu_0 & (gap_up | gap_down)
    return signal(
        cond,
        c.color(),
        warmup=_settings_warmup(c, 1, "BodyLong", "ShadowVeryShort"),
    )

cdl_kicking_by_length

cdl_kicking_by_length(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Kicking by Length — a kicking whose direction follows the longer marubozu.

Identical geometry to cdl_kicking; only the sign convention differs.

Source code in polars_ta/candles.py

def cdl_kicking_by_length(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Kicking by Length — a kicking whose direction follows the longer marubozu.

    Identical geometry to [`cdl_kicking`][polars_ta.candles.cdl_kicking]; only
    the sign convention differs.
    """
    c = make_candles(open_, high, low, close)
    very_short_0 = c.average("ShadowVeryShort", 0)
    very_short_1 = c.average("ShadowVeryShort", 1)
    marubozu_1 = (
        (c.body(1) > c.average("BodyLong", 1))
        & (c.upper_shadow(1) < very_short_1)
        & (c.lower_shadow(1) < very_short_1)
    )
    marubozu_0 = (
        (c.body(0) > c.average("BodyLong", 0))
        & (c.upper_shadow(0) < very_short_0)
        & (c.lower_shadow(0) < very_short_0)
    )
    gap_up = c.is_black(1) & c.is_white(0) & (c.low_(0) > c.h(1))
    gap_down = c.is_white(1) & c.is_black(0) & (c.h(0) < c.low_(1))
    cond = marubozu_1 & marubozu_0 & (gap_up | gap_down)
    # Direction comes from the longer of the two bodies, not the latest candle.
    longer = pl.when(c.body(1) > c.body(0)).then(c.color(1)).otherwise(c.color(0))
    return signal(
        cond,
        longer,
        warmup=_settings_warmup(c, 1, "BodyLong", "ShadowVeryShort"),
    )

cdl_morning_star

cdl_morning_star(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C, penetration: float = 0.3) -> Expr

Morning Star — long black, a small gapped-down body, then a strong white.

The classic bullish bottom: capitulation, indecision, then recovery.

Parameters:

Name	Type	Description	Default
penetration	float	How far the third candle must close back into the first body, as a fraction of it. TA-Lib's default is 0.3.	0.3

Source code in polars_ta/candles.py

def cdl_morning_star(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
    penetration: float = 0.3,
) -> pl.Expr:
    """Morning Star — long black, a small gapped-down body, then a strong white.

    The classic bullish bottom: capitulation, indecision, then recovery.

    Args:
        penetration: How far the third candle must close back into the first
            body, as a fraction of it. TA-Lib's default is `0.3`.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body(2) > c.average("BodyLong", 2))
        & c.is_black(2)
        & (c.body(1) <= c.average("BodyShort", 1))
        & (c.body_top(1) < c.c(2))
        & c.is_white(0)
        & (c.body(0) > c.average("BodyShort", 0))
        & (c.o(0) > c.body_top(1))
        & (c.c(0) > c.c(2) + c.body(2) * penetration)
    )
    return signal(
        cond, 1, warmup=_settings_warmup(c, 2, "BodyLong", "BodyShort")
    )

cdl_evening_star

cdl_evening_star(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C, penetration: float = 0.3) -> Expr

Evening Star — long white, a small gapped-up body, then a strong black.

The bearish mirror of the morning star.

Parameters:

Name	Type	Description	Default
penetration	float	How far the third candle must close back into the first body, as a fraction of it. TA-Lib's default is 0.3.	0.3

Source code in polars_ta/candles.py

def cdl_evening_star(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
    penetration: float = 0.3,
) -> pl.Expr:
    """Evening Star — long white, a small gapped-up body, then a strong black.

    The bearish mirror of the morning star.

    Args:
        penetration: How far the third candle must close back into the first
            body, as a fraction of it. TA-Lib's default is `0.3`.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body(2) > c.average("BodyLong", 2))
        & c.is_white(2)
        & (c.body(1) <= c.average("BodyShort", 1))
        & (c.body_bottom(1) > c.c(2))
        & c.is_black(0)
        & (c.body(0) > c.average("BodyShort", 0))
        & (c.o(0) < c.body_bottom(1))
        & (c.c(0) < c.c(2) - c.body(2) * penetration)
    )
    return signal(
        cond, -1, warmup=_settings_warmup(c, 2, "BodyLong", "BodyShort")
    )

cdl_morning_doji_star

cdl_morning_doji_star(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C, penetration: float = 0.3) -> Expr

Morning Doji Star — a morning star whose middle candle is a doji.

Parameters:

Name	Type	Description	Default
penetration	float	How far the third candle must close back into the first body, as a fraction of it. TA-Lib's default is 0.3.	0.3

Source code in polars_ta/candles.py

def cdl_morning_doji_star(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
    penetration: float = 0.3,
) -> pl.Expr:
    """Morning Doji Star — a morning star whose middle candle is a doji.

    Args:
        penetration: How far the third candle must close back into the first
            body, as a fraction of it. TA-Lib's default is `0.3`.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body(2) > c.average("BodyLong", 2))
        & c.is_black(2)
        & (c.body(1) <= c.average("BodyDoji", 1))
        & (c.body_top(1) < c.c(2))
        & c.is_white(0)
        & (c.body(0) > c.average("BodyShort", 0))
        & (c.o(0) > c.body_top(1))
        & (c.c(0) > c.c(2) + c.body(2) * penetration)
    )
    return signal(
        cond,
        1,
        warmup=_settings_warmup(c, 2, "BodyLong", "BodyDoji", "BodyShort"),
    )

cdl_evening_doji_star

cdl_evening_doji_star(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C, penetration: float = 0.3) -> Expr

Evening Doji Star — an evening star whose middle candle is a doji.

Parameters:

Name	Type	Description	Default
penetration	float	How far the third candle must close back into the first body, as a fraction of it. TA-Lib's default is 0.3.	0.3

Source code in polars_ta/candles.py

def cdl_evening_doji_star(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
    penetration: float = 0.3,
) -> pl.Expr:
    """Evening Doji Star — an evening star whose middle candle is a doji.

    Args:
        penetration: How far the third candle must close back into the first
            body, as a fraction of it. TA-Lib's default is `0.3`.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body(2) > c.average("BodyLong", 2))
        & c.is_white(2)
        & (c.body(1) <= c.average("BodyDoji", 1))
        & (c.body_bottom(1) > c.c(2))
        & c.is_black(0)
        & (c.body(0) > c.average("BodyShort", 0))
        & (c.o(0) < c.body_bottom(1))
        & (c.c(0) < c.c(2) - c.body(2) * penetration)
    )
    return signal(
        cond,
        -1,
        warmup=_settings_warmup(c, 2, "BodyLong", "BodyDoji", "BodyShort"),
    )

cdl_abandoned_baby

cdl_abandoned_baby(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C, penetration: float = 0.3) -> Expr

Abandoned Baby — a star pattern where the doji gaps away on both sides.

Rare and considered strong: the middle candle shares no price overlap with either neighbour.

Parameters:

Name	Type	Description	Default
penetration	float	How far the third candle must close back into the first body, as a fraction of it. TA-Lib's default is 0.3.	0.3

Source code in polars_ta/candles.py

def cdl_abandoned_baby(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
    penetration: float = 0.3,
) -> pl.Expr:
    """Abandoned Baby — a star pattern where the doji gaps away on *both* sides.

    Rare and considered strong: the middle candle shares no price overlap with
    either neighbour.

    Args:
        penetration: How far the third candle must close back into the first
            body, as a fraction of it. TA-Lib's default is `0.3`.
    """
    c = make_candles(open_, high, low, close)
    bullish = (
        (c.body(2) > c.average("BodyLong", 2))
        & c.is_black(2)
        & (c.body(1) <= c.average("BodyDoji", 1))
        & c.is_white(0)
        & (c.body(0) > c.average("BodyShort", 0))
        & (c.c(0) > c.c(2) + c.body(2) * penetration)
        & (c.h(1) < c.low_(2))
        & (c.low_(0) > c.h(1))
    )
    bearish = (
        (c.body(2) > c.average("BodyLong", 2))
        & c.is_white(2)
        & (c.body(1) <= c.average("BodyDoji", 1))
        & c.is_black(0)
        & (c.body(0) > c.average("BodyShort", 0))
        & (c.c(0) < c.c(2) - c.body(2) * penetration)
        & (c.low_(1) > c.h(2))
        & (c.h(0) < c.low_(1))
    )
    direction = pl.when(bullish).then(1).otherwise(-1)
    return signal(
        bullish | bearish,
        direction,
        warmup=_settings_warmup(c, 2, "BodyLong", "BodyDoji", "BodyShort"),
    )

cdl_tristar

cdl_tristar(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Tristar Pattern — three consecutive doji, the middle one gapping away.

Total indecision three bars running, with the middle bar detached.

Source code in polars_ta/candles.py

def cdl_tristar(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Tristar Pattern — three consecutive doji, the middle one gapping away.

    Total indecision three bars running, with the middle bar detached.
    """
    c = make_candles(open_, high, low, close)
    all_doji = (
        (c.body(2) <= c.average("BodyDoji", 2))
        & (c.body(1) <= c.average("BodyDoji", 1))
        & (c.body(0) <= c.average("BodyDoji", 0))
    )
    bullish = all_doji & (c.body_bottom(1) < c.body_bottom(2)) & (
        c.body_bottom(1) < c.body_bottom(0)
    )
    bearish = all_doji & (c.body_top(1) > c.body_top(2)) & (
        c.body_top(1) > c.body_top(0)
    )
    direction = pl.when(bullish).then(1).otherwise(-1)
    return signal(
        bullish | bearish, direction, warmup=_settings_warmup(c, 2, "BodyDoji")
    )

cdl_3_white_soldiers

cdl_3_white_soldiers(open_: str | Expr = _O, high: str | Expr = _L" backlink-type="used-by" backlink-anchor="polars_ta.candles.cdl_3_white_soldiers" optional>_L, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Three Advancing White Soldiers — three long white candles, each higher.

Strong bullish continuation: steady accumulation with short upper shadows and each open inside the previous body.

Source code in polars_ta/candles.py

def cdl_3_white_soldiers(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Three Advancing White Soldiers — three long white candles, each higher.

    Strong bullish continuation: steady accumulation with short upper shadows
    and each open inside the previous body.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_white(2)
        & c.is_white(1)
        & c.is_white(0)
        & (c.c(1) > c.c(2))
        & (c.c(0) > c.c(1))
        & (c.upper_shadow(2) < c.average("ShadowVeryShort", 2))
        & (c.upper_shadow(1) < c.average("ShadowVeryShort", 1))
        & (c.upper_shadow(0) < c.average("ShadowVeryShort", 0))
        & (c.o(1) > c.o(2))
        & (c.o(1) <= c.c(2))
        & (c.o(0) > c.o(1))
        & (c.o(0) <= c.c(1))
    )
    return signal(cond, 1, warmup=_settings_warmup(c, 2, "ShadowVeryShort"))

cdl_3_black_crows

cdl_3_black_crows(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Three Black Crows — three long black candles, each closing lower.

Strong bearish continuation, each opening inside the prior body.

Source code in polars_ta/candles.py

def cdl_3_black_crows(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Three Black Crows — three long black candles, each closing lower.

    Strong bearish continuation, each opening inside the prior body.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_black(2)
        & c.is_black(1)
        & c.is_black(0)
        & (c.lower_shadow(2) < c.average("ShadowVeryShort", 2))
        & (c.lower_shadow(1) < c.average("ShadowVeryShort", 1))
        & (c.lower_shadow(0) < c.average("ShadowVeryShort", 0))
        & (c.c(1) < c.c(2))
        & (c.c(0) < c.c(1))
        & (c.o(1) < c.o(2))
        & (c.o(1) > c.c(2))
        & (c.o(0) < c.o(1))
        & (c.o(0) > c.c(1))
    )
    return signal(cond, -1, warmup=_settings_warmup(c, 2, "ShadowVeryShort"))

cdl_identical_3_crows

cdl_identical_3_crows(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Identical Three Crows — three black candles, each opening at the prior close.

A stricter three-crows: no gaps or overlap, just relentless selling.

Source code in polars_ta/candles.py

def cdl_identical_3_crows(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Identical Three Crows — three black candles, each opening at the prior close.

    A stricter three-crows: no gaps or overlap, just relentless selling.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_black(2)
        & c.is_black(1)
        & c.is_black(0)
        & (c.body(2) > c.average("BodyLong", 2))
        & (c.body(1) > c.average("BodyLong", 1))
        & (c.body(0) > c.average("BodyLong", 0))
        & (c.lower_shadow(2) < c.average("ShadowVeryShort", 2))
        & (c.lower_shadow(1) < c.average("ShadowVeryShort", 1))
        & (c.lower_shadow(0) < c.average("ShadowVeryShort", 0))
        & (c.c(1) < c.c(2))
        & (c.c(0) < c.c(1))
        & (c.o(1) <= c.c(2) + c.average("Equal", 2))
        & (c.o(1) >= c.c(2) - c.average("Equal", 2))
        & (c.o(0) <= c.c(1) + c.average("Equal", 1))
        & (c.o(0) >= c.c(1) - c.average("Equal", 1))
    )
    return signal(
        cond,
        -1,
        warmup=_settings_warmup(c, 2, "BodyLong", "ShadowVeryShort", "Equal"),
    )

cdl_2_crows

cdl_2_crows(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Two Crows — a gap-up black candle that then closes into the white body.

Bearish reversal: the gap up was completely rejected over two bars.

Source code in polars_ta/candles.py

def cdl_2_crows(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Two Crows — a gap-up black candle that then closes into the white body.

    Bearish reversal: the gap up was completely rejected over two bars.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_white(2)
        & (c.body(2) > c.average("BodyLong", 2))
        & c.is_black(1)
        & (c.o(1) > c.c(2))
        & c.is_black(0)
        & (c.o(0) < c.o(1))
        & (c.o(0) > c.c(1))
        & (c.c(0) > c.o(2))
        & (c.c(0) < c.c(2))
    )
    return signal(cond, -1, warmup=_settings_warmup(c, 2, "BodyLong"))

cdl_upside_gap_2_crows

cdl_upside_gap_2_crows(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Upside Gap Two Crows — a gap up, then two black candles closing the gap.

Bearish reversal in an uptrend.

Source code in polars_ta/candles.py

def cdl_upside_gap_2_crows(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Upside Gap Two Crows — a gap up, then two black candles closing the gap.

    Bearish reversal in an uptrend.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_white(2)
        & (c.body(2) > c.average("BodyLong", 2))
        & c.is_black(1)
        & (c.body_bottom(1) > c.c(2))
        & c.is_black(0)
        & (c.o(0) > c.o(1))
        & (c.c(0) < c.c(1))
        & (c.c(0) > c.c(2))
    )
    return signal(cond, -1, warmup=_settings_warmup(c, 2, "BodyLong"))

cdl_3_inside

cdl_3_inside(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Three Inside Up/Down — a harami confirmed by a third candle.

The confirmation bar closes beyond the harami, turning a pause into a reversal signal.

Source code in polars_ta/candles.py

def cdl_3_inside(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Three Inside Up/Down — a harami confirmed by a third candle.

    The confirmation bar closes beyond the harami, turning a pause into a
    reversal signal.
    """
    c = make_candles(open_, high, low, close)
    harami = (
        (c.body(2) > c.average("BodyLong", 2))
        & (c.body(1) <= c.average("BodyShort", 1))
        & (c.body_top(1) <= c.body_top(2))
        & (c.body_bottom(1) >= c.body_bottom(2))
    )
    bullish = harami & c.is_black(2) & c.is_white(0) & (c.c(0) > c.c(2))
    bearish = harami & c.is_white(2) & c.is_black(0) & (c.c(0) < c.c(2))
    direction = pl.when(bullish).then(1).otherwise(-1)
    return signal(
        bullish | bearish,
        direction,
        warmup=_settings_warmup(c, 2, "BodyLong", "BodyShort"),
    )

cdl_3_outside

cdl_3_outside(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Three Outside Up/Down — an engulfing pattern confirmed by a third candle.

Source code in polars_ta/candles.py

def cdl_3_outside(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Three Outside Up/Down — an engulfing pattern confirmed by a third candle."""
    c = make_candles(open_, high, low, close)
    bullish = (
        c.is_white(1)
        & c.is_black(2)
        & (c.c(1) > c.o(2))
        & (c.o(1) < c.c(2))
        & (c.c(0) > c.c(1))
    )
    bearish = (
        c.is_black(1)
        & c.is_white(2)
        & (c.o(1) > c.c(2))
        & (c.c(1) < c.o(2))
        & (c.c(0) < c.c(1))
    )
    direction = pl.when(bullish).then(1).otherwise(-1)
    return signal(bullish | bearish, direction, warmup=_warmup(c, 2))

cdl_3_stars_in_south

cdl_3_stars_in_south(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Three Stars In The South — three black candles with shrinking range.

Bullish reversal: selling that visibly runs out of steam, each candle smaller and holding above the previous low.

Source code in polars_ta/candles.py

def cdl_3_stars_in_south(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Three Stars In The South — three black candles with shrinking range.

    Bullish reversal: selling that visibly runs out of steam, each candle
    smaller and holding above the previous low.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_black(2)
        & c.is_black(1)
        & c.is_black(0)
        & (c.body(2) > c.average("BodyLong", 2))
        & (c.lower_shadow(2) > c.average("ShadowLong", 2))
        & (c.body(1) < c.body(2))
        & (c.o(1) > c.c(2))
        & (c.o(1) <= c.h(2))
        & (c.low_(1) < c.c(2))
        & (c.low_(1) >= c.low_(2))
        & (c.lower_shadow(1) > c.average("ShadowVeryShort", 1))
        & (c.body(0) < c.average("BodyShort", 0))
        & (c.lower_shadow(0) < c.average("ShadowVeryShort", 0))
        & (c.upper_shadow(0) < c.average("ShadowVeryShort", 0))
        & (c.low_(0) > c.low_(1))
        & (c.h(0) < c.h(1))
    )
    return signal(
        cond,
        1,
        warmup=_settings_warmup(
            c, 2, "BodyLong", "BodyShort", "ShadowVeryShort"
        ),
    )

cdl_advance_block

cdl_advance_block(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Advance Block — three white candles whose bodies shrink and shadows grow.

Bearish: an advance that is visibly losing conviction.

Source code in polars_ta/candles.py

def cdl_advance_block(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Advance Block — three white candles whose bodies shrink and shadows grow.

    Bearish: an advance that is visibly losing conviction.
    """
    c = make_candles(open_, high, low, close)
    far_2 = c.average("Far", 2)
    far_1 = c.average("Far", 1)
    near_1 = c.average("Near", 1)
    cond = (
        c.is_white(2)
        & c.is_white(1)
        & c.is_white(0)
        & (c.c(1) > c.c(2))
        & (c.c(0) > c.c(1))
        & (c.o(1) > c.o(2))
        & (c.o(1) <= c.c(2) + near_1)
        & (c.o(0) > c.o(1))
        & (c.o(0) <= c.c(1) + c.average("Near", 0))
        & (c.body(2) > c.average("BodyLong", 2))
        & (c.upper_shadow(2) < c.average("ShadowVeryShort", 2))
        & (
            (
                (c.body(1) < c.body(2) - far_2)
                & (c.body(0) < c.body(1) + near_1)
            )
            | (c.body(0) < c.body(1) - far_1)
            | (
                (c.body(0) < c.body(1))
                & (c.body(1) < c.body(2))
                & (
                    (c.upper_shadow(0) > c.average("ShadowShort", 0))
                    | (c.upper_shadow(1) > c.average("ShadowShort", 1))
                )
            )
            | (
                (c.body(0) < c.body(1))
                & (c.upper_shadow(0) > c.average("ShadowLong", 0))
            )
        )
    )
    return signal(
        cond,
        -1,
        warmup=_settings_warmup(
            c, 2, "BodyLong", "ShadowVeryShort", "ShadowShort", "Far", "Near"
        ),
    )

cdl_stalled_pattern

cdl_stalled_pattern(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Stalled Pattern — three white candles ending in a small body riding the prior.

Bearish: the third advance is tiny and gaps up onto the second body — the rally has stalled.

Source code in polars_ta/candles.py

def cdl_stalled_pattern(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Stalled Pattern — three white candles ending in a small body riding the prior.

    Bearish: the third advance is tiny and gaps up onto the second body — the
    rally has stalled.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_white(2)
        & c.is_white(1)
        & c.is_white(0)
        & (c.c(1) > c.c(2))
        & (c.c(0) > c.c(1))
        & (c.body(2) > c.average("BodyLong", 2))
        & (c.upper_shadow(2) < c.average("ShadowVeryShort", 2))
        & (c.body(1) > c.average("BodyLong", 1))
        & (c.upper_shadow(1) < c.average("ShadowVeryShort", 1))
        & (c.o(1) > c.o(2))
        & (c.o(1) <= c.c(2) + c.average("Near", 1))
        & (c.body(0) < c.average("BodyShort", 0))
        & (c.o(0) >= c.c(1) - c.average("Near", 0))
    )
    return signal(
        cond,
        -1,
        warmup=_settings_warmup(
            c, 2, "BodyLong", "BodyShort", "ShadowVeryShort", "Near"
        ),
    )

cdl_unique_3_river

cdl_unique_3_river(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Unique 3 River — a long black, a harami making a new low, then a small white.

A rare bullish bottom formation.

Source code in polars_ta/candles.py

def cdl_unique_3_river(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Unique 3 River — a long black, a harami making a new low, then a small white.

    A rare bullish bottom formation.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_black(2)
        & (c.body(2) > c.average("BodyLong", 2))
        & (c.lower_shadow(2) > c.average("ShadowLong", 2))
        & c.is_black(1)
        & (c.o(1) <= c.o(2))
        & (c.c(1) >= c.c(2))
        & (c.low_(1) < c.low_(2))
        & c.is_white(0)
        & (c.body(0) < c.average("BodyShort", 0))
        & (c.o(0) > c.low_(1))
        & (c.c(0) < c.o(1))
    )
    return signal(
        cond, 1, warmup=_settings_warmup(c, 2, "BodyLong", "BodyShort")
    )

cdl_stick_sandwich

cdl_stick_sandwich(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Stick Sandwich — two black candles sandwiching a white one, equal closes.

Bullish: the same close was defended twice.

Source code in polars_ta/candles.py

def cdl_stick_sandwich(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Stick Sandwich — two black candles sandwiching a white one, equal closes.

    Bullish: the same close was defended twice.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_black(2)
        & c.is_white(1)
        & c.is_black(0)
        & (c.low_(1) > c.c(2))
        & (c.c(0) <= c.c(2) + c.average("Equal", 2))
        & (c.c(0) >= c.c(2) - c.average("Equal", 2))
    )
    return signal(cond, 1, warmup=_settings_warmup(c, 2, "Equal"))

cdl_tasuki_gap

cdl_tasuki_gap(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Tasuki Gap — a gap, a continuation candle, then a partial fill.

A continuation pattern: the counter-candle fails to close the gap.

Source code in polars_ta/candles.py

def cdl_tasuki_gap(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Tasuki Gap — a gap, a continuation candle, then a partial fill.

    A continuation pattern: the counter-candle fails to close the gap.
    """
    c = make_candles(open_, high, low, close)
    bullish = (
        (c.body_bottom(1) > c.body_top(2))
        & c.is_white(1)
        & c.is_black(0)
        & (c.o(0) > c.body_bottom(1))
        & (c.o(0) < c.body_top(1))
        & (c.c(0) < c.o(1))
        & (c.c(0) > c.c(2))
        & ((c.body(1) - c.body(0)).abs() < c.average("Near", 1))
    )
    bearish = (
        (c.body_top(1) < c.body_bottom(2))
        & c.is_black(1)
        & c.is_white(0)
        & (c.o(0) < c.body_top(1))
        & (c.o(0) > c.body_bottom(1))
        & (c.c(0) > c.o(1))
        & (c.c(0) < c.c(2))
        & ((c.body(1) - c.body(0)).abs() < c.average("Near", 1))
    )
    direction = pl.when(bullish).then(1).otherwise(-1)
    return signal(
        bullish | bearish, direction, warmup=_settings_warmup(c, 2, "Near")
    )

cdl_gap_side_side_white

cdl_gap_side_side_white(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Up/Down-gap side-by-side white lines — two similar whites after a gap.

Continuation in the gap's direction.

Source code in polars_ta/candles.py

def cdl_gap_side_side_white(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Up/Down-gap side-by-side white lines — two similar whites after a gap.

    Continuation in the gap's direction.
    """
    c = make_candles(open_, high, low, close)
    near_1 = c.average("Near", 1)
    equal_1 = c.average("Equal", 1)
    similar = (
        c.is_white(1)
        & c.is_white(0)
        & ((c.body(0) - c.body(1)).abs() < near_1)
        & (c.o(0) >= c.o(1) - equal_1)
        & (c.o(0) <= c.o(1) + equal_1)
    )
    gap_up = similar & (c.body_bottom(1) > c.body_top(2))
    gap_down = similar & (c.body_top(1) < c.body_bottom(2))
    direction = pl.when(gap_up).then(1).otherwise(-1)
    return signal(
        gap_up | gap_down,
        direction,
        warmup=_settings_warmup(c, 2, "Near", "Equal"),
    )

cdl_xside_gap_3_methods

cdl_xside_gap_3_methods(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Upside/Downside Gap Three Methods — a gap filled by the third candle.

Continuation: two same-colored candles with a gap, then a counter-candle that opens and closes inside both, filling the gap.

Source code in polars_ta/candles.py

def cdl_xside_gap_3_methods(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Upside/Downside Gap Three Methods — a gap filled by the third candle.

    Continuation: two same-colored candles with a gap, then a counter-candle
    that opens and closes inside both, filling the gap.
    """
    c = make_candles(open_, high, low, close)
    same_color = c.color(2) == c.color(1)
    opposite = c.color(0) == -c.color(1)
    gap_up = c.is_white(1) & (c.body_bottom(1) > c.body_top(2))
    gap_down = c.is_black(1) & (c.body_top(1) < c.body_bottom(2))
    cond = (
        same_color
        & opposite
        & (gap_up | gap_down)
        & (c.o(0) > c.body_bottom(1))
        & (c.o(0) < c.body_top(1))
        & (c.c(0) > c.body_bottom(2))
        & (c.c(0) < c.body_top(2))
    )
    return signal(cond, c.color(1), warmup=_warmup(c, 2))

cdl_concealing_baby_swallow

cdl_concealing_baby_swallow(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Concealing Baby Swallow — four blacks, the last engulfing the third.

A rare bullish bottom in a strong downtrend.

Source code in polars_ta/candles.py

def cdl_concealing_baby_swallow(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Concealing Baby Swallow — four blacks, the last engulfing the third.

    A rare bullish bottom in a strong downtrend.
    """
    c = make_candles(open_, high, low, close)
    very_short_3 = c.average("ShadowVeryShort", 3)
    very_short_2 = c.average("ShadowVeryShort", 2)
    cond = (
        c.is_black(3)
        & c.is_black(2)
        & c.is_black(1)
        & c.is_black(0)
        # First two are marubozu-like: no meaningful shadows.
        & (c.lower_shadow(3) < very_short_3)
        & (c.upper_shadow(3) < very_short_3)
        & (c.lower_shadow(2) < very_short_2)
        & (c.upper_shadow(2) < very_short_2)
        # Third gaps down but trades back up into the second's body.
        & (c.o(1) < c.c(2))
        & (c.upper_shadow(1) > c.average("ShadowVeryShort", 1))
        & (c.h(1) > c.c(2))
        # Fourth completely engulfs the third, including its shadows.
        & (c.h(0) > c.h(1))
        & (c.low_(0) < c.low_(1))
    )
    return signal(cond, 1, warmup=_settings_warmup(c, 3, "ShadowVeryShort"))

cdl_3_line_strike

cdl_3_line_strike(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Three-Line Strike — three trending candles, then one that engulfs all three.

Counter-intuitively a continuation pattern in TA-Lib's convention: the sign follows the three-candle trend, not the striking candle.

Source code in polars_ta/candles.py

def cdl_3_line_strike(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Three-Line Strike — three trending candles, then one that engulfs all three.

    Counter-intuitively a *continuation* pattern in TA-Lib's convention: the
    sign follows the three-candle trend, not the striking candle.
    """
    c = make_candles(open_, high, low, close)
    near_1 = c.average("Near", 1)
    near_2 = c.average("Near", 2)
    three_same = (c.color(3) == c.color(2)) & (c.color(2) == c.color(1))
    opposite = c.color(0) == -c.color(1)
    # Each of the three opens within/near the prior body and extends the trend.
    ordered = (
        (c.o(2) >= pl.min_horizontal(c.o(3), c.c(3)) - near_2)
        & (c.o(2) <= pl.max_horizontal(c.o(3), c.c(3)) + near_2)
        & (c.o(1) >= pl.min_horizontal(c.o(2), c.c(2)) - near_1)
        & (c.o(1) <= pl.max_horizontal(c.o(2), c.c(2)) + near_1)
    )
    bullish = (
        three_same
        & c.is_white(1)
        & opposite
        & ordered
        & (c.c(2) > c.c(3))
        & (c.c(1) > c.c(2))
        & (c.o(0) > c.c(1))
        & (c.c(0) < c.o(3))
    )
    bearish = (
        three_same
        & c.is_black(1)
        & opposite
        & ordered
        & (c.c(2) < c.c(3))
        & (c.c(1) < c.c(2))
        & (c.o(0) < c.c(1))
        & (c.c(0) > c.o(3))
    )
    direction = pl.when(bullish).then(1).otherwise(-1)
    return signal(
        bullish | bearish, direction, warmup=_settings_warmup(c, 3, "Near")
    )

cdl_rise_fall_3_methods

cdl_rise_fall_3_methods(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Rising/Falling Three Methods — long candle, three pullbacks, long candle.

A continuation pattern: the pullback stays inside the first candle's range and the fifth candle resumes the trend at a new extreme.

Source code in polars_ta/candles.py

def cdl_rise_fall_3_methods(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Rising/Falling Three Methods — long candle, three pullbacks, long candle.

    A continuation pattern: the pullback stays inside the first candle's range
    and the fifth candle resumes the trend at a new extreme.
    """
    c = make_candles(open_, high, low, close)
    body_short_ok = (
        (c.body(3) < c.average("BodyShort", 3))
        & (c.body(2) < c.average("BodyShort", 2))
        & (c.body(1) < c.average("BodyShort", 1))
    )
    long_ends = (c.body(4) > c.average("BodyLong", 4)) & (
        c.body(0) > c.average("BodyLong", 0)
    )
    # The three middle candles retrace against the trend but stay within the
    # first candle's high-low range.
    contained = (
        (pl.min_horizontal(c.o(3), c.c(3)) > c.low_(4))
        & (pl.max_horizontal(c.o(3), c.c(3)) < c.h(4))
        & (pl.min_horizontal(c.o(2), c.c(2)) > c.low_(4))
        & (pl.max_horizontal(c.o(2), c.c(2)) < c.h(4))
        & (pl.min_horizontal(c.o(1), c.c(1)) > c.low_(4))
        & (pl.max_horizontal(c.o(1), c.c(1)) < c.h(4))
    )
    counter = (c.color(3) == -c.color(4)) & (c.color(1) == -c.color(4))
    bullish = (
        long_ends
        & body_short_ok
        & contained
        & counter
        & c.is_white(4)
        & c.is_white(0)
        & (c.c(2) < c.c(3))
        & (c.c(1) < c.c(2))
        & (c.o(0) > c.c(1))
        & (c.c(0) > c.c(4))
    )
    bearish = (
        long_ends
        & body_short_ok
        & contained
        & counter
        & c.is_black(4)
        & c.is_black(0)
        & (c.c(2) > c.c(3))
        & (c.c(1) > c.c(2))
        & (c.o(0) < c.c(1))
        & (c.c(0) < c.c(4))
    )
    direction = pl.when(bullish).then(1).otherwise(-1)
    return signal(
        bullish | bearish,
        direction,
        warmup=_settings_warmup(c, 4, "BodyLong", "BodyShort"),
    )

cdl_mat_hold

cdl_mat_hold(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C, penetration: float = 0.5) -> Expr

Mat Hold — a bullish five-candle continuation with a gapped-up pullback.

Parameters:

Name	Type	Description	Default
penetration	float	How far the pullback may retrace into the first body. TA-Lib's default is 0.5.	0.5

Source code in polars_ta/candles.py

def cdl_mat_hold(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
    penetration: float = 0.5,
) -> pl.Expr:
    """Mat Hold — a bullish five-candle continuation with a gapped-up pullback.

    Args:
        penetration: How far the pullback may retrace into the first body.
            TA-Lib's default is `0.5`.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        (c.body(4) > c.average("BodyLong", 4))
        & c.is_white(4)
        & c.is_white(3)
        & (c.body_bottom(3) > c.c(4))
        & (c.body(2) < c.average("BodyShort", 2))
        & (c.body(1) < c.average("BodyShort", 1))
        & (c.body(0) > c.average("BodyShort", 0))
        & c.is_white(0)
        # The pullback stays above the reference level set by the first candle.
        & (
            pl.min_horizontal(c.low_(3), c.low_(2), c.low_(1))
            > c.c(4) - c.body(4) * penetration
        )
        & (pl.max_horizontal(c.c(2), c.c(1)) < c.o(3))
        & (c.o(0) > pl.max_horizontal(c.body_top(2), c.body_top(1)))
        & (c.c(0) > pl.max_horizontal(c.h(3), c.h(2), c.h(1)))
    )
    return signal(
        cond, 1, warmup=_settings_warmup(c, 4, "BodyLong", "BodyShort")
    )

cdl_breakaway

cdl_breakaway(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Breakaway — a five-candle gap-and-return that closes back into the gap.

Bullish after a downside gap, bearish after an upside one.

Source code in polars_ta/candles.py

def cdl_breakaway(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Breakaway — a five-candle gap-and-return that closes back into the gap.

    Bullish after a downside gap, bearish after an upside one.
    """
    c = make_candles(open_, high, low, close)
    long_first = c.body(4) > c.average("BodyLong", 4)
    same_3 = (c.color(4) == c.color(3)) & (c.color(1) == c.color(3))
    opposite_last = c.color(0) == -c.color(3)
    bullish = (
        long_first
        & c.is_black(4)
        & c.is_black(3)
        & same_3
        & opposite_last
        & c.is_white(0)
        & (c.body_top(3) < c.body_bottom(4))
        & (c.low_(2) < c.low_(3))
        & (c.h(2) > c.h(3))
        & (c.low_(1) < c.low_(2))
        & (c.c(0) > c.body_top(3))
        & (c.c(0) < c.body_bottom(4))
    )
    bearish = (
        long_first
        & c.is_white(4)
        & c.is_white(3)
        & same_3
        & opposite_last
        & c.is_black(0)
        & (c.body_bottom(3) > c.body_top(4))
        & (c.h(2) > c.h(3))
        & (c.low_(2) < c.low_(3))
        & (c.h(1) > c.h(2))
        & (c.c(0) < c.body_bottom(3))
        & (c.c(0) > c.body_top(4))
    )
    direction = pl.when(bullish).then(1).otherwise(-1)
    return signal(
        bullish | bearish,
        direction,
        warmup=_settings_warmup(c, 4, "BodyLong"),
    )

cdl_ladder_bottom

cdl_ladder_bottom(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Ladder Bottom — three descending blacks, a shadowed black, then a white.

A bullish bottom reversal.

Source code in polars_ta/candles.py

def cdl_ladder_bottom(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Ladder Bottom — three descending blacks, a shadowed black, then a white.

    A bullish bottom reversal.
    """
    c = make_candles(open_, high, low, close)
    cond = (
        c.is_black(4)
        & c.is_black(3)
        & c.is_black(2)
        # Three consecutively lower opens and closes.
        & (c.o(4) > c.o(3))
        & (c.o(3) > c.o(2))
        & (c.c(4) > c.c(3))
        & (c.c(3) > c.c(2))
        # Fourth is black with a significant upper shadow.
        & c.is_black(1)
        & (c.upper_shadow(1) > c.average("ShadowVeryShort", 1))
        # Fifth is white and gaps above the fourth's body.
        & c.is_white(0)
        & (c.o(0) > c.o(1))
        & (c.c(0) > c.h(1))
    )
    return signal(cond, 1, warmup=_settings_warmup(c, 4, "ShadowVeryShort"))

cdl_hikkake

cdl_hikkake(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Hikkake Pattern — an inside bar, a false breakout, then a reversal.

Emits ±100 when the false breakout completes, and ±100 again if the move is confirmed within the following three bars.

Source code in polars_ta/candles.py

def cdl_hikkake(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Hikkake Pattern — an inside bar, a false breakout, then a reversal.

    Emits `±100` when the false breakout completes, and `±100` again if the
    move is confirmed within the following three bars.
    """
    c = make_candles(open_, high, low, close)
    inside = (c.h(1) < c.h(2)) & (c.low_(1) > c.low_(2))
    bull = inside & (c.h(0) < c.h(1)) & (c.low_(0) < c.low_(1))
    bear = inside & (c.h(0) > c.h(1)) & (c.low_(0) > c.low_(1))
    detected = bull | bear
    direction = pl.when(bull).then(1).otherwise(-1)
    # Confirmation compares against the bar *before* the pattern completed.
    confirm_up = c.c(0) > c.h(1)
    confirm_down = c.c(0) < c.low_(1)
    out = _hikkake_confirm(detected, direction, confirm_up, confirm_down, 3)
    return pl.when(_warmup(c, 2).is_null()).then(None).otherwise(out).cast(pl.Int32)

cdl_hikkake_mod

cdl_hikkake_mod(open_: str | Expr = _O, high: str | Expr = _H, low: str | Expr = _L, close: str | Expr = _C) -> Expr

Modified Hikkake Pattern — a hikkake with an extra context bar.

Adds a requirement on where the inside bar closed within its own range, which makes it rarer and, by reputation, more reliable than the plain cdl_hikkake.

Source code in polars_ta/candles.py

def cdl_hikkake_mod(
    open_: str | pl.Expr = _O,
    high: str | pl.Expr = _H,
    low: str | pl.Expr = _L,
    close: str | pl.Expr = _C,
) -> pl.Expr:
    """Modified Hikkake Pattern — a hikkake with an extra context bar.

    Adds a requirement on where the inside bar closed within its own range,
    which makes it rarer and, by reputation, more reliable than the plain
    [`cdl_hikkake`][polars_ta.candles.cdl_hikkake].
    """
    c = make_candles(open_, high, low, close)
    nested = (
        (c.h(2) < c.h(3))
        & (c.low_(2) > c.low_(3))
        & (c.h(1) < c.h(2))
        & (c.low_(1) > c.low_(2))
    )
    near_2 = c.average("Near", 2)
    bull = (
        nested
        & (c.h(0) < c.h(1))
        & (c.low_(0) < c.low_(1))
        & (c.c(2) <= c.low_(2) + near_2)
    )
    bear = (
        nested
        & (c.h(0) > c.h(1))
        & (c.low_(0) > c.low_(1))
        & (c.c(2) >= c.h(2) - near_2)
    )
    detected = bull | bear
    direction = pl.when(bull).then(1).otherwise(-1)
    confirm_up = c.c(0) > c.h(1)
    confirm_down = c.c(0) < c.low_(1)
    out = _hikkake_confirm(detected, direction, confirm_up, confirm_down, 3)
    warm = _settings_warmup(c, 3, "Near")
    return pl.when(warm.is_null()).then(None).otherwise(out).cast(pl.Int32)