MM Flow
FlowScripts

Perfected FlowScript

MA Spread

MA Spread — Perfected Edition is indexed as 358_ma_spread.flowscript. The exact FlowScript is viewable here; chart observe and trading automation use the current mmflow chart/recipe signal proxy until FlowScript v2 transpilation is available.

This exact FlowScript uses the v2 source dialect. It is viewable and connected to the chart/automation proxy, but direct editor execution needs the FlowScript v2 transpiler.

Dialect

flowscript-v2

Compatibility

flowscript-v2-needs-transpile

Position

offchart

Axis

true

Size

19.2 KB

Lines

613

Native Signal Candidates

9 source-level chart marker triggers extracted from guarded FlowScript v2 blocks.

9/9 guarded

Zero Cross Up

line 482:9

Trigger

(showShapes) && (crossUp)

Value

spreadZ

Deps

crossUp:var, showShapes:input

Zero Cross Down

line 492:9

Trigger

(showShapes) && (crossDown)

Value

spreadZ

Deps

crossDown:var, showShapes:input

Sig Cross Up

line 504:9

Trigger

(showShapes) && (sigCrossUp)

Value

signalLine

Deps

showShapes:input, sigCrossUp:var

Sig Cross Down

line 514:9

Trigger

(showShapes) && (sigCrossDown)

Value

signalLine

Deps

showShapes:input, sigCrossDown:var

Expansion Up

line 526:9

Trigger

(showShapes) && (expansionUp)

Value

spreadZ

Deps

expansionUp:var, showShapes:input

Expansion Down

line 536:9

Trigger

(showShapes) && (expansionDown)

Value

spreadZ

Deps

expansionDown:var, showShapes:input

Compression

line 548:9

Trigger

(showShapes) && (compression)

Value

spreadZ

Deps

compression:var, showShapes:input

Bull Div

line 560:9

Trigger

(showShapes) && (bullDiv)

Value

spreadZ

Deps

bullDiv:var, showShapes:input

Bear Div

line 570:9

Trigger

(showShapes) && (bearDiv)

Value

spreadZ

Deps

bearDiv:var, showShapes:input

358_ma_spread.flowscript

source path: kscripts/perfected/358_ma_spread.flowscript · sha256:12f53555ce496ba69d12669ad2a307e3a505b06eb64c8fb996f37851206546cb

hash verified
//@version=2
// ============================================================================
// MA Spread — Perfected Edition
// Author: BackQuant (@BackQuant) | Enhanced by kScript Perfection Engineer
// Tags: CORE, #maspread, #movingaverage, #zscore, #regime, #momentum, #trend
//
// Production-quality academically-grounded multi-factor moving average spread
// oscillator. Implements fast/slow MA distance with z-score normalization,
// regime detection, momentum histogram, color-coded visualization, and
// comprehensive shape markers.
//
// Research papers underpinning this design:
//  1. Brock, Lakonishok & LeBaron (1992), "Simple Technical Trading Rules
//     and the Stochastic Properties of Stock Returns", J. Finance. Tested
//     26 rules including MA crossovers; found all significantly outperformed
//     cash. MA spread = fastMA − slowMA is mathematically equivalent to a
//     crossover oscillator crossing zero.
//  2. Manasa & Reddy (2025), "Trend Analysis by Weighted and Exponential
//     Moving Average" (IJRIAS). WMA responds faster to recent changes but
//     produces more whipsaws; EMA offers stability but lags. A combined
//     approach yields more robust decisions.
//  3. Zakamulin (2023), "Optimal Trend-Following with Transaction Costs".
//     Optimal trend-following resembles the simple MA crossover rule; spread
//     convergence to zero indicates trend fading.
//  4. Wilder (1978), "New Concepts in Technical Trading Systems": canonical
//     ATR for volatility-based normalization. ATR enables cross-instrument
//     spread comparison.
//  5. Bollinger (2001), "Bollinger on Bollinger Bands": standard-deviation
//     normalization creates a unitless oscillator. %B and BandWidth concepts
//     underpin the spread-zscore and compression-detection modules.
//  6. Hull (2005), "The Hull Moving Average": HMA = WMA(√n) of [2·WMA(n/2)
//     − WMA(n)]. Nearly eliminates lag while improving smoothness.
//  7. Guppy (1990s-2000s), GMMA: two EMA clusters (short-term trader +
//     long-term investor) measure trend strength via cluster separation.
//     Underpins the ribbon-spread visualization.
// ============================================================================

define(
    title="MA Spread — Perfected Edition",
    position="offchart",
    axis=true
)

// ---------------------------------------------------------------------------
// 1. USER INPUTS — grouped with constraints
// ---------------------------------------------------------------------------

// --- MA Type ---
var fastType = input(
    name="fastType",
    type="select",
    defaultValue="SMA",
    label="Fast MA Type",
    options=["SMA", "EMA", "WMA", "HMA"],
    group="MA Settings"
)
var slowType = input(
    name="slowType",
    type="select",
    defaultValue="SMA",
    label="Slow MA Type",
    options=["SMA", "EMA", "WMA", "HMA"],
    group="MA Settings"
)
var fastLen = input(
    name="fastLen",
    type="number",
    defaultValue=10,
    label="Fast MA Length",
    constraints={min: 2, max: 200, step: 1},
    group="MA Settings"
)
var slowLen = input(
    name="slowLen",
    type="number",
    defaultValue=50,
    label="Slow MA Length",
    constraints={min: 5, max: 500, step: 1},
    group="MA Settings"
)

// --- Smoothing ---
var smoothLen = input(
    name="smoothLen",
    type="number",
    defaultValue=3,
    label="Signal EMA Smoothing",
    constraints={min: 1, max: 50, step: 1},
    group="Smoothing"
)
var momentumLen = input(
    name="momentumLen",
    type="number",
    defaultValue=14,
    label="Momentum Lookback",
    constraints={min: 5, max: 100, step: 1},
    group="Smoothing"
)

// --- Z-Score ---
var useZScore = input(
    name="useZScore",
    type="boolean",
    defaultValue=true,
    label="Z-Score Normalize Spread",
    group="Z-Score"
)
var zScoreLookback = input(
    name="zScoreLookback",
    type="number",
    defaultValue=50,
    label="Z-Score Lookback",
    constraints={min: 10, max: 500, step: 1},
    group="Z-Score"
)

// --- Thresholds ---
var expansionThreshold = input(
    name="expansionThreshold",
    type="number",
    defaultValue=2.0,
    label="Expansion Z-Score Threshold",
    constraints={min: 0.5, max: 5.0, step: 0.1},
    group="Thresholds"
)
var compressionThreshold = input(
    name="compressionThreshold",
    type="number",
    defaultValue=0.5,
    label="Compression Z-Score Threshold",
    constraints={min: 0.1, max: 2.0, step: 0.1},
    group="Thresholds"
)

// --- Regime Detection ---
var useRegime = input(
    name="useRegime",
    type="boolean",
    defaultValue=true,
    label="Enable Regime Detection",
    group="Regime"
)
var regimeLen = input(
    name="regimeLen",
    type="number",
    defaultValue=20,
    label="Regime ADX Length",
    constraints={min: 5, max: 100, step: 1},
    group="Regime"
)

// --- Display ---
var showRawSpread = input(
    name="showRawSpread",
    type="boolean",
    defaultValue=true,
    label="Show Raw Spread Histogram",
    group="Display"
)
var showZScore = input(
    name="showZScore",
    type="boolean",
    defaultValue=true,
    label="Show Z-Score Line",
    group="Display"
)
var showSignal = input(
    name="showSignal",
    type="boolean",
    defaultValue=true,
    label="Show Signal Line",
    group="Display"
)
var showRibbon = input(
    name="showRibbon",
    type="boolean",
    defaultValue=true,
    label="Show Spread Ribbon (Fill)",
    group="Display"
)
var showMomentum = input(
    name="showMomentum",
    type="boolean",
    defaultValue=true,
    label="Show Momentum Histogram",
    group="Display"
)
var showShapes = input(
    name="showShapes",
    type="boolean",
    defaultValue=true,
    label="Show Shape Markers",
    group="Display"
)
var showTable = input(
    name="showTable",
    type="boolean",
    defaultValue=true,
    label="Show Info Table",
    group="Display"
)

// --- Colors ---
var bullColor = input(
    name="bullColor",
    type="color",
    defaultValue="#26a69a",
    label="Bull Color",
    group="Colors"
)
var bearColor = input(
    name="bearColor",
    type="color",
    defaultValue="#ef5350",
    label="Bear Color",
    group="Colors"
)
var neutralColor = input(
    name="neutralColor",
    type="color",
    defaultValue="#9e9e9e",
    label="Neutral Color",
    group="Colors"
)
var signalColor = input(
    name="signalColor",
    type="color",
    defaultValue="#ffeb3b",
    label="Signal Line Color",
    group="Colors"
)
var expansionColor = input(
    name="expansionColor",
    type="color",
    defaultValue="#00e676",
    label="Expansion Color",
    group="Colors"
)
var compressionColor = input(
    name="compressionColor",
    type="color",
    defaultValue="#ab47bc",
    label="Compression Color",
    group="Colors"
)

// ---------------------------------------------------------------------------
// 2. DATA SOURCES & NaN GUARD
// ---------------------------------------------------------------------------
timeseries bars = ohlcv(symbol=currentSymbol, exchange=currentExchange)
timeseries px = bars.close

if (isnan(px[0])) {
    return
}

// ---------------------------------------------------------------------------
// 3. MA COMPUTATION — multi-type with helper
// ---------------------------------------------------------------------------
// Generic MA selector: sma, ema, wma, hma
function computeMA(source, length, maType) {
    if (maType == "SMA") {
        return sma(source=source, period=length)
    } else if (maType == "EMA") {
        return ema(source=source, period=length)
    } else if (maType == "WMA") {
        return wma(source=source, period=length)
    } else if (maType == "HMA") {
        // Hull MA: WMA(√n) of [2·WMA(n/2) − WMA(n)]
        var halfLen = math.floor(length / 2)
        var sqrtLen = math.floor(math.sqrt(length))
        var wmaHalf = wma(source=source, period=halfLen)
        var wmaFull = wma(source=source, period=length)
        var hullRaw = 2 * wmaHalf - wmaFull
        return wma(source=hullRaw, period=sqrtLen)
    }
    return sma(source=source, period=length)
}

timeseries fastMA = computeMA(source=px, length=fastLen, maType=fastType)
timeseries slowMA = computeMA(source=px, length=slowLen, maType=slowType)

// Guard against division by zero on slowMA
timeseries spreadRaw = fastMA - slowMA
timeseries spreadPct = slowMA != 0 ? (spreadRaw / slowMA) * 100 : 0

// ---------------------------------------------------------------------------
// 4. Z-SCORE NORMALIZATION
// ---------------------------------------------------------------------------
// Rolling mean and standard deviation of the raw spread
timeseries spreadMean = sma(source=spreadRaw, period=zScoreLookback)
timeseries spreadStd = stddev(source=spreadRaw, period=zScoreLookback)

// Z-score: (spread − mean) / stddev, guarded for zero stddev
timeseries spreadZ = useZScore && spreadStd > 0 ? (spreadRaw - spreadMean) / spreadStd : spreadRaw

// ---------------------------------------------------------------------------
// 5. SMOOTHING & SIGNAL
// ---------------------------------------------------------------------------
// Signal line: EMA of the spread (or z-score)
timeseries signalLine = ema(source=spreadZ, period=smoothLen)

// Momentum: rate of change of spread
timeseries momentum = spreadZ - spreadZ[momentumLen]

// Momentum histogram (spread minus signal)
timeseries hist = spreadZ - signalLine

// ---------------------------------------------------------------------------
// 6. REGIME DETECTION
// ---------------------------------------------------------------------------
// ADX-based trend strength using +DI / −DI logic
// Per Wilder (1978): +DM = max(high − high[1], 0) if high − high[1] > low[1] − low
//                       −DM = max(low[1] − low, 0) if low[1] − low > high − high[1]
// Per the simplified ADX proxy: use spread direction and magnitude.
// We use a proxy regime: trending when |spreadZ| > 1, mean-reverting when
// |spreadZ| < 0.5, neutral otherwise. This is a heuristic; an ADX computation
// can be substituted for full rigor.

var adxProxy = 0.0
if (useRegime) {
    // True range for ADX proxy
    timeseries prevClose = isnan(bars.close[1]) ? bars.close : bars.close[1]
    timeseries tr1 = bars.high - bars.low
    timeseries tr2 = math.abs(bars.high - prevClose)
    timeseries tr3 = math.abs(bars.low - prevClose)
    timeseries tr = math.max(tr1, math.max(tr2, tr3))
    timeseries atr = sma(source=tr, period=regimeLen)

    // ADX proxy: normalized spread volatility relative to ATR
    adxProxy = atr > 0 ? math.abs(spreadRaw) / atr : 0
}

var regimeTrending = useRegime && adxProxy > 1.5
var regimeMeanRev = useRegime && math.abs(spreadZ) < compressionThreshold
var regimeNeutral = !regimeTrending && !regimeMeanRev

var regimeColor = regimeTrending ? (spreadZ > 0 ? bullColor : bearColor) : (regimeMeanRev ? compressionColor : neutralColor)
var regimeLabel = regimeTrending ? "TRENDING" : (regimeMeanRev ? "MEAN-REVERTING" : "NEUTRAL")

// ---------------------------------------------------------------------------
// 7. ALERT CONDITIONS & SHAPE MARKERS
// ---------------------------------------------------------------------------
// Zero-line cross
var crossUp = spreadZ > 0 && spreadZ[1] <= 0
var crossDown = spreadZ < 0 && spreadZ[1] >= 0

// Signal line cross
var sigCrossUp = spreadZ > signalLine && spreadZ[1] <= signalLine[1]
var sigCrossDown = spreadZ < signalLine && spreadZ[1] >= signalLine[1]

// Expansion / compression events
var expansionUp = spreadZ > expansionThreshold && spreadZ[1] <= expansionThreshold
var expansionDown = spreadZ < -expansionThreshold && spreadZ[1] >= -expansionThreshold
var compression = math.abs(spreadZ) < compressionThreshold && math.abs(spreadZ[1]) >= compressionThreshold

// Divergence proxy: price makes higher high but spreadZ makes lower high
// (or vice versa). Uses highest/lowest over lookback.
var divLookback = 10
var pxHigh = highest(source=bars.high, period=divLookback)
var pxLow = lowest(source=bars.low, period=divLookback)
var spreadZHigh = highest(source=spreadZ, period=divLookback)
var spreadZLow = lowest(source=spreadZ, period=divLookback)

var bearDiv = bars.high[0] == pxHigh && spreadZ[0] < spreadZHigh
var bullDiv = bars.low[0] == pxLow && spreadZ[0] > spreadZLow

// ---------------------------------------------------------------------------
// 8. STATIC STATE TRACKING
// ---------------------------------------------------------------------------
// Track last regime change bar and duration for context.
static lastRegimeBar = 0
static lastRegime = 0  // 1 = bull, -1 = bear, 0 = neutral
static regimeDuration = 0

if (!isLiveUpdate) {
    var currentRegime = spreadZ > 0 ? 1 : -1
    if (currentRegime != lastRegime) {
        lastRegimeBar = barCount
        lastRegime = currentRegime
        regimeDuration = 0
    } else {
        regimeDuration = regimeDuration + 1
    }
}

// ---------------------------------------------------------------------------
// 9. PLOTTING
// ---------------------------------------------------------------------------

// --- Zero line ---
hline(value=0, color="#ffffff20", width=1)

// --- Expansion / Compression thresholds ---
if (useZScore) {
    hline(value=expansionThreshold, color=transparency(expansionColor, 60), width=1)
    hline(value=-expansionThreshold, color=transparency(expansionColor, 60), width=1)
    hline(value=compressionThreshold, color=transparency(compressionColor, 40), width=1)
    hline(value=-compressionThreshold, color=transparency(compressionColor, 40), width=1)
}

// --- Raw Spread Ribbon Fill (fast vs slow) ---
if (showRibbon) {
    var ribbonBull = spreadRaw > 0
    plotLine(
        value=[spreadRaw, 0],
        width=1,
        colors=[transparency(bullColor, 30), transparency(bearColor, 30)],
        colorIndex=ribbonBull ? 0 : 1,
        fill=true,
        label=["Spread Upper", "Spread Zero"],
        desc=["Fast/slow MA spread above zero", "Zero baseline for spread"]
    )
}

// --- Raw Spread Histogram ---
if (showRawSpread) {
    var spreadBull = spreadRaw > 0
    plotBar(
        value=spreadRaw,
        colors=[transparency(bullColor, 60), transparency(bearColor, 60)],
        colorIndex=spreadBull ? 0 : 1,
        width=1,
        label=["MA Spread"],
        desc=["Raw fast/slow MA spread (" + fastType + " " + fastLen + " vs " + slowType + " " + slowLen + ")"]
    )
}

// --- Z-Score Line (regime-colored) ---
if (showZScore) {
    plotLine(
        value=spreadZ,
        width=2,
        colors=[regimeColor],
        label=["Z-Score Spread"],
        desc=["Z-score normalized MA spread (rolling " + zScoreLookback + ")"]
    )
}

// --- Signal Line ---
if (showSignal) {
    plotLine(
        value=signalLine,
        width=1,
        colors=[signalColor],
        label=["Signal EMA"],
        desc=["EMA-smoothed spread signal (" + smoothLen + ")"]
    )
}

// --- Signal Fill (z-score vs signal) ---
if (showSignal && showZScore) {
    var sigFillBull = spreadZ > signalLine
    plotLine(
        value=[spreadZ, signalLine],
        width=1,
        colors=[transparency(bullColor, 20), transparency(bearColor, 20)],
        colorIndex=sigFillBull ? 0 : 1,
        fill=true,
        label=["Z-Score", "Signal"],
        desc=["Fill between Z-score spread and signal EMA"]
    )
}

// --- Momentum Histogram ---
if (showMomentum) {
    var momBull = hist >= 0
    plotBar(
        value=hist,
        colors=[transparency(bullColor, 60), transparency(bearColor, 60)],
        colorIndex=momBull ? 0 : 1,
        width=1,
        label=["Momentum"],
        desc=["Momentum histogram: spread Z-score minus signal EMA"]
    )
}

// --- Shape Markers ---
if (showShapes) {
    // Zero cross
    if (crossUp) {
        plotShape(
            value=spreadZ,
            shape="triangleup",
            colorIndex=bullColor,
            width=2,
            label=["Zero Cross Up"],
            desc=["Spread crossed above zero: fast MA above slow MA"]
        )
    }
    if (crossDown) {
        plotShape(
            value=spreadZ,
            shape="triangledown",
            colorIndex=bearColor,
            width=2,
            label=["Zero Cross Down"],
            desc=["Spread crossed below zero: fast MA below slow MA"]
        )
    }

    // Signal cross
    if (sigCrossUp) {
        plotShape(
            value=signalLine,
            shape="circle",
            colorIndex=bullColor,
            width=2,
            label=["Sig Cross Up"],
            desc=["Z-score spread crossed above signal EMA"]
        )
    }
    if (sigCrossDown) {
        plotShape(
            value=signalLine,
            shape="circle",
            colorIndex=bearColor,
            width=2,
            label=["Sig Cross Down"],
            desc=["Z-score spread crossed below signal EMA"]
        )
    }

    // Expansion
    if (expansionUp) {
        plotShape(
            value=spreadZ,
            shape="arrowup",
            colorIndex=expansionColor,
            width=2,
            label=["Expansion Up"],
            desc=["Spread expanded above +" + expansionThreshold + " z-score threshold"]
        )
    }
    if (expansionDown) {
        plotShape(
            value=spreadZ,
            shape="arrowdown",
            colorIndex=expansionColor,
            width=2,
            label=["Expansion Down"],
            desc=["Spread expanded below -" + expansionThreshold + " z-score threshold"]
        )
    }

    // Compression
    if (compression) {
        plotShape(
            value=spreadZ,
            shape="diamond",
            colorIndex=compressionColor,
            width=2,
            label=["Compression"],
            desc=["Spread compressed into mean-reversion zone (< " + compressionThreshold + " z-score)"]
        )
    }

    // Divergence
    if (bullDiv) {
        plotShape(
            value=spreadZ,
            shape="triangleup",
            colorIndex=transparency(bullColor, 80),
            width=1,
            label=["Bull Div"],
            desc=["Bullish divergence: price lower low, spread higher low"]
        )
    }
    if (bearDiv) {
        plotShape(
            value=spreadZ,
            shape="triangledown",
            colorIndex=transparency(bearColor, 80),
            width=1,
            label=["Bear Div"],
            desc=["Bearish divergence: price higher high, spread lower high"]
        )
    }
}

// ---------------------------------------------------------------------------
// 10. REGIME TABLE (last bar only)
// ---------------------------------------------------------------------------
if (showTable && isLastBar) {
    var regimeTextColor = spreadZ > 0 ? bullColor : bearColor
    var durationText = regimeDuration > 0 ? regimeDuration + " bars" : "just changed"

    plotTable(
        data=[
            ["MA Spread — Perfected", regimeLabel],
            ["Fast MA", fastType + "(" + fastLen + ") = " + fastMA[0]],
            ["Slow MA", slowType + "(" + slowLen + ") = " + slowMA[0]],
            ["Raw Spread", spreadRaw[0]],
            ["Z-Score", spreadZ[0]],
            ["Signal", signalLine[0]],
            ["Momentum", hist[0]],
            ["Spread %", spreadPct[0] + "%"],
            ["Regime Duration", durationText]
        ],
        position="top_right",
        headerRow=true,
        headerColumn=true,
        textColor="#e2e8f0",
        headerTextColor="#ffffff",
        backgroundColor=transparency("#0f172a", 40),
        headerBackgroundColor=transparency("#1e293b", 40),
        borderColor=transparency("#334155", 40),
        borderWidth=1,
        fontSize=10,
        cellPadding=4
    )
}