Package 'GNAR'

Description

Produces an active node matrix heat-map, which compares the local impact each node has on all the other ones (i.e., regressing $j$ on $i$) once a model order has been chosen. The local relevance indes is $\mathrm{local} (i, j) := \bigg ( w_{ij} \sum_{k = 1}^{p} |\hat{\beta}_{kr}| \bigg ) \bigg \{ \sum_{l \in \mathcal{N} (i)} \sum_{r = 1}^{r^*} \sum_{k = 1}^{p} w_{il} |\hat{\beta}_{kr}| \bigg) \bigg \}^{-1},$ which is closer to one the more relevant $j$ is when forecasting $i$.

Usage

active_node_plot(vts, network, max_lag, r_stages)

Arguments

Value

Produces the local influence matrix heat-map for a specific model order. Does not return any values.

Author(s)

Daniel Salnikov and Guy Nason

References

Nason, G.P., Salnikov, D. and Cortina-Borja, M. (2023) New tools for network time series with an application to COVID-19 hospitalisations. https://arxiv.org/abs/2312.00530

Examples

#
# Produces an active node heat-map matrix from a stationary GNAR(2, [2, 1]) simulation.
#
gnar_simulation <- GNARsim(n = 100, net=fiveNet,
	alphaParams = list(rep(0.25, 5), rep(0.12, 5)), 
        betaParams = list(c(0.25, 0.13), c(0.20)), sigma=1)
#
# Active node plot
#
active_node_plot(gnar_simulation, fiveNet, 2, c(2, 1))

Description

Function calculating AIC for GNARfit models.

Usage

## S3 method for class 'GNARfit'
AIC(object, ..., k=2)

Arguments

Details

Smaller AIC values correspond to better fit.

Value

A numeric value corresponding to the AIC (or other criterion if k is set to something other than 2). Note that the value returned is the “time-normalised” AIC for the GNAR model, and also removes any proportionality constants in the calculation.

Note

Occasionally it has been observed that when the forecast horizon has been set too high, this can result in NA AIC values. This can be resolved by reducing the forecast horizon. If package users find this problem persists or they experience any other unexpected behaviour, please contact the package maintainer.

Examples

#AIC for two different GNAR fits for fiveNet data
#GNAR(2,[1,1])
AIC(GNARfit())
#GNAR(2,[1,0])
AIC(GNARfit(betaOrder=c(1,0)))

Description

Takes an input GNARnet and neighbour stage and outputs the corresponding adjacency matrix.

Usage

## S3 method for class 'GNARnet'
as.matrix(x, stage=1, normalise=FALSE, ...)

Arguments

Details

S3 method for class "GNARnet".

With normalisation this is a non-invertible transform. See NofNeighbours for neighbour set definition.

Value

as.matrix performed on a GNARnet returns a square matrix with the number of rows and columns equal to the length of the $edges list. Entry i,j of the matrix will be non-zero if node j is in the stage neighbour set of i.

Examples

#fiveNet as an adjacency matrix
as.matrix(fiveNet)

Description

Function calculating BIC for GNARfit models.

Usage

## S3 method for class 'GNARfit'
BIC(object, ...)

Arguments

Details

Smaller BIC values correspond to better fit.

Value

A numeric value corresponding to the BIC. Note that this is the “time-normalised” value of the AIC for the GNAR model, and also removes any proportionality constants in the calculation.

Examples

#BIC for two different GNAR fits for fiveNet data
#GNAR(2,[1,1])
BIC(GNARfit())
#GNAR(2,[1,0])
BIC(GNARfit(betaOrder=c(1,0)))

Description

coef.GNARfit returns the vector of coefficients from a GNARfit object.

Usage

## S3 method for class 'GNARfit'
coef(object,...)

Arguments

Details

S3 method for class "GNARfit".

Value

coef.GNARfit returns a vector of coefficient values.

Examples

#get the coefficients of the fiveNode data GNAR fit
coef(GNARfit())

Description

Plots the GNAR network autcorrelation funciton for a choice of maximum lag and maximum r-stage depth in the network. Using the nacf function for network autocorrelation and pnacf for partial network autocorrelation.

Usage

corbit_plot(vts, net, max_lag, max_stage, weight_matrix, 
viridis_color_option="viridis", size_option="absolute_val", 
partial="no", r_corbit="no", line_segment="no", rectangular_plot="no")

Arguments

Details

This function computes network autocorrelation or partial network autocorrelation function values for a specific choice of maximum lag and r-stage depth, and produces the corresponing Corbit plot. Each point in a Corbit plot corresponds to the (P)NACF value, i.e., (p)nacf(h, r), at a h-lag and r-stage pair. The ring number starting from the inside corresponds to r-stage depth (path length), and the numbers on the outside ring indicate time lag. The colour scale is based on the overall network autocorrelation values (i.e., the colour is set to highlight strong correlations). The dot at the centre has (p)nacf(h, r)=0 and the smallest size for aiding comparison. Please see the RMarkdown document mentioned in GNAR references for plot examples.

Value

Produces the specified, i.e, NACF or PNACF for a choice of lag and $r$-stage depth, $(h, r)$, Corbit plot. Does not print (P)NACF values, these are stored as an invisble data frame (matrix), and can be accessed by printing or calling the object produced by the corbit_plot call.

Author(s)

Daniel Salnikov and Guy Nason.

References

Nason, G.P., Salnikov, D. and Cortina-Borja, M. (2023) New tools for network time series with an application to COVID-19 hospitalisations. https://arxiv.org/abs/2312.00530

Examples

#
# Simulate 100 observations from a stationary GNAR(2, [2, 1]), where 
# fiveNet is the underlying network.
# 
gnar_simulation <- GNARsim(n = 100, net=fiveNet, alphaParams = list(rep(0.25, 5), rep(0.12, 5)), 
        betaParams = list(c(0.25, 0.13), c(0.20)), sigma=1)
# We produce the corresponding Corbit plots.
corbit_plot(gnar_simulation, fiveNet, 20, 3)
corbit_plot(gnar_simulation, fiveNet, 20, 3, partial = "yes")

# If the network object comes with its own weights, then these can be added by including 
# the option weight_matrix in the corbit call.
# corbit_plot(vts, net, max_lag, max_stage, weight_matrix = object_weights_matrix)

Description

fitted.GNARfit returns the fitted values of a GNARfit object as a matrix.

Usage

## S3 method for class 'GNARfit'
fitted(object,...)

Arguments

Details

S3 method for class "GNARfit".

Value

fitted.GNARfit returns a ts object of fitted values, with t-alphaOrder rows and nnodes columns.

Examples

#get the fitted values of the fiveNode GNAR fit
fitted(GNARfit())

Description

A multivariate time series fiveVTS and corresponding network fiveNet.

Usage

data("fiveNode")

Format

This dataset contains two R objects:
fiveVTS is a ts object with a matrix of 200 rows (t=200) and 5 columns (n=5) fiveNet is a GNARnet object containing $edges and $dist.
edges is a list of length five, with edges[[i]] containing the vertices that node i is connected to.
dist is a list of length five, with dist[[i]] containing the length of the vertices that node i is connected to.

Examples

plot(fiveNet)
image(fiveVTS)

Description

This dataset is from the OECD (OECD (2018), Quarterly GDP (indicator). <doi:10.1787/b86d1fc8-en> (Accessed on 29 January 2018)) and is differenced annual growth rate for 35 countries for 1962-2013.

Usage

gdpVTS

Format

gdpVTS is a ts object with a matrix of 52 rows (t=52) and 35 columns (n=35)

Examples

#Plot using 'ts' S3 function, can only plot up to 10 columns at once
plot(gdpVTS[,1:5])

#Plot as heatmap
image(gdpVTS)

Description

Computes a list of r-stage adjacency matrices, each matrix in the list inidicates whether or not nodes $i$ and $j$ are r-stage neighbours in the underlying network. Essentially $[\mathbf{S}_r]_{ij} = 1$ if and only if $d(i, j) = r$

Usage

get_k_stages_adjacency_tensor(St_1, r)

Arguments

Value

List containing the adjacency matrices in ascending order.

Author(s)

Daniel Salnikov and Guy Nason

References

Nason, G.P., Salnikov, D. and Cortina-Borja, M. (2023) New tools for network time series with an application to COVID-19 hospitalisations. https://arxiv.org/abs/2312.00530

Examples

#
# Produce the r-stage adjacency tensors for the fiveNet network.
#
get_k_stages_adjacency_tensor(as.matrix(GNARtoigraph(fiveNet)), 3)
#

Description

A package to fit, predict, and simulate time series using the Generalised Network AutoRegressive (GNAR) model, potentially with exogenous variables. The main functions are GNARfit and GNARXfit, which fits the model to a time series and network(s), S3 method predict.GNARfit which predicts from a fitted GNAR model, and GNARsim which simulates from a GNAR model with specified parameters. For details of the model, see GNARfit. The package also contains an example network time series in data file fiveNode, with network fiveNet, and simulated time series fiveVTS.

References

Knight, M.I., Nunes, M.A. and Nason, G.P. (2015) Modelling, detrending and decorrelation of network time series. arXiv preprint.

Knight, M.I., Leeming, K., Nason, G.P. and Nunes, M. A. (2020) Generalised Network Autoregressive Processes and the GNAR package. Journal of Statistical Software, 96 (5), 1–36.

Nason G.P. and Wei J. (2022) Quantifying the economic response to COVID-19 mitigations and death rates via forecasting Purchasing Managers’ Indices using Generalised Network Autoregressive models with exogenous variables. Journal of the Royal Statistical Society Series A, 185 (4), 1778–1792.

Description

Creates the design matrix necessary for fitting the GNAR model.

Usage

GNARdesign(vts = GNAR::fiveVTS, net = GNAR::fiveNet, alphaOrder = 2, betaOrder = c(1,1),
 fact.var = NULL, globalalpha=TRUE, tvnets=NULL, netsstart=NULL)

Arguments

Value

Examples

#Design matrix to fit GNAR(2,[1,1]) to the fiveVTS data
GNARdesign()

Description

Fits the GNAR model to the given inputs using GNARdesign and lm.

Usage

GNARfit(vts=GNAR::fiveVTS, net=GNAR::fiveNet, alphaOrder=2, betaOrder=c(1,1),
 fact.var=NULL, globalalpha=TRUE, tvnets=NULL, netsstart=NULL, ErrorIfNoNei=TRUE)

Arguments

Details

The GNAR model of order $(p,S)$ is defined as

$X_{i,t} = \sum_{j=1}^p \left( \alpha_{i,j} X_{i,t-j} +\sum_{c=1}^C \sum_{r=1}^{S_j} \beta_{j,r, c}\sum_{q \in {N}^{(r)}_t(i)} \omega_{i,q,c}^{(t)} X_{q,t-j} \right) + u_{i,t}$

where $p$ is the maximum time lag, $S=(S_1,...,S_p)$ and $S_j$ is the maximum stage of neighbour dependence for time lag $j$, ${N}^{(r)}_t(i)$ is the $r$th stage neighbour set of node $i$ at time $t$, $\omega_{i,q,c}^{(t)}$ is the connection weight between node $i$ and node $q$ at time $t$ if the path corresponds to covariate $c$. Here, we consider a sum from one to zero to be zero and $\{u_{i,t}\}$, are assumed to be independent and identically distributed at each node $i$, with mean zero and variance $\sigma_i^2$. Currently, only a single network GNAR model can be fitted. The connection weight, $\omega_{i,q,c}^{(t)}$, is the inverse of the distance between nodes i and q, normalised so that they sum to 1 for each i,t. See is.GNARnet for GNARnet object information and example construction.

Value

References

Knight, M.I., Nunes, M.A. and Nason, G.P. Modelling, detrending and decorrelation of network time series. arXiv preprint.

Knight, M.I., Leeming, K., Nason, G.P. and Nunes, M. A. (2020) Generalised Network Autoregressive Processes and the GNAR package. Journal of Statistical Software, 96 (5), 1–36.

Examples

#Fit the GNAR(2,[1,1]) model to the fiveVTS data
GNARfit()

#Convert the residuals to matrix form
residToMat(GNARfit())$resid

Description

Simulates a GNAR process with Normally distributed innovations.

Usage

GNARsim(n=200, net=GNAR::fiveNet, alphaParams=list(c(rep(0.2,5))),
 betaParams=list(c(0.5)), sigma=1, tvnets=NULL, netsstart=NULL)

Arguments

Details

Parameter lists should not be NULL, set unused parameters to be zero. See GNARfit for model description.

Value

GNARsim returns the multivariate time series as a ts object, with n rows and a column for each of the nodes in the network.

References

Knight, M.I., Nunes, M.A. and Nason, G.P. Modelling, detrending and decorrelation of network time series. arXiv preprint.

Knight, M.I., Leeming, K., Nason, G.P. and Nunes, M. A. (2020) Generalised Network Autoregressive Processes and the GNAR package. Journal of Statistical Software, 96 (5), 1–36.

Examples

#Simulate a GNAR(1,[1]) process with the fiveNet network
GNARsim()

Description

Takes an input network and neighbour stage and returns it in igraph form.

Usage

GNARtoigraph(net=GNAR::fiveNet, stage=1, normalise=FALSE)

Arguments

Details

With normalisation this is a non-invertible transform. See NofNeighbours for neighbour set definition. See is.GNARnet for GNARnet object information and example construction.

Value

GNARtoigraph returns an 'igraph' object with weights as the inverse distances of the input network.

Examples

#fiveNet as an igraph object
GNARtoigraph()

Description

Creates the design matrix necessary for fitting the GNAR model.

Usage

GNARXdesign(vts = GNAR::fiveVTS, net = GNAR::fiveNet, alphaOrder = 2, betaOrder = c(1,1),
 fact.var = NULL, globalalpha=TRUE, tvnets=NULL, netsstart=NULL, lambdaOrder=NULL, 
 xvts=NULL)

Arguments

Value

References

Nason G.P. and Wei J. (2022) Quantifying the economic response to COVID-19 mitigations and death rates via forecasting Purchasing Managers’ Indices using Generalised Network Autoregressive models with exogenous variables. Journal of the Royal Statistical Society Series A, 185, 1778–1792.

Examples

set.seed(1)
n = 1000
xvts=list()
xvts[[1]] = matrix(rnorm(5*n, mean=0, sd=2), nrow=n, ncol=5)
xvts[[2]] = matrix(rnorm(5*n, mean=0, sd=2), nrow=n, ncol=5)
lambdaParams=list()
lambdaParams[[1]] = c(0.5, -0.5)
lambdaParams[[2]] = c(0.3, 0.1)

# Simulate the GNARX using the exogenous variables xvts with associated parameters lambdaParams

Y_data <- GNARXsim(n=n, net=GNAR::fiveNet, alphaParams=list(c(rep(0.2,5))), betaParams=list(c(0.5)),
                      sigma=1, xvts=xvts, lambdaParams=lambdaParams)

#Design matrix to fit GNARX(2,[1,1]) to the fiveVTS data

Xdesign <- GNARXdesign(vts = Y_data, net = GNAR::fiveNet, globalalpha = TRUE, alphaOrder = 1,
                betaOrder = 1, xvts = xvts, lambdaOrder = c(1,1))

Xdesign

Description

Fits the GNARX model to the given inputs using GNARdesignX and lm.

Usage

GNARXfit(vts=GNAR::fiveVTS, net=GNAR::fiveNet, alphaOrder=2, betaOrder=c(1,1),
 fact.var=NULL, globalalpha=TRUE, tvnets=NULL, netsstart=NULL, ErrorIfNoNei=TRUE, 
 xvts=NULL, lambdaOrder=NULL)

Arguments

Details

The GNAR model of order $(p,S)$ is defined as

$X_{i,t} = \sum_{j=1}^p \left( \alpha_{i,j} X_{i,t-j} +\sum_{c=1}^C \sum_{r=1}^{S_j} \beta_{j,r, c}\sum_{q \in {N}^{(r)}_t(i)} \omega_{i,q,c}^{(t)} X_{q,t-j} \right) + u_{i,t}$

where $p$ is the maximum time lag, $S=(S_1,...,S_p)$ and $S_j$ is the maximum stage of neighbour dependence for time lag $j$, ${N}^{(r)}_t(i)$ is the $r$th stage neighbour set of node $i$ at time $t$, $\omega_{i,q,c}^{(t)}$ is the connection weight between node $i$ and node $q$ at time $t$ if the path corresponds to covariate $c$. Here, we consider a sum from one to zero to be zero and $\{u_{i,t}\}$, are assumed to be independent and identically distributed at each node $i$, with mean zero and variance $\sigma_i^2$. Currently, only a single network GNAR model can be fitted. The connection weight, $\omega_{i,q,c}^{(t)}$, is the inverse of the distance between nodes i and q, normalised so that they sum to 1 for each i,t. See is.GNARnet for GNARnet object information and example construction.

A GNARX process of order $p$, neighbourhood order vector $s$ of length $p$ and $H$ node-specific time series exogenous variables with order vector $p'$, denoted GNARX $(p, s, p')$, is given by

$Y_{i,t}=\sum_{j=1}^{p}\left(\alpha_{i,j}Y_{i,t-j} + \sum_{r=1}^{s_j} \beta_{j,r} \sum_{q\in\mathcal{N}^{(r)}(i)}\omega_{i,q}Y_{q,t-j}\right)+ {\color{blue} \sum_{h=1}^H \sum_{j'=0}^{p'_h} \lambda_{h,j'} X_{h,i,t-j'}+u_{i,t}},$

where $u_{i, t}$ are assumed to be set of mutually uncorrelated random variables with mean zero and variance of $\sigma^2$.

Value

References

Knight, M.I., Nunes, M.A. and Nason, G.P. Modelling, detrending and decorrelation of network time series. arXiv preprint.

Knight, M.I., Leeming, K., Nason, G.P. and Nunes, M. A. (2020) Generalised Network Autoregressive Processes and the GNAR package. Journal of Statistical Software, 96 (5), 1–36.

Nason G.P. and Wei J. (2022) Quantifying the economic response to COVID-19 mitigations and death rates via forecasting Purchasing Managers’ Indices using Generalised Network Autoregressive models with exogenous variables. Journal of the Royal Statistical Society Series A, 185, 1778–1792.

Examples

set.seed(1)
n = 1000
xvts=list()
xvts[[1]] = matrix(rnorm(5*n, mean=0, sd=2), nrow=n, ncol=5)
xvts[[2]] = matrix(rnorm(5*n, mean=0, sd=2), nrow=n, ncol=5)
lambdaParams=list()
lambdaParams[[1]] = c(0.5, -0.5)
lambdaParams[[2]] = c(0.3, 0.1)

# Simulate the GNARX using the exogenous variables xvts with associated parameters lambdaParams

Y_data <- GNARXsim(n=n, net=GNAR::fiveNet, alphaParams=list(c(rep(0.2,5))), betaParams=list(c(0.5)),
                      sigma=1, xvts=xvts, lambdaParams=lambdaParams)

# fit a GNARX to the model

model <- GNARXfit(vts = Y_data, net = GNAR::fiveNet,globalalpha = TRUE, alphaOrder = 1,
                betaOrder = 1, xvts = xvts, lambdaOrder = c(1,1))

# look at the residuals
residToMat(model)$resid

Description

Simulates a GNAR process with Normally distributed innovations.

Usage

GNARXsim(n=200, net=GNAR::fiveNet, alphaParams=list(c(rep(0.2,5))),
	betaParams=list(c(0.5)), sigma=1, tvnets=NULL, netsstart=NULL, xvts=NULL, 
	lambdaParams=NULL)

Arguments

Details

Parameter lists should not be NULL, set unused parameters to be zero. See GNARXfit for model description.

Value

GNARXsim returns the multivariate time series as a ts object, with n rows and a column for each of the nodes in the network.

References

Knight, M.I., Nunes, M.A. and Nason, G.P. Modelling, detrending and decorrelation of network time series. arXiv preprint.

Knight, M.I., Leeming, K., Nason, G.P. and Nunes, M. A. (2020) Generalised Network Autoregressive Processes and the GNAR package. Journal of Statistical Software, 96 (5), 1–36.

Nason G.P. and Wei J. (2022) Quantifying the economic response to COVID-19 mitigations and death rates via forecasting Purchasing Managers’ Indices using Generalised Network Autoregressive models with exogenous variables. Journal of the Royal Statistical Society Series A, 185, 1778–1792.

Examples

#Simulate a GNARX process with the fiveNet network

set.seed(1)
n = 1000
xvts=list()
xvts[[1]] = matrix(rnorm(5*n, mean=0, sd=2), nrow=n, ncol=5)
xvts[[2]] = matrix(rnorm(5*n, mean=0, sd=2), nrow=n, ncol=5)
lambdaParams=list()
lambdaParams[[1]] = c(0.5, -0.5)
lambdaParams[[2]] = c(0.3, 0.1)

# Simulate the GNARX using the exogenous variables xvts with associated parameters lambdaParams
 
Y_data <- GNARXsim(n=n, net=GNAR::fiveNet, alphaParams=list(c(rep(0.2,5))), betaParams=list(c(0.5)),
                      sigma=1, xvts=xvts, lambdaParams=lambdaParams)

# now try to refit the model
 
model <- GNARXfit(vts = Y_data, net = GNAR::fiveNet,globalalpha = TRUE, alphaOrder = 1, 
		betaOrder = 1, xvts = xvts, lambdaOrder = c(1,1))

model

Description

Converts an 'igraph' to the GNARnet form for use as an input to GNAR functions.

Usage

igraphtoGNAR(ig)

Arguments

Details

The values in the $dist list are the reciprocal of the values from the weighted adjacency matrix.

Value

igraphtoGNAR returns a GNARnet: a list with elements $edges and $dist.

Examples

#Convert fiveNet to igraph and back again
igraphtoGNAR(GNARtoigraph(fiveNet))

Description

is.GNARfit returns either TRUE or FALSE according to a series of GNARfit checks.

Usage

is.GNARfit(x)

Arguments

Details

The is.GNARfit function checks whether the object passes a series of tests that correspond to it being the output of GNARfit:

• Is it a list containing $mod and $frbic

• Does it contain either $y and $dd or $ys and $ds

• Is $mod a lm object

• Does $frbic have the components to calculate the BIC with BIC.GNARfit

Value

is.GNARfit returns TRUE or FALSE corresponding to passing the above tests.

Examples

#check that the example fit meets the criteria above
is.GNARfit(GNARfit())

Description

is.GNARnet returns either TRUE or FALSE according to a series of GNARnet checks. as.GNARnet returns a GNARnet object from an input weights matrix, 'igraph' object, or a GNARnet without assigned class.

Usage

is.GNARnet(x)
as.GNARnet(x)

Arguments

Details

The is.GNARnet function checks whether the network passes a series of tests:

• Is it a list containing $edges and $dist

• Are the $edges and $dist lists of the same length

• Are each of the elements of $edges the same length as the corresponding $dist element

• Do the edges only contain valid entries, 1,...,nnodes (or NULL)

• Is it labelled as GNARnet class

• Are no duplicate edges present

• Are all distances positive

• Are there no self-loops in the network

The as.GNARnet function converts igraph objects to GNARnet form, other possible inputs are adjacency matrices, and lists with $edges and $dist entries of the correct form.

Value

is.GNARnet returns TRUE or FALSE corresponding to passing the above tests. as.GNARnet returns a GNARnet object.

Examples

#check that the example network meets the criteria above
is.GNARnet(fiveNet)

#convert to igraph and back again
as.GNARnet(GNARtoigraph(fiveNet))

#generate a new network with three nodes
#edges 1->2, 2->1, 2->3
#dist 1, 2, 1
#note 1->2 and 2->1 are of different lengths
threeEdge <- list(c(2), c(1,3), NULL)
threeDist <- list(c(1), c(2,1), NULL)
threeNet <- list(edges=threeEdge, dist=threeDist)
#check if this is a GNARnet
is.GNARnet(threeNet)
#use as.GNARnet to change the class
threeNet <- as.GNARnet(threeNet)
#check if this is a GNARnet now
is.GNARnet(threeNet)

Description

Produces a local neighbourhood relevance plot based on the distances in the underlying network. The heat-map matrix should reflect clusters if a GNAR model is valid. The size of the clusters depends on the maximum r-stage depth for neighbourhood regression, as $r^*$ gets larger, the clusters grow or intersect and cover more nodes. The relative strength of conditionally correlated nodes is $\mathrm{rscc} (i, j) := \{ d(i,j) \}^{-1} \mathbb{I} \{ d(i, j) \leq r^* \} + \{2 d(i,j) \}^{-1} \mathbb{I} \{ r^* < d(i, j) \leq 2 r^* \}$.

Usage

local_relevance_plot(network, r_star)
  cross_correlation_plot(h, vts)

Arguments

Value

Produces the local relevance plot. Does not return any values.

Author(s)

Daniel Salnikov and Guy Nason

References

Nason, G.P., Salnikov, D. and Cortina-Borja, M. (2023) New tools for network time series with an application to COVID-19 hospitalisations. https://arxiv.org/abs/2312.00530

Examples

#
# Produces a local relevance plot, which is a heat-map matrix from a stationary 
# GNAR(1, [1]) simulation.
#
gnar_simulation <- GNARsim(n = 100, net=fiveNet, alphaParams = list(rep(0.35, 5)), 
        betaParams = list(c(0.25)), sigma=1)
# Active node plot
local_relevance_plot(fiveNet, 1)
# Compare to the cross-correlation plot at one-lag
cross_correlation_plot(1, gnar_simulation)

Description

Returns the log-likelihood for a GNARfit object.

Usage

## S3 method for class 'GNARfit'
logLik(object,...)

Arguments

Details

S3 method for the GNARfit class. The function returns the value of

$-TN/2 \log(2 \pi) - T/2 \log(| \Sigma |) - 1/2 trace(E \Sigma^{-1} E'),$

where $T$ is the time length of the observations, $N$ is the number of nodes, $\Sigma = E E' /T$ is the estimated covariance matrix and $E$ is the matrix of residuals.

Value

A logLik object.

Examples

#calculate log-likelihood for fiveNode data
#global alphas
logLik(GNARfit())
#individual alphas
logLik(GNARfit(globalalpha=FALSE))

Description

This matrix contains a multivariate/vector time series that counts the number of daily admissions to mechanical ventilation beds in one of 140 NHS Trusts from 2nd April 2020 to 27th June 2021.

Format

The dimension of the matrix is 452x140. The dates and Trust ID codes are stored in the dimnames (first and second) respectively.

SEE ALSO

corbit_plot,NHSTrustMVCAug120.net

Author(s)

Daniel Salnikov and Guy Nason

Source

UK Coronavirus website https://ukhsa-dashboard.data.gov.uk

References

Nason, G.P., Salnikov, D. and Cortina-Borja, M. (2023) New tools for network time series with an application to COVID-19 hospitalisations. https://arxiv.org/abs/2312.00530

Examples

## Not run: 
data(logMVbedMVC.vts)
data(NHSTrustMVCAug120.net)

#
# Do a corbit plot with this data, with only three lags and one stage
#
# Note, normally max_lag and max_stage would be higher than this, the
# values are artificially small here, as otherwise the run-time restrictions
# for CRAN packaging might be exceeded. 

corbit_plot(vts=logMVbedMVC.vts, net=NHSTrustMVCAug120.net, max_lag=3, max_stage=1)

## End(Not run)

Description

Converts an adjacency matrix to the GNARnet form for use as an input to GNAR functions.

Usage

matrixtoGNAR(input.mat)

Arguments

Details

The values in the $dist list are the reciprocal of the values from the weighted adjacency matrix. Any self-loops (diagonal entries) and negatively weighted edges are removed.

Value

matrixtoGNAR returns a GNARnet list with elements $edges and $dist.

Examples

#Convert fiveNet to an adjacency matrix and back again
matrixtoGNAR(as.matrix(fiveNet))

Description

Returns a vector with elements TRUE/FALSE identifying which rows contain NA elements.

Usage

na.row(mat)

Arguments

Details

This function is used in the unstacking of residuals into a residual matrix and replacing NAs where they were previously present.

Value

na.row returns a vector of length equal to the number of rows in mat. Each element is either TRUE or FALSE.

Examples

#Check if there are and NAs in fiveVTS
na.row(fiveVTS)

Description

Computes the NACF for a choice of lag $h$ and r-stage depth $r$, the NACF is given by $\mathrm{nacf}(h, r) = \frac{\sum_{t=1}^{T - h} ( \boldsymbol{X}_{t + h} - \boldsymbol{\overline{X}})^{T} \big ( \mathbf{W} \odot \mathbf{S}_r + \mathbf{I_d} \big ) ( \boldsymbol{X}_{t} - \boldsymbol{\overline{X}})} {\sum_{t=1}^{T} ( \boldsymbol{X}_{t} - \boldsymbol{\overline{X}})^{T} \big \{ \big (1 + \lambda \big) \mathbf{I_d} \big \} ( \boldsymbol{X}_{t} - \boldsymbol{\overline{X}})},$ where $\lambda = \bigg [ \underset{j = 1, \dots, d}{\max} \big \{\sum_{i = 1}^d [(\mathbf{W} \odot \mathbf{W})]_{i j} \big \} \bigg ]^{\frac{1}{2}}$ is the autocovariance bound of the GNAR process.

Usage

nacf(h, s, weight_matrix, stages_tensor, nts_data)

Arguments

Details

If the network time series contains missing values, then the weights matrix and $\lambda$ are adjusted, so that missing values do not contribute to the network autocorrelation. This is done by setting to zero the weights which correspond to a missing value and computing the new weight matrix and $\lambda$ value.

Value

Returns a number between $-1$ and $1$, which measures the linear correlation between lagged network observations - i.e., $\mathrm{nacf}(h, r)$.

Author(s)

Daniel Salnikov and Guy Nason.

References

Nason, G.P., Salnikov, D. and Cortina-Borja, M. (2023) New tools for network time series with an application to COVID-19 hospitalisations. https://arxiv.org/abs/2312.00530

Examples

#
# Compute the NACF with respect to a stationary GNAR simulation
#
gnar_simulation <- GNARsim(n = 100, net=fiveNet, alphaParams = list(rep(0.35, 5)), 
                           betaParams = list(c(0.25)), sigma=1)
W = weights_matrix(fiveNet)
stages_list = get_k_stages_adjacency_tensor(as.matrix(GNARtoigraph(fiveNet)), 3)
# NACF
nacf(3, 1, W, stages_list, gnar_simulation)

Description

This matrix contains a multivariate/vector time series that counts the number of daily admissions to mechanical ventilation beds in one of 140 NHS Trusts from 2nd April 2020 to 27th June 2021.

Format

An object of class GNARnet from the GNAR package

Author(s)

Daniel Salnikov and Guy Nason

Source

UK Coronavirus website https://ukhsa-dashboard.data.gov.uk

References

Nason, G.P., Salnikov, D. and Cortina-Borja, M. (2023) New tools for network time series with an application to COVID-19 hospitalisations. https://arxiv.org/abs/2312.00530

See Also

corbit_plot,NHSTrustMVCAug120.net

Examples

## Not run: 
data(logMVbedMVC.vts)
data(NHSTrustMVCAug120.net)

#
# Plot the network and see what it is like
#
plot(NHSTrustMVCAug120.net)

#
# Do a corbit plot with this data, with only three lags and one stage
#
# Note, normally max_lag and max_stage would be higher than this, the
# values are artificially small here, as otherwise the run-time restrictions
# for CRAN packaging might be exceeded. 

corbit_plot(vts=logMVbedMVC.vts, net=NHSTrustMVCAug120.net, max_lag=3, max_stage=1)

## End(Not run)

Description

nobs returns the number of obervations (T) of the input multivariate time series in the GNARfit function.

Usage

## S3 method for class 'GNARfit'
nobs(object,...)

Arguments

Details

S3 method for class "GNARfit".

Value

An integer specifying the number of rows in the input vts to the GNARfit function.

Examples

#observations of example fiveVTS
nobs(GNARfit())
#check this is the same as number of rows in fiveVTS
all.equal(nobs(GNARfit()), nrow(fiveVTS))

Description

Produces a node relevance plot based on the node relevance index $\mathrm{globindex}(X_{i, t}) := \bigg (\sum_{j = 1}^{d} [\mathbf{W} \odot \mathbf{S}]_{j i} \bigg ) \bigg \{ \underset{l \in \mathcal{K}}{\max} \bigg ( \sum_{j = 1}^{d} [\mathbf{W} \odot \mathbf{S}]_{j l} \bigg ) \bigg \}^{-1},$ which computes the ratio between nodes $i$ column sum for nodes in neighbourhood regressions. Nodes are ordered according to the relative contribution eahc has to the autocovariance. The nodes are ordered in ascending order.

Usage

node_relevance_plot(network, r_star, node_names, node_label_size = 2)

Arguments

Value

Data Frame consisting of two variable, the node name and the node relevance value.

Author(s)

Daniel Salnikov and Guy Nason.

References

Nason, G.P., Salnikov, D. and Cortina-Borja, M. (2023) New tools for network time series with an application to COVID-19 hospitalisations. https://arxiv.org/abs/2312.00530

Examples

#
# Produces a node relevance plot with respect to a stationary GNAR process 
# with underlying network fiveNet
#
# GNAR simulation
gnar_simulation <- GNARsim(n = 100, net=fiveNet, alphaParams = list(rep(0.25, 5), rep(0.12, 5)), 
        betaParams = list(c(0.25, 0.13), c(0.20)), sigma=1)
# Node relevance plot without names
node_relevance_plot(network = fiveNet, r_star = 2, node_label_size = 10)
#
# Node relevance plot with names
#
node_relevance_plot(network = fiveNet, r_star = 2, node_names = c("A", "B", "C", "D", "E"), 
	node_label_size = 10)

Description

Calculates neighbour sets of a particular node in the network and their distances.

Usage

NofNeighbours(node=1, stage=2, net=GNAR::fiveNet)

Arguments

Details

Note that the distances are calculated as the sum along the shortest path; do not use this with a weights (rather than distance) list. Stage-r neighbours of node i are denoted $N^(r)(i)$, and are nodes that are r edges (but no fewer) away from i. Hence stage-1 neighbours are the immediate neighbours, stage-2 neighbours are the neighbours of neighbours and so on.

Value

Examples

#First and second stage neighbours of node 1 in fiveNet
NofNeighbours()

Description

Plots a GNAR network using the 'igraph' package.

Usage

## S3 method for class 'GNARnet'
plot(x, ...)

Arguments

Details

S3 method for class "GNARnet".

Examples

#Plot fiveNet
plot(fiveNet)

Description

Computes the PNACF for a choice of lag $h$ and r-stage depth $r$, the PNACF is given by $\mathrm{pnacf}(h, r) = \frac{\sum_{t=1}^{T - h} ( \boldsymbol{\hat{u}}_{t + h} - \boldsymbol{\overline{u}})^{T} \big ( \mathbf{W} \odot \mathbf{S}_r + \mathbf{I_d} \big ) ( \boldsymbol{\hat{u}}_{t} - \boldsymbol{\overline{u}})} {\sum_{t=1}^{T} ( \boldsymbol{\hat{u}}_{t} - \boldsymbol{\overline{u}})^{T} \big \{ \big (1 + \lambda \big) \mathbf{I_d} \big \} ( \boldsymbol{\hat{u}}_{t} - \boldsymbol{\overline{u}})},$ where $\hat{\boldsymbol{X}}_{t}^{h - 1, r - 1} = \sum_{k = 1}^{h - 1} ( \hat{\alpha}_k \boldsymbol{X}_{t - k} + \sum_{s = 1}^{r - 1} \hat{\beta}_{ks} \boldsymbol{Z}_{t - k}^{s} )$, $\boldsymbol{\hat{u}}_{t + h} = \boldsymbol{X}_{t + h} - \hat{\boldsymbol{X}}_{t + h}^{h - 1, r - 1}$, and $\boldsymbol{\hat{u}}_{t} = \boldsymbol{X}_{t} - \hat{\boldsymbol{X}}_{t}^{h - 1, r - 1}$ are the empirical residuals corresponding to GNAR(h -1, [r-1, ..., r - 1]) fits, $\lambda$ is the same as for the NACF; see nacf, and $\boldsymbol{\overline{u}}$ is the mean of the fitted residuals

Usage

pnacf(h, s,  weight_matrix, stages_tensor, nts_data)

Arguments

Value

If the network time series contains missing values, then the weights matrix and $\lambda$ are adjusted, so that missing values do not contribute to the partial network autocorrelation. This is done by setting to zero the weights which correspond to a missing value and computing the new weight matrix and $\lambda$ value.

Author(s)

Daniel Salnikov and Guy Nason

References

Nason, G.P., Salnikov, D. and Cortina-Borja, M. (2023) New tools for network time series with an application to COVID-19 hospitalisations. https://arxiv.org/abs/2312.00530

Examples

#
# Compute the PNACF with respect to a stationary GNAR simulation
#
gnar_simulation <- GNARsim(n = 100, net=fiveNet, alphaParams = list(rep(0.35, 5)), 
                           betaParams = list(c(0.25)), sigma=1)
W = weights_matrix(fiveNet)
stages_list = get_k_stages_adjacency_tensor(as.matrix(GNARtoigraph(fiveNet)), 3)
# PNACF
pnacf(3, 1, W, stages_list, gnar_simulation)

Description

Predicts future observations from a GNARfit object, based on the fitted GNAR model.

Usage

## S3 method for class 'GNARfit'
predict(object, n.ahead=1, ...)

Arguments

Details

S3 method for class "GNARfit". This function calls simulate.GNARfit.

Value

A multivariate time series of dimension n.ahead x nnodes.

Examples

#simulate 5 future observations from fiveVTS
predict(GNARfit(), n.ahead=5)

Description

print.GNARfit prints model, call, and coefficients of a GNARfit object.

Usage

## S3 method for class 'GNARfit'
print(x,...)

Arguments

Details

S3 method for class "GNARfit".

Examples

#print the information of the fiveNode GNAR fit
print(GNARfit())

Description

Prints information about a GNAR network.

Usage

## S3 method for class 'GNARnet'
print(x, ...)

Arguments

Details

S3 method for class "GNARnet".

Examples

#print fiveNet information
print(fiveNet)

Description

Produces a R-Corbit plot for comparing the network autocorrelation (NACF) and partial network autocorrelation function (PNACF) values for a choice of maximum lag and maximum $r$-stage depth. Starting from the first and continuing to the outermost ring, each ring corresponds to said choice of $r$-stage depth. The numbers on the outermost ring are time-lags, and each dot corresponds to a specific time-slice or covariate-level.

Usage

r_corbit_plot(vts_frames, network_list, max_lag, max_stage, weight_matrices, 
frame_names, same_net="no", viridis_color_option="viridis", size_option="absolute_val", 
partial="no", r_corbit="yes")

Arguments

Details

R-Corbit plots compare the network autocorrelation function (NACF) and partial network autocorrelation function (PNACF) values for a choice of different time-slices and/or covariate-levels. R-Corbit plots are read in the same manner as Corbit plots corbit_plot, and include a legend on the right-hand side for distinguishing between covariate-levels and/or time-slices. The point at the centre is the mean value of the NACF or PNACF values arising from the time-slices and/or covariate-levels data splits. Essentially, if $c \in \{1, \dots, C\}$, where $C \in \mathbb{N}$ is the number of covariate-levels or time-slices, then the value at the centre is $\mathrm{(p)nacf}(h, r) = C^{-1} \sum_{c = 1}^{C} \mathrm{(p)nacf}_c (h, r),$ where $\mathrm{(p)nacf}_c(h, r)$ is the (P)NACF value corresponding to the covariate-level/time-slice $c$. The number of covariate-levels and time-slices $C$ must be equal to the length of the lists used for producing the R-Corbit plot.

Value

Produces the specified, i.e., NACF or PNACF, values for a choice of lag and $r$-stage depth, $(h, r)$, R-Corbit plot. Does not print (P)NACF values, these are stored as invisble data frames (matrices), and can be accessed by printing or calling the object produced by the r_corbit_plot call. The invisible object is a list of matrices, one matrix for each covariate-level/time-slice.

Author(s)

Guy Nason and Daniel Salnikov

References

Nason, G.P., Salnikov, D. and Cortina-Borja, M. (2023) New tools for network time series with an application to COVID-19 hospitalisations. https://arxiv.org/abs/2312.00530

Examples

## Not run: 
#
# Produces a R-Corbit plot, which compares three stationary GNAR simulations, where 
# the underlying network is fiveNet.
#
# Compute the weight matrix
W = weights_matrix(fiveNet)
#
# Simulate three stationary GNAR processe
sim1 <-  GNARsim(n = 100, net=fiveNet, alphaParams = list(c(0.1, 0.12, 0.16, 0.075, 0.21),
                                                          c(0.12, 0.14, 0.15, 0.6, 0.22)), 
                 betaParams = list(c(0.1, 0.16), c(0.11, 0.14)))

sim2 <-  GNARsim(n = 100, net=fiveNet, alphaParams = list(rep(.25, 5)), 
                 betaParams = list(c(0.1, 0.16)))

sim3 <- GNARsim(n = 100, net=fiveNet, alphaParams = list(rep(.25, 5), rep(0.13, 5)), 
                betaParams = list(c(0.1, 0.16), c(0.11)))
                
# Produce NACF R-Corbit plot with the same network and weights matrix
r_corbit_plot(list(sim1, sim2, sim3), list(fiveNet), 10, 3, list(W), 
		c("sim1", "sim2", "sim3"), same_net = "yes")
# 
# Produce PNACF R-Corbit with different networks and weight matrices
print(r_corbit_plot(list(sim1, sim2, sim3), list(fiveNet, fiveNet, fiveNet), 10, 3, list(W, W, W),
		 c("sim1", "sim2", "sim3"), same_net = "no", partial = "yes"))


## End(Not run)

Description

Unstacks the entries of the GNARfit fitted and residual values to return matrices of a similar form to the multivariate time series input.

Usage

residToMat(GNARobj=GNARfit(), nnodes=5)

Arguments

Details

This function also replaces the NAs that were removed in fitting.

Value

Examples

#Get residual and fitted matrices from GNARpredict fit of fiveVTS
residToMat()

Description

residuals.GNARfit returns the residuals of a GNARfit object as a matrix.

Usage

## S3 method for class 'GNARfit'
residuals(object,...)

Arguments

Details

The function first checks if the object is of GNARfit class, then uses residToMat to return the residuals.

Value

residuals.GNARfit returns a 'ts' object of residuals, with t-alphaOrder rows and nnodes columns.

Examples

#get the residuals of the fiveNode GNAR fit
residuals(GNARfit())

Description

Seed numbers for reproducible random graphs.

Usage

seed.nos

Format

seed.nos is a vector of length 10,000 containing integers.

Examples

g <- seedToNet(seed.nos[1], nnodes=35, graph.prob=0.15)
plot(g, vertex.label=colnames(gdpVTS), vertex.size=0)

Description

Produces a reproducible undirected Erdos-Reyni random network using a particular seed value.

Usage

seedToNet(seed.no, nnodes=34, graph.prob=0.5)

Arguments

Details

graph.prob effectively controls the sparsity of the network. All distances are set to 1.

Value

A GNARnet object.

Examples

#Generate the random graph from seed 10, with 5 nodes and connection prob 0.5
seedToNet(10,nnodes=5,graph.prob=0.5)

Description

Simulates from a GNARfit object, either creating a new series or future observations of the original series based upon the fitted GNAR model.

Usage

## S3 method for class 'GNARfit'
simulate(object, nsim=object$frbic$time.in, seed=NULL,
                             future=TRUE, set.noise=NULL, allcoefs=FALSE, ...)

Arguments

Details

S3 method for class "GNARfit".

Value

A multivariate time series of dimension nsim x nnodes.

Examples

#simulate 5 future observations from fiveVTS
simulate(GNARfit(), nsim=5)

Description

Returns the summary of a GNARfit object, including BIC.

Usage

## S3 method for class 'GNARfit'
summary(object, ...)

Arguments

Details

The output is the summary of the fit using summary.lm, and BIC calculated using BIC.GNARfit.

Value

summary.GNARfit prints the model summary and the value of the BIC.

Examples

#summary for the GNAR(2,[1,1]) model using GNARfit on fiveVTS
summary(GNARfit())

Description

Prints brief information about a GNAR network.

Usage

## S3 method for class 'GNARnet'
summary(object, ...)

Arguments

Details

S3 method for class "GNARnet".

Examples

#print fiveNet summary information
summary(fiveNet)

Description

Returns the varaince-covariance matrix of the parameters of a GNARfit object.

Usage

## S3 method for class 'GNARfit'
vcov(object,...)

Arguments

Details

S3 method for class "GNARfit".

Value

A matrix of estimated covariances between the parameter estimates, this is calculated using vcov for lm objects.

Examples

#covariance matrix of fiveNode fit
vcov(GNARfit())

Description

A suite of data objects concerning wind speed analysis. The dataset contains a multivariate time series of wind speeds, two network descriptions, a vector of names for weather stations, and the coordinates of the weather stations.

Usage

data("vswind")

Format

This dataset contains six R objects:
vswindts is a ts object with a matrix of 721 rows (t=721) and 102 columns (n=102). This corresponds to 721 observations made through time at 102 weather stations. vswindnetD is a GNARnet object containing $edges and $dist.
edges is a list of length 102, with edges[[i]] containing the vertices that node i is connected to.
dist is a list of length 102, with dist[[i]] containing the length of the vertices that node i is connected to. vswindnet is the same as vswindnetD except that all the distances are replaced by 1. vswindnames is a character vector of length 102 containing the wind speed site names and vswindcoords is a matrix with 102 rows (one for each wind station) and two columns providing the x and y coordinates of the weather stations.

Source

The base data were obtained from the http://wow.metoffice.gov.uk UK Met Office WeatherObservationsWebsite distributed under the UK Open Government License https://www.nationalarchives.gov.uk/doc/open-government-licence/version/1/open-government-licence.htm Contains public sector information licensed under the Open Goverment Licence v1.0.

See Also

windnetplot

Examples

#
# The name entry for Bristol
#
vswindnames[77]
#[1] "BRIST"
#
# plot the distance network
#
## Not run: windnetplot()

Description

Computes the weights matrix with normalised weights (i.e., add up to one) for the network time series with underlying network provided by the user. If the network is unweighted, then each r-stage neighbour is considered equally relevant, i.e., $w_{ij}$ = $\{ \mathcal{N}_r (i)\}^{-1} \mathbb{I} (d(i, j) = r)$, where $\mathbb{I}$ is the indicator function and the distance is the shortest path in the underlying network.

Usage

weights_matrix(network, max_r_stage)

Arguments

Value

Weight matrix $\mathbf{W}$, each entry is the weight $w_{ij}$ between a pair of nodes. The matrix is not symmetric, and each row adds up to one when considering r-stage neighbours for a particular r.

Author(s)

Daniel Salnikov and Guy Nason.

References

Nason, G.P., Salnikov, D. and Cortina-Borja, M. (2023) New tools for network time series with an application to COVID-19 hospitalisations. https://arxiv.org/abs/2312.00530

Examples

#
# Weights matrix linked to the mechanical ventilation beds time series. 
# This network has a longest shortest path equal to six.
# 
#data(fiveNet)
W_norm = weights_matrix(fiveNet, 6)

Description

Plots the wind speed data network with distance information.

Usage

windnetplot()

Arguments

None.

Details

The wind speed data is to be found in the vswind data set. This function contains commands, using functionality from the wordcloud package, to plot the network, with node names and edges. Distances between nodes are plotted next to the edges.

See Also

vswind

Examples

## Not run: windplotnet()