Package 'MetricGraph'

Description

'MetricGraph' is used for creation and manipulation of metric graphs, such as street or river networks. It also has several functions thatfacilitates operations and visualizations of data on metric graphs, and the creation of a large class of random fields and stochastic partial differential equations on such spaces. The main models are the Whittle-Matérn fields, which are specified through the fractional elliptic SPDE

$(\kappa^2 - \Delta)^{\alpha/2} (\tau u(s)) = W,$

$\kappa,\tau>0$ and $\alpha>1/2$ are parameters and $W$ is Gaussian white noise. It contains exact implementations of the above model for $\alpha=1$ and $\alpha=2$, and contains approximate implementations, via the finite element method, for any $\alpha > 0.5$. It also implements models based on graph Laplacians and isotropic covariance functions. Several utility functions for specifying graphs, computing likelihoods, performing prediction, simulating processes, and visualizing results on metric graphs are provided. In particular, linear mixed effects models including random field components can be fitted to data based on computationally efficient sparse matrix representations. Interfaces to the R packages 'INLA' and 'inlabru' are also provided, which facilitate working with Bayesian statistical models on metric graphs.

Details

At the heart of the package is the R6 class ⁠[metric_graph()]⁠. This is used for specifying metric graphs, and contains various utility functions which are needed for specifying Gaussian processes on such spaces.

Linear mixed effects models are provided (see ⁠[graph_lme]⁠) and perform predictions (see ⁠[predict.graph_lme]⁠). The package also has interfaces for 'INLA' (see ⁠[graph_spde]⁠), and it this interface also works with 'inlabru'.

For a more detailed introduction to the package, see the 'MetricGraph' Vignettes.

Author(s)

Maintainer: David Bolin [email protected]

Authors:

• Alexandre Simas [email protected]

• Jonas Wallin [email protected]

See Also

Useful links:

• https://davidbolin.github.io/MetricGraph/

• Report bugs at https://github.com/davidbolin/MetricGraph/issues

Description

Augment accepts a model object and a dataset and adds information about each observation in the dataset. It includes predicted values in the .fitted column, residuals in the .resid column, and standard errors for the fitted values in a .se.fit column. It also contains the New columns always begin with a . prefix to avoid overwriting columns in the original dataset.

Usage

## S3 method for class 'graph_lme'
augment(
  x,
  newdata = NULL,
  which_repl = NULL,
  sd_post_re = FALSE,
  se_fit = FALSE,
  conf_int = FALSE,
  pred_int = FALSE,
  level = 0.95,
  edge_number = "edge_number",
  distance_on_edge = "distance_on_edge",
  coord_x = "coord_x",
  coord_y = "coord_y",
  data_coords = c("PtE", "spatial"),
  normalized = FALSE,
  no_nugget = FALSE,
  check_euclidean = FALSE,
  ...
)

Arguments

Value

A tidyr::tibble() with columns:

• .fitted Fitted or predicted value.

• .relwrconf Lower bound of the confidence interval of the random effects, if conf_int = TRUE

• .reuprconf Upper bound of the confidence interval of the random effects, if conf_int = TRUE

• .fittedlwrpred Lower bound of the prediction interval, if conf_int = TRUE

• .fitteduprpred Upper bound of the prediction interval, if conf_int = TRUE

• .fixed Prediction of the fixed effects.

• .random Prediction of the random effects.

• .resid The ordinary residuals, that is, the difference between observed and fitted values.

• .std_resid The standardized residuals, that is, the ordinary residuals divided by the standard error of the fitted values (by the prediction standard error), if se_fit = TRUE or pred_int = TRUE.

• .se_fit Standard errors of fitted values, if se_fit = TRUE.

• .sd_post_re Standard deviation of the posterior mean of the random effects, if se_fit = TRUE.

See Also

glance.graph_lme

Description

Metric graph 'inlabru' mapper

Usage

bru_get_mapper.inla_metric_graph_spde(model, ...)

ibm_n.bru_mapper_inla_metric_graph_spde(mapper, ...)

ibm_values.bru_mapper_inla_metric_graph_spde(mapper, ...)

ibm_jacobian.bru_mapper_inla_metric_graph_spde(mapper, input, ...)

Arguments

Description

Applies tidyr::drop_na() function for datasets obtained from a metric graph object.

Usage

## S3 method for class 'metric_graph_data'
drop_na(data, ...)

Arguments

Value

A tidyr::tibble with the resulting selected columns.

Description

Evaluates the exponential covariance function

$C(h) = \sigma^2 \exp\{-kappa h\}$

Usage

exp_covariance(h, theta)

Arguments

Value

A vector with the values of the covariance function.

Description

Applies dplyr::filter() function for datasets obtained from a metric graph object.

Usage

## S3 method for class 'metric_graph_data'
filter(.data, ...)

Arguments

Value

A tidyr::tibble with the resulting selected columns.

Description

Returns a 'ggplot2'-friendly data-frame with the marginal posterior densities.

Usage

## S3 method for class 'metric_graph_spde_result'
gg_df(
  result,
  parameter = result$params,
  transform = TRUE,
  restrict_x_axis = parameter,
  restrict_quantiles = list(sigma = c(0, 1), range = c(0, 1), kappa = c(0, 1), sigma =
    c(0, 1)),
  ...
)

Arguments

Value

A data.frame containing the posterior densities.

Description

Glance accepts a graph_lme object and returns a tidyr::tibble() with exactly one row of model summaries. The summaries are the square root of the estimated variance of the measurement error, residual degrees of freedom, AIC, BIC, log-likelihood, the type of latent model used in the fit and the total number of observations.

Usage

## S3 method for class 'graph_lme'
glance(x, ...)

Arguments

Value

A tidyr::tibble() with exactly one row and columns:

• nobs Number of observations used.

• sigma the square root of the estimated residual variance

• logLik The log-likelihood of the model.

• AIC Akaike's Information Criterion for the model.

• BIC Bayesian Information Criterion for the model.

• deviance Deviance of the model.

• df.residual Residual degrees of freedom.

• model.type Type of latent model fitted.

See Also

augment.graph_lme

Description

Prepare data frames or data lists to be used with 'inlabru' in metric graphs

Usage

graph_bru_process_data(
  data,
  edge_number = "edge_number",
  distance_on_edge = "distance_on_edge",
  loc = "loc"
)

Arguments

Value

A list containing the processed data to be used in a user-friendly manner by 'inlabru'.

Description

Class representing connected components of a metric graph.

Details

A list of metric_graph objects (representing the different connected components in the full graph) created from vertex and edge matrices, or from an sp::SpatialLines object where each line is representing and edge. For more details, see the vignette: vignette("metric_graph", package = "MetricGraph")

Value

Object of R6Class for creating metric graph components.

Public fields

Methods

Public methods

• graph_components$new()

• graph_components$get_largest()

• graph_components$plot()

• graph_components$clone()

Method new()

Usage

graph_components$new(
  edges = NULL,
  V = NULL,
  E = NULL,
  by_length = TRUE,
  edge_weights = NULL,
  ...,
  lines = deprecated()
)

Arguments

Returns

A graph_components object.

Method get_largest()

Returns the largest component in the graph.

Usage

graph_components$get_largest()

Returns

A metric_graph object.

Method plot()

Plots all components.

Usage

graph_components$plot(edge_colors = NULL, vertex_colors = NULL, ...)

Arguments

Returns

A ggplot object.

Method clone()

The objects of this class are cloneable with this method.

Usage

graph_components$clone(deep = FALSE)

Arguments

Examples

library(sp)
edge1 <- rbind(c(0, 0), c(1, 0))
edge2 <- rbind(c(1, 0), c(2, 0))
edge3 <- rbind(c(1, 1), c(2, 1))
edges <- list(edge1, edge2, edge3)

graphs <- graph_components$new(edges)
graphs$plot()

Description

Extracts data from metric graphs to be used by 'INLA' and 'inlabru'.

Usage

graph_data_spde(
  graph_spde,
  name = "field",
  repl = NULL,
  repl_col = NULL,
  group = NULL,
  group_col = NULL,
  likelihood_col = NULL,
  resp_col = NULL,
  covariates = NULL,
  only_pred = FALSE,
  loc_name = NULL,
  tibble = FALSE,
  drop_na = FALSE,
  drop_all_na = TRUE,
  loc = deprecated()
)

Arguments

Value

An 'INLA' and 'inlabru' friendly list with the data.

Description

Simulation of log-Gaussian Cox processes driven by Whittle-Matérn fields on metric graphs

Usage

graph_lgcp(n = 1, intercept = 0, sigma, range, alpha, graph)

Arguments

Value

List with Gaussian process sample and simulated points.

Description

Fitting linear mixed effects model in metric graphs. The random effects can be Gaussian Whittle-Matern fields, discrete Gaussian Markov random fields based on the graph Laplacian, as well as Gaussian random fields with isotropic covariance functions.

Usage

graph_lme(
  formula,
  graph,
  model = list(type = "linearModel"),
  which_repl = NULL,
  optim_method = "L-BFGS-B",
  possible_methods = "L-BFGS-B",
  model_options = list(),
  BC = 1,
  previous_fit = NULL,
  fix_coeff = FALSE,
  parallel = FALSE,
  n_cores = parallel::detectCores() - 1,
  optim_controls = list(),
  improve_hessian = FALSE,
  hessian_args = list(),
  check_euclidean = TRUE
)

Arguments

Value

A list containing the fitted model.

Description

This function creates an 'INLA' object that can be used in 'INLA' or 'inlabru' to fit Whittle-Matérn fields on metric graphs.

Usage

graph_spde(
  graph_object,
  alpha = 1,
  directional = FALSE,
  stationary_endpoints = "all",
  parameterization = c("matern", "spde"),
  start_range = NULL,
  prior_range = NULL,
  start_kappa = NULL,
  prior_kappa = NULL,
  start_sigma = NULL,
  prior_sigma = NULL,
  start_tau = NULL,
  prior_tau = NULL,
  factor_start_range = 0.3,
  max_dim_start_range = TRUE,
  shared_lib = "detect",
  debug = FALSE,
  verbose = 0
)

Arguments

Details

This function is used to construct a Matern SPDE model on a metric graph. The latent field $u$ is the solution of the SPDE

$(\kappa^2 - \Delta)^\alpha u = \sigma W,$

where $W$ is Gaussian white noise on the metric graph. This model implements exactly the cases in which $\alpha = 1$ or $\alpha = 2$. For a finite element approximation for general $\alpha$ we refer the reader to the 'rSPDE' package and to the Whittle–Matérn fields with general smoothness vignette.

We also have the alternative parameterization $\rho = \frac{\sqrt{8(\alpha-0.5)}}{\kappa}$, which can be interpreted as a range parameter.

Let $\kappa_0$ and $\sigma_0$ be the starting values for $\kappa$ and $\sigma$, we write $\sigma = \exp\{\theta_1\}$ and $\kappa = \exp\{\theta_2\}$. We assume priors on $\theta_1$ and $\theta_2$ to be normally distributed with mean, respectively, $\log(\sigma_0)$ and $\log(\kappa_0)$, and variance 10. Similarly, if we let $\rho_0$ be the starting value for $\rho$, then we write $\rho = \exp\{\theta_2\}$ and assume a normal prior for $\theta_2$, with mean $\log(\rho_0)$ and variance 10.

Value

An 'INLA' object.

Description

Constructs observation/prediction weight matrices for metric graph models.

Usage

graph_spde_basis(graph_spde, repl = NULL, drop_na = FALSE, drop_all_na = TRUE)

Arguments

Value

The observation matrix.

Description

Constructs observation/prediction weight matrices for metric graph models.

Usage

graph_spde_make_A(graph_spde, repl = NULL)

Arguments

Value

The observation matrix.

Description

Computes appropriate starting values for optimization of Gaussian random field models on metric graphs.

Usage

graph_starting_values(
  graph,
  model = c("alpha1", "alpha2", "isoExp", "GL1", "GL2"),
  data = TRUE,
  data_name = NULL,
  range_par = FALSE,
  nu = FALSE,
  manual_data = NULL,
  like_format = FALSE,
  log_scale = FALSE,
  model_options = list(),
  rec_tau = TRUE,
  factor_start_range = 0.3,
  max_dim_start_range = TRUE
)

Arguments

Value

A vector, c(start_sigma_e, start_sigma, start_kappa)

Description

Create lines for package name

Usage

logo_lines()

Value

SpatialLines object with package name.

Description

The precision matrix for all vertices for space-time field

Usage

make_Q_euler(graph, t, kappa, rho, gamma, alpha, beta, sigma, theta = 1)

Arguments

Value

Precision matrix.

Description

The precision matrix for all vertices for space-time field.

Usage

make_Q_spacetime(graph, t, kappa, rho, gamma, alpha, beta, sigma)

Arguments

Value

Precision matrix.

Description

Class representing a general metric graph.

Details

A graph object created from vertex and edge matrices, or from an sp::SpatialLines object where each line is representing and edge. For more details, see the vignette: vignette("metric_graph", package = "MetricGraph")

Value

Object of R6Class for creating metric graphs.

Public fields

Methods

Public methods

• metric_graph$new()

• metric_graph$remove_small_circles()

• metric_graph$get_edges()

• metric_graph$get_bounding_box()

• metric_graph$get_vertices()

• metric_graph$export()

• metric_graph$leaflet()

• metric_graph$mapview()

• metric_graph$set_edge_weights()

• metric_graph$get_edge_weights()

• metric_graph$get_vertices_incomp_dir()

• metric_graph$summary()

• metric_graph$print()

• metric_graph$compute_characteristics()

• metric_graph$check_euclidean()

• metric_graph$check_distance_consistency()

• metric_graph$compute_geodist()

• metric_graph$compute_geodist_PtE()

• metric_graph$compute_geodist_mesh()

• metric_graph$compute_resdist()

• metric_graph$compute_resdist_PtE()

• metric_graph$get_degrees()

• metric_graph$compute_PtE_edges()

• metric_graph$compute_resdist_mesh()

• metric_graph$compute_laplacian()

• metric_graph$prune_vertices()

• metric_graph$set_manual_edge_lengths()

• metric_graph$get_groups()

• metric_graph$get_PtE()

• metric_graph$get_edge_lengths()

• metric_graph$get_locations()

• metric_graph$observation_to_vertex()

• metric_graph$edgeweight_to_data()

• metric_graph$get_mesh_locations()

• metric_graph$clear_observations()

• metric_graph$process_data()

• metric_graph$add_observations()

• metric_graph$mutate_weights()

• metric_graph$select_weights()

• metric_graph$filter_weights()

• metric_graph$summarise_weights()

• metric_graph$drop_na_weights()

• metric_graph$mutate()

• metric_graph$drop_na()

• metric_graph$select()

• metric_graph$filter()

• metric_graph$summarise()

• metric_graph$get_data()

• metric_graph$setDirectionalWeightFunction()

• metric_graph$buildDirectionalConstraints()

• metric_graph$buildC()

• metric_graph$build_mesh()

• metric_graph$compute_fem()

• metric_graph$mesh_A()

• metric_graph$fem_basis()

• metric_graph$VtEfirst()

• metric_graph$plot()

• metric_graph$plot_connections()

• metric_graph$is_tree()

• metric_graph$plot_function()

• metric_graph$plot_movie()

• metric_graph$add_mesh_observations()

• metric_graph$get_initial_graph()

• metric_graph$coordinates()

• metric_graph$clone()

Method new()

Create a new metric_graph object.

Usage

metric_graph$new(
  edges = NULL,
  V = NULL,
  E = NULL,
  vertex_unit = NULL,
  length_unit = NULL,
  edge_weights = NULL,
  kirchhoff_weights = NULL,
  directional_weights = NULL,
  longlat = NULL,
  crs = NULL,
  proj4string = NULL,
  which_longlat = "sp",
  include_obs = NULL,
  include_edge_weights = NULL,
  project = FALSE,
  project_data = FALSE,
  which_projection = "Winkel tripel",
  manual_edge_lengths = NULL,
  perform_merges = NULL,
  approx_edge_PtE = TRUE,
  tolerance = list(vertex_vertex = 0.001, vertex_edge = 0.001, edge_edge = 0),
  check_connected = TRUE,
  remove_deg2 = FALSE,
  merge_close_vertices = NULL,
  factor_merge_close_vertices = 1,
  remove_circles = FALSE,
  auto_remove_point_edges = TRUE,
  verbose = 1,
  add_obs_options = list(return_removed = FALSE, verbose = verbose),
  lines = deprecated()
)

Arguments

Details

A graph object can be initialized in two ways. The first method is to specify V and E. In this case, all edges are assumed to be straight lines. The second option is to specify the graph via the lines input. In this case, the vertices are set by the end points of the lines. Thus, if two lines are intersecting somewhere else, this will not be viewed as a vertex.

Returns

A metric_graph object.

Method remove_small_circles()

Sets the edge weights

Usage

metric_graph$remove_small_circles(tolerance, verbose = 1)

Arguments

Returns

No return value. Called for its side effects.

Method get_edges()

Exports the edges of the MetricGraph object as an sf or sp.

Usage

metric_graph$get_edges(format = c("sf", "sp", "list"))

Arguments

Returns

For format == "sf", the function returns an sf object of LINESTRING geometries, where the associated data frame includes edge weights.

For format == "sp", the function returns a SpatialLinesDataFrame where the data frame includes edge weights.

Method get_bounding_box()

Bounding box of the metric graph

Usage

metric_graph$get_bounding_box(format = "sf")

Arguments

Returns

A bounding box of the metric graph

Method get_vertices()

Exports the vertices of the MetricGraph object as an sf, sp or as a matrix.

Usage

metric_graph$get_vertices(format = c("sf", "sp", "list"))

Arguments

Returns

For which_format == "sf", the function returns an sf object of POINT geometries.

For which_format == "sp", the function returns a SpatialPointsDataFrame object.

Method export()

Exports the MetricGraph object as an sf or sp object.

Usage

metric_graph$export(format = "sf")

Arguments

Returns

Returns a list with three elements: edges, vertices, and data.

For format == "sf", edges is an sf object of LINESTRING geometries with edge weights, and vertices and data are sf objects with POINT geometries.

For format == "sp", edges is a SpatialLinesDataFrame with edge weights, and vertices and data are SpatialPointsDataFrame.

Method leaflet()

Return the metric graph as a leaflet::leaflet() object to be built upon.

Usage

metric_graph$leaflet(
  width = NULL,
  height = NULL,
  padding = 0,
  options = leafletOptions(),
  elementId = NULL,
  sizingPolicy = leafletSizingPolicy(padding = padding)
)

Arguments

Method mapview()

Returns a mapview::mapview() object of the metric graph

Usage

metric_graph$mapview(...)

Arguments

Method set_edge_weights()

Sets the edge weights

Usage

metric_graph$set_edge_weights(
  weights = NULL,
  kirchhoff_weights = NULL,
  directional_weights = NULL,
  verbose = 0
)

Arguments

Returns

No return value. Called for its side effects.

Method get_edge_weights()

Gets the edge weights

Usage

metric_graph$get_edge_weights(
  data.frame = FALSE,
  format = c("tibble", "sf", "sp", "list"),
  tibble = deprecated()
)

Arguments

Returns

A vector or data.frame containing the edge weights.

Method get_vertices_incomp_dir()

Gets vertices with incompatible directions

Usage

metric_graph$get_vertices_incomp_dir()

Returns

A vector containing the vertices with incompatible directions.

Method summary()

Prints a summary of various informations of the graph

Usage

metric_graph$summary(
  messages = FALSE,
  compute_characteristics = NULL,
  check_euclidean = NULL,
  check_distance_consistency = NULL
)

Arguments

Returns

No return value. Called for its side effects.

Method print()

Prints various characteristics of the graph

Usage

metric_graph$print()

Returns

No return value. Called for its side effects.

Method compute_characteristics()

Computes various characteristics of the graph

Usage

metric_graph$compute_characteristics(check_euclidean = FALSE)

Arguments

Returns

No return value. Called for its side effects. The computed characteristics are stored in the characteristics element of the metric_graph object.

Method check_euclidean()

Check if the graph has Euclidean edges.

Usage

metric_graph$check_euclidean()

Returns

Returns TRUE if the graph has Euclidean edges, or FALSE otherwise. The result is stored in the characteristics element of the metric_graph object. The result is displayed when the graph is printed.

Method check_distance_consistency()

Checks distance consistency of the graph.

Usage

metric_graph$check_distance_consistency()

Returns

No return value. The result is stored in the characteristics element of the metric_graph object. The result is displayed when the graph is printed.

Method compute_geodist()

Computes shortest path distances between the vertices in the graph

Usage

metric_graph$compute_geodist(
  full = FALSE,
  obs = TRUE,
  group = NULL,
  verbose = 0
)

Arguments

Returns

No return value. Called for its side effects. The computed geodesic distances are stored in the geo_dist element of the metric_graph object.

Method compute_geodist_PtE()

Computes shortest path distances between the vertices in the graph.

Usage

metric_graph$compute_geodist_PtE(
  PtE,
  normalized = TRUE,
  include_vertices = TRUE,
  verbose = 0
)

Arguments

Returns

A matrix containing the geodesic distances.

Method compute_geodist_mesh()

Computes shortest path distances between the vertices in the mesh.

Usage

metric_graph$compute_geodist_mesh()

Returns

No return value. Called for its side effects. The geodesic distances on the mesh are stored in mesh$geo_dist in the metric_graph object.

Method compute_resdist()

Computes the resistance distance between the observation locations.

Usage

metric_graph$compute_resdist(
  full = FALSE,
  obs = TRUE,
  group = NULL,
  check_euclidean = FALSE,
  include_vertices = FALSE,
  verbose = 0
)

Arguments

Returns

No return value. Called for its side effects. The geodesic distances are stored in the res_dist element of the metric_graph object.

Method compute_resdist_PtE()

Computes the resistance distance between the observation locations.

Usage

metric_graph$compute_resdist_PtE(
  PtE,
  normalized = TRUE,
  include_vertices = FALSE,
  check_euclidean = FALSE,
  verbose = 0
)

Arguments

Returns

A matrix containing the resistance distances.

Method get_degrees()

Returns the degrees of the vertices in the metric graph.

Usage

metric_graph$get_degrees(which = "degree")

Arguments

Returns

A vector containing the degrees of the vertices.

Method compute_PtE_edges()

Computes the relative positions of the coordinates of the edges and save it as an attribute to each edge. This improves the quality of plots obtained by the plot_function() method, however it might be costly to compute.

Usage

metric_graph$compute_PtE_edges(approx = TRUE, verbose = 0)

Arguments

Returns

No return value, called for its side effects.

Method compute_resdist_mesh()

Computes the resistance metric between the vertices in the mesh.

Usage

metric_graph$compute_resdist_mesh()

Returns

No return value. Called for its side effects. The geodesic distances on the mesh are stored in the mesh$res_dist element in the metric_graph object.

Method compute_laplacian()

Computes the weigthed graph Laplacian for the graph.

Usage

metric_graph$compute_laplacian(
  full = FALSE,
  obs = TRUE,
  group = NULL,
  verbose = 0
)

Arguments

Returns

No reutrn value. Called for its side effects. The Laplacian is stored in the Laplacian element in the metric_graph object.

Method prune_vertices()

Removes vertices of degree 2 from the metric graph.

Usage

metric_graph$prune_vertices(
  check_weights = TRUE,
  check_circles = TRUE,
  verbose = FALSE
)

Arguments

Details

Vertices of degree 2 are removed as long as the corresponding edges that would be merged are compatible in terms of direction.

Returns

No return value. Called for its side effects.

Method set_manual_edge_lengths()

Gets the groups from the data.

Usage

metric_graph$set_manual_edge_lengths(edge_lengths, unit = NULL)

Arguments

Returns

does not return anything. Called for its side effects.

Method get_groups()

Gets the groups from the data.

Usage

metric_graph$get_groups(get_cols = FALSE)

Arguments

Returns

A vector containing the available groups in the internal data.

Method get_PtE()

Gets PtE from the data.

Usage

metric_graph$get_PtE()

Arguments

Returns

A matrix with two columns, where the first column contains the edge number and the second column contains the distance on edge of the observation locations.

Method get_edge_lengths()

Gets the edge lengths with the corresponding unit.

Usage

metric_graph$get_edge_lengths(unit = NULL)

Arguments

Returns

a vector with the length unit (if the graph was constructed with a length unit).

Method get_locations()

Gets the spatial locations from the data.

Usage

metric_graph$get_locations()

Returns

A data.frame object with observation locations. If longlat = TRUE, the column names are lon and lat, otherwise the column names are x and y.

Method observation_to_vertex()

Adds observation locations as vertices in the graph.

Usage

metric_graph$observation_to_vertex(
  mesh_warning = TRUE,
  verbose = 0,
  tolerance = deprecated()
)

Arguments

Returns

No return value. Called for its side effects.

Method edgeweight_to_data()

Turns edge weights into data on the metric graph

Usage

metric_graph$edgeweight_to_data(
  loc = NULL,
  mesh = FALSE,
  data_loc = FALSE,
  weight_col = NULL,
  add = TRUE,
  data_coords = c("PtE", "spatial"),
  normalized = FALSE,
  tibble = FALSE,
  format = c("tibble", "sf", "sp", "list"),
  verbose = 1,
  suppress_warnings = FALSE,
  return = FALSE
)

Arguments

Method get_mesh_locations()

Returns a list or a matrix with the mesh locations.

Usage

metric_graph$get_mesh_locations(
  bru = FALSE,
  loc = c(".edge_number", ".distance_on_edge"),
  loc_name = NULL,
  normalized = TRUE
)

Arguments

Returns

A list or a matrix containing the mesh locations.

Method clear_observations()

Clear all observations from the metric_graph object.

Usage

metric_graph$clear_observations()

Returns

No return value. Called for its side effects.

Method process_data()

Process data to the metric graph data format.

Usage

metric_graph$process_data(
  data = NULL,
  edge_number = "edge_number",
  distance_on_edge = "distance_on_edge",
  coord_x = "coord_x",
  coord_y = "coord_y",
  data_coords = c("PtE", "spatial"),
  group = NULL,
  group_sep = ".",
  normalized = FALSE,
  format = c("tibble", "sf", "sp", "list"),
  duplicated_strategy = "closest",
  include_distance_to_graph = TRUE,
  only_return_removed = FALSE,
  tolerance = max(self$edge_lengths)/2,
  verbose = FALSE,
  suppress_warnings = FALSE,
  Spoints = lifecycle::deprecated(),
  tibble = lifecycle::deprecated()
)

Arguments

Returns

No return value. Called for its side effects. The observations are stored in the data element of the metric_graph object.

Method add_observations()

Add observations to the metric graph.

Usage

metric_graph$add_observations(
  data = NULL,
  edge_number = "edge_number",
  distance_on_edge = "distance_on_edge",
  coord_x = "coord_x",
  coord_y = "coord_y",
  data_coords = c("PtE", "spatial"),
  group = NULL,
  group_sep = ".",
  normalized = FALSE,
  clear_obs = FALSE,
  tibble = FALSE,
  tolerance = max(self$edge_lengths)/2,
  duplicated_strategy = "closest",
  include_distance_to_graph = TRUE,
  return_removed = TRUE,
  tolerance_merge = 0,
  merge_strategy = "merge",
  verbose = 1,
  suppress_warnings = FALSE,
  Spoints = lifecycle::deprecated()
)

Arguments

Returns

No return value. Called for its side effects. The observations are stored in the data element of the metric_graph object.

Method mutate_weights()

Use dplyr::mutate function on the internal edge weights object.

Usage

metric_graph$mutate_weights(
  ...,
  .drop_na = FALSE,
  .drop_all_na = TRUE,
  format = "tibble"
)

Arguments

Details

A wrapper to use dplyr::mutate() on the internal edge weights object and return the result in the requested format.

Returns

A tidyr::tibble, sf or sp object containing the resulting data list after the mutate.

Method select_weights()

Use dplyr::select function on the internal edge weights object.

Usage

metric_graph$select_weights(
  ...,
  .drop_na = FALSE,
  .drop_all_na = TRUE,
  format = "tibble"
)

Arguments

Details

A wrapper to use dplyr::select() on the internal edge weights object and return the result in the requested format.

Returns

A tidyr::tibble, sf or sp object containing the resulting data list after the select.

Method filter_weights()

Use dplyr::filter function on the internal edge weights object.

Usage

metric_graph$filter_weights(
  ...,
  .drop_na = FALSE,
  .drop_all_na = TRUE,
  format = "tibble"
)

Arguments

Details

A wrapper to use dplyr::filter() on the internal edge weights object and return the result in the requested format.

Returns

A tidyr::tibble, sf or sp object containing the resulting data list after the filter.

Method summarise_weights()

Use dplyr::summarise function on the internal edge weights object grouped by the edge numbers.

Usage

metric_graph$summarise_weights(
  ...,
  .groups = NULL,
  .drop_na = FALSE,
  .drop_all_na = TRUE,
  format = "tibble"
)

Arguments

Details

A wrapper to use dplyr::summarise() on the internal edge weights object and return the result in the requested format.

Returns

A tidyr::tibble, sf or sp object containing the resulting data list after the summarise.

Method drop_na_weights()

Use tidyr::drop_na() function on the internal edge weights object.

Usage

metric_graph$drop_na_weights(..., format = "tibble")

Arguments

Details

A wrapper to use tidyr::drop_na() within the internal edge weights object.

Returns

A tidyr::tibble, sf, or sp object containing the resulting data list after the drop_na.

Method mutate()

Use dplyr::mutate function on the internal metric graph data object.

Usage

metric_graph$mutate(
  ...,
  .drop_na = FALSE,
  .drop_all_na = TRUE,
  format = "tibble"
)

Arguments

Details

A wrapper to use dplyr::mutate() within the internal metric graph data object and return the result in the requested format.

Returns

A tidyr::tibble, sf, or sp object containing the resulting data list after the mutate.

Method drop_na()

Use tidyr::drop_na() function on the internal metric graph data object.

Usage

metric_graph$drop_na(..., format = "tibble")

Arguments

Details

A wrapper to use dplyr::drop_na() within the internal metric graph data object.

Returns

A tidyr::tibble object containing the resulting data list after the drop_na.

Method select()

Use dplyr::select function on the internal metric graph data object.

Usage

metric_graph$select(
  ...,
  .drop_na = FALSE,
  .drop_all_na = TRUE,
  format = "tibble"
)

Arguments

Details

A wrapper to use dplyr::select() within the internal metric graph data object. Observe that it is a bit different from directly using dplyr::select() since it does not allow to remove the internal positions that are needed for the metric_graph methods to work.

Returns

A tidyr::tibble object containing the resulting data list after the selection.

Method filter()

Use dplyr::filter function on the internal metric graph data object.

Usage

metric_graph$filter(
  ...,
  .drop_na = FALSE,
  .drop_all_na = TRUE,
  format = "tibble"
)

Arguments

Details

A wrapper to use dplyr::filter() within the internal metric graph data object.

Returns

A tidyr::tibble object containing the resulting data list after the filter.

Method summarise()

Use dplyr::summarise function on the internal metric graph data object grouped by the spatial locations and the internal group variable.

Usage

metric_graph$summarise(
  ...,
  .include_graph_groups = FALSE,
  .groups = NULL,
  .drop_na = FALSE,
  .drop_all_na = TRUE,
  format = "tibble"
)

Arguments

Details

A wrapper to use dplyr::summarise() within the internal metric graph data object grouped by manually inserted groups (optional), the internal group variable (optional) and the spatial locations. Observe that if the integral group variable was not used as a grouping variable for the summarise, a new column, called .group, will be added, with the same value 1 for all rows.

Returns

A tidyr::tibble object containing the resulting data list after the summarise.

Method get_data()

Return the internal data with the option to filter by groups.

Usage

metric_graph$get_data(
  group = NULL,
  format = c("tibble", "sf", "sp", "list"),
  drop_na = FALSE,
  drop_all_na = TRUE,
  tibble = deprecated()
)

Arguments

Method setDirectionalWeightFunction()

Define the columns to be used for creating the directional vertex weights. Also possible to supply user defined functions for input and output to create ones own weights.

Usage

metric_graph$setDirectionalWeightFunction(f_in = NULL, f_out = NULL)

Arguments

Details

For more details see paper (that does not exists yet).

Returns

No return value.

Method buildDirectionalConstraints()

Build directional ODE constraint matrix from edges.

Usage

metric_graph$buildDirectionalConstraints(alpha = 1)

Arguments

Details

Currently not implemented for circles (edges that start and end in the same vertex)

Returns

No return value. Called for its side effects.

Method buildC()

Build Kirchoff constraint matrix from edges.

Usage

metric_graph$buildC(alpha = 2, edge_constraint = FALSE)

Arguments

Details

Currently not implemented for circles (edges that start and end in the same vertex)

Returns

No return value. Called for its side effects.

Method build_mesh()

Builds mesh object for graph.

Usage

metric_graph$build_mesh(
  h = NULL,
  n = NULL,
  continuous = TRUE,
  continuous.outs = FALSE,
  continuous.deg2 = FALSE
)

Arguments

Details

The mesh is a list with the objects:

• PtE The mesh locations excluding the original vertices;

• V The verties of the mesh;

• E The edges of the mesh;

• n_e The number of vertices in the mesh per original edge in the graph;

• h_e The mesh width per edge in the graph;

• ind The indices of the vertices in the mesh;

• VtE All mesh locations including the original vertices.

Returns

No return value. Called for its side effects. The mesh is stored in the mesh element of the metric_graph object.

Method compute_fem()

Build mass and stiffness matrices for given mesh object.

Usage

metric_graph$compute_fem(petrov = FALSE)

Arguments

Details

The function builds: The matrix C which is the mass matrix with elements $C_{ij} = <\phi_i, \phi_j>$, the matrix G which is the stiffness matrix with elements $G_{ij} = <d\phi_i, d\phi_j>$, the matrix B with elements $B_{ij} = <d\phi_i, \phi_j>$, the matrix D with elements $D_{ij} = \sum_{v\in V}\phi_i(v)\phi_j(v)$, and the vector with weights $<\phi_i, 1>$.

Returns

No return value. Called for its side effects. The finite element matrices C, G and B are stored in the mesh element in the metric_graph object. If petrov=TRUE, the corresponding Petrov-Galerkin matrices are stored in Cpet and Gpet.

Method mesh_A()

Deprecated - Computes observation matrix for mesh.

in favour of metric_graph$fem_basis().

Usage

metric_graph$mesh_A(PtE)

Arguments

Details

For n locations and a mesh with m nodes, A is an n x m matrix with elements $A_{ij} = \phi_j(s_i)$.

Returns

The observation matrix.

Method fem_basis()

Computes observation matrix for mesh.

Usage

metric_graph$fem_basis(PtE)

Arguments

Details

For n locations and a mesh with m nodes, A is an n x m matrix with elements $A_{ij} = \phi_j(s_i)$.

Returns

The observation matrix.

Method VtEfirst()

Find one edge corresponding to each vertex.

Usage

metric_graph$VtEfirst()

Returns

A nV x 2 matrix the first element of the ith row is the edge number corresponding to the ith vertex and the second value is 0 if the vertex is at the start of the edge and 1 if the vertex is at the end of the edge.

Method plot()

Plots the metric graph.

Usage

metric_graph$plot(
  data = NULL,
  newdata = NULL,
  group = 1,
  type = c("ggplot", "plotly", "mapview"),
  interactive = FALSE,
  vertex_size = 3,
  vertex_color = "black",
  edge_width = 0.3,
  edge_color = "black",
  data_size = 1,
  support_width = 0.5,
  support_color = "gray",
  mesh = FALSE,
  X = NULL,
  X_loc = NULL,
  p = NULL,
  degree = FALSE,
  direction = FALSE,
  arrow_size = ggplot2::unit(0.25, "inches"),
  edge_weight = NULL,
  edge_width_weight = NULL,
  scale_color_main = ggplot2::scale_color_viridis_c(option = "D"),
  scale_color_weights = ggplot2::scale_color_viridis_c(option = "C"),
  scale_color_degree = ggplot2::scale_color_viridis_d(option = "D"),
  scale_color_weights_discrete = ggplot2::scale_color_viridis_d(option = "C"),
  scale_color_main_discrete = ggplot2::scale_color_viridis_d(option = "C"),
  add_new_scale_weights = TRUE,
  scale_color_mapview = viridis::viridis(100, option = "D"),
  scale_color_weights_mapview = viridis::viridis(100, option = "C"),
  scale_color_weights_discrete_mapview = NULL,
  scale_color_degree_mapview = NULL,
  plotly = deprecated(),
  ...
)

Arguments

Returns

A plot_ly (if type = "plotly") or ggplot object.

Method plot_connections()

Plots the connections in the graph

Usage

metric_graph$plot_connections()

Returns

No return value. Called for its side effects.

Method is_tree()

Checks if the graph is a tree (without considering directions)

Usage

metric_graph$is_tree()

Returns

TRUE if the graph is a tree and FALSE otherwise.

Method plot_function()

Plots continuous function on the graph.

Usage

metric_graph$plot_function(
  data = NULL,
  newdata = NULL,
  group = 1,
  X = NULL,
  type = c("ggplot", "plotly", "mapview"),
  continuous = TRUE,
  interpolate_plot = TRUE,
  edge_weight = NULL,
  vertex_size = 5,
  vertex_color = "black",
  edge_width = 1,
  edge_color = "black",
  line_width = NULL,
  line_color = "rgb(0,0,200)",
  scale_color = ggplot2::scale_color_viridis_c(option = "D"),
  scale_color_mapview = viridis::viridis(100, option = "D"),
  support_width = 0.5,
  support_color = "gray",
  mapview_caption = "Function",
  p = NULL,
  plotly = deprecated(),
  improve_plot = deprecated(),
  ...
)

Arguments

Returns

Either a ggplot (if plotly = FALSE) or a plot_ly object.

Method plot_movie()

Plots a movie of a continuous function evolving on the graph.

Usage

metric_graph$plot_movie(
  X,
  type = "plotly",
  vertex_size = 5,
  vertex_color = "black",
  edge_width = 1,
  edge_color = "black",
  line_width = NULL,
  line_color = "rgb(0,0,200)",
  ...
)

Arguments

Returns

Either a ggplot (if plotly=FALSE) or a plot_ly object.

Method add_mesh_observations()

Add observations on mesh to the object.

Usage

metric_graph$add_mesh_observations(data = NULL, group = NULL)

Arguments

Returns

No return value. Called for its side effects. The observations are stored in the data element in the metric_graph object.

Method get_initial_graph()

Returns a copy of the initial metric graph.

Usage

metric_graph$get_initial_graph()

Returns

A metric_graph object.

Method coordinates()

Convert between locations on the graph and Euclidean coordinates.

Usage

metric_graph$coordinates(PtE = NULL, XY = NULL, normalized = TRUE)

Arguments

Returns

If PtE is specified, then a matrix with Euclidean coordinates of the locations is returned. If XY is provided, then a matrix with the closest locations on the graph is returned. Gets the edge weights data.frame If the edge weights are given as vectors, should the result be returned as a data.frame? A vector or data.frame containing the edge weights. data List containing data on the metric graph.

Method clone()

The objects of this class are cloneable with this method.

Usage

metric_graph$clone(deep = FALSE)

Arguments

Examples

edge1 <- rbind(c(0, 0), c(2, 0))
edge2 <- rbind(c(2, 0), c(1, 1))
edge3 <- rbind(c(1, 1), c(0, 0))
edges <- list(edge1, edge2, edge3)
graph <- metric_graph$new(edges)
graph$plot()

Description

Applies dplyr::mutate() function for datasets obtained from a metric graph object.

Usage

## S3 method for class 'metric_graph_data'
mutate(.data, ...)

Arguments

Value

A tidyr::tibble with the resulting selected columns.

Description

Data set of traffic speed observations on highways in the city of San Jose, California.

Usage

pems

Format

pems

A list with two elements:

edges

A list object containing the coordinates of the road segments.

data

Locations of the observations on the road segments as a data.frame with 325 rows and 3 columns. The first column indicates the edge number, the second column indicates the distance on edge of the position, and the third column indicates the average speed observed.

Source

https://www.openstreetmap.org

https://github.com/spbu-math-cs/Graph-Gaussian-Processes/blob/main/examples/data/PEMS.zip

References

Chen, C., K. Petty, A. Skabardonis, P. Varaiya, and Z. Jia (2001). Freeway performance measurement system: mining loop detector data. Transportation Research Record 1748(1), 96-102.

OpenStreetMap contributors (2017). Planet dump retrieved from https://planet.osm.org. https://www.openstreetmap.org.

Description

Data set of traffic speed observations on highways in the city of San Jose, California.

Usage

pems_repl

Format

pems_repl

A list with two elements:

edges

A list object containing the coordinates of the road segments.

data

Locations of the observations on the road segments as a data.frame with 325 rows and 4 columns. The first column indicates the observed speed, the second column indicates the edge number, the third column indicates the distance on edge of the position, and the fourth column indicates the replicate number.

Source

https://www.openstreetmap.org

https://github.com/spbu-math-cs/Graph-Gaussian-Processes/blob/main/examples/data/PEMS.zip

References

Chen, C., K. Petty, A. Skabardonis, P. Varaiya, and Z. Jia (2001). Freeway performance measurement system: mining loop detector data. Transportation Research Record 1748(1), 96-102.

OpenStreetMap contributors (2017). Planet dump retrieved from https://planet.osm.org. https://www.openstreetmap.org.

Description

Auxiliary function to obtain plots of the predictions of the field using 'inlabru'.

Usage

## S3 method for class 'graph_bru_pred'
plot(x, y = NULL, vertex_size = 0, ...)

Arguments

Value

A 'ggplot2' object.

Description

Auxiliary function to obtain plots of the processed predictions of the field using 'inlabru'.

Usage

## S3 method for class 'graph_bru_proc_pred'
plot(x, y = NULL, vertex_size = 0, ...)

Arguments

Value

A 'ggplot2' object.

Description

Leave-one-out crossvalidation for graph_lme models assuming observations at the vertices of metric graphs

Usage

posterior_crossvalidation(object, factor = 1, tibble = TRUE)

Arguments

Value

Vector with the posterior expectations and variances as well as mean absolute error (MAE), root mean squared errors (RMSE), and three negatively oriented proper scoring rules: log-score, CRPS, and scaled CRPS.

Description

Prediction for a mixed effects regression model on a metric graph

Usage

## S3 method for class 'graph_lme'
predict(
  object,
  newdata = NULL,
  mesh = FALSE,
  mesh_h = 0.01,
  which_repl = NULL,
  compute_variances = FALSE,
  compute_pred_variances = FALSE,
  posterior_samples = FALSE,
  pred_samples = FALSE,
  n_samples = 100,
  edge_number = "edge_number",
  distance_on_edge = "distance_on_edge",
  normalized = FALSE,
  no_nugget = FALSE,
  return_as_list = FALSE,
  return_original_order = TRUE,
  check_euclidean = TRUE,
  ...,
  data = deprecated()
)

Arguments

Value

A list with elements mean, which contains the means of the predictions, fe_mean, which is the prediction for the fixed effects, re_mean, which is the prediction for the random effects, variance (if compute_variance is TRUE), which contains the posterior variances of the random effects, samples (if posterior_samples is TRUE), which contains the posterior samples.

Description

Auxiliar function to obtain predictions of the field using 'inlabru'.

Usage

## S3 method for class 'inla_metric_graph_spde'
predict(
  object,
  cmp,
  bru_fit,
  newdata = NULL,
  formula = NULL,
  data_coords = c("PtE", "euclidean"),
  normalized = TRUE,
  repl = NULL,
  repl_col = NULL,
  group = NULL,
  group_col = NULL,
  n.samples = 100,
  seed = 0L,
  probs = c(0.025, 0.5, 0.975),
  return_original_order = TRUE,
  num.threads = NULL,
  include = NULL,
  exclude = NULL,
  drop = FALSE,
  ...,
  data = deprecated()
)

Arguments

Value

A list with predictions.

Description

Auxiliar function to obtain predictions of the field using 'inlabru' and 'rSPDE'.

Usage

## S3 method for class 'rspde_metric_graph'
predict(
  object,
  cmp,
  bru_fit,
  newdata = NULL,
  formula = NULL,
  data_coords = c("PtE", "euclidean"),
  normalized = TRUE,
  n.samples = 100,
  seed = 0L,
  probs = c(0.025, 0.5, 0.975),
  num.threads = NULL,
  include = NULL,
  exclude = NULL,
  drop = FALSE,
  ...,
  data = deprecated()
)

Arguments

Value

A list with predictions.

Description

Auxiliar function to transform the predictions of the field into a plot friendly object.

Usage

process_rspde_predictions(pred, graph, PtE = NULL)

Arguments

Value

A list with predictions.

Description

Obtains samples of a Whittle-Matérn field on a metric graph.

Usage

sample_spde(
  kappa,
  tau,
  range,
  sigma,
  sigma_e = 0,
  alpha = 1,
  directional = FALSE,
  graph,
  PtE = NULL,
  type = "manual",
  posterior = FALSE,
  nsim = 1,
  method = c("conditional", "Q"),
  BC = 1
)

Arguments

Details

Samples a Gaussian Whittle-Matérn field on a metric graph, either from the prior or conditionally on observations

$y_i = u(t_i) + \sigma_e e_i$

on the graph, where $e_i$ are independent standard Gaussian variables. The parameters for the field can either be specified in terms of tau and kappa or practical correlation range and marginal standard deviation.

Value

Matrix or vector with the samples.

Description

Selects columns on metric graphs, while keeps the spatial positions.

Usage

## S3 method for class 'metric_graph_data'
select(.data, ...)

Arguments

Value

A tidyr::tibble with the resulting selected columns.

Description

Simulation with starting value u0

Usage

simulate_spacetime(graph, t, kappa, rho, gamma, alpha, beta, sigma, u0, BC = 0)

Arguments

Value

Precision matrix.

Description

The function samples a Gaussian random field based on a fitted model using graph_lme().

Usage

## S3 method for class 'graph_lme'
simulate(
  object,
  nsim = 1,
  seed = NULL,
  sample_latent = FALSE,
  posterior = FALSE,
  which_repl = NULL,
  ...
)

Arguments

Value

A list containing elements samples, edge_number and distance_on_edge. Each of them is a list, whose indexes are the replicates, and in samples a matrix is given with nsim columns, each one being a sample. edge_number and distance_on_edges contain the respective edge numbers and distances on edge for each sampled element. The locations of the samples are the location of the data in which the model was fitted.

Description

Computes the covariance function for a Whittle-Matérn field.

Usage

spde_covariance(P, kappa, tau, range, sigma, alpha, graph, directional = F)

Arguments

Details

Compute the covariance function $\rho(P,s_i)$ where P is the provided location and $s_i$ are all locations in the mesh of the graph.

Value

Vector with the covariance function evaluate at the mesh locations.

Description

Extract field and parameter values and distributions for a metric graph spde effect from an 'INLA' result object.

Usage

spde_metric_graph_result(
  inla,
  name,
  metric_graph_spde,
  compute.summary = TRUE,
  n_samples = 5000,
  n_density = 1024
)

Arguments

Value

If the model was fitted with matern parameterization (the default), it returns a list containing:

If compute.summary is TRUE, then the list will also contain

If the model was fitted with the spde parameterization, it returns a list containing:

If compute.summary is TRUE, then the list will also contain

Description

Computes the precision matrix for all vertices for a Whittle-Matérn field.

Usage

spde_precision(kappa, tau, alpha, graph, BC = 1, build = TRUE)

Arguments

Value

Precision matrix or list.

Description

Computes the variance function for a Whittle-Matérn field. Warning is not feasible for large graph due to matrix inversion

Usage

spde_variance(kappa, tau, range, sigma, alpha, graph, BC = 1, directional = F)

Arguments

Details

Compute the variance $\rho(s_i,s_i)$ where $s_i$ are all locations in the mesh of the graph.

Value

Vector with the variance function evaluate at the mesh locations.

Description

Creates summaries, while keeps the spatial positions.

Usage

## S3 method for class 'metric_graph_data'
summarise(.data, ..., .include_graph_groups = FALSE, .groups = NULL)

Arguments

Value

A tidyr::tibble with the resulting selected columns.

Description

Function providing a summary of results related to metric graph mixed effects regression models.

Usage

## S3 method for class 'graph_lme'
summary(object, all_times = FALSE, ...)

Arguments

Value

An object of class summary_graph_lme containing information about a graph_lme object.

Description

Function providing a summary of several informations/characteristics of a metric graph object.

Usage

## S3 method for class 'metric_graph'
summary(
  object,
  messages = FALSE,
  compute_characteristics = NULL,
  check_euclidean = NULL,
  check_distance_consistency = NULL,
  ...
)

Arguments

Value

An object of class summary_graph_lme containing information about a metric_graph object.

Description

Summary for posteriors of 'rSPDE' field parameters in their original scales.

Usage

## S3 method for class 'metric_graph_spde_result'
summary(object, digits = 6, ...)

Arguments

Value

A data.frame containing the summary.