MM Flow
FlowScripts

Perfected FlowScript

Liquidity Gradient / Topography Oscillator

Liquidity Gradient Topography V2 is indexed as 248_liquidity_gradient_topography_oscillator.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

14.0 KB

Lines

313

Native Signal Candidates

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

4/4 guarded

Aggressive

line 273:9

Trigger

(showShapes) && (extremeAggressive)

Value

gradient

Deps

extremeAggressive:var, showShapes:input

Defensive

line 283:9

Trigger

(showShapes) && (extremeDefensive)

Value

gradient

Deps

extremeDefensive:var, showShapes:input

Cross Up

line 293:9

Trigger

(showShapes) && (crossZeroUp)

Value

gradient

Deps

crossZeroUp:var, showShapes:input

Cross Down

line 303:9

Trigger

(showShapes) && (crossZeroDown)

Value

gradient

Deps

crossZeroDown:var, showShapes:input

248_liquidity_gradient_topography_oscillator.flowscript

source path: kscripts/perfected/248_liquidity_gradient_topography_oscillator.flowscript · sha256:54a3486bf918d91c307eea65adfb6cf4e2231b94fcaf29eb3a5d7b9572fc8c47

hash verified
//@version=2
// ============================================================================
// Liquidity Gradient Topography Oscillator V2 — Production-Quality
// Author: D (@ddave334)  |  Perfected by: kScript Perfection Engineer
// Tags: FLOW, #liquidity, #gradient, #orderbook, #topography, #zscore
//
// Measures the slope of liquidity distribution across orderbook depth levels,
// producing bid/ask gradients, a composite topography score, and z-score
// normalization for statistically unusual conditions. Negative values indicate
// defensive positioning (liquidity far from spread); positive values show
// aggressive positioning (liquidity concentrated near spread).
//
// FORMULA FOUNDATION:
// 1. Bid Gradient: slope of bid depth from L1 to Lmax (log-linear fit proxy)
//    per Xu, Gould & Howison (2019) — multi-level OFI with spatial decay.
// 2. Ask Gradient: slope of ask depth from L1 to Lmax (same method)
//    per Paddrik et al. (2014) — OBWA using L1-L10 weighted average spread.
// 3. Composite Topography: (bidGradient + askGradient) / 2, normalized
// 4. Z-Score: (gradient − mean) / σ over rolling lookback
//    per Kizilersü et al. (2016) — universal Weibull shape, maximum entropy.
// 5. Regime: aggressive (>0.5σ), defensive (<−0.5σ), neutral otherwise
//
// RESEARCH BASIS:
//  • Xu, Gould & Howison (2019), "Multi-Level Order-Flow Imbalance in a Limit
//    Order Book", arXiv:1907.06230. Multi-level OFI with decaying weights;
//    deeper levels contain meaningful predictive information.
//  • Paddrik et al. (2014), "Effects of Limit Order Book Information Level on
//    Market Stability Metrics", OFR WP 2014-09. OBWA = weighted average spread
//    using L1-L10; deeper book information improves stability assessment.
//  • Kizilersü et al. (2016), "Universal Behaviour in the Stock Market: Time
//    Dynamics of the Electronic Orderbook", Phys. Lett. A 380, 2207–2212.
//    Orderbook changes follow left-truncated Weibull with universal shape;
//    deviations from expected behavior signal unusual conditions.
//  • Cont, Kukanov & Stoikov (2014), "The Price Impact of Order Book Events",
//    J. Financial Econometrics 12(1), 47–88. Price impact slope ∝ 1/depth.
//  • Bouchaud, Farmer & Lillo (2009), "How Markets Slowly Digest Changes in
//    Supply and Demand", Handbook of Financial Markets. Liquidity memory time
//    explains why gradient shifts predict future volatility regimes.
// ============================================================================

define(
    title="Liquidity Gradient Topography V2",
    position="offchart",
    axis=true
)

// ---------------------------------------------------------------------------
// User Inputs — grouped and constrained per production spec
// ---------------------------------------------------------------------------

// --- Depth Configuration ---
var depthLevels = input(name="depthLevels", type="number", defaultValue=10, label="Number of Depth Levels", constraints={min: 3, max: 50, step: 1}, group="Depth")
var nearDepth1 = input(name="nearDepth1", type="number", defaultValue=1.0, label="Near Depth 1 (%)", constraints={min: 0.1, max: 10.0, step: 0.1}, group="Depth")
var nearDepth2 = input(name="nearDepth2", type="number", defaultValue=2.5, label="Near Depth 2 (%)", constraints={min: 0.1, max: 20.0, step: 0.1}, group="Depth")
var farDepth1 = input(name="farDepth1", type="number", defaultValue=5.0, label="Far Depth 1 (%)", constraints={min: 1.0, max: 50.0, step: 0.1}, group="Depth")
var farDepth2 = input(name="farDepth2", type="number", defaultValue=10.0, label="Far Depth 2 (%)", constraints={min: 1.0, max: 50.0, step: 0.1}, group="Depth")

// --- Z-Score & Smoothing ---
var zLookback = input(name="zLookback", type="number", defaultValue=50, label="Z-Score Lookback", constraints={min: 10, max: 200, step: 5}, group="Z-Score")
var smoothLen = input(name="smoothLen", type="number", defaultValue=5, label="EMA Smoothing Length", constraints={min: 1, max: 50, step: 1}, group="Z-Score")
var useZScore = input(name="useZScore", type="boolean", defaultValue=true, label="Show Z-Score Line", group="Z-Score")

// --- Thresholds ---
var aggressiveThresh = input(name="aggressiveThresh", type="number", defaultValue=0.5, label="Aggressive Threshold (σ)", constraints={min: 0.1, max: 3.0, step: 0.1}, group="Thresholds")
var defensiveThresh = input(name="defensiveThresh", type="number", defaultValue=-0.5, label="Defensive Threshold (σ)", constraints={min: -3.0, max: -0.1, step: 0.1}, group="Thresholds")

// --- Display ---
var showGradient = input(name="showGradient", type="boolean", defaultValue=true, label="Show Gradient Line", group="Display")
var showHistogram = input(name="showHistogram", type="boolean", defaultValue=true, label="Show Histogram", group="Display")
var showBidAsk = input(name="showBidAsk", type="boolean", defaultValue=false, label="Show Separate Bid/Ask Gradients", group="Display")
var showShapes = input(name="showShapes", type="boolean", defaultValue=true, label="Show Extreme Shapes", group="Display")
var showGuides = input(name="showGuides", type="boolean", defaultValue=true, label="Show Guide Lines", group="Display")

// --- Colors ---
var aggressiveColor = input(name="aggressiveColor", type="color", defaultValue="#26a69a", label="Aggressive Color", group="Colors")
var defensiveColor = input(name="defensiveColor", type="color", defaultValue="#ef5350", label="Defensive Color", group="Colors")
var neutralColor = input(name="neutralColor", type="color", defaultValue="#9e9e9e", label="Neutral Color", group="Colors")
var bidColor = input(name="bidColor", type="color", defaultValue="#42a5f5", label="Bid Gradient Color", group="Colors")
var askColor = input(name="askColor", type="color", defaultValue="#ab47bc", label="Ask Gradient Color", group="Colors")
var zScoreColor = input(name="zScoreColor", type="color", defaultValue="#ffa726", label="Z-Score Color", group="Colors")

// ---------------------------------------------------------------------------
// Data Sources
// ---------------------------------------------------------------------------
timeseries priceBars = ohlcv(symbol=currentSymbol, exchange=currentExchange)
timeseries px = priceBars.close
timeseries book = source("orderbook", currentSymbol, currentExchange)

// NaN guard — prevent execution before data is loaded
if (isnan(px[0])) {
    return
}

// ---------------------------------------------------------------------------
// Depth Aggregation at Multiple Levels (Xu, Gould & Howison 2019)
// ---------------------------------------------------------------------------
// Aggregate liquidity at near and far depths to measure gradient slope.
// Near = aggressive positioning (close to spread); Far = defensive positioning.

var nearBids1 = sumBids(book, nearDepth1)
var nearAsks1 = sumAsks(book, nearDepth1)
var nearBids2 = sumBids(book, nearDepth2)
var nearAsks2 = sumAsks(book, nearDepth2)
var farBids1 = sumBids(book, farDepth1)
var farAsks1 = sumAsks(book, farDepth1)
var farBids2 = sumBids(book, farDepth2)
var farAsks2 = sumAsks(book, farDepth2)

var bookAvailable = nearBids1 > 0 && nearAsks1 > 0 && farBids1 > 0 && farAsks1 > 0 && farBids2 > 0 && farAsks2 > 0

// ---------------------------------------------------------------------------
// Gradient Computation (Paddrik et al. 2014 OBWA extension)
// ---------------------------------------------------------------------------
// Gradient = (nearDepth − farDepth) / (nearDepth + farDepth)
// Positive = liquidity concentrated near spread (aggressive)
// Negative = liquidity concentrated far from spread (defensive)

var nearBidTotal = nearBids1 + nearBids2
var farBidTotal = farBids1 + farBids2
var nearAskTotal = nearAsks1 + nearAsks2
var farAskTotal = farAsks1 + farAsks2

var bidDenom = nearBidTotal + farBidTotal
var askDenom = nearAskTotal + farAskTotal

var bidGradient = bookAvailable && bidDenom > 0 ? (nearBidTotal - farBidTotal) / bidDenom : 0.0
var askGradient = bookAvailable && askDenom > 0 ? (nearAskTotal - farAskTotal) / askDenom : 0.0

// Composite topography: average of bid and ask gradients
timeseries rawGradient = bookAvailable ? (bidGradient + askGradient) / 2.0 : 0.0

// EMA smoothing for noise reduction
timeseries gradient = ema(rawGradient, smoothLen)

// ---------------------------------------------------------------------------
// Z-Score Normalization (Kizilersü et al. 2016 universal behavior)
// ---------------------------------------------------------------------------
// Tests whether current liquidity distribution deviates from expected
// historical behavior — flagging statistically unusual conditions.

timeseries gradMean = sma(source=gradient, period=zLookback)
timeseries gradStd = stddev(source=gradient, period=zLookback)
timeseries zScore = gradStd > 0 ? (gradient - gradMean) / gradStd : 0.0

// ---------------------------------------------------------------------------
// Regime Detection (aggressive / neutral / defensive)
// ---------------------------------------------------------------------------
// Based on z-score thresholds: aggressive = liquidity near spread,
// defensive = liquidity far from spread, neutral = balanced.

var regime = 0  // 0 = neutral, 1 = aggressive, -1 = defensive

if (zScore >= aggressiveThresh) {
    regime = 1
} else if (zScore <= defensiveThresh) {
    regime = -1
}

// ---------------------------------------------------------------------------
// Static State Tracking (session-level persistence)
// ---------------------------------------------------------------------------
// Tracks gradient extremes, regime transitions, and unusual event counts.

static lastRegime = 0
static regimeChangeCount = 0
static sessionHighGradient = -999999.0
static sessionLowGradient = 999999.0
static extremeAggressiveCount = 0
static extremeDefensiveCount = 0
static lastBarIndex = 0

var currentBarIndex = bar_index[0]

if (!isnan(currentBarIndex) && currentBarIndex != lastBarIndex) {
    lastBarIndex = currentBarIndex

    if (gradient > sessionHighGradient) {
        sessionHighGradient = gradient
    }
    if (gradient < sessionLowGradient) {
        sessionLowGradient = gradient
    }

    if (lastRegime != regime) {
        lastRegime = regime
        regimeChangeCount = regimeChangeCount + 1
    }

    if (regime == 1) {
        extremeAggressiveCount = extremeAggressiveCount + 1
    } else if (regime == -1) {
        extremeDefensiveCount = extremeDefensiveCount + 1
    }
}

// ---------------------------------------------------------------------------
// Plots — Multiple Visualization Types (Line, Bar, Shape, Fill, HLine)
// ---------------------------------------------------------------------------

// Horizontal guide lines
hline(value=0, color="#ffffff30", width=1)

if (showGuides) {
    hline(value=aggressiveThresh, color=opacity(aggressiveColor, 30), width=1)
    hline(value=defensiveThresh, color=opacity(defensiveColor, 30), width=1)
}

// Color mapping for gradient line
var gradientColorIdx = gradient > 0 ? 0 : (gradient < 0 ? 2 : 1)

// Gradient histogram (regime-colored bars)
if (showHistogram) {
    plotBar(
        value=gradient,
        colors=[aggressiveColor, neutralColor, defensiveColor],
        colorIndex=gradientColorIdx,
        width=1,
        label=["Liquidity Gradient"],
        desc=["Topography gradient: positive = aggressive (near spread), negative = defensive (far from spread)"]
    )
}

// Smoothed gradient line with fill
if (showGradient) {
    plotLine(
        value=gradient,
        width=2,
        colors=[aggressiveColor, neutralColor, defensiveColor],
        colorIndex=gradientColorIdx,
        label=["Gradient"],
        desc=["Smoothed liquidity gradient topography. Color: aggressive/neutral/defensive."],
        fill=true
    )
}

// Z-Score line (secondary diagnostic)
if (useZScore) {
    plotLine(
        value=zScore,
        width=1,
        colors=[zScoreColor],
        label=["Z-Score"],
        desc=["Statistical unusualness: deviations from expected liquidity distribution (Kizilersü et al. 2016)"]
    )
}

// Separate bid/ask gradients (optional, for granular analysis)
if (showBidAsk) {
    plotLine(
        value=bidGradient,
        width=1,
        colors=[bidColor],
        label=["Bid Gradient"],
        desc=["Bid-side liquidity gradient: positive = bids near spread (supportive)"]
    )
    plotLine(
        value=askGradient,
        width=1,
        colors=[askColor],
        label=["Ask Gradient"],
        desc=["Ask-side liquidity gradient: positive = asks near spread (resistive)"]
    )
}

// Extreme event shapes — statistically unusual conditions
if (showShapes) {
    var extremeAggressive = zScore >= aggressiveThresh && !isnan(zScore[1]) && zScore[1] < aggressiveThresh
    var extremeDefensive = zScore <= defensiveThresh && !isnan(zScore[1]) && zScore[1] > defensiveThresh
    var crossZeroUp = gradient >= 0 && !isnan(gradient[1]) && gradient[1] < 0
    var crossZeroDown = gradient <= 0 && !isnan(gradient[1]) && gradient[1] > 0

    if (extremeAggressive) {
        plotShape(
            value=gradient,
            shape="triangleup",
            color=aggressiveColor,
            width=3,
            label=["Aggressive"],
            desc=["Liquidity concentrated near spread — aggressive positioning detected"]
        )
    }
    if (extremeDefensive) {
        plotShape(
            value=gradient,
            shape="triangledown",
            color=defensiveColor,
            width=3,
            label=["Defensive"],
            desc=["Liquidity concentrated far from spread — defensive positioning detected"]
        )
    }
    if (crossZeroUp) {
        plotShape(
            value=gradient,
            shape="circle",
            color=aggressiveColor,
            width=2,
            label=["Cross Up"],
            desc=["Gradient crossed above zero — shifting to aggressive liquidity posture"]
        )
    }
    if (crossZeroDown) {
        plotShape(
            value=gradient,
            shape="circle",
            color=defensiveColor,
            width=2,
            label=["Cross Down"],
            desc=["Gradient crossed below zero — shifting to defensive liquidity posture"]
        )
    }
}