Candle Pattern Library [1CG]

Candle Pattern Library

A comprehensive and easy-to-use Pine Script™ library for detecting single, two, and three-candle patterns. This library provides detailed pattern analysis including size classification, direction validation, and specific pattern identification.

Quick Start

1. Import the Library
import OneCleverGuy/CandlePatternLibrary/1 as CPL

2. Analyze Candles
Use the main analysis functions to detect patterns. You can analyze the current forming candle or confirmed historical candles.

// 1. Analyze candles (Current [0], Previous [1], and the one before [2])
// Note: We use full variable names for clarity.
CandleData candleNewest = CPL.analyzeCandle(open, high, low, close, 250, 50, 10, 50, 85)
CandleData candleMiddle = CPL.analyzeCandle(open[1], high[1], low[1], close[1], 250, 50, 10, 50, 85)
CandleData candleOldest = CPL.analyzeCandle(open[2], high[2], low[2], close[2], 250, 50, 10, 50, 85)

// 2. Analyze multi-candle patterns
// Pass candles in chronological order: Oldest -> Newest
var twoCandleData = CPL.analyzeTwoCandlePattern(candleMiddle, candleNewest, 10, 85)
var threeCandleData = CPL.analyzeThreeCandlePattern(candleOldest, candleMiddle, candleNewest)

Enums Reference

These are the Enum Types exported by the library. When checking results, use the pattern Alias.EnumType.Value (e.g., CPL.CandlePattern.Hammer).

CandlePattern
  Enum Type for single-candle formations.
  Usage: CPL.CandlePattern.<Value>
  Values:
    Unknown: No specific pattern detected.
    RegularBullish: A standard bullish candle.
    RegularBearish: A standard bearish candle.
    BullishMarubozu: Bullish candle with little to no wicks.
    BearishMarubozu: Bearish candle with little to no wicks.
    Hammer: Small body at the top of the range (bullish reversal).
    ShootingStar: Small body at the bottom of the range (bearish reversal).
    SpinningTop: Small body centered in the range.
    Doji: Open and close are effectively equal.
    LongLeggedDoji: Doji with long upper and lower wicks.
    CrossDoji: Doji with the body in the upper section.
    DragonflyDoji: Doji where open/close are at the high.
    InvertedCrossDoji: Doji with the body in the lower section.
    GravestoneDoji: Doji where open/close are at the low.
    FourPriceDoji: Open, High, Low, and Close are all equal.

TwoCandlePattern
  Enum Type for two-candle formations.
  Usage: CPL.TwoCandlePattern.<Value>
  Values:
    None: No two-candle pattern detected.
    BullishEngulfingWeak: Bullish candle engulfs the previous body (close does not engulf range).
    BullishEngulfingStrong: Bullish candle completely engulfs the previous body close outside range.
    BearishEngulfingWeak: Bearish candle engulfs the previous body.
    BearishEngulfingStrong: Bearish candle completely engulfs the previous body.
    InsideBar: The second candle is completely contained within the first.
    TweezerTop: Two candles with matching highs (bearish reversal).
    TweezerBottom: Two candles with matching lows (bullish reversal).
    BullishRailRoad: Two opposite Marubozus (Down -> Up).
    BearishRailRoad: Two opposite Marubozus (Up -> Down).

ThreeCandlePattern
  Enum Type for three-candle formations.
  Usage: CPL.ThreeCandlePattern.<Value>
  Values:
    None: No three-candle pattern detected.
    ThreeWhiteSoldiers: Three consecutive bullish candles.
    ThreeBlackCrows: Three consecutive bearish candles.
    ThreeWhiteSoldiersWithBullishFVG: Three White Soldiers containing a Bullish FVG.
    ThreeWhiteSoldiersWithBearishFVG: Three White Soldiers containing a Bearish FVG.
    ThreeBlackCrowsWithBullishFVG: Three Black Crows containing a Bullish FVG.
    ThreeBlackCrowsWithBearishFVG: Three Black Crows containing a Bearish FVG.
    MorningStar: Bearish -> Small/Doji -> Bullish (Bullish Reversal).
    EveningStar: Bullish -> Small/Doji -> Bearish (Bearish Reversal).
    BullishAbandonedBaby: Morning Star with gaps between all candles.
    BearishAbandonedBaby: Evening Star with gaps between all candles.
    EngulfingSandwich: Bearish -> Bullish (Engulfing) -> Bearish (Inside).
    BullishFairValueGap: A gap between Candle 1 High and Candle 3 Low.
    BearishFairValueGap: A gap between Candle 1 Low and Candle 3 High.

CandleSize
  Enum Type for candle size classification.
  Usage: CPL.CandleSize.<Value>
  Values:
    Short
    Normal
    Long

CandleDirection
  Enum Type for candle direction classification.
  Usage: CPL.CandleDirection.<Value>
  Values:
    Bearish
    Neutral
    Bullish

Function Reference

Analysis Functions

analyzeCandle(_open, _high, _low, _close, _avgSize, _sizeThresholdPct, _equivTolerance, _bodyTolerance, _positionThreshold)
  analyzeCandle - Analyzes a single candle's OHLC data to determine its size, direction, and single-candle pattern.
  Parameters:
    _open (float): (float) - Candle open price.
    _high (float): (float) - Candle high price.
    _low (float): (float) - Candle low price.
    _close (float): (float) - Candle close price.
    _avgSize (float): (float) - Baseline size (wick range) to compare against.
    _sizeThresholdPct (float): (float) - % difference from average to be considered Long/Short (e.g., 50.0).
    _equivTolerance (float): (float) - Absolute price diff for Close to equal Open (Doji checks).
    _bodyTolerance (float): (float) - Absolute price diff for "Small Body" checks.
    _positionThreshold (int): (int) - Int (0-100) determining valid wick ratios for Hammers/Shooting Stars (e.g., 85).
  Returns: (CandleData) - CandleData object containing CandlePattern, CandleSize, CandleDirection.

analyzeTwoCandlePattern(_candle1, _candle2, _equivTolerance, _positionThreshold)
  analyzeTwoCandlePattern - Analyzes two consecutive candles to find pairs like Engulfing, Tweezers, or Inside Bars.
  Parameters:
    _candle1 (CandleData): (CandleData) - The first (older) candle data (previous).
    _candle2 (CandleData): (CandleData) - The second (newer) candle data (current).
    _equivTolerance (float): (float) - Price tolerance for matching highs/lows (Tweezers).
    _positionThreshold (int): (int) - Threshold for wick validations.
  Returns: (TwoCandleData) - TwoCandleData object containing TwoCandlePattern.

analyzeThreeCandlePattern(_candle1, _candle2, _candle3)
  analyzeThreeCandlePattern - Analyzes three consecutive candles to find complex patterns like Morning Stars, Abandoned Babies, or Three White Soldiers.
  Parameters:
    _candle1 (CandleData): (CandleData) - The first (oldest) candle data.
    _candle2 (CandleData): (CandleData) - The second (middle) candle data.
    _candle3 (CandleData): (CandleData) - The third (newest) candle data.
  Returns: (ThreeCandleData) - ThreeCandleData object containing ThreeCandlePattern.

Naming Utilities

getPatternName(_pattern)
  getPatternName - Returns the string name of a candle pattern.
  Parameters:
    _pattern (CandlePattern): (CandlePattern) - The candle pattern enum value.
  Returns: (string) - Human-readable pattern name (e.g., "Hammer").

getTwoCandlePatternName(_pattern)
  getTwoCandlePatternName - Returns the string name of a two-candle pattern.
  Parameters:
    _pattern (TwoCandlePattern): (TwoCandlePattern) - The two-candle pattern enum value.
  Returns: (string) - Human-readable pattern name (e.g., "Bullish Engulfing").

getThreeCandlePatternName(_pattern)
  getThreeCandlePatternName - Returns the string name of a three-candle pattern.
  Parameters:
    _pattern (ThreeCandlePattern): (ThreeCandlePattern) - The three-candle pattern enum value.
  Returns: (string) - Human-readable pattern name (e.g., "Morning Star").

getSizeName(_size)
  getSizeName - Returns the string name of a candle size.
  Parameters:
    _size (CandleSize): (CandleSize) - The candle size enum value.
  Returns: (string) - Human-readable size name ("Short", "Normal", or "Long").

getDirectionName(_direction)
  getDirectionName - Returns the string name of a candle direction.
  Parameters:
    _direction (CandleDirection): (CandleDirection) - The candle direction enum value.
  Returns: (string) - Human-readable direction name ("Bullish", "Bearish", or "Neutral").