Skip to content

Volatility Surface#

A class to compute and hold market and model-implied volatility surfaces.

This class takes a DataFrame of option market data and provides methods to calculate the Black-Scholes implied volatility (IV) for each option, either from its market price or from a price generated by a financial model.

Source code in src/quantfin/calibration/iv_surface.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
class VolatilitySurface:
    """
    A class to compute and hold market and model-implied volatility surfaces.

    This class takes a DataFrame of option market data and provides methods
    to calculate the Black-Scholes implied volatility (IV) for each option,
    either from its market price or from a price generated by a financial model.
    """

    def __init__(self, option_data: pd.DataFrame):
        """
        Initializes the VolatilitySurface.

        Parameters
        ----------
        option_data : pd.DataFrame
            A DataFrame containing market prices of options. Must include
            'strike', 'maturity', 'marketPrice', 'optionType', and 'expiry' columns.

        Raises
        ------
        ValueError
            If any of the required columns are missing from `option_data`.
        """
        required_cols = ["strike", "maturity", "marketPrice", "optionType", "expiry"]
        if not all(col in option_data.columns for col in required_cols):
            msg = (
                "Input option_data is missing one "
                f"of the required columns: {required_cols}"
            )
            raise ValueError(msg)

        self.data = option_data[required_cols].copy()
        self.surface: pd.DataFrame | None = None
        self.iv_solver = BSMIVSolver()

    def _calculate_ivs(
        self,
        stock: Stock,
        rate: Rate,
        prices_to_invert: pd.Series,
    ) -> np.ndarray:
        """Calculates IVs using the fast, vectorized BSM solver."""
        ivs = self.iv_solver.solve(prices_to_invert.values, self.data, stock, rate)
        return ivs

    def calculate_market_iv(
        self,
        stock: Stock,
        rate: Rate,
    ) -> VolatilitySurface:
        """
        Calculates the market implied volatility surface from market prices.

        This method inverts the Black-Scholes formula for each option's market
        price to find the corresponding implied volatility. The results are
        stored in the `self.surface` DataFrame.

        Parameters
        ----------
        stock : Stock
            The underlying asset's properties.
        rate : Rate
            The risk-free rate structure.

        Returns
        -------
        VolatilitySurface
            The same instance of the class, allowing for method chaining.
        """
        print("Calculating market implied volatility surface...")
        market_ivs = self._calculate_ivs(stock, rate, self.data["marketPrice"])
        self.surface = self.data.copy()
        self.surface["iv"] = market_ivs
        self.surface.dropna(inplace=True)
        self.surface = self.surface[
            (self.surface["iv"] > 1e-4) & (self.surface["iv"] < 2.0)
        ]
        return self

    def calculate_model_iv(
        self,
        stock: Stock,
        rate: Rate,
        model: BaseModel,
        technique: BaseTechnique,
    ) -> VolatilitySurface:
        """
        Calculates a model's implied volatility surface.

        This method first prices every option in the dataset using the provided
        model and technique. It then inverts the Black-Scholes formula for each
        of these model prices to generate the model-implied volatility surface.

        Parameters
        ----------
        stock : Stock
            The underlying asset's properties.
        rate : Rate
            The risk-free rate structure.
        model : BaseModel
            The financial model to generate prices from.
        technique : BaseTechnique
            The pricing technique to use with the model.

        Returns
        -------
        VolatilitySurface
            The same instance of the class, allowing for method chaining.
        """
        print(f"Calculating {model.name} implied volatility surface...")

        model_prices = np.array(
            [
                technique.price(
                    Option(
                        strike=row.strike,
                        maturity=row.maturity,
                        option_type=OptionType.CALL
                        if row.optionType == "call"
                        else OptionType.PUT,
                    ),
                    stock,
                    model,
                    rate,
                    **model.params,
                ).price
                for _, row in self.data.iterrows()
            ]
        )

        model_ivs = self._calculate_ivs(
            stock, rate, pd.Series(model_prices, index=self.data.index)
        )
        self.surface = self.data.copy()
        self.surface["iv"] = model_ivs
        self.surface.dropna(inplace=True)
        return self

__init__(option_data: pd.DataFrame) #

Initializes the VolatilitySurface.

Parameters:

Name Type Description Default
option_data DataFrame

A DataFrame containing market prices of options. Must include 'strike', 'maturity', 'marketPrice', 'optionType', and 'expiry' columns.

 required

Raises:

Type Description
ValueError

If any of the required columns are missing from option_data.
Source code in src/quantfin/calibration/iv_surface.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
def __init__(self, option_data: pd.DataFrame):
    """
    Initializes the VolatilitySurface.

    Parameters
    ----------
    option_data : pd.DataFrame
        A DataFrame containing market prices of options. Must include
        'strike', 'maturity', 'marketPrice', 'optionType', and 'expiry' columns.

    Raises
    ------
    ValueError
        If any of the required columns are missing from `option_data`.
    """
    required_cols = ["strike", "maturity", "marketPrice", "optionType", "expiry"]
    if not all(col in option_data.columns for col in required_cols):
        msg = (
            "Input option_data is missing one "
            f"of the required columns: {required_cols}"
        )
        raise ValueError(msg)

    self.data = option_data[required_cols].copy()
    self.surface: pd.DataFrame | None = None
    self.iv_solver = BSMIVSolver()

calculate_market_iv(stock: Stock, rate: Rate) -> VolatilitySurface #

Calculates the market implied volatility surface from market prices.

This method inverts the Black-Scholes formula for each option's market price to find the corresponding implied volatility. The results are stored in the self.surface DataFrame.

Parameters:

Name Type Description Default
stock Stock

The underlying asset's properties.

 required
rate Rate

The risk-free rate structure.

 required

Returns:

Type Description
VolatilitySurface

The same instance of the class, allowing for method chaining.
Source code in src/quantfin/calibration/iv_surface.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def calculate_market_iv(
    self,
    stock: Stock,
    rate: Rate,
) -> VolatilitySurface:
    """
    Calculates the market implied volatility surface from market prices.

    This method inverts the Black-Scholes formula for each option's market
    price to find the corresponding implied volatility. The results are
    stored in the `self.surface` DataFrame.

    Parameters
    ----------
    stock : Stock
        The underlying asset's properties.
    rate : Rate
        The risk-free rate structure.

    Returns
    -------
    VolatilitySurface
        The same instance of the class, allowing for method chaining.
    """
    print("Calculating market implied volatility surface...")
    market_ivs = self._calculate_ivs(stock, rate, self.data["marketPrice"])
    self.surface = self.data.copy()
    self.surface["iv"] = market_ivs
    self.surface.dropna(inplace=True)
    self.surface = self.surface[
        (self.surface["iv"] > 1e-4) & (self.surface["iv"] < 2.0)
    ]
    return self

calculate_model_iv(stock: Stock, rate: Rate, model: BaseModel, technique: BaseTechnique) -> VolatilitySurface #

Calculates a model's implied volatility surface.

This method first prices every option in the dataset using the provided model and technique. It then inverts the Black-Scholes formula for each of these model prices to generate the model-implied volatility surface.

Parameters:

Name Type Description Default
stock Stock

The underlying asset's properties.

 required
rate Rate

The risk-free rate structure.

 required
model BaseModel

The financial model to generate prices from.

 required
technique BaseTechnique

The pricing technique to use with the model.

 required

Returns:

Type Description
VolatilitySurface

The same instance of the class, allowing for method chaining.
Source code in src/quantfin/calibration/iv_surface.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
def calculate_model_iv(
    self,
    stock: Stock,
    rate: Rate,
    model: BaseModel,
    technique: BaseTechnique,
) -> VolatilitySurface:
    """
    Calculates a model's implied volatility surface.

    This method first prices every option in the dataset using the provided
    model and technique. It then inverts the Black-Scholes formula for each
    of these model prices to generate the model-implied volatility surface.

    Parameters
    ----------
    stock : Stock
        The underlying asset's properties.
    rate : Rate
        The risk-free rate structure.
    model : BaseModel
        The financial model to generate prices from.
    technique : BaseTechnique
        The pricing technique to use with the model.

    Returns
    -------
    VolatilitySurface
        The same instance of the class, allowing for method chaining.
    """
    print(f"Calculating {model.name} implied volatility surface...")

    model_prices = np.array(
        [
            technique.price(
                Option(
                    strike=row.strike,
                    maturity=row.maturity,
                    option_type=OptionType.CALL
                    if row.optionType == "call"
                    else OptionType.PUT,
                ),
                stock,
                model,
                rate,
                **model.params,
            ).price
            for _, row in self.data.iterrows()
        ]
    )

    model_ivs = self._calculate_ivs(
        stock, rate, pd.Series(model_prices, index=self.data.index)
    )
    self.surface = self.data.copy()
    self.surface["iv"] = model_ivs
    self.surface.dropna(inplace=True)
    return self