MM Flow
FlowScripts

Perfected FlowScript

OI Z-Score

OI Z-Score — Perfected Edition is indexed as 155_oi_z_score.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

13.5 KB

Lines

439

Native Signal Candidates

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

8/8 guarded

Extreme Overlev

line 326:9

Trigger

(showShapes) && (extremeUp)

Value

z

Deps

extremeUp:var, showShapes:input

Extreme Capit

line 336:9

Trigger

(showShapes) && (extremeDown)

Value

z

Deps

extremeDown:var, showShapes:input

σ2 Overlev

line 346:9

Trigger

(showShapes) && (sigma2Up)

Value

z

Deps

showShapes:input, sigma2Up:var

σ2 Capit

line 356:9

Trigger

(showShapes) && (sigma2Down)

Value

z

Deps

showShapes:input, sigma2Down:var

Zero Cross Up

line 366:9

Trigger

(showShapes) && (crossUp)

Value

0

Deps

crossUp:var, showShapes:input

Zero Cross Down

line 376:9

Trigger

(showShapes) && (crossDown)

Value

0

Deps

crossDown:var, showShapes:input

OI Spike Up

line 386:9

Trigger

(showShapes) && (oiSpikeUp)

Value

band3Sigma

Deps

oiSpikeUp:var, showShapes:input

OI Spike Down

line 396:9

Trigger

(showShapes) && (oiSpikeDown)

Value

-band3Sigma

Deps

oiSpikeDown:var, showShapes:input

155_oi_z_score.flowscript

source path: kscripts/perfected/155_oi_z_score.flowscript · sha256:31b77e6fa4cac34732da0dd4a1fdf5581b342a59e361105dcf83f10c15e4cb2b

hash verified
//@version=2
// ============================================================================
// OI Z-Score — Perfected Edition
// Author: arkutrades_1669 (@arkutrades_1669) | Enhanced by kScript_Perfection_Engineer
// Tags: ADVANCED, FLOW, #OI, #Z-Score, #regime, #leverage, #capitulation
//
// Production-quality Open Interest statistical oscillator that standardizes
// OI levels into a z-score regime indicator. Implements ±1/2/3σ bands with
// fill, regime detection (over-leveraged / capitulation / normal), color coding,
// shape markers, and static state tracking for duration context.
//
// Research papers underpinning this design:
//  1. Chen, Cuny & Haugen (1995), "Stock Volatility and the Levels of the
//     Basis and Open Interest in Futures Contracts": establishes that OI
//     levels contain information about future price volatility and market
//     expectations. Higher OI correlates with greater information flow.
//  2. Yang Xu et al. (2021), "Price Volatility Characteristics of China's
//     Soybean Futures Market": unexpected OI changes have larger impact on
//     price volatility than expected changes. Z-score precisely captures
//     these unexpected deviations from the rolling mean.
//  3. Zhao & Palomar (2018), "Mean-Reverting Portfolio With Budget Constraint":
//     z = (X − μ) / σ with threshold entry/exit at ±1σ, ±2σ.
//  4. Brunnermeier & Pedersen (2009), "Market Liquidity and Funding Liquidity":
//     liquidity spirals; when leverage is high, small shocks amplify into
//     systemic crises. Extreme positive OI z-scores flag over-leveraged tops
//     where cascade risk is elevated.
//  5. He & Manela (2022), "Fundamentals of Perpetual Futures": past-return
//     momentum explains the futures-spot gap with R² > 50%. OI spikes in
//     perps signal crowded positioning that drives funding deviations.
// ============================================================================

define(
    title="OI Z-Score — Perfected Edition",
    position="offchart",
    axis=true
)

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

// --- Data Sources ---
var src = input(
    name="src",
    type="select",
    defaultValue="BTCUSDT",
    label="Symbol",
    options=["BTCUSDT", "ETHUSDT", "SOLUSDT"],
    group="Data Sources"
)
var exc = input(
    name="exc",
    type="select",
    defaultValue="BINANCE_FUTURES",
    label="Exchange",
    options=["BINANCE_FUTURES", "BYBIT", "OKEX_SWAP", "DERIBIT"],
    group="Data Sources"
)

// --- Computation ---
var zLen = input(
    name="zLen",
    type="number",
    defaultValue=30,
    label="Z Window",
    constraints={min: 10, max: 100, step: 5},
    group="Computation"
)
var smoothLen = input(
    name="smoothLen",
    type="number",
    defaultValue=3,
    label="Smoothing",
    constraints={min: 1, max: 20, step: 1},
    group="Computation"
)
var showOIChange = input(
    name="showOIChange",
    type="boolean",
    defaultValue=true,
    label="Show OI Change (bar-to-bar)",
    group="Computation"
)

// --- Sigma Bands ---
var showBands = input(
    name="showBands",
    type="boolean",
    defaultValue=true,
    label="Show ±1/2/3σ Bands",
    group="Sigma Bands"
)
var band1Sigma = input(
    name="band1Sigma",
    type="number",
    defaultValue=1.0,
    label="1σ Band",
    constraints={min: 0.5, max: 2.0, step: 0.5},
    group="Sigma Bands"
)
var band2Sigma = input(
    name="band2Sigma",
    type="number",
    defaultValue=2.0,
    label="2σ Band",
    constraints={min: 1.0, max: 3.0, step: 0.5},
    group="Sigma Bands"
)
var band3Sigma = input(
    name="band3Sigma",
    type="number",
    defaultValue=3.0,
    label="3σ Band",
    constraints={min: 2.0, max: 4.0, step: 0.5},
    group="Sigma Bands"
)

// --- Display ---
var showShapes = input(
    name="showShapes",
    type="boolean",
    defaultValue=true,
    label="Show Extreme Shapes",
    group="Display"
)
var showMomentum = input(
    name="showMomentum",
    type="boolean",
    defaultValue=true,
    label="Show OI Change Momentum",
    group="Display"
)
var showRegimeTable = input(
    name="showRegimeTable",
    type="boolean",
    defaultValue=true,
    label="Show Regime Table",
    group="Display"
)

// --- Colors ---
var overlevColor = input(
    name="overlevColor",
    type="color",
    defaultValue="#ef5350",
    label="Over-Leveraged Color",
    group="Colors"
)
var capitColor = input(
    name="capitColor",
    type="color",
    defaultValue="#26a69a",
    label="Capitulation Color",
    group="Colors"
)
var neutralColor = input(
    name="neutralColor",
    type="color",
    defaultValue="#78909c",
    label="Neutral Color",
    group="Colors"
)
var extremeColor = input(
    name="extremeColor",
    type="color",
    defaultValue="#ffeb3b",
    label="Extreme Color",
    group="Colors"
)
var lineColor = input(
    name="lineColor",
    type="color",
    defaultValue="#42a5f5",
    label="Line Color",
    group="Colors"
)

// ---------------------------------------------------------------------------
// 2. DATA SOURCES & NaN GUARD
// ---------------------------------------------------------------------------
timeseries oi = open_interest(symbol=src, exchange=exc)

if (isnan(oi.close[0])) {
    return
}

// ---------------------------------------------------------------------------
// 3. Z-SCORE CALCULATION
// ---------------------------------------------------------------------------
// z = (OI − μ) / σ; guard against zero division.
timeseries oiMean = sma(oi.close, zLen)
timeseries oiStd = stdev(oi.close, zLen)
timeseries rawZ = (oi.close - oiMean) / math.max(oiStd, 0.0001)
timeseries z = ema(rawZ, smoothLen)

// Bar-to-bar OI change (momentum)
timeseries oiChange = oi.close - oi.close[1]
timeseries oiChangePct = oiMean > 0 ? (oiChange / oiMean) * 100.0 : 0.0

// ---------------------------------------------------------------------------
// 4. REGIME DETECTION
// ---------------------------------------------------------------------------
// Regime classification based on z position relative to sigma bands:
//   Over-Leveraged (Hot):    z > +1σ  → unusually high OI = over-leveraged top risk
//   Capitulation (Cold):     z < −1σ  → unusually low OI = capitulation / deleveraging
//   Normal:                  |z| ≤ 1σ → typical positioning regime

var regimeOverlev = z > band1Sigma
var regimeCapit = z < -band1Sigma
var regimeNormal = !regimeOverlev && !regimeCapit

var regimeColor = regimeOverlev ? overlevColor : (regimeCapit ? capitColor : neutralColor)

// ---------------------------------------------------------------------------
// 5. STATIC STATE TRACKING — regime duration
// ---------------------------------------------------------------------------
static overlevBars = 0
static capitBars = 0
static normalBars = 0
static lastRegime = 0

if (regimeOverlev) {
    overlevBars = overlevBars + 1
    capitBars = 0
    normalBars = 0
    lastRegime = 1
} else if (regimeCapit) {
    capitBars = capitBars + 1
    overlevBars = 0
    normalBars = 0
    lastRegime = -1
} else {
    normalBars = normalBars + 1
    overlevBars = 0
    capitBars = 0
    lastRegime = 0
}

// ---------------------------------------------------------------------------
// 6. ALERT CONDITIONS
// ---------------------------------------------------------------------------
var extremeUp = z > band3Sigma && z[1] <= band3Sigma
var extremeDown = z < -band3Sigma && z[1] >= -band3Sigma
var sigma2Up = z > band2Sigma && z[1] <= band2Sigma
var sigma2Down = z < -band2Sigma && z[1] >= -band2Sigma

// Zero-line cross
var crossUp = z > 0 && z[1] <= 0
var crossDown = z < 0 && z[1] >= 0

// OI spike conditions
var oiSpikeUp = oiChange > 0 && oiChange > stdev(oiChange, zLen) * 2
var oiSpikeDown = oiChange < 0 && -oiChange > stdev(oiChange, zLen) * 2

// ---------------------------------------------------------------------------
// 7. PLOTTING
// ---------------------------------------------------------------------------

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

// --- Sigma Bands (±1/2/3σ) with fill ---
if (showBands) {
    hline(value=band1Sigma, color=transparency(overlevColor, 60), width=1)
    hline(value=-band1Sigma, color=transparency(capitColor, 60), width=1)
    hline(value=band2Sigma, color=transparency(overlevColor, 40), width=1)
    hline(value=-band2Sigma, color=transparency(capitColor, 40), width=1)
    hline(value=band3Sigma, color=transparency(extremeColor, 30), width=1)
    hline(value=-band3Sigma, color=transparency(extremeColor, 30), width=1)

    // Fill between ±1σ and ±2σ bands
    plotLine(
        value=[band2Sigma, band1Sigma],
        width=1,
        colors=[transparency(overlevColor, 15), transparency(overlevColor, 15)],
        fill=true,
        label=["2σ Band", "1σ Band"],
        desc=["Upper 2σ band", "Upper 1σ band"]
    )
    plotLine(
        value=[-band1Sigma, -band2Sigma],
        width=1,
        colors=[transparency(capitColor, 15), transparency(capitColor, 15)],
        fill=true,
        label=["1σ Band", "2σ Band"],
        desc=["Lower 1σ band", "Lower 2σ band"]
    )
}

// --- Z-Score Line (regime-colored) ---
plotLine(
    value=z,
    width=2,
    colors=[regimeColor],
    label=["OI Z"],
    desc=["Smoothed Open Interest Z-Score (regime-colored)"]
)

// --- Z-Score Histogram (color-coded by regime) ---
var histColorIdx = regimeOverlev ? 0 : (regimeCapit ? 1 : 2)
plotBar(
    value=z,
    colors=[transparency(overlevColor, 60), transparency(capitColor, 60), transparency(neutralColor, 50)],
    colorIndex=histColorIdx,
    width=1,
    label=["OI Z Hist"],
    desc=["OI Z-Score histogram (color-coded by regime)"]
)

// --- OI Change Momentum ---
if (showMomentum && showOIChange) {
    var changeBull = oiChange >= 0
    plotBar(
        value=oiChangePct,
        colors=[transparency(capitColor, 40), transparency(overlevColor, 40)],
        colorIndex=changeBull ? 0 : 1,
        width=1,
        label=["OI Change %"],
        desc=["Bar-to-bar OI change as % of rolling mean"]
    )
}

// --- Extreme Shape Markers ---
if (showShapes) {
    if (extremeUp) {
        plotShape(
            value=z,
            shape="triangledown",
            colorIndex=extremeColor,
            width=3,
            label=["Extreme Overlev"],
            desc=["OI Z-Score exceeded +3σ — over-leveraged top / cascade risk"]
        )
    }
    if (extremeDown) {
        plotShape(
            value=z,
            shape="triangleup",
            colorIndex=extremeColor,
            width=3,
            label=["Extreme Capit"],
            desc=["OI Z-Score fell below −3σ — capitulation / deleveraging bottom"]
        )
    }
    if (sigma2Up) {
        plotShape(
            value=z,
            shape="xcross",
            colorIndex=overlevColor,
            width=2,
            label=["σ2 Overlev"],
            desc=["OI Z-Score crossed above +2σ — over-leveraged warning"]
        )
    }
    if (sigma2Down) {
        plotShape(
            value=z,
            shape="xcross",
            colorIndex=capitColor,
            width=2,
            label=["σ2 Capit"],
            desc=["OI Z-Score crossed below −2σ — capitulation warning"]
        )
    }
    if (crossUp) {
        plotShape(
            value=0,
            shape="circle",
            colorIndex=capitColor,
            width=2,
            label=["Zero Cross Up"],
            desc=["OI Z-Score crossed above zero — positioning building"]
        )
    }
    if (crossDown) {
        plotShape(
            value=0,
            shape="circle",
            colorIndex=overlevColor,
            width=2,
            label=["Zero Cross Down"],
            desc=["OI Z-Score crossed below zero — positioning reducing"]
        )
    }
    if (oiSpikeUp) {
        plotShape(
            value=band3Sigma,
            shape="diamond",
            colorIndex=overlevColor,
            width=2,
            label=["OI Spike Up"],
            desc=["Unusually large OI increase — aggressive positioning build"]
        )
    }
    if (oiSpikeDown) {
        plotShape(
            value=-band3Sigma,
            shape="diamond",
            colorIndex=capitColor,
            width=2,
            label=["OI Spike Down"],
            desc=["Unusually large OI decrease — forced deleveraging / liquidation"]
        )
    }
}

// ---------------------------------------------------------------------------
// 8. REGIME TABLE (last bar only)
// ---------------------------------------------------------------------------
if (showRegimeTable && isLastBar) {
    var regimeText = regimeOverlev ? "OVER-LEVERAGED" : (regimeCapit ? "CAPITULATION" : "NORMAL")
    var regimeTextColor = regimeOverlev ? overlevColor : (regimeCapit ? capitColor : neutralColor)

    plotTable(
        data=[
            ["OI Z-Score — Perfected", regimeText],
            ["OI Z", z[0]],
            ["OI Level", oi.close[0]],
            ["OI Mean", oiMean[0]],
            ["OI Std", oiStd[0]],
            ["OI Change %", oiChangePct[0]],
            ["Overlev Bars", overlevBars],
            ["Capit Bars", capitBars],
            ["Normal Bars", normalBars]
        ],
        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
    )
}