Type: Package
Title: Geopolitical Volatility (GEOVOL) Modelling
Version: 1.1
Date: 2025-05-06
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.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Depends: R (≥ 3.5.0), zoo
URL: https://sites.google.com/site/susanacamposmartins/
NeedsCompilation: no
Packaged: 2025-05-06 11:16:26 UTC; susanacamposmartins
Repository: CRAN
Date/Publication: 2025-05-07 12:30:09 UTC
Author: Susana Campos-Martins [aut, cre]
Maintainer: Susana Campos-Martins <scmartins@ucp.pt>

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)