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