IV Band 52-week

Family: Volatility

What it computes

Emits IvBand52WTick ticks carrying iv_pct_rank_252, high/low/median off IV-history cache.

Available on the live and replay drives. The historical drive fails closed with KAIROS_ERR_HISTORICAL_UNWIRED until the relevant cache is hydrated externally.

Methodology

52-week IV percentile rank per tenor.

See the methodology overview for the citation index.

Inputs

IV-history cache.

Key outputs

Iv_pct_rank_252, high/low/median. The full field set is in the tick table below.

Output schema (IvBand52WTick)

The field / type / description table below is regenerated from the IvBand52WTick Rust source by docs-site/scripts/inject-doc-tables.ts on every npm run docs:build. Do not hand-edit between the sentinels.

Field	Type	Description
symbol	Arc<str>	Underlying symbol (interned).
tenor_days	u16	Canonical tenor (calendar days) — 30 / 60 / 90 / 120 / 180 / 360 / 720 per the CANONICAL_TENOR_LADDER.
date	i32	Session date the emission anchors at (YYYYMMDD). For watermark-driven snapshots, the watermark's session date.
ms_of_day	i64	Milliseconds since midnight ET at emission time. For boot-snapshot emissions before any live tick, the start of the session (0).
ivol_current	f64	Current ATM IV observation — the last admitted sample for (symbol, tenor) (per-unit decimal, matching the IvHistorySample::atm_iv convention). NaN when no row has been observed yet.
ivol_high_52w	f64	Highest ATM IV observed across the trailing [ROLLING_WINDOW_DAYS] sessions. NaN when the cache holds no rows for this (symbol, tenor).
ivol_low_52w	f64	Lowest ATM IV observed across the trailing [ROLLING_WINDOW_DAYS] sessions. NaN when the cache holds no rows for this (symbol, tenor).
ivol_median_52w	f64	Exact median of the trailing-window ATM IV distribution. Sort and middle pick (linear interpolation for even counts), NOT a streaming approximation. NaN when the cache holds no rows for this (symbol, tenor).
ivol_percentile_52w	f64	Current ATM IV's percentile rank within the trailing-window distribution, on 0.0..=100.0. 0.0 = current is the lowest; 100.0 = current is the highest. Linear interpolation across the sorted sample, matching numpy.percentile(method="linear") / Bloomberg IMP_VOL_PCT_RANK. NaN when the cache holds no rows for this (symbol, tenor).
sessions_observed	i32	Count of admitted sessions in the rolling window today (≤ window_days). Values strictly less than the configured window mean the band is still warming up — consumers that require a full year of history can mask warm-up emissions on this field.

Configuration (IvBand52WParams)

Regenerated from the IvBand52WParams Rust source — see the note above.

Field	Type	Description
contracts	SecurityFilter	Contracts the subscription tracks. The analytic keys its rolling band off (symbol, tenor_days); the filter selects the symbols.
iv_history	Arc<IvHistoryCache>	Boot-time hydrated per-(symbol, tenor) IV history. Sealed for the lifetime of the subscription. Must contain at least one row per tracked symbol at the configured tenor for the band to compute — symbols with no rows emit NaN extrema and sessions_observed = 0 (cold-start data-quality signal).
window_days	usize	Rolling window length in trading sessions. 252 = 52 weeks (default — matches the field-name suffix); 21 = 1 month; 63 = 1 quarter; 1300 = 5 years. Tick field names retain the 52w suffix per industry glossary terminology (Bloomberg IMP_VOL_*_52WK_HI, trade-alert.com ivol30_52w_high) even when the configured window deviates from 252 — the suffix is the trade-alert glossary term, not a declaration of the underlying lookback.
tenor_days	u16	Canonical tenor (calendar days) the band tracks. Default [DEFAULT_TENOR_DAYS] (30). Bloomberg / Refinitiv / trade-alert.com publish the band at every tenor on the CANONICAL_TENOR_LADDER; each subscription tracks ONE tenor (instantiate multiple subscriptions for the full ladder).

Example

Python

import kairos_thetadata as kt

client = kt.Client.connect(kt.Credentials.from_env())

def on_event(row):
    print(row)

sub = client.live().iv_band_52w(["QQQ"]).on_event(on_event)
sub.wait(timeout_seconds=60.0)

TypeScript

import { Client, Credentials } from "kairos-thetadata";

const client = await Client.connect(Credentials.fromEnv());

await client
  .live()
  .ivBand52w(["QQQ"])
  .onEvent((tick) => {
    console.log(tick);
  });

Rust

// Cargo.toml:
//   kairos = "0.1"

use kairos::{Client, IvBand52wRow};

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::connect(("me@example.com", "secret"))?;

let sub = client
    .live()
    .iv_band_52w(["QQQ"])
    .on_event(|row: &IvBand52wRow| println!("ivol_current={} ivol_percentile_52w={}", row.ivol_current, row.ivol_percentile_52w))?;
// ... later ...
sub.unsubscribe();
# Ok(())
# }