Correlation matrix

// Correlation Matrix: how this chart's market moved with eight crypto perpetuals over the last 'window' bars (the
// Binance Futures BTC, ETH, SOL, BNB, XRP, DOGE, ADA and AVAX perpetuals), as a market by market heatmap below the
// chart. Teal cells moved together, violet cells moved apart, the surface colour is no relation, and an empty cell is
// a pair with too few shared bars in the window (a coin listed after the window began, or one whose candles the
// chart's bars cannot join); its row keeps its name. The chart's own market is the first row and column; when it is
// one of the eight, that row carries the market's name and the grid is 8 by 8. The card reads the chart market's
// average correlation with the others, the market it is most tied to and the one it is most free of; the panel's
// legend counts how many moved with it above the 'strong' setting, and an Avg row under the grid gives every market
// the same reading. The trader sees in one glance whether the market is trading on its own or as one of the crowd,
// and which market to watch as a lead or a hedge. Correlation is written for crypto charts: on a chart whose candles
// carry no volume (forex, gold, silver) it says so in one sentence with the way out, and draws no grid.

section("Window");
param.int("window", 96, { min: 30, max: 500, label: "Window in bars", description: "Bars in the correlation window" });
param.number("strong", 0.7, { min: 0.3, max: 0.95, step: 0.05, label: "Strong correlation", description: "Correlation at or above which two markets count as moving together" });

// Inputs: the chart's own close is the grid and the first row, its volume tells a crypto chart from a quote-only
// one (forex, gold and silver candles carry none; the same candles, so no extra source); the eight pins join by
// timestamp and read NaN on a bar their market has no candle for, so a missing candle never fabricates a return.
input("close", ohlcv.close, { description: "This chart's close: the first row and column of the grid" });
input("volume", ohlcv.volume, { description: "This chart's volume: candles that never carry any (forex, gold, silver) mark a chart that is not crypto" });
input("btc", ohlcv.close, { exchange: "BINANCE_FUTURES", symbol: "BTCUSDT", missing: "nan", description: "Bitcoin, Binance Futures perpetual" });
input("eth", ohlcv.close, { exchange: "BINANCE_FUTURES", symbol: "ETHUSDT", missing: "nan", description: "Ether, Binance Futures perpetual" });
input("sol", ohlcv.close, { exchange: "BINANCE_FUTURES", symbol: "SOLUSDT", missing: "nan", description: "Solana, Binance Futures perpetual" });
input("bnb", ohlcv.close, { exchange: "BINANCE_FUTURES", symbol: "BNBUSDT", missing: "nan", description: "BNB, Binance Futures perpetual" });
input("xrp", ohlcv.close, { exchange: "BINANCE_FUTURES", symbol: "XRPUSDT", missing: "nan", description: "XRP, Binance Futures perpetual" });
input("doge", ohlcv.close, { exchange: "BINANCE_FUTURES", symbol: "DOGEUSDT", missing: "nan", description: "Dogecoin, Binance Futures perpetual" });
input("ada", ohlcv.close, { exchange: "BINANCE_FUTURES", symbol: "ADAUSDT", missing: "nan", description: "Cardano, Binance Futures perpetual" });
input("avax", ohlcv.close, { exchange: "BINANCE_FUTURES", symbol: "AVAXUSDT", missing: "nan", description: "Avalanche, Binance Futures perpetual" });

// Outputs are data-only, written on the live bar: the card, the Console and a watch read the same numbers.
output("avg_corr", none, overlay, { format: "0.00", description: "The chart market's average correlation with the other markets in the grid" });
output("tone", none, overlay, { description: "0 moving apart, 1 loosely related, 2 moving together, NaN with no reading: the headline's colour" });
output("strong_count", none, overlay, { description: "How many of the other markets correlate with the chart's market at or above 'strong'" });
output("served_count", none, overlay, { description: "How many of the other markets had enough bars in the window to be measured" });
output("bars", none, overlay, { format: "int", description: "The window in bars, read by the card's title" });
string("avg_text", { max_bytes: 24 }); // "0.62 avg"
string("tied_text", { max_bytes: 24 }); // "ETH 0.91"
string("free_text", { max_bytes: 24 }); // "AVAX 0.12"
string("note", { max_bytes: 80 }); // the one sentence: the window still loading, or a chart that is not crypto

// The one sentence: a slate knockout label at the top right of the price pane, under the card.
handles.label({ text: "note", anchor: "top_right", align: "right", color: "#94a3b8", size: 11, style: "knockout", padding: 6, safe_area: true });
const note = draw.label(0);
const NOTE_Y: f64 = 200.0; // pixels down from the top-right corner: under the card, which ends about 172 px down

// The grid: one cell per market pair, violet at -1 through the chart surface at 0 to teal at +1, every cell printed
// with two decimals, a hover card per cell, the chart's own row lit in the row labels.
const grid = frame("grid", { max_bytes: 8192 });
panel.heatmap({ name: "corr_grid", title: "Correlation of returns", x: "category", place: "below", frame: grid, scale: "palette", palette: ["#a78bfa", "theme.bg", "#2dd4bf"], min: -1, max: 1, row_title: "Market", col_title: "vs", format: "0.00", hover_card: true, height_frac: 0.35 });

// The card, in the signal look, below the chart's own High tag: the window in the title, the average correlation as the headline (violet apart,
// slate loose, teal together; slate words when there is no reading), then the most tied and the most free market
// with their readings. The headline is a big number: its words stay short enough to fit the card.
render.hud("card", { position: "top_right", look: "signal", title: "Correlation, last {{bars:int}} bars", columns: 1, width: 250, offset: [0, 24], safe_area: true, tiles: [
  tile.pill("Average with the others", "avg_text", { headline: true, color_by: "tone", colors: ["#a78bfa", "#94a3b8", "#2dd4bf"], color: "#94a3b8" }),
  tile.rows([["Most tied", "tied_text"], ["Most free", "free_text"]]),
] });

const SERIES = 9; // the chart's market plus the eight pins
const MAX_WINDOW = 500; const MAX_RING = MAX_WINDOW + 1; // 'window' returns need 'window' + 1 closes
const NAMES: StaticArray<string> = ["Chart", "BTC", "ETH", "SOL", "BNB", "XRP", "DOGE", "ADA", "AVAX"];
const closes = new StaticArray<f64>(SERIES * MAX_RING); // the ring of closes, one row per series
const rets = new StaticArray<f64>(SERIES * MAX_WINDOW); // the window's log returns per series, oldest first
const corr = new StaticArray<f64>(SERIES * SERIES); // the live grid, NaN where a pair has too few bars
const order = new StaticArray<i32>(SERIES); // the series behind each grid row: the chart first, then the pins
const colAvg = new StaticArray<f64>(SERIES); // each column's average with the other markets (the Avg row)
let window = 96; let strong = 0.7; let ring = 97; let minPairs = 48; // the params, read in onStart()
let head = -1; let count = 0; // the ring: head is the newest slot, count the slots in use
let rows = SERIES; let chartName = "Chart"; // the grid's size and the chart row's name this run
let volumeSeen = false; // a bar of the chart carried volume: every crypto market trades some, quote-only candles never do

function readSeries(s: i32): f64 {
  switch (s) {
    case 1: return in_btc(); case 2: return in_eth(); case 3: return in_sol(); case 4: return in_bnb();
    case 5: return in_xrp(); case 6: return in_doge(); case 7: return in_ada(); case 8: return in_avax();
    default: return bar.close();
  }
}
function slotAt(k: i32, used: i32): i32 { return (head - used + 1 + k + MAX_RING) % MAX_RING; } // the k-th oldest of 'used' slots
function sameClose(a: f64, b: f64): bool { return Math.abs(a - b) <= 1e-9 * Math.max(1.0, Math.abs(a)); }
// At or above 'strong' as the cells print it, two decimals: a 0.6955 cell reads 0.70 and counts at 0.70.
function isStrong(r: f64): bool { return Math.round(r * 100.0) >= Math.round(strong * 100.0); }

// The pin that is this chart's own market, if any: its closes equal the chart's on every bar both have (the forming
// bar may lag by a tick, so one mismatch is allowed). That row is dropped and the chart row takes its name.
function duplicatePin(used: i32): i32 {
  for (let p = 1; p < SERIES; p += 1) {
    let present = 0; let equal = 0;
    for (let k = 0; k < used; k += 1) {
      const slot = slotAt(k, used); const a = closes[slot]; const b = closes[p * MAX_RING + slot];
      if (isNaN(a) || isNaN(b)) continue;
      present += 1; if (sameClose(a, b)) equal += 1;
    }
    if (present >= 2 && equal >= present - 1) return p;
  }
  return 0;
}
// Log returns of every series over the window, NaN where either close is missing.
function buildReturns(used: i32): i32 {
  const n = used - 1;
  for (let s = 0; s < SERIES; s += 1) {
    for (let k = 0; k < n; k += 1) {
      const a = closes[s * MAX_RING + slotAt(k, used)]; const b = closes[s * MAX_RING + slotAt(k + 1, used)];
      rets[s * MAX_WINDOW + k] = a > 0.0 && b > 0.0 ? Math.log(b / a) : NaN;
    }
  }
  return n;
}
// Pearson correlation of two series over the bars both have; NaN under 'minPairs' bars or a flat series.
function pearson(a: i32, b: i32, n: i32): f64 {
  let m = 0; let sx = 0.0; let sy = 0.0; let sxx = 0.0; let syy = 0.0; let sxy = 0.0;
  for (let k = 0; k < n; k += 1) {
    const x = rets[a * MAX_WINDOW + k]; const y = rets[b * MAX_WINDOW + k];
    if (isNaN(x) || isNaN(y)) continue;
    m += 1; sx += x; sy += y; sxx += x * x; syy += y * y; sxy += x * y;
  }
  if (m < minPairs) return NaN;
  const vx = sxx - (sx * sx) / f64(m); const vy = syy - (sy * sy) / f64(m);
  if (!(vx > 0.0) || !(vy > 0.0)) return NaN;
  const r = (sxy - (sx * sy) / f64(m)) / Math.sqrt(vx * vy);
  return r > 1.0 ? 1.0 : r < -1.0 ? -1.0 : r;
}
function buildGrid(n: i32): void {
  for (let i = 0; i < rows; i += 1) {
    for (let j = i; j < rows; j += 1) {
      const r = pearson(order[i], order[j], n);
      corr[i * SERIES + j] = r; corr[j * SERIES + i] = r;
    }
  }
  for (let j = 0; j < rows; j += 1) { // the Avg row: each column against the other markets
    let sum = 0.0; let m = 0;
    for (let i = 0; i < rows; i += 1) { if (i == j) continue; const r = corr[i * SERIES + j]; if (isNaN(r)) continue; sum += r; m += 1; }
    colAvg[j] = m > 0 ? sum / f64(m) : NaN;
  }
}
function writeGrid(strongCount: i32, served: i32): void { // [column market, row market, correlation] per cell, null where unmeasured
  fb_clear();
  fb_text("{\"title\":\"Correlation of returns, "); fb_int(<i64>window); fb_text(" bars\",\"caption\":\"");
  fb_text(chartName); fb_text(" moves with "); fb_int(<i64>strongCount); fb_text(" of "); fb_int(<i64>served);
  fb_text("\",\"highlight\":{\"row\":"); fb_str(chartName); fb_text("},\"rows\":[");
  for (let i = 0; i < rows; i += 1) {
    for (let j = 0; j < rows; j += 1) {
      if (i > 0 || j > 0) fb_text(",");
      fb_text("["); fb_str(order[j] == 0 ? chartName : NAMES[order[j]]); fb_text(","); fb_str(order[i] == 0 ? chartName : NAMES[order[i]]); fb_text(",");
      fb_f64(corr[i * SERIES + j], 2); fb_text("]");
    }
  }
  fb_text("],\"summary\":[{\"label\":\"Avg\",\"values\":[");
  for (let j = 0; j < rows; j += 1) { if (j > 0) fb_text(","); fb_f64(colAvg[j], 2); }
  fb_text("]}]}");
  writeFrameBuffer(FRAME_GRID);
}
// A state with no grid: the one sentence under the card, and the card's headline for that state with a dash per row.
function sayInstead(sentence: string, headline: string): void {
  sb_clear(); sb_text(sentence); note.set(0.0, NOTE_Y).text(str_note_sb);
  sb_clear(); sb_text(headline); str_avg_text_sb();
  sb_clear(); sb_text("-"); str_tied_text_sb();
  sb_clear(); sb_text("-"); str_free_text_sb();
}

// onStart() runs once before the first bar: read the params and size the ring to the window.
function onStart(): void {
  window = i32(p_window()); strong = p_strong(); ring = window + 1; minPairs = (window + 1) / 2;
}
// onBar() runs once per bar: push every close into the ring and note whether the chart's candles carry volume; on
// the live bar, measure the grid and write the panel, the card's words and the outputs, or the one sentence when
// the chart is not crypto or the window is not full yet.
function onBar(): void {
  head = (head + 1) % MAX_RING; if (count < ring) count += 1;
  for (let s = 0; s < SERIES; s += 1) closes[s * MAX_RING + head] = readSeries(s);
  if (in_volume() > 0.0) volumeSeen = true;
  if (!bar.isLast()) return;
  out_bars(f64(window));
  if (!volumeSeen) { // no candle carried volume: a forex, gold or silver chart, so no grid
    sayInstead("Correlation is written for crypto charts: switch to a BTC or ETH perp", "Not crypto");
    return;
  }
  if (count < window) { // fewer bars than the window: no grid yet
    sayInstead("Loading more history for the correlation window", "Loading");
    return;
  }
  note.delete();
  const used = count < ring ? count : ring;
  const dup = duplicatePin(used);
  chartName = dup > 0 ? NAMES[dup] : "Chart";
  rows = 0; order[rows] = 0; rows += 1;
  for (let p = 1; p < SERIES; p += 1) if (p != dup) { order[rows] = p; rows += 1; }
  buildGrid(buildReturns(used));
  // The chart's row: its average with the others, the most tied and most free markets, the count above 'strong'.
  let sum = 0.0; let served = 0; let strongCount = 0; let tied = -1; let free = -1;
  for (let j = 1; j < rows; j += 1) {
    const r = corr[j]; if (isNaN(r)) continue;
    sum += r; served += 1; if (isStrong(r)) strongCount += 1;
    if (tied < 0 || r > corr[tied]) tied = j;
    if (free < 0 || r < corr[free]) free = j;
  }
  const avg = served > 0 ? sum / f64(served) : NaN;
  out_avg_corr(avg); out_strong_count(f64(strongCount)); out_served_count(f64(served));
  out_tone(isNaN(avg) ? NaN : avg < 0.0 ? 0.0 : isStrong(avg) ? 2.0 : 1.0);
  sb_clear(); if (served > 0) { sb_f64(avg, 2); sb_text(" avg"); } else sb_text("No pairs"); str_avg_text_sb();
  sb_clear(); if (tied >= 0) { sb_text(NAMES[order[tied]]); sb_text(" "); sb_f64(corr[tied], 2); } else sb_text("-"); str_tied_text_sb();
  sb_clear(); if (free >= 0) { sb_text(NAMES[order[free]]); sb_text(" "); sb_f64(corr[free], 2); } else sb_text("-"); str_free_text_sb();
  writeGrid(strongCount, served);
}