MM Flow
FlowScripts

Perfected FlowScript

Term Skew Oscillator

Term Skew Oscillator V2 is indexed as 125_term_skew_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

13.5 KB

Lines

315

Native Signal Candidates

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

4/4 guarded

Backwardation

line 240:9

Trigger

(showShapes) && (crossUp)

Value

termSkew

Deps

crossUp:var, showShapes:input

Contango

line 250:9

Trigger

(showShapes) && (crossDn)

Value

termSkew

Deps

crossDn:var, showShapes:input

Extreme Stress

line 260:9

Trigger

(showShapes) && (extremeUp)

Value

termSkew

Deps

extremeUp:var, showShapes:input

Extreme Calm

line 270:9

Trigger

(showShapes) && (extremeDn)

Value

termSkew

Deps

extremeDn:var, showShapes:input

125_term_skew_oscillator.flowscript

source path: kscripts/perfected/125_term_skew_oscillator.flowscript · sha256:5bb672f9718765eb5f5502f129055f0b926efd83af90cfe355fb6588ed36eeee

hash verified
//@version=2
// ============================================================================
// Term Skew Oscillator V2 — Production-Quality Volatility Term Structure Indicator
// Author: BackQuant (@BackQuant) | Perfected by: kScript Perfection Engineer
// Tags: ADVANCED, SPECIALIZED, #skew, #options, #termskew, #oscillator, #volatility
//
// Compares short-term vs. longer-term realized volatility via rolling z-scores,
// computing z(short) − z(long) to identify near-term stress vs. calm term
// structure regimes. Uses historical volatility as a proxy for implied volatility
// (IV data not directly available in kScript; HV and IV are highly correlated
// per Xu & Taylor 1994 and Heynen et al. 1994).
//
// FORMULA FOUNDATION:
// 1. Realized Volatility (annualized): σ = stddev(log returns) × √365
// 2. Z-Score: z = (σ − μ_σ) / std_σ over rolling lookback
// 3. Term Skew: z_short − z_long (positive = front rich, negative = front cheap)
// 4. Regime: Steep Contango (skew < −z), Flat (−z, +z), Backwardation (skew > +z)
// 5. Dynamic Bands: adjust to rolling skew volatility per Poterba & Summers (1988).
//
// RESEARCH BASIS:
//  • Xu & Taylor (1994), "Term Structure of Volatility Implied by FX Options":
//    IV term structure decomposable into level, slope, curvature factors.
//  • Heynen, Kemna & Vorst (1994), "Analysis of the Term Structure of IV":
//    Short-term IV mean-reverts; term structure predicts future realized vol.
//  • Clements, Liao & Tang (2022), "HARnessing the term structure of IV":
//    HAR-TSIV model: slope factor significantly improves RV forecasts.
//  • Coval & Shumway (2001), "Expected Option Returns": term structure slope
//    contains information about future volatility regimes.
//  • Poterba & Summers (1988), "Mean Reversion in Stock Prices": volatility
//    mean-reverts; supports z-score normalization and dynamic threshold bands.
// ============================================================================

define(
    title="Term Skew Oscillator V2",
    position="offchart",
    axis=true
)

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

// --- Tenor Configuration ---
var shortLook = input(name="shortLook", type="number", defaultValue=7, label="Short Tenor (bars)", constraints={min: 2, max: 50, step: 1}, group="Tenor")
var longLook = input(name="longLook", type="number", defaultValue=90, label="Long Tenor (bars)", constraints={min: 10, max: 300, step: 5}, group="Tenor")
var zLen = input(name="zLen", type="number", defaultValue=30, label="Z-Score Lookback", constraints={min: 10, max: 200, step: 5}, group="Tenor")

// --- Smoothing ---
var smoothLen = input(name="smoothLen", type="number", defaultValue=3, label="EMA Smoothing Length", constraints={min: 1, max: 20, step: 1}, group="Smoothing")

// --- Thresholds & Regime ---
var contangoThresh = input(name="contangoThresh", type="number", defaultValue=-1.0, label="Contango Threshold (z)", constraints={min: -3.0, max: 0.0, step: 0.1}, group="Thresholds")
var backwardationThresh = input(name="backwardationThresh", type="number", defaultValue=1.0, label="Backwardation Threshold (z)", constraints={min: 0.0, max: 3.0, step: 0.1}, group="Thresholds")
var extremeThresh = input(name="extremeThresh", type="number", defaultValue=2.0, label="Extreme Threshold (z)", constraints={min: 1.0, max: 4.0, step: 0.1}, group="Thresholds")

// --- Display ---
var showBands = input(name="showBands", type="boolean", defaultValue=true, label="Show Reference Bands", group="Display")
var showShapes = input(name="showShapes", type="boolean", defaultValue=true, label="Show Regime Shapes", group="Display")
var showHistogram = input(name="showHistogram", type="boolean", defaultValue=true, label="Show Skew Histogram", group="Display")
var showTable = input(name="showTable", type="boolean", defaultValue=true, label="Show Summary Table", group="Display")

// --- Colors ---
var contangoColor = input(name="contangoColor", type="color", defaultValue="#26a69a", label="Contango / Calm Color", group="Colors")
var backwardationColor = input(name="backwardationColor", type="color", defaultValue="#ef5350", label="Backwardation / Stress Color", group="Colors")
var neutralColor = input(name="neutralColor", type="color", defaultValue="#9e9e9e", label="Neutral Color", group="Colors")
var extremeColor = input(name="extremeColor", type="color", defaultValue="#ffeb3b", label="Extreme Color", group="Colors")

// ------------------------------------------------------------------------------
// Data Sources
// ------------------------------------------------------------------------------
timeseries bars = ohlcv(symbol=currentSymbol, exchange=currentExchange)
timeseries c = bars.close
timeseries h = bars.high
timeseries l = bars.low

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

// ------------------------------------------------------------------------------
// Realized Volatility Proxies (Annualized)
// ------------------------------------------------------------------------------
// Per Xu & Taylor (1994) and Heynen et al. (1994): realized vol serves as a
// practical proxy for implied vol when options data is unavailable. The
// correlation between HV and IV is typically > 0.85 for liquid underlyings.
// Annualization factor: √365 for crypto (24/7 markets); use √252 for equities.

var logRet = c > 0 && c[1] > 0 ? math.log(c / c[1]) : 0.0
var hvShort = stdev(logRet, shortLook) * math.sqrt(365.0)
var hvLong = stdev(logRet, longLook) * math.sqrt(365.0)

// ------------------------------------------------------------------------------
// Z-Score Normalization
// ------------------------------------------------------------------------------
// Rolling z-scores standardize each tenor's volatility against its own history,
// enabling direct comparison across different absolute volatility levels.

var shortMean = sma(hvShort, zLen)
var shortStd = stddev(hvShort, zLen)
var shortZ = shortStd > 0 ? (hvShort - shortMean) / shortStd : 0.0

var longMean = sma(hvLong, zLen)
var longStd = stddev(hvLong, zLen)
var longZ = longStd > 0 ? (hvLong - longMean) / longStd : 0.0

// ------------------------------------------------------------------------------
// Term Skew Oscillator
// ------------------------------------------------------------------------------
// termSkew = z(short) − z(long)
// Positive → front-month volatility is rich relative to back (near-term stress)
// Negative → front-month is cheap relative to back (calm near-term, risk pushed out)

var termSkewRaw = shortZ - longZ
var termSkew = ema(termSkewRaw, smoothLen)

// ------------------------------------------------------------------------------
// Regime Detection
// ------------------------------------------------------------------------------
// Regime classification per Clements et al. (2022) HAR-TSIV slope interpretation:
//   Backwardation (stress): termSkew > backwardationThresh (front rich)
//   Contango (calm): termSkew < contangoThresh (front cheap)
//   Flat / Neutral: everything in between

var regime = 0      // 0 = flat, 1 = backwardation, -1 = contango
var extremeRegime = 0  // 0 = normal, 1 = extreme stress, -1 = extreme calm

if (termSkew >= backwardationThresh) {
    regime = 1
} else if (termSkew <= contangoThresh) {
    regime = -1
}

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

// Regime color for skew line
var skewColor = regime == 1 ? backwardationColor : (regime == -1 ? contangoColor : neutralColor)

// ------------------------------------------------------------------------------
// Dynamic Reference Bands
// ------------------------------------------------------------------------------
// Per Poterba & Summers (1988), volatility mean-reverts. Dynamic bands adjust
// to the rolling standard deviation of the term skew itself, making the thresholds
// adaptive to the current volatility environment.

var skewVol = stddev(termSkew, zLen)
var dynUpper = math.min(3.0, 1.0 + skewVol)
var dynLower = math.max(-3.0, -1.0 - skewVol)
var dynExtreme = math.min(4.0, 2.0 + skewVol)

// Guard: dynamic bands never cross
if (dynUpper <= dynLower) {
    dynUpper = 1.0
    dynLower = -1.0
}

// ------------------------------------------------------------------------------
// Static State Tracking (Session-level persistence)
// ------------------------------------------------------------------------------
// Stateful computation for session highs/lows, regime counts, and extreme events.

static sessionHighSkew = -999999.0
static sessionLowSkew = 999999.0
static backwardationCount = 0
static contangoCount = 0
static extremeCount = 0
static lastBarIndex = 0

var currentBarIndex = bar_index[0]

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

    if (termSkew > sessionHighSkew) {
        sessionHighSkew = termSkew
    }
    if (termSkew < sessionLowSkew) {
        sessionLowSkew = termSkew
    }

    if (regime == 1) {
        backwardationCount = backwardationCount + 1
    } else if (regime == -1) {
        contangoCount = contangoCount + 1
    }

    if (math.abs(termSkew) >= extremeThresh) {
        extremeCount = extremeCount + 1
    }
}

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

hline(value=0, color="#ffffff30", width=1)

// Reference bands — dynamic per rolling skew volatility
if (showBands) {
    hline(value=dynExtreme, color=transparency(extremeColor, 20), width=1)
    hline(value=-dynExtreme, color=transparency(extremeColor, 20), width=1)
    hline(value=dynUpper, color=transparency(backwardationColor, 30), width=1)
    hline(value=dynLower, color=transparency(contangoColor, 30), width=1)
}

// Term Skew line with regime-coded fill area
plotLine(
    value=termSkew,
    width=2,
    colors=[skewColor],
    label=["Term Skew"],
    desc=["Term Skew Oscillator: z(short HV) − z(long HV). Positive = front rich (stress); Negative = front cheap (calm)"],
    fill=true
)

// Skew histogram
if (showHistogram) {
    var histColor = termSkew >= 0 ? backwardationColor : contangoColor
    plotBar(
        value=termSkew,
        colors=[histColor],
        width=1,
        label=["Term Skew Hist"],
        desc=["Term skew histogram: positive = backwardation (front rich), negative = contango (front cheap)"]
    )
}

// Regime transition shapes
if (showShapes) {
    var crossUp = termSkew >= backwardationThresh && !isnan(termSkew[1]) && termSkew[1] < backwardationThresh
    var crossDn = termSkew <= contangoThresh && !isnan(termSkew[1]) && termSkew[1] > contangoThresh
    var extremeUp = termSkew >= extremeThresh && !isnan(termSkew[1]) && termSkew[1] < extremeThresh
    var extremeDn = termSkew <= -extremeThresh && !isnan(termSkew[1]) && termSkew[1] > -extremeThresh

    if (crossUp) {
        plotShape(
            value=termSkew,
            shape="triangleup",
            color=extremeColor,
            width=3,
            label=["Backwardation"],
            desc=["Term skew crossed into backwardation (front rich to back) — near-term stress / hedge demand"]
        )
    }
    if (crossDn) {
        plotShape(
            value=termSkew,
            shape="triangledown",
            color=extremeColor,
            width=3,
            label=["Contango"],
            desc=["Term skew crossed into contango (front cheap to back) — calmer near-term, risk pushed out"]
        )
    }
    if (extremeUp) {
        plotShape(
            value=termSkew,
            shape="diamond",
            color=extremeColor,
            width=4,
            label=["Extreme Stress"],
            desc=["Extreme term skew: near-term volatility is unusually rich — potential mean-reversion candidate"]
        )
    }
    if (extremeDn) {
        plotShape(
            value=termSkew,
            shape="diamond",
            color=extremeColor,
            width=4,
            label=["Extreme Calm"],
            desc=["Extreme term skew: near-term volatility is unusually cheap — watch for near-term risk repricing"]
        )
    }
}

// ------------------------------------------------------------------------------
// Summary Table (last bar only)
// ------------------------------------------------------------------------------
if (showTable && isLastBar) {
    var regimeText = regime == 1 ? "BACKWARDATION" : (regime == -1 ? "CONTANGO" : "FLAT")
    var regimeTextColor = regime == 1 ? backwardationColor : (regime == -1 ? contangoColor : neutralColor)

    plotTable(
        data=[
            ["Term Skew Oscillator", regimeText],
            ["Term Skew", termSkew[0]],
            ["Short HV Z", shortZ[0]],
            ["Long HV Z", longZ[0]],
            ["Dyn Upper Band", dynUpper],
            ["Dyn Lower Band", dynLower],
            ["Session High", sessionHighSkew],
            ["Session Low", sessionLowSkew],
            ["Backwardation Bars", backwardationCount],
            ["Contango Bars", contangoCount],
            ["Extreme Events", extremeCount]
        ],
        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
    )
}