WHALE ENGINE
Documentation
WHALE ENGINE

Correlation

[[correlation]] measures the linear relationship between two numeric series over a given window. It indicates to what extent the variations of source1 and source2, observed relative to their average over that window, tend to occur together.

Correlation is expressed on a scale from -1 to +1. A value close to +1 indicates that the two series generally vary in the same direction. A value close to -1 indicates that they vary in opposite directions. A value close to 0 means that no clear linear relationship stands out over the observed window.

Block declaration

A strategy can contain multiple [[correlation]] blocks. Each block produces one numeric series: the correlation between source1 and source2.

Examples

Minimal configuration

This block computes the correlation on the main symbol and timeframe defined in [backtest].

[[correlation]]
id      = "corr"
source1 = "close"
source2 = "open"
length  = 20

Finding the optimal window length

This block explores a range of values for length to identify the best-performing window length, using close and open as the two input series.

[[correlation]]
id           = "corr"
source1      = "close"
source2      = "open"
length.start = 20
length.stop  = 80
length.step  = 10

Dedicated timeframe

This block computes the correlation between close and open on a specific timeframe, independent of the main grid timeframe. See the Exchanges, Symbols and Timeframes page for alignment rules between timeframes.

[[correlation]]
id        = "corr"
source1   = "close"
source2   = "open"
length    = 50
timeframe = "D"

Correlation between two symbols

To correlate two distinct markets, first define one series per symbol, then use those ids as source1 and source2. Here, each [[price]] block reads a different symbol, and the [[correlation]] block then measures the relationship between those two series on the 4-hour timeframe.

[[price]]
id        = "btc_close"
symbol    = "BINANCE:BTCUSDT"
timeframe = "240"

[[price]]
id        = "eth_close"
symbol    = "BINANCE:ETHUSDT"
timeframe = "240"

[[correlation]]
id        = "corr_cross_symbol"
source1   = "btc_close"
source2   = "eth_close"
length    = 50
timeframe = "240"

Correlation between a price and a moving average

You can also correlate a price series with a derived series. Here, the block measures the relationship between close and an exponential moving average computed from that same series.

[[moving_average]]
id     = "ma"
type   = "ema"
length = 20

[[correlation]]
id      = "corr"
source1 = "close"
source2 = "ma"
length  = 30

Parameters

ParameterDescription
id
 String
 Required		Unique series name for the correlation output.
source1
 String
 or Array
 Required		First input series.
Can be a standard price ("close", "hlc3", etc.) or the id of another indicator.
Supports grid search by providing an array of candidate sources.
source2
 String
 or Array
 Required		Second input series.
Can be a standard price ("close", "hlc3", etc.) or the id of another indicator.
Supports grid search by providing an array of candidate sources.
length
 Integer or Range
 Required		Number of valid pairs used in the correlation window; must be ≥ 1.

Usage:
• Fixed: length = value
• Grid search:
 – length.start = min_value
 – length.stop = max_value
 – length.step = value (optional, default 1)
symbol
 String
 or Array
 Optional		Market symbol(s) used when both source1 and source2 consist only of standard prices (open, close, high, low, hl2, hlc3, ohlc4, hlcc4, volume). In that case, a single symbol context applies to both standard sources in the block: it cannot assign a different symbol to source1 and source2.
If symbol is provided while at least one possible source1/source2 combination references an indicator, strategy loading fails. This restriction avoids an ambiguous configuration, because the correlation block exposes only one market context for its output and therefore cannot apply symbol to only one of the two sources.
To correlate two distinct symbols, first create two upstream series, for example with [[price]], then use their ids in source1 and source2.
If omitted, the block inherits the symbol from [backtest].
For symbol format, arrays, and alignment rules, see Exchanges, Symbols and Timeframes.
timeframe
 String
 or Array
 Optional		Timeframe on which this correlation is computed.
If timeframe is omitted, the computation uses the grid’s main timeframe defined in [backtest].
For accepted formats and alignment rules, see Exchanges, Symbols and Timeframes.

Available variables

You can use the identifiers below directly in your expressions. The correlation block exposes one numeric series, its window length, the input series names, and the symbol/timeframe metadata.

Assume the block is configured as:

[[correlation]]
id      = "corr"
source1 = "close"
source2 = "open"
length  = 50

Then:

VariableDescription
corr or corr[0]
Decimal		Current correlation value between source1 and source2.
corr[n]
Decimal		Correlation value from n candles ago.
corr.length
Decimal		Window length currently in use.
corr.source1
String		Name of the first input series.
corr.source2
String		Name of the second input series.
corr.symbol
String		Symbol used for this block.
corr.timeframe
String		Timeframe used for this block.

Notes

  • The computation uses a fixed window of length valid (source1, source2) pairs. Bars where either input is na are skipped, and the output remains na until length valid pairs have been accumulated.
  • If either input series has zero variance over the window, the correlation is undefined and the block returns na.
  • corr.symbol and corr.timeframe describe the context of the correlation block, not a separate context for each source.
Prev
Or
Next
Position