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.
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
//@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"]
)
}
}