Plugin

Market Structure

Confirmed swing highs and lows without repainting, the trend they form (HH and HL or LH and LL), and the last break of structure and change of character.

IndicatorNo networkDesktop onlyv1.0.0

Get early access Plugin API documentation Built in indicators

About

A swing high is a bar whose high is strictly above the highs of the length bars before it and the length bars after it; a swing low is the same with lows, strictly below. Equal highs or lows on either side make no swing. A swing is confirmed only when its length right hand bars have closed, and it is reported on that confirming bar, never earlier, so the indicator never redraws: what it says at a bar uses that bar and the ones before it only. A swing therefore always arrives length bars late.

Each new swing high is labelled HH (above the previous swing high), LH (below) or EH (equal); each swing low HL, LL or EL. The trend (value) is 1 when the last high is HH and the last low is HL, -1 when they are LH and LL, and 0 for any other mix.

A close above the last confirmed swing high, or below the last confirmed swing low, breaks structure; each swing level can be broken once, and wicks do not count. A break in the direction of the current bias, or the very first break, is a break of structure (BOS). A break against the bias is a change of character (CHoCH) and turns the bias. At most one break per bar: a close above the last high and below the last low at once (only possible when that low sits above that high) counts as the break up.

Parameters

Name	Type	Default	Range or options	Description
`length`	int	`3`	min 1, max 50	Bars on each side of a swing. A swing is confirmed, and reported, this many bars after its own bar.

Use it in a strategy

pythonms = ctx.plugin_indicator("market_structure", "structure", {"length": 3})
if ms is not None and ms.bias is not None:
    # A break of structure up while the swings make HH and HL: long.
    if ms.bos == 1 and ms.value == 1:
        ctx.signal("LONG")
    # A change of character down: out.
    elif ms.choch == -1:
        ctx.signal("EXIT")

What it provides

`value`Value	The trend, the same as `trend`: 1 (HH and HL), -1 (LH and LL), 0 (mixed). None until there are two swing highs and two swing lows.
`bias`Value	The direction of the last break: 1 after a break up, -1 after a break down. None until the first break.
`last_high`Value	The price of the last confirmed swing high, and `last_high_time` the time of its bar. None until the first one.
`last_low`Value	The price of the last confirmed swing low, and `last_low_time` the time of its bar. None until the first one.
`high_label`Value	"HH", "LH" or "EH" for the last swing high against the one before; `low_label` is "HL", "LL" or "EL". None until there are two.
`high_confirmed`Value	True on the bar that confirms a swing high, `length` bars after it; `low_confirmed` the same for a swing low. None during warm up.
`bos`Value	1 or -1 on the bar of a break of structure up or down, else 0; `bos_level` keeps the level of the last one. None during warm up.
`choch`Value	1 or -1 on the bar of a change of character up or down, else 0; `choch_level` keeps the level of the last one. None during warm up.

When values are known

A swing is known length bars after its own bar, at the close of the confirming bar; breaks are known at the close of the breaking bar. Nothing reported is ever changed by later bars. Warm up: the first 2 x length bars report None.

Limits

Swings arrive length bars late by design. A chart tool that marks a swing on its own bar is looking ahead; this one does not.
Strict comparisons: a double top with exactly equal highs makes no swing high.
BOS and CHoCH have many definitions in trading literature. This one uses closes against the last confirmed swing only; other tools may mark different bars.
A plugin indicator is not drawn on the chart and is not available in Blocks, Pine, Rust or C#; it runs on the run's own instrument only.

Preview

json{
  "bias": 1,
  "bos": 0,
  "bos_level": 1.0903,
  "choch": 0,
  "choch_level": 1.0812,
  "high_confirmed": false,
  "high_label": "HH",
  "last_high": 1.0921,
  "last_low": 1.0874,
  "low_confirmed": true,
  "low_label": "HL",
  "value": 1
}

A made-up sample that shows the shape of the output. Not vendor data and not a result.

The code

main.py, the file the app installs.

python"""Market structure: confirmed swings, the trend they form, and structure breaks.

The definitions this plugin uses:

- Swing high: a bar whose high is strictly above the highs of the `length`
  bars before it and the `length` bars after it. Swing low: the same with lows,
  strictly below. Equal highs or lows on either side make no swing.
- A swing is confirmed only when its `length` right hand bars have closed, and
  it is reported on that confirming bar, never earlier. Nothing is redrawn:
  what the indicator says at a bar uses that bar and the bars before it only.
- Labels: a swing high above the previous swing high is HH, below it LH, equal
  EH; a swing low above the previous swing low is HL, below it LL, equal EL.
- Trend (value): 1 when the last high is HH and the last low is HL, -1 when
  they are LH and LL, 0 for any other mix.
- Breaks: a close above the last confirmed swing high, or below the last
  confirmed swing low, breaks structure. Each swing level can be broken once.
  A break in the direction of the current bias (or the very first break) is a
  break of structure (BOS); a break against it is a change of character
  (CHoCH) and turns the bias. Closes only, wicks do not count. At most one
  break per bar: a close above the last high and below the last low at once
  (possible only when that low sits above that high) counts as the break up.

A strategy reads it through
ctx.plugin_indicator("market_structure", "structure", {"length": 3}).
"""

from collections import deque


def _bar(bar):
    """high, low, close and time of an engine Bar or of a plain dict."""
    if isinstance(bar, dict):
        return float(bar["high"]), float(bar["low"]), float(bar["close"]), bar.get("ts")
    return float(bar.high), float(bar.low), float(bar.close), bar.ts


def _label(new, old, higher, lower, equal):
    if old is None:
        return None
    if new > old:
        return higher
    if new < old:
        return lower
    return equal


class MarketStructure:
    """update(bar) then read value (the trend), bias, the last swings and their
    labels, and this bar's events. See the module docstring for the rules."""

    def __init__(self, length=3):
        self.length = max(1, int(length))
        self._window = deque(maxlen=2 * self.length + 1)  # (high, low, ts)

        self.last_high = None
        self.last_low = None
        self.last_high_time = None
        self.last_low_time = None
        self.high_label = None
        self.low_label = None
        self.trend = None
        self.bias = None
        self.bos_level = None
        self.choch_level = None
        # This bar's events, None during warm up.
        self.high_confirmed = None
        self.low_confirmed = None
        self.bos = None
        self.choch = None

        self._high_live = False  # the last swing high is not broken yet
        self._low_live = False

    def update(self, bar):
        high, low, close, ts = _bar(bar)
        self._window.append((high, low, ts))
        if len(self._window) < self._window.maxlen:
            return  # warm up: no bar can be confirmed yet

        # 1. Breaks, against the swings known before this bar.
        self.bos, self.choch = 0, 0
        if self._high_live and close > self.last_high:
            self._break(1, self.last_high)
            self._high_live = False
        elif self._low_live and close < self.last_low:
            self._break(-1, self.last_low)
            self._low_live = False

        # 2. The middle bar of the window now has its right hand bars closed.
        self.high_confirmed, self.low_confirmed = False, False
        mid = self.length
        m_high, m_low, m_ts = self._window[mid]
        others = [w for i, w in enumerate(self._window) if i != mid]
        if all(m_high > h for h, _, _ in others):
            self.high_label = _label(m_high, self.last_high, "HH", "LH", "EH")
            self.last_high, self.last_high_time = m_high, m_ts
            self._high_live = True
            self.high_confirmed = True
        if all(m_low < lo for _, lo, _ in others):
            self.low_label = _label(m_low, self.last_low, "HL", "LL", "EL")
            self.last_low, self.last_low_time = m_low, m_ts
            self._low_live = True
            self.low_confirmed = True

        # 3. The trend from the last two labels.
        if self.high_label is None or self.low_label is None:
            self.trend = None
        elif self.high_label == "HH" and self.low_label == "HL":
            self.trend = 1
        elif self.high_label == "LH" and self.low_label == "LL":
            self.trend = -1
        else:
            self.trend = 0

    def _break(self, direction, level):
        if self.bias is not None and self.bias != direction:
            self.choch, self.choch_level = direction, level
        else:
            self.bos, self.bos_level = direction, level
        self.bias = direction

    @property
    def value(self):
        """The trend: 1 up (HH and HL), -1 down (LH and LL), 0 mixed, None until
        there are two swing highs and two swing lows."""
        return self.trend


def make(params):
    params = params or {}
    return MarketStructure(params.get("length", 3))


def register(api):
    api.register_indicator(
        "structure",
        "Market structure",
        make,
        [{"key": "length", "label": "Bars each side", "type": "int", "default": 3, "min": 1, "max": 50}],
    )
    api.log("Market structure indicator registered")