MM Flow
FlowScripts

Perfected FlowScript

Orderbook Pressure Gradient

Orderbook Pressure Gradient V2 is indexed as 159_orderbook_pressure_gradient.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

22.9 KB

Lines

512

Native Signal Candidates

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

8/8 guarded

Bull Regime

line 398:9

Trigger

(showShapes) && (crossUp)

Value

smoothedComposite

Deps

crossUp:var, showShapes:input

Bear Regime

line 408:9

Trigger

(showShapes) && (crossDn)

Value

smoothedComposite

Deps

crossDn:var, showShapes:input

Extreme Bid

line 418:9

Trigger

(showShapes) && (extremeUp)

Value

smoothedComposite

Deps

extremeUp:var, showShapes:input

Extreme Ask

line 428:9

Trigger

(showShapes) && (extremeDn)

Value

smoothedComposite

Deps

extremeDn:var, showShapes:input

Grad Bull

line 438:9

Trigger

(showShapes) && (gradAccelUp)

Value

gradSmoothed

Deps

gradAccelUp:var, showShapes:input

Grad Bear

line 448:9

Trigger

(showShapes) && (gradAccelDn)

Value

gradSmoothed

Deps

gradAccelDn:var, showShapes:input

Z+ Extreme

line 458:9

Trigger

(showShapes) && (zExtremeUp)

Value

gradZ

Deps

showShapes:input, zExtremeUp:var

Z- Extreme

line 468:9

Trigger

(showShapes) && (zExtremeDn)

Value

gradZ

Deps

showShapes:input, zExtremeDn:var

159_orderbook_pressure_gradient.flowscript

source path: kscripts/perfected/159_orderbook_pressure_gradient.flowscript · sha256:6271912fbef4d9f2ae93181411c29c7dc4e6eeb57e647c0c8b466fb5bec80438

hash verified
//@version=2
// ============================================================================
// Orderbook Pressure Gradient V2 — Production-Quality Orderbook Microstructure
// Author: D (@ddave334)  |  Perfected by: kScript Perfection Engineer
// Tags: FLOW, #orderbook, #liquidity, #microstructure, #OBI, #gradient, #zscore
//
// Order Book Imbalance (OBI) gradient with rate-of-change, z-score normalization,
// regime detection, and multi-depth composite. Academic microstructure foundations.
//
// FORMULA FOUNDATION:
// 1. Order Book Imbalance (OBI): OBI = (BidVol − AskVol) / (BidVol + AskVol) ∈ [−1, +1]
//    per Cont, Kukanov & Stoikov (2014).
// 2. OBI Gradient: ∇OBI = OBI[t] − OBI[t−1]  — first-difference rate of change.
// 3. Z-Score Normalization: z = (∇OBI − μ) / σ  over rolling lookback window,
//    per Zhao & Palomar (2018) mean-reversion threshold framework.
// 4. Depth-Weighted Composite OBI: Σ w_i × OBI_i / Σ w_i  where w_i = decay^(i−1)
//    per Xu, Gould & Howison (2019) multi-level OFI with decaying weights.
// 5. Regime Segmentation: Sell-heavy (−1, −1/3), Neutral (−1/3, +1/3),
//    Buy-heavy (+1/3, +1) per Cartea, Donnelly & Jaimungal (2018).
// 6. Linear Price-Impact Model: ΔP ≈ OFI / Depth  per Cont, Kukanov & Stoikov (2014).
//
// RESEARCH BASIS:
//  • Cont, Kukanov & Stoikov (2014), "The Price Impact of Order Book Events",
//    J. Financial Econometrics 12(1), 47–88. OFI = Σ(E_i × ΔP_i); slope ∝ 1/depth.
//  • Xu, Gould & Howison (2019), "Multi-Level Order-Flow Imbalance in a Limit
//    Order Book", arXiv:1907.06230. Multi-level OFI with decaying weights.
//  • Zhao & Palomar (2018), "Mean-Reverting Portfolio With Budget Constraint".
//    Z-score normalization: z̄ = (z − μ) / σ; entry thresholds at ±1σ, ±2σ.
//  • Cartea, Donnelly & Jaimungal (2018), "Enhancing Trading Strategies with
//    Order Book Signals", Appl. Math. Finance 25(1), 1–35. Three-regime
//    segmentation: Sell-heavy (−1,−1/3), Neutral (−1/3,1/3), Buy-heavy (1/3,1).
//  • Gould & Bonart (2016), "Queue Imbalance as a One-Tick-Ahead Price
//    Predictor", Market Microstructure & Liquidity 2(1), 1650006. Queue
//    imbalance logistic regression for next-tick direction prediction.
//  • Order Book Filtration and Directional Signal Extraction (2025). OBI as
//    bounded regime indicator; |OBI| → 1 flags directional extremes.
// ============================================================================

define(
    title="Orderbook Pressure Gradient V2",
    position="offchart",
    axis=true
)

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

// --- Depth Configuration ---
var depth1 = input(name="depth1", type="number", defaultValue=1.0, label="Depth Band 1 (%)", constraints={min: 0.1, max: 50.0, step: 0.1}, group="Depth")
var depth2 = input(name="depth2", type="number", defaultValue=2.5, label="Depth Band 2 (%)", constraints={min: 0.1, max: 50.0, step: 0.1}, group="Depth")
var depth3 = input(name="depth3", type="number", defaultValue=5.0, label="Depth Band 3 (%)", constraints={min: 0.1, max: 50.0, step: 0.1}, group="Depth")
var depth4 = input(name="depth4", type="number", defaultValue=10.0, label="Depth Band 4 (%)", constraints={min: 0.1, max: 50.0, step: 0.1}, group="Depth")

var useDepthWeighting = input(name="useDepthWeighting", type="boolean", defaultValue=true, label="Use Depth-Decaying Weights", group="Depth")
var weightDecay = input(name="weightDecay", type="number", defaultValue=0.75, label="Weight Decay Factor", constraints={min: 0.0, max: 1.0, step: 0.05}, group="Depth")

// --- Smoothing ---
var smoothLen = input(name="smoothLen", type="number", defaultValue=5, label="EMA Smoothing Length", constraints={min: 1, max: 50, step: 1}, group="Smoothing")
var smoothComposite = input(name="smoothComposite", type="boolean", defaultValue=true, label="Smooth Composite OBI", group="Smoothing")

// --- Gradient & Z-Score ---
var gradLen = input(name="gradLen", type="number", defaultValue=1, label="Gradient Length (bars)", constraints={min: 1, max: 10, step: 1}, group="Gradient")
var zLookback = input(name="zLookback", type="number", defaultValue=20, label="Z-Score Lookback", constraints={min: 5, max: 100, step: 1}, group="Gradient")
var useZScore = input(name="useZScore", type="boolean", defaultValue=true, label="Z-Score Normalize Gradient", group="Gradient")

// --- Thresholds & Regime ---
var bullThresh = input(name="bullThresh", type="number", defaultValue=33.0, label="Bullish Regime Threshold (%)", constraints={min: 10.0, max: 90.0, step: 1.0}, group="Thresholds")
var bearThresh = input(name="bearThresh", type="number", defaultValue=-33.0, label="Bearish Regime Threshold (%)", constraints={min: -90.0, max: -10.0, step: 1.0}, group="Thresholds")
var extremeThresh = input(name="extremeThresh", type="number", defaultValue=66.0, label="Extreme Imbalance Threshold (%)", constraints={min: 50.0, max: 95.0, step: 1.0}, group="Thresholds")

// --- Display ---
var showGuides = input(name="showGuides", type="boolean", defaultValue=true, label="Show Guide Lines", group="Display")
var showRawBars = input(name="showRawBars", type="boolean", defaultValue=true, label="Show Raw OBI Histogram", group="Display")
var showShapes = input(name="showShapes", type="boolean", defaultValue=true, label="Show Regime Shapes", group="Display")
var showComposite = input(name="showComposite", type="boolean", defaultValue=true, label="Show Composite Line", group="Display")
var showGradient = input(name="showGradient", type="boolean", defaultValue=true, label="Show OBI Gradient", group="Display")
var showZScore = input(name="showZScore", type="boolean", defaultValue=true, label="Show Z-Score Line", group="Display")
var showIndividual = input(name="showIndividual", type="boolean", defaultValue=false, label="Show Individual Depth Lines", group="Display")
var showBidAskRatio = input(name="showBidAskRatio", type="boolean", defaultValue=false, label="Show Bid/Ask Ratio (1% depth)", group="Display")

// --- Colors ---
var bidColor = input(name="bidColor", type="color", defaultValue="#26a69a", label="Bid-Dominant Color", group="Colors")
var askColor = input(name="askColor", type="color", defaultValue="#ef5350", label="Ask-Dominant Color", group="Colors")
var neutralColor = input(name="neutralColor", type="color", defaultValue="#9e9e9e", label="Neutral Color", group="Colors")
var extremeBidColor = input(name="extremeBidColor", type="color", defaultValue="#00e676", label="Extreme Bid Color", group="Colors")
var extremeAskColor = input(name="extremeAskColor", type="color", defaultValue="#ff1744", label="Extreme Ask Color", group="Colors")
var gradColor = input(name="gradColor", type="color", defaultValue="#ffa726", label="Gradient Color", group="Colors")
var zPosColor = input(name="zPosColor", type="color", defaultValue="#29b6f6", label="Z-Score Positive Color", group="Colors")
var zNegColor = input(name="zNegColor", type="color", defaultValue="#ab47bc", label="Z-Score Negative 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 (Cont et al. 2014 data-integrity best practice)
if (isnan(px[0])) {
    return
}

// ------------------------------------------------------------------------------
// Order Book Aggregation
// ------------------------------------------------------------------------------
// CRITICAL: kScript API accepts depth as a float percentage (e.g., 1.0 = 1%, 2.5 = 2.5%).
// Do NOT use math.floor() or math.round() — these would truncate precision.
// Research basis: Cont, Kukanov & Stoikov (2014) showed price impact slope
// is inversely proportional to depth; deeper books absorb imbalance with
// smaller price moves. The multi-depth bands (1%, 2.5%, 5%, 10%) directly
// operationalize this finding.

var bids1 = sumBids(book, depth1)
var asks1 = sumAsks(book, depth1)
var bids2 = sumBids(book, depth2)
var asks2 = sumAsks(book, depth2)
var bids3 = sumBids(book, depth3)
var asks3 = sumAsks(book, depth3)
var bids4 = sumBids(book, depth4)
var asks4 = sumAsks(book, depth4)

// Book availability check — prevents NaN/undefined propagation (Gould & Bonart 2016 robustness)
var bookAvailable = bids1 > 0 && asks1 > 0 && bids2 > 0 && asks2 > 0 && bids3 > 0 && asks3 > 0 && bids4 > 0 && asks4 > 0

// ------------------------------------------------------------------------------
// OBI Computation with Zero-Division Guards
// ------------------------------------------------------------------------------
// OBI = (Bid − Ask) / (Bid + Ask)  ∈ [−1, +1]
// Formula from Order Book Filtration and Directional Signal Extraction (2025)
// and Korean Derivatives Association (2015).

var denom1 = bids1 + asks1
var denom2 = bids2 + asks2
var denom3 = bids3 + asks3
var denom4 = bids4 + asks4

var obi1 = bookAvailable && denom1 > 0 ? (bids1 - asks1) / denom1 * 100.0 : 0.0
var obi2 = bookAvailable && denom2 > 0 ? (bids2 - asks2) / denom2 * 100.0 : 0.0
var obi3 = bookAvailable && denom3 > 0 ? (bids3 - asks3) / denom3 * 100.0 : 0.0
var obi4 = bookAvailable && denom4 > 0 ? (bids4 - asks4) / denom4 * 100.0 : 0.0

// Bid/Ask ratio for 1% depth (additional diagnostic per Gould & Bonart 2016)
var ratio1 = bookAvailable && asks1 > 0 ? bids1 / asks1 : 1.0

// ------------------------------------------------------------------------------
// Depth-Weighted Composite OBI (Xu, Gould & Howison 2019)
// ------------------------------------------------------------------------------
// Multi-level OFI with geometrically decaying weights.
// w_i = decay^(i−1) for i = 1,2,3,4.
// Composite = Σ w_i × OBI_i / Σ w_i.
// This significantly improves short-horizon prediction vs. top-of-book alone.

var w1 = 1.0
var w2 = useDepthWeighting ? weightDecay : 1.0
var w3 = useDepthWeighting ? weightDecay * weightDecay : 1.0
var w4 = useDepthWeighting ? weightDecay * weightDecay * weightDecay : 1.0

var wSum = w1 + w2 + w3 + w4
var compositeOBI = wSum > 0 ? (w1 * obi1 + w2 * obi2 + w3 * obi3 + w4 * obi4) / wSum : 0.0

// ------------------------------------------------------------------------------
// Smoothing (EMA per Cont et al. 2014 noise-reduction)
// ------------------------------------------------------------------------------
var smoothed1 = ema(obi1, smoothLen)
var smoothed2 = ema(obi2, smoothLen)
var smoothed3 = ema(obi3, smoothLen)
var smoothed4 = ema(obi4, smoothLen)
var smoothedComposite = smoothComposite ? ema(compositeOBI, smoothLen) : compositeOBI

// ------------------------------------------------------------------------------
// OBI Gradient — Rate of Change (First Difference)
// ------------------------------------------------------------------------------
// The gradient measures how fast orderbook pressure is shifting.
// Positive gradient = bid pressure accelerating (buyers stacking faster).
// Negative gradient = ask pressure accelerating (sellers stacking faster).
// Per Cont et al. (2014): rapid OFI changes predict near-term price moves.

var obiGradient = smoothedComposite - (!isnan(smoothedComposite[gradLen]) ? smoothedComposite[gradLen] : smoothedComposite)
var gradSmoothed = ema(obiGradient, smoothLen)

// ------------------------------------------------------------------------------
// Z-Score Normalization (Zhao & Palomar 2018)
// ------------------------------------------------------------------------------
// Standardizes the gradient into statistical deviation units.
// z = (gradient − mean) / stddev over rolling lookback.
// |z| > 1 = typical; |z| > 2 = extreme; |z| > 3 = rare.

var gradMean = sma(gradSmoothed, zLookback)
var gradStd = stddev(gradSmoothed, zLookback)
var gradZ = useZScore && gradStd > 0 ? (gradSmoothed - gradMean) / gradStd : gradSmoothed

// ------------------------------------------------------------------------------
// Regime Detection (Cartea, Donnelly & Jaimungal 2018 three-segment model)
// ------------------------------------------------------------------------------
// Segmented into three regimes:
//   Sell-heavy: OBI ≤ bearThresh
//   Neutral:    bearThresh < OBI < bullThresh
//   Buy-heavy:  OBI ≥ bullThresh
// These segments predict future price moves: positive changes preceded by
// buy-heavy books; negative changes by sell-heavy books.

var regime = 0      // 0 = neutral, 1 = bull, -1 = bear
var extremeRegime = 0  // 0 = normal, 1 = extreme bull, -1 = extreme bear

if (smoothedComposite >= bullThresh) {
    regime = 1
} else if (smoothedComposite <= bearThresh) {
    regime = -1
}

if (smoothedComposite >= extremeThresh) {
    extremeRegime = 1
} else if (smoothedComposite <= -extremeThresh) {
    extremeRegime = -1
}

// Gradient regime (acceleration/deceleration)
var gradRegime = gradSmoothed > 0 ? 1 : (gradSmoothed < 0 ? -1 : 0)

// ------------------------------------------------------------------------------
// Static State Tracking (Session-level persistence)
// ------------------------------------------------------------------------------
// Stateful computation for anchoring, session tracking, and counters.
// Tracks regime transitions, session extremes, gradient extremes, and z-score events.

static lastRegime = 0
static regimeChangeCount = 0
static sessionHighOBI = -999999.0
static sessionLowOBI = 999999.0
static sessionHighGrad = -999999.0
static sessionLowGrad = 999999.0
static extremeBidCount = 0
static extremeAskCount = 0
static zScoreExtremeCount = 0
static lastBarIndex = 0

var currentBarIndex = bar_index[0]

if (!isnan(currentBarIndex) && currentBarIndex != lastBarIndex) {
    // New bar — update session tracking
    lastBarIndex = currentBarIndex

    if (compositeOBI > sessionHighOBI) {
        sessionHighOBI = compositeOBI
    }
    if (compositeOBI < sessionLowOBI) {
        sessionLowOBI = compositeOBI
    }
    if (gradSmoothed > sessionHighGrad) {
        sessionHighGrad = gradSmoothed
    }
    if (gradSmoothed < sessionLowGrad) {
        sessionLowGrad = gradSmoothed
    }

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

    if (extremeRegime == 1) {
        extremeBidCount = extremeBidCount + 1
    } else if (extremeRegime == -1) {
        extremeAskCount = extremeAskCount + 1
    }

    if (useZScore && math.abs(gradZ) > 2.0) {
        zScoreExtremeCount = zScoreExtremeCount + 1
    }
}

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

// Horizontal guide lines — zero line and configurable threshold zones
hline(value=0, color="#ffffff30", width=1)

if (showGuides) {
    hline(value=bullThresh, color=opacity(bidColor, 30), width=1)
    hline(value=bearThresh, color=opacity(askColor, 30), width=1)
    hline(value=extremeThresh, color=opacity(extremeBidColor, 20), width=1)
    hline(value=-extremeThresh, color=opacity(extremeAskColor, 20), width=1)
}

// Raw composite OBI as histogram bars (bid/ask pressure visualization)
if (showRawBars) {
    plotBar(
        value=compositeOBI,
        colors=[bidColor, askColor],
        width=1,
        label=["Composite OBI Raw"],
        desc=["Depth-weighted composite OBI histogram (positive=bid, negative=ask)"]
    )
}

// Smoothed composite line with regime-coded fill area
if (showComposite) {
    plotLine(
        value=smoothedComposite,
        width=2,
        colors=[bidColor, askColor, neutralColor],
        colorIndex=regime == 1 ? 0 : (regime == -1 ? 1 : 2),
        label=["Composite OBI"],
        desc=["Depth-weighted composite OBI (EMA-smoothed). Regime: bull/bear/neutral."],
        fill=true
    )
}

// OBI Gradient — rate of change of pressure (acceleration/deceleration)
if (showGradient) {
    plotLine(
        value=gradSmoothed,
        width=2,
        colors=[bidColor, askColor, gradColor],
        colorIndex=gradRegime == 1 ? 0 : (gradRegime == -1 ? 1 : 2),
        label=["OBI Gradient"],
        desc=["Rate of change of composite OBI (positive=bid pressure accelerating, negative=ask pressure accelerating)"]
    )
}

// Z-Score normalized gradient (statistical deviation)
if (showZScore && useZScore) {
    plotLine(
        value=gradZ,
        width=2,
        colors=[zPosColor, zNegColor, neutralColor],
        colorIndex=gradZ > 0 ? 0 : (gradZ < 0 ? 1 : 2),
        label=["Gradient Z-Score"],
        desc=["Z-score normalized gradient: (grad − mean) / stddev over " + zLookback + " bars. |z|>2 = extreme."]
    )
    // Z-score guide lines
    hline(value=1, color=opacity(zPosColor, 20), width=1)
    hline(value=-1, color=opacity(zNegColor, 20), width=1)
    hline(value=2, color=opacity(zPosColor, 15), width=1)
    hline(value=-2, color=opacity(zNegColor, 15), width=1)
}

// Individual depth lines (optional, for granular analysis)
if (showIndividual) {
    plotLine(
        value=smoothed1,
        width=1,
        colors=[opacity(bidColor, 50)],
        label=["OBI 1%"],
        desc=["Order Book Imbalance at 1% depth (shallow book, top-of-book)"]
    )
    plotLine(
        value=smoothed2,
        width=1,
        colors=[opacity(bidColor, 40)],
        label=["OBI 2.5%"],
        desc=["Order Book Imbalance at 2.5% depth (near-term liquidity)"]
    )
    plotLine(
        value=smoothed3,
        width=1,
        colors=[opacity(askColor, 40)],
        label=["OBI 5%"],
        desc=["Order Book Imbalance at 5% depth (medium-term absorption)"]
    )
    plotLine(
        value=smoothed4,
        width=1,
        colors=[opacity(askColor, 50)],
        label=["OBI 10%"],
        desc=["Order Book Imbalance at 10% depth (deep book, structural level)"]
    )
}

// Bid/Ask ratio line (1% depth diagnostic, per Gould & Bonart 2016)
if (showBidAskRatio) {
    var ratioPct = (ratio1 - 1.0) * 100.0
    plotLine(
        value=ratioPct,
        width=1,
        colors=[bidColor, askColor, neutralColor],
        colorIndex=ratioPct > 5.0 ? 0 : (ratioPct < -5.0 ? 1 : 2),
        label=["Bid/Ask Ratio 1%"],
        desc=["Bid/Ask ratio at 1% depth, centered at 0 (positive = bid heavy)"]
    )
}

// Regime transition shapes — directional signal extraction (Cartea et al. 2018)
if (showShapes) {
    var crossUp = smoothedComposite >= bullThresh && !isnan(smoothedComposite[1]) && smoothedComposite[1] < bullThresh
    var crossDn = smoothedComposite <= bearThresh && !isnan(smoothedComposite[1]) && smoothedComposite[1] > bearThresh
    var extremeUp = smoothedComposite >= extremeThresh && !isnan(smoothedComposite[1]) && smoothedComposite[1] < extremeThresh
    var extremeDn = smoothedComposite <= -extremeThresh && !isnan(smoothedComposite[1]) && smoothedComposite[1] > -extremeThresh
    // Gradient-based shapes (acceleration signals)
    var gradAccelUp = gradSmoothed > 0 && !isnan(gradSmoothed[1]) && gradSmoothed[1] <= 0
    var gradAccelDn = gradSmoothed < 0 && !isnan(gradSmoothed[1]) && gradSmoothed[1] >= 0
    var zExtremeUp = useZScore && gradZ >= 2.0 && !isnan(gradZ[1]) && gradZ[1] < 2.0
    var zExtremeDn = useZScore && gradZ <= -2.0 && !isnan(gradZ[1]) && gradZ[1] > -2.0

    if (crossUp) {
        plotShape(
            value=smoothedComposite,
            shape="triangleup",
            color=extremeBidColor,
            width=3,
            label=["Bull Regime"],
            desc=["Composite OBI crossed into bullish regime (buy-heavy)"]
        )
    }
    if (crossDn) {
        plotShape(
            value=smoothedComposite,
            shape="triangledown",
            color=extremeAskColor,
            width=3,
            label=["Bear Regime"],
            desc=["Composite OBI crossed into bearish regime (sell-heavy)"]
        )
    }
    if (extremeUp) {
        plotShape(
            value=smoothedComposite,
            shape="diamond",
            color=extremeBidColor,
            width=4,
            label=["Extreme Bid"],
            desc=["Extreme bid pressure detected — deep book buy-heavy imbalance"]
        )
    }
    if (extremeDn) {
        plotShape(
            value=smoothedComposite,
            shape="diamond",
            color=extremeAskColor,
            width=4,
            label=["Extreme Ask"],
            desc=["Extreme ask pressure detected — deep book sell-heavy imbalance"]
        )
    }
    if (gradAccelUp) {
        plotShape(
            value=gradSmoothed,
            shape="arrowup",
            color=extremeBidColor,
            width=2,
            label=["Grad Bull"],
            desc=["Gradient turned positive — bid pressure accelerating"]
        )
    }
    if (gradAccelDn) {
        plotShape(
            value=gradSmoothed,
            shape="arrowdown",
            color=extremeAskColor,
            width=2,
            label=["Grad Bear"],
            desc=["Gradient turned negative — ask pressure accelerating"]
        )
    }
    if (zExtremeUp) {
        plotShape(
            value=gradZ,
            shape="circle",
            color=zPosColor,
            width=3,
            label=["Z+ Extreme"],
            desc=["Z-score crossed +2 — statistically extreme positive gradient"]
        )
    }
    if (zExtremeDn) {
        plotShape(
            value=gradZ,
            shape="circle",
            color=zNegColor,
            width=3,
            label=["Z- Extreme"],
            desc=["Z-score crossed −2 — statistically extreme negative gradient"]
        )
    }
}

// ------------------------------------------------------------------------------
// Regime Table (last bar only)
// ------------------------------------------------------------------------------
if (isLastBar) {
    var regimeText = regime == 1 ? "BULLISH" : (regime == -1 ? "BEARISH" : "NEUTRAL")
    var regimeTextColor = regime == 1 ? bidColor : (regime == -1 ? askColor : neutralColor)
    var gradText = gradRegime == 1 ? "ACCEL BID" : (gradRegime == -1 ? "ACCEL ASK" : "FLAT")

    plotTable(
        data=[
            ["Orderbook Pressure Gradient V2", regimeText],
            ["Composite OBI", smoothedComposite[0]],
            ["Gradient", gradSmoothed[0]],
            ["Z-Score", useZScore ? gradZ[0] : 0],
            ["Session High OBI", sessionHighOBI],
            ["Session Low OBI", sessionLowOBI],
            ["Regime Changes", regimeChangeCount],
            ["Extreme Bid Events", extremeBidCount],
            ["Extreme Ask Events", extremeAskCount]
        ],
        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
    )
}