Three White Soldiers

Install and import#

npm install fintech-algorithms

import { threeWhiteSoldiers } from "fintech-algorithms/price-action-and-candlesticks/multi-candle-patterns/three-white-soldiers";

Signature#

threeWhiteSoldiers(inputs)

Evaluates exactly three candles against explicit white-soldiers body, close, shadow, scale, and downtrend conventions.

Parameters#

Returns#

{ topic_id, pattern, matched, state, direction, trend_context, required_context, history_count, body_scale, range_scale, geometry_score, checks, failed_checks, reason, thresholds, candles }

One three-candle pattern record. state is warmup, wrong-context, matched, or not-matched; readiness is record state, not positional output.

Warm-up#

The first 5 prior observations positions are state: warmup. The detector returns one readiness record before five prior body/range observations are available; it does not emit a positional null prefix.

Errors#

• When the record does not contain exactly three valid candles or scale/context inputs are invalid — throws

Complexity: time , space .

Worked example#

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input#

{
  "candles": [
    {
      "open": 100,
      "high": 102.2,
      "low": 99.8,
      "close": 102
    },
    {
      "open": 101.5,
      "high": 103.7,
      "low": 101.3,
      "close": 103.5
    },
    {
      "open": 103,
      "high": 105.2,
      "low": 102.8,
      "close": 105
    }
  ],
  "trend_context": "downtrend",
  "prior_bodies": [2, 2.1, 1.9, 2.2, 2, 2.1],
  "prior_ranges": [3, 3.2, 2.9, 3.1, 3, 3.3],
  "tick_size": 0.1,
  "penetration_fraction": 0.5
}

Call#

threeWhiteSoldiers(inputs)

Returns#

object with 16 fields: topic_id, pattern, matched, state, direction, trend_context, required_context, history_count, …

{
  "topic_id": "D06-F04-A03",
  "pattern": "Three White Soldiers",
  "matched": true,
  "state": "matched",
  "direction": "bullish",
  "trend_context": "downtrend",
  "required_context": "downtrend",
  "history_count": 10,
  "body_scale": 2,
  "range_scale": 3,
  "geometry_score": 1,
  "checks": {
    "three_bullish": true,
    "material_bodies": true,
    "rising_closes": true,
    "second_opens_in_prior_body": true,
    "third_opens_in_prior_body": true,
    "short_upper_shadows": true
  },
  "failed_checks": [],
  "reason": "all declared checks pass"
}

Showing 14 of 16 fields.

Other exports#

This module also exports calculate, morningStar, eveningStar, threeBlackCrows, threeInsideUpDown, threeOutsideUpDown, abandonedBaby. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams#

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

• CDL3WHITESOLDIERS function documentation — TA-Lib project
• TA-Lib Pattern Recognition Functions — TA-Lib project
• Japanese Candlestick Charting Techniques, Second Edition — Steve Nison; Prentice Hall Press
• Measures of Location: Mean and Median — NIST/SEMATECH
• Evidence boundary

The rest of the Multi-Candle Patterns family#

• Morning StarEvaluates exactly three candles against explicit morning-star gap, penetration, scale, and downtrend conventions.
• Evening StarEvaluates exactly three candles against explicit evening-star gap, penetration, scale, and uptrend conventions.
• Three Black CrowsEvaluates exactly three candles against explicit black-crows body, close, shadow, scale, and uptrend conventions.
• Three Inside Up/DownEvaluates exactly three candles against explicit inside-pair containment, confirmation, scale, and trend-context conventions.
• Three Outside Up/DownEvaluates exactly three candles against explicit outside-pair engulfing, confirmation, scale, and trend-context conventions.
• Abandoned BabyEvaluates exactly three candles against explicit abandoned-baby isolation, doji, penetration, scale, and context conventions.