WHALE ENGINE
Documentation

Bollinger Band Width (bbw)

Bollinger Band Width (BBW) expresses the width of the Bollinger Bands relative to their middle line. It produces a single percentage series: the distance between the upper and lower bands is divided by the moving average between them. This normalization distinguishes BBW from a raw distance expressed in the unit of the source.

When the middle line and multiplier are both positive, as in the usual configuration with a price source, a high value indicates bands that are wide relative to that level, reflecting strong recent dispersion. A low value means that the bands are tighter and dispersion is more limited. length sets the common horizon of the average and dispersion, while multiplier widens or narrows the bands and changes BBW in the same proportion.

Block declaration

A strategy can contain multiple [[bbw]] blocks. Each block produces one numeric series representing the BBW value.

Examples

Minimal setup

This block computes BBW from close using the default settings: a 20-period window and a multiplier of 2.0.

[[bbw]]
id = "bbw"

Custom fixed setup

This block uses custom length and multiplier values.

[[bbw]]
id         = "bbw"
length     = 24
multiplier = 2.4

Search for the optimal period and multiplier

This block explores ranges of values for length and multiplier to identify the best-performing configuration.

[[bbw]]
id               = "bbw"
length.start     = 10
length.stop      = 30
multiplier.start = 1.0
multiplier.stop  = 3.0
multiplier.step  = 0.2

Dedicated symbol and timeframe

This BBW block uses the daily candles from BINANCE:ETHUSDT. The price series needed to compute the bands comes from this symbol and timeframe, independently of the primary symbol and timeframe defined in [backtest]. See Exchanges, Symbols and Timeframes for alignment rules.

[[bbw]]
id        = "bbw"
symbol    = "BINANCE:ETHUSDT"
timeframe = "D"

Parameters

ParameterDescription
id
String
Required		Unique series name.
source
 String
 or Array
 Optional		Input series used for the calculation.
Accepted forms: source = "hl2" or source = ["close", "hl2"].
Each value can be either a standard price source (open, close, high, low, hl2, hlc3, ohlc4, hlcc4, volume) or the id of another indicator.
Default value: "close"
length
Integer or Range
Optional		SMA and standard deviation window; must be ≥ 1. Default value: 20.

Usage:
• Fixed: length = value
• Grid search:
 – length.start = min_value
 – length.stop = max_value
 – length.step = value (optional, default 1)
multiplier
Decimal or Range
Optional		Standard deviation factor. Default value: 2.0.

Usage:
• Fixed: multiplier = value
• Grid search:
 – multiplier.start = min_value
 – multiplier.stop = max_value
 – multiplier.step = value (optional, default 1)
symbol
String or Array
Optional		Market symbol(s) used when source contains standard prices (open, close, high, low, hl2, hlc3, ohlc4, hlcc4, volume).
If source mixes standard prices and indicator ids, symbol is applied only to combinations based on standard prices.
If source contains only indicator ids, symbol is ignored.
For symbol format and alignment rules, see Exchanges, Symbols and Timeframes.
timeframe
String or Array
Optional		Timeframe on which this indicator is computed.
If timeframe is omitted, the computation uses the grid’s main timeframe defined in [backtest].
For accepted formats and timeframe alignment rules, see Exchanges, Symbols and Timeframes.

Available variables

The BBW block exposes one numeric series and its parameters, along with the input source, symbol, and timeframe.

Assume the block is configured as:

[[bbw]]
id = "bbw"

Then:

VariableDescription
bbw or bbw[0]
Decimal		Current BBW value.
bbw[n]
Decimal		BBW value from n candles ago.
bbw.length
Decimal		Length in use.
bbw.multiplier
Decimal		Multiplier in use.
bbw.source
String		Input series name.
bbw.symbol
String		Symbol used.
bbw.timeframe
String		Timeframe used.

Notes

Because the calculation is normalized by the middle line, BBW is NaN when that line is zero. If the middle line is negative, the result changes sign and the usual interpretation of a positive width no longer applies directly. A negative multiplier also reverses the bands and the sign of BBW.

Prev
Bars Since (barssince)
Next
Cross