Package 'geovol'

Geopolitical Volatility (GEOVOL) Modelling

Description

Simulation, estimation and testing for geopolitical volatility (GEOVOL) based on the global common volatility model of Engle and Campos-Martins (2023) <doi:10.1016/j.jfineco.2022.09.009>. GEOVOL is modelled as a latent multiplicative volatility factor with heterogeneous factor loadings. Estimation is carried out as a maximization-maximization procedure, where GEOVOL and the GEOVOL loadings are estimated iteratively until convergence.

Details

Package:	GEOVOL
Type:	Package
Version:	1.1
Date:	2025-05-06
License:	GPL>=2

Author(s)

Susana Campos-Martins, https://sites.google.com/site/susanacamposmartins/

Maintainer: Susana Campos-Martins

References

Engle, R.F. and Campos-Martins, S. (2023) Measuring and hedging geopolitical risk, Journal of Financial Economics 147: 221–242. Available at doi:10.1016/j.jfineco.2022.09.009.

See Also

geovol, geovolSim, geovolTest

Examples

set.seed(123)

## Simulate from a GEOVOL model (default):
eSim <- geovolSim(n = 1500, m = 30)

## Test for GEOVOL:
geovolTest(e = eSim^2-1)

## Estimate a GEOVOL model:
eEst <- geovol(e = eSim)
eEst

---

Extraction functions for a 'geovol' object

Description

Extraction functions for objects of class 'geovol'.

Usage

## S3 method for class 'geovol'
coef(object, as.zoo = TRUE, ...)
  ## S3 method for class 'geovol'
fitted(object, as.zoo = TRUE, ...)
  ## S3 method for class 'geovol'
logLik(object, ...)
  ## S3 method for class 'geovol'
nobs(object, ...)
  ## S3 method for class 'geovol'
print(x, n.extreme = 20, ...)
  ## S3 method for class 'geovol'
residuals(object, as.zoo = TRUE, ...)
  ## S3 method for class 'geovol'
summary(object, ...)

Arguments

object	an object of class 'geovol'.
x	an object of class 'geovol'.
as.zoo	logical. If TRUE, then the returned result is of class zoo.
n.extreme	integer indicating the n.extreme most extreme GEOVOL events to be printed.
...	additional arguments.

Value

coef:	numeric vector containing parameter estimates.
fitted:	fitted (squared) GEOVOL time series.
logLik:	log-likelihood (normal density).
nobs:	the number of observations used in the estimation.
print:	print of the estimation results.
residuals:	GEOVOL standardised residuals.
summary:	summary of estimation results.

Author(s)

Susana Campos-Martins

References

Engle, R.F. and Campos-Martins, S. (2023) Measuring and hedging geopolitical risk, Journal of Financial Economics 147: 221–242. Available at doi:10.1016/j.jfineco.2022.09.009.

See Also

geovol, geovolSim, zoo

Examples

set.seed(123)

## Simulate from a GEOVOL model (default):
eSim <- geovolSim(n = 1000,  m = 30)

## Test for GEOVOL
eTest <- geovolTest(e = eSim^2)

## Estimate a GEOVOL model:
geovolEst <- geovol(e = eSim)

## Print estimation results:
print(geovolEst)

## Extract coefficients:
coef(geovolEst)

## Extract and store GEOVOL:
sigma2Est <- fitted(geovolEst)

## Extract optimised log-likelihood values:
logLik(geovolEst)

## Extract and store GEOVOL standardised residuals:
etaEst <- residuals(geovolEst)

---

Estimate GEOVOL and GEOVOL loadings

Description

Maximum likehlihood estimation of the GEOVOL and GEOVOL loadings. Estimation is carried out as a maximization-maximization procedure, where the latent multiplicative volatility factor and the factor loadings are estimated iteratively until convergence. Either a balanced or an unbalanced panel can be used. For each point in time t, GEOVOL is estimated using all the available values in the cross-section. The GEOVOL loadings are estimated for each time series.

Usage

geovol(e, initial.values = list())

Arguments

e	matrix, multivariate time series or zoo object of volatility standardized residuals with zero mean and unit variance.
initial.values	a list containing the initial parameter values passed on to the optimization routine (optim for the GEOVOL factor and loadings. If list(), the default, then the values are chosen automatically; x - NULL or numeric vector containing the n initial values for the GEOVOL factor, x_{t}, t=1,...,n. s - NULL or numeric vector containing the m initial values for the GEOVOL loadings, s_{i}, i=1,...,m.

Value

An object of class 'geovol'.

Author(s)

Susana Campos-Martins

References

Engle, R.F. and Campos-Martins, S. (2023) Measuring and hedging geopolitical risk, Journal of Financial Economics 147: 221–242. Available at doi:10.1016/j.jfineco.2022.09.009.

See Also

geovol, geovolSim, geovolTest, optim,

Examples

set.seed(123)

## Simulate from a GEOVOL model (default):
eSim <- geovolSim(n = 1000,  m = 30)

## Test for GEOVOL
geovolTest(e = eSim^2-1)

## Estimate a GEOVOL model:
geovolEst <- geovol(e = eSim)

## Print estimation results:
print(geovolEst)

## Extract coefficients:
coef(geovolEst)

## Extract and store GEOVOL:
sigma2Est <- fitted(geovolEst)

## Extract optimised log-likelihood values:
logLik(geovolEst)

## Extract and store GEOVOL standardised residuals:
etaEst <- residuals(geovolEst)

---

Auxiliary function

Description

Auxiliary function used in the estimation of the GEOVOL model. Not intended for the average user.

Usage

geovolObj(par, par.fixed, y, x, flag)

Arguments

par	scalar with the value of the parameter being estimated. If x=TRUE, par contains the value of the GEOVOL factor at time t. Otherwise, it contains the value of the GEOVOL loading for time series i.
par.fixed	numeric vector with the values of the parameters being fixed during estimation. If x=TRUE, par.fixed contains the values of the estimated GEOVOL loadings from previous iteration. Otherwise, it contains the values of the estimated GEOVOL factor from previous iteration.
y	numeric vector, time series or zoo containing the cross-section at time t if x=TRUE or the time series i if otherwise.)
x	logical. If TRUE, it estimates the value of the GEOVOL factor at time t. Otherwise, it estimates the GEOVOL loading for time series i.
flag	integer. If 0, returns a numeric vector with the values of the objective function; if 1 returns the the value of the objective function; if 2, it returns the GEOVOL scaled by the loading of series i, if x=FALSE.

Value

The values of the objective function or GEOVOL.

Author(s)

Susana Campos-Martins

See Also

geovol, fitted.geovol, residuals.geovol

---

Simulate from a GEOVOL model

Description

Simulate from a GEOVOL model.

Usage

geovolSim(n, m, innovations = NULL, x.sd = 0.5, as.zoo = TRUE, verbose = FALSE)

Arguments

n	integer indicating the number of observations.
m	integer indicating the number of time series.
innovations	NULL or numeric vector with the innovations. If NULL, then standard normal innovations are generated with rnorm.
x.sd	numeric scalar indicating the standard deviation of the normal random variable, v, used to simulate the squared GEOVOL factor, x, according to the formula x = exp(v).
as.zoo	logical. If TRUE, then the returned result is of class zoo.
verbose	logical, if TRUE, the simulated time series, e, the innovations and the squared GEOVOL factor, x, are also returned.

Value

A matrix with the simulated values.

Author(s)

Susana Campos-Martins

See Also

geovol, geovolTest,

Examples

set.seed(123)

## Simulate from a GEOVOL model with s.d. 0.5 (default):
eSim <- geovolSim(n = 1000, m = 30)

## Simulate from a GEOVOL model with s.d. 1:
eSim <- geovolSim(n = 1000, m = 30, x.sd = 1)

---

Test for GEOVOL

Description

Compute the GEOVOL test statistic for examining the null hypothesis that the average correlation of the squared volatility standardized residuals (which should be uncorrelated) is zero against the alternative that it is positive.

Usage

geovolTest(e)

Arguments

e	matrix, multivariate time series or zoo object.

Value

The average correlation, the test statistic and the p-value.

Author(s)

Susana Campos-Martins

References

Engle, R.F. and Campos-Martins, S. (2023) Measuring and hedging geopolitical risk, Journal of Financial Economics 147: 221–242. Available at doi:10.1016/j.jfineco.2022.09.009.

See Also

geovol, ]geovolSim

Examples

set.seed(123)

## Simulate from a GEOVOL model with s.d. 0.5 (default):
eSim <- geovolSim(n = 1500, m = 30)

## Test for GEOVOL:
geovolTest(e = eSim^2-1)

---