@spec cone([number()], [pos_integer()]) :: %{
  required(pos_integer()) => volatility() | nil
}

Calculate volatility cone for term structure analysis.

Parameters

• prices - List of prices (chronological order) (value)
• periods - List of lookback periods to calculate (value)

Returns

Map of period => volatility value (or nil if insufficient data) (map)

Example

%{7 => 0.42, 30 => 0.36}

# descripex:contract
%{
  params: %{
    periods: %{
      description: "List of lookback periods to calculate",
      kind: :value
    },
    prices: %{description: "List of prices (chronological order)", kind: :value}
  },
  returns: %{
    type: :map,
    description: "Map of period => volatility value (or nil if insufficient data)"
  },
  returns_example: %{7 => 0.42, 30 => 0.36}
}

@spec elevated?(number(), number(), number()) :: boolean()

Check if volatility regime is elevated.

Parameters

• current_vol - Current volatility (value)
• baseline_vol - Normal/baseline volatility (value)

Options

• threshold - Multiple of baseline considered elevated (default: 1.5)

Returns

true if current_vol > baseline_vol * threshold (boolean)

Example

true

# descripex:contract
%{
  opts: %{
    threshold: %{
      default: 1.5,
      type: :number,
      description: "Multiple of baseline considered elevated"
    }
  },
  params: %{
    current_vol: %{description: "Current volatility", kind: :value},
    baseline_vol: %{description: "Normal/baseline volatility", kind: :value}
  },
  returns: %{
    type: :boolean,
    description: "true if current_vol > baseline_vol * threshold"
  },
  returns_example: true
}

@spec garman_klass(
  [candle()],
  keyword()
) :: volatility() | nil | {:error, :invalid_prices}

Calculate Garman-Klass volatility estimator from OHLC data.

Parameters

• candles - List of candles with :open, :high, :low, :close fields (exchange_data)

Options

• annualize - Whether to annualize (default: false)
• trading_days - Trading days per year (default: 365)

Returns

Garman-Klass volatility, nil if insufficient data, or {:error, :invalid_prices} (float)

Example

0.1095

Errors

• :invalid_prices

# descripex:contract
%{
  opts: %{
    annualize: %{
      default: false,
      type: :boolean,
      description: "Whether to annualize"
    },
    trading_days: %{
      default: 365,
      type: :integer,
      description: "Trading days per year"
    }
  },
  params: %{
    candles: %{
      description: "List of candles with :open, :high, :low, :close fields",
      source: "fetch_ohlcv(symbol)",
      kind: :exchange_data
    }
  },
  errors: [:invalid_prices],
  returns: %{
    type: :float,
    description: "Garman-Klass volatility, nil if insufficient data, or {:error, :invalid_prices}"
  },
  returns_example: 0.1095
}

@spec iv_percentile(number(), [number()]) :: float() | nil

Calculate IV percentile relative to historical distribution.

Parameters

• current_iv - Current implied volatility (value)
• historical_ivs - List of historical IV values (value)

Returns

Percentile (0-100) of historical values below current, or nil if empty (float)

Example

0.1095

# descripex:contract
%{
  params: %{
    current_iv: %{description: "Current implied volatility", kind: :value},
    historical_ivs: %{description: "List of historical IV values", kind: :value}
  },
  returns: %{
    type: :float,
    description: "Percentile (0-100) of historical values below current, or nil if empty"
  },
  returns_example: 0.1095
}

@spec iv_rank(number(), [number()]) :: float() | nil

Calculate IV rank (normalized position in min-max range).

Parameters

• current_iv - Current implied volatility (value)
• historical_ivs - List of historical IV values (value)

Returns

Rank (0-100) showing position in min-max range, or nil if insufficient data (float)

Example

0.1095

# descripex:contract
%{
  params: %{
    current_iv: %{description: "Current implied volatility", kind: :value},
    historical_ivs: %{description: "List of historical IV values", kind: :value}
  },
  returns: %{
    type: :float,
    description: "Rank (0-100) showing position in min-max range, or nil if insufficient data"
  },
  returns_example: 0.1095
}

@spec iv_vs_rv(volatility(), volatility(), iv_format()) :: float() | nil

Compare implied volatility to realized volatility.

Parameters

• implied_vol - Current implied volatility (value)
• realized_vol - Realized volatility over same period (value)

Options

• format - :ratio (IV/RV), :premium (IV-RV), or :premium_pct ((IV-RV)/RV*100) (default: :ratio)

Returns

Comparison result in specified format, or nil if RV is zero (float)

Example

0.1095

# descripex:contract
%{
  opts: %{
    format: %{
      default: :ratio,
      type: :atom,
      description: ":ratio (IV/RV), :premium (IV-RV), or :premium_pct ((IV-RV)/RV*100)"
    }
  },
  params: %{
    implied_vol: %{description: "Current implied volatility", kind: :value},
    realized_vol: %{
      description: "Realized volatility over same period",
      kind: :value
    }
  },
  returns: %{
    type: :float,
    description: "Comparison result in specified format, or nil if RV is zero"
  },
  returns_example: 0.1095
}

@spec normalize_candles([ohlcv_row()]) :: [candle()]

Normalize positional OHLCV rows into candle maps.

Parameters

• rows - List of [timestamp, open, high, low, close, volume] rows (exchange_data)

Returns

List of candle maps with atom keys (list)

Example

[
  %{
    close: 103.0,
    high: 105.0,
    low: 98.0,
    open: 100.0,
    timestamp: 1700000000000,
    volume: 42.0
  }
]

# descripex:contract
%{
  params: %{
    rows: %{
      description: "List of [timestamp, open, high, low, close, volume] rows",
      source: "fetch_ohlcv(symbol)",
      kind: :exchange_data
    }
  },
  returns: %{type: :list, description: "List of candle maps with atom keys"},
  returns_example: [
    %{
      close: 103.0,
      high: 105.0,
      low: 98.0,
      open: 100.0,
      timestamp: 1700000000000,
      volume: 42.0
    }
  ]
}

@spec parkinson(
  [candle()],
  keyword()
) :: volatility() | nil | {:error, :invalid_prices}

Calculate Parkinson volatility estimator from high-low ranges.

Parameters

• candles - List of candles with :high and :low fields (exchange_data)

Options

• annualize - Whether to annualize (default: false)
• trading_days - Trading days per year (default: 365)

Returns

Parkinson volatility estimate, nil if insufficient data, or {:error, :invalid_prices} (float)

Example

0.1095

Errors

• :invalid_prices

# descripex:contract
%{
  opts: %{
    annualize: %{
      default: false,
      type: :boolean,
      description: "Whether to annualize"
    },
    trading_days: %{
      default: 365,
      type: :integer,
      description: "Trading days per year"
    }
  },
  params: %{
    candles: %{
      description: "List of candles with :high and :low fields",
      source: "fetch_ohlcv(symbol)",
      kind: :exchange_data
    }
  },
  errors: [:invalid_prices],
  returns: %{
    type: :float,
    description: "Parkinson volatility estimate, nil if insufficient data, or {:error, :invalid_prices}"
  },
  returns_example: 0.1095
}

@spec realized(
  [number()],
  keyword()
) :: volatility() | nil | {:error, :invalid_prices}

Calculate realized (historical) volatility from close-to-close returns.

Parameters

• prices - List of prices (chronological order, oldest first) (value)

Options

• annualize - Whether to annualize the result (default: false)
• trading_days - Trading days per year for annualization (default: 365)

Returns

Standard deviation of returns, nil if insufficient data, or {:error, :invalid_prices} (float)

Example

0.1095

Errors

• :invalid_prices

# descripex:contract
%{
  opts: %{
    annualize: %{
      default: false,
      type: :boolean,
      description: "Whether to annualize the result"
    },
    trading_days: %{
      default: 365,
      type: :integer,
      description: "Trading days per year for annualization"
    }
  },
  params: %{
    prices: %{
      description: "List of prices (chronological order, oldest first)",
      kind: :value
    }
  },
  errors: [:invalid_prices],
  returns: %{
    type: :float,
    description: "Standard deviation of returns, nil if insufficient data, or {:error, :invalid_prices}"
  },
  returns_example: 0.1095
}

@spec rolling([number()], pos_integer(), keyword()) :: [volatility()]

Calculate rolling volatility over a price series.

Parameters

• prices - List of prices (chronological order) (value)
• window - Rolling window size (> 2) (value)

Options

• annualize - Whether to annualize (default: false)
• trading_days - Trading days per year (default: 365)

Returns

List of volatility values, empty if insufficient data (list)

Example

[0.38, 0.41]

# descripex:contract
%{
  opts: %{
    annualize: %{
      default: false,
      type: :boolean,
      description: "Whether to annualize"
    },
    trading_days: %{
      default: 365,
      type: :integer,
      description: "Trading days per year"
    }
  },
  params: %{
    window: %{description: "Rolling window size (> 2)", kind: :value},
    prices: %{description: "List of prices (chronological order)", kind: :value}
  },
  returns: %{
    type: :list,
    description: "List of volatility values, empty if insufficient data"
  },
  returns_example: [0.38, 0.41]
}

@spec yang_zhang(
  [candle()],
  keyword()
) :: volatility() | nil | {:error, :invalid_prices}

Calculate Yang-Zhang volatility estimator from OHLC data.

Parameters

• candles - List of consecutive candles with :open, :high, :low, :close fields (exchange_data)

Options

• annualize - Whether to annualize (default: false)
• trading_days - Trading days per year (default: 365)

Returns

Yang-Zhang volatility, nil if insufficient data, or {:error, :invalid_prices} (float)

Example

0.1095

Errors

• :invalid_prices

# descripex:contract
%{
  opts: %{
    annualize: %{
      default: false,
      type: :boolean,
      description: "Whether to annualize"
    },
    trading_days: %{
      default: 365,
      type: :integer,
      description: "Trading days per year"
    }
  },
  params: %{
    candles: %{
      description: "List of consecutive candles with :open, :high, :low, :close fields",
      source: "fetch_ohlcv(symbol)",
      kind: :exchange_data
    }
  },
  errors: [:invalid_prices],
  returns: %{
    type: :float,
    description: "Yang-Zhang volatility, nil if insufficient data, or {:error, :invalid_prices}"
  },
  returns_example: 0.1095
}