*Last updated: 2023-03-16.*
# tf_quant_finance.models.realized_volatility
View source
Calculates the total realized volatility for each path.
```python
tf_quant_finance.models.realized_volatility(
sample_paths, times=None, scaling_factors=None,
returns_type=tf_quant_finance.models.ReturnsType.LOG,
path_scale=tf_quant_finance.models.PathScale.ORIGINAL, axis=-1, dtype=None,
name=None
)
```
With `t_i, i=0,...,N` being a discrete sequence of times at which a series
`S_{t_k}, i=0,...,N` is observed. The logarithmic returns (ReturnsType.LOG)
process is given by:
```
R_k = log(S_{t_{k}} / S_{t_{k-1}})^2
```
Whereas for absolute returns (ReturnsType.ABS) it is given by:
```
R_k = |S_{t_k}} - S_{t_{k-1}})| / |S_{t_{k-1}}|
```
Letting `dt_k = t_k - t_{k-1}` the realized variance is then calculated as:
```
V = c * f( \Sum_{k=1}^{N-1} R_k / dt_k )
```
Where `f` is the square root for logarithmic returns and the identity function
for absolute returns. If `times` is not supplied then it is assumed that
`dt_k = 1` everywhere. The arbitrary scaling factor `c` enables various
flavours of averaging or annualization (for examples of which see [1] or
section 9.7 of [2]).
#### Examples
Calculation of realized logarithmic volatility as in [1]:
```python
import tensorflow as tf
import tf_quant_finance as tff
dtype=tf.float64
num_samples = 1000
num_times = 252
seed = (1, 2)
annual_vol = 20
sigma = annual_vol / (100 * np.sqrt(num_times - 1))
mu = -0.5*sigma**2
gbm = tff.models.GeometricBrownianMotion(mu=mu, sigma=sigma, dtype=dtype)
sample_paths = gbm.sample_paths(
times=range(num_times),
num_samples=num_samples,
seed=seed,
random_type=tff.math.random.RandomType.STATELESS_ANTITHETIC)
annualization = 100 * np.sqrt( (num_times / (num_times - 1)) )
tf.math.reduce_mean(
realized_volatility(sample_paths,
scaling_factors=annualization,
path_scale=PathScale.ORIGINAL,
axis=1))
# 20.03408344960287
```
Carrying on with the same paths the realized absolute volatility (`RV_d2` in
[3]) is:
```
scaling = 100 * np.sqrt((np.pi/(2 * (num_times-1))))
tf.math.reduce_mean(
realized_volatility(sample_paths,
scaling_factors=scaling,
returns_type=ReturnsType.ABS,
path_scale=PathScale.LOG))
# 19.811590402553158
```
#### References:
[1]: CBOE. Summary Product Specifications Chart for S&P 500 Variance Futures.
2012.
https://cdn.cboe.com/resources/futures/sp_500_variance_futures_contract.pdf
[2]: Iain J. Clark. Foreign exchange option pricing - A Practitioner's
guide. Chapter 5. 2011.
[3]: Zhu, S.P. and Lian, G.H., 2015. Analytically pricing volatility swaps
under stochastic volatility. Journal of Computational and Applied Mathematics.
#### Args:
* `sample_paths`: A real `Tensor` of shape
`batch_shape_0 + [N] + batch_shape_1`.
* `times`: A real `Tensor` of shape compatible with `batch_shape_0 + [N] +
batch_shape_1`. The times represented on the axis of interest (the `t_k`).
Default value: None. Resulting in the assumption of unit time increments.
* `scaling_factors`: An optional real `Tensor` of shape compatible with
`batch_shape_0 + batch_shape_1`. Any scaling factors to be applied to the
result (e.g. for annualization).
Default value: `None`. Resulting in `c=1` in the above calculation.
* `returns_type`: Value of ReturnsType. Indicates which definition of returns
should be used.
Default value: ReturnsType.LOG, representing logarithmic returns.
* `path_scale`: Value of PathScale. Indicates which space the supplied
`sample_paths` are in. If required the paths will then be transformed onto
the appropriate scale.
Default value: PathScale.ORIGINAL.
* `axis`: Python int. The axis along which to calculate the statistic.
Default value: -1 (the final axis).
* `dtype`: `tf.DType`. If supplied the dtype for the input and output `Tensor`s.
Default value: `None` leading to use of `sample_paths`.
* `name`: Python str. The name to give to the ops created by this function.
Default value: `None` which maps to 'realized_volatility'.
#### Returns:
Tensor of shape equal to `batch_shape_0 + batch_shape_1` (i.e. with axis
`axis` having been reduced over).