Candle Anatomy: Turn OHLC Into Testable Geometry

A candlestick looks simple: a rectangle with a line above and below it. But reliable software needs more than a drawing. It needs exact definitions, input validation, a zero-range policy, tests, and a contract that produces the same result in every language.

By the end of this tutorial, you will be able to take one open-high-low-close record, calculate its body, upper and lower shadows, range, direction, and normalized proportions, and verify the result in Python or TypeScript.

This is geometry, not a trading signal. A correctly measured candle does not by itself predict a future return.

Why a precise candle matters

CME Group and Nasdaq both describe a candlestick as a representation of four prices for one period: open, high, low, and close. The body spans open to close, while the thin lines extend to the high and low (CME Group, Nasdaq).

That visual definition becomes the foundation for later rules such as doji, marubozu, hammer, and engulfing detection. If the foundation is ambiguous, every later classifier inherits the ambiguity.

There are also data-engineering traps hiding behind the picture:

• a live candle can still change;
• the provider's day boundary may use UTC, an exchange session, or another time zone;
• an official futures settlement can differ from a last-trade close;
• raw and adjusted prices must not be mixed;
• a flat candle has no denominator for normalized proportions.

The correct response is a small, explicit contract.

Intuition: one range partitioned into three pieces

For one candle, imagine walking downward from the high to the low.

1. First comes the upper shadow.
2. Then comes the real body.
3. Finally comes the lower shadow.

Those three non-overlapping distances must add to the full range.

The worked candle has:

• open $O=100$;
• high $H=108$;
• low $L=97$;
• close $C=105$.

Its upper shadow is 3, body is 5, lower shadow is 3, and range is 11. The most useful independent check is therefore:

Define the input before doing arithmetic

At minimum, the calculator needs finite numeric values for open, high, low, and close. Booleans, missing values, NaN, and infinity are invalid.

The geometry constraints are:

The full production record should also retain:

• an RFC 3339 timestamp with an explicit offset, preferably UTC;
• a source-qualified instrument identifier;
• the interval or event-bucket definition;
• the venue session and time-zone convention;
• whether the bar is closed;
• the price adjustment basis;
• the vendor and license.

The reference calculator requires only OHLC, but it validates optional metadata when supplied and normalizes omitted metadata to null in both languages. It does not infer that a bar is closed from its timestamp or attempt to validate a venue calendar.

The IETF's RFC 3339 provides the timestamp interchange profile and recommends UTC for interoperability. A real exchange feed can also expose an interval, start and close times, and a closed-kline flag; Binance's official kline stream is one concrete example (RFC 3339, Binance Spot API).

Do not silently treat every close field as an exchange settlement. CME's rulebook defines settlement as an official price determined under exchange rules and used in clearing, which is a different provenance from “last eligible trade in this bar” (CME rulebook definitions).

The formulas

First find the body's price boundaries:

Then calculate the four distances:

where $B$ is body, $U$ is upper shadow, $D$ is lower shadow, and $R$ is range.

For every valid candle:

When the range is positive, normalize each component:

and check:

Open and close positions within the range are:

All five normalized values are undefined when $R=0$. This package returns null rather than silently returning zero.

Direction is a label, not a body rewrite

The raw body is always $|C-O|$. An optional tolerance $\epsilon$ changes only the direction label:

A fixed epsilon is useful for absorbing a known tick-scale difference, but it is not a universal definition of a doji. Scale-aware classification belongs in the next topic.

From input to output

The whole algorithm has one meaningful branch: whether range normalization has a positive denominator.

The interactive candle build lets you move forward and backward through that flow one exact stage at a time. Compare the canonical, bearish, tolerance-edge provisional, and flat synthetic cases to see direction, closure state, and the null branch change without rewriting the geometry formulas.

Worked numerical example

With $O=100$, $H=108$, $L=97$, and $C=105$:

The machine-readable input and output are in worked-example.json.

Why not attach a famous market date?

For candle anatomy, a named historical event adds narrative but not mathematical evidence. Selecting a well-known reversal would also tempt readers to infer forecasting value from one chosen bar. This tutorial therefore uses a synthetic, freely redistributable example whose arithmetic and price basis are explicit. A real provider bar can be substituted only with its symbol, venue, interval, session, adjustment basis, retrieval time, and revision status recorded; the result is still a description of geometry, not a causal event explanation or predictive test.

Python implementation

The Python API accepts a mapping and returns a typed dictionary:

from candle_anatomy import analyze_candle

result = analyze_candle({
    "timestamp": "2026-01-05T10:00:00Z",
    "instrument_id": "SYNTH:ABC",
    "interval": "5m",
    "open": 100,
    "high": 108,
    "low": 97,
    "close": 105,
    "is_closed": True,
})

assert result["body"] == 5
assert result["upper_shadow"] == 3
assert result["lower_shadow"] == 3
assert result["range"] == 11

See the complete Python source and runnable example.

TypeScript implementation

The TypeScript API exposes the same field names so one JSON fixture can verify both languages:

import { analyzeCandle } from "./candleAnatomy.ts";

const result = analyzeCandle({
  timestamp: "2026-01-05T10:00:00Z",
  instrument_id: "SYNTH:ABC",
  interval: "5m",
  open: 100,
  high: 108,
  low: 97,
  close: 105,
  is_closed: true,
});

console.assert(result.body === 5);
console.assert(result.range === 11);

See the complete TypeScript source and runnable example.

Both implementations run in constant time per candle. They intentionally use ordinary binary floating-point for cross-language parity. Systems requiring exact tick arithmetic can represent prices as integer ticks first.

Tests that matter

A canonical example alone is not enough. The shared fixture suite includes:

• bullish and bearish candles;
• an exact-neutral candle with positive range;
• a flat candle;
• valid negative prices;
• a tiny body labeled neutral under epsilon;
• invalid highs and lows;
• missing, boolean, string, and non-finite inputs;
• a negative direction tolerance;
• malformed optional metadata and a non-object input;
• metadata preservation and ordered batch output.

Every positive-range result must satisfy both:

The Python test is test_candle_anatomy.py, and the TypeScript test is candleAnatomy.test.ts.

Edge cases in one view

Notice three distinctions:

1. negative prices can still produce valid distances;
2. a neutral body can have a positive range;
3. a flat candle is valid even though its normalized ratios are null.

Incomplete candles and corrections

A live candle does not create look-ahead bias if you calculate only from values observed so far, but its geometry is provisional. High, low, and close can change until the interval ends.

Store the closure and revision state. Do not train on a final candle and pretend the final high and low were already known halfway through the interval.

What candle anatomy cannot tell you

A candle loses the intrabar path. One market may trade smoothly from open to close; another may oscillate violently and finish with the same OHLC.

Valid geometry also does not prove clean data. Bad ticks, stale feeds, corporate actions, roll adjustments, and wrong session boundaries can all produce a plausible-looking candle.

Most importantly, anatomy is not evidence of predictive power. Correct implementation answers “did we measure this shape correctly?” It does not answer “will this shape make money after costs and out-of-sample testing?”

Summary and next topic

You can now:

• validate one OHLC record;
• derive body, shadows, range, direction, and positions;
• normalize only when the range is positive;
• test the range partition and cross-language parity;
• distinguish provisional candle state from final data.

The natural next step is D06-F01-A02 — Scale-Aware Body Classification, where body size is evaluated relative to an instrument-aware scale instead of a fixed absolute threshold.