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:

• David Bolin [email protected]

• 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

## S3 method for class 'inla_metric_graph_spde'
bru_get_mapper(model, ...)

## S3 method for class 'bru_mapper_inla_metric_graph_spde'
ibm_n(mapper, ...)

## S3 method for class 'bru_mapper_inla_metric_graph_spde'
ibm_values(mapper, ...)

## S3 method for class 'bru_mapper_inla_metric_graph_spde'
ibm_jacobian(mapper, input, ...)

Arguments

Description

Mirrors rSPDE::cross_validation() for bru fits (output from inlabru::bru()). For each fold, the held-out responses are set to NA with inlabru::bru_set_missing() and the model is refit with inlabru::bru_rerun(). When true_CV = FALSE, the original fit's mode$theta is held fixed so only the latent posterior is updated; when TRUE, theta is re-estimated. Posterior response samples are then drawn at the held-out locations via inlabru::generate(). Works with the exact, non-FEM SPDE models in MetricGraph (inla_metric_graph_spde) and FEM-based rSPDE models alike.

Usage

cross_validation(
  models,
  model_names = NULL,
  scores = c("mae", "mse", "crps", "scrps", "dss"),
  cv_type = c("k-fold", "loo", "lpo"),
  weight_thr = NULL,
  k = 5,
  percentage = 20,
  number_folds = 10,
  n_samples = 1000,
  return_scores_folds = FALSE,
  orientation_results = c("negative", "positive"),
  include_best = TRUE,
  train_test_indexes = NULL,
  return_train_test = FALSE,
  return_post_samples = FALSE,
  return_true_test_values = FALSE,
  parallelize_RP = FALSE,
  n_cores_RP = parallel::detectCores() - 1,
  true_CV = TRUE,
  save_settings = FALSE,
  model_options_bru = list(),
  print = TRUE,
  fit_verbose = FALSE
)

Arguments

Value

Either a data.frame (default), or a list with scores_df plus the optional components requested by ⁠return_*⁠ / save_settings 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

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

This function simulates point patterns from a log-Gaussian Cox process (LGCP) driven by Whittle-Matérn Gaussian random fields on metric graphs. The intensity function is modeled as $\lambda(s) = exp(\beta + u(s))$, where $\beta$ is an intercept parameter and $u(s)$ is a Gaussian field with Whittle-Matérn covariance.

Usage

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

Arguments

Details

The function implements a two-step simulation procedure:

1. Simulate the Gaussian random field u(s) using finite element methods

2. Generate point locations using acceptance-rejection sampling from the intensity $\lambda(s) = exp(\beta + u(s))$

The Gaussian field is characterized by the SPDE: $(\kappa^2 - \Delta)^{\alpha/2} \tau u = \mathcal{W}$ where $\kappa, \tau$ are derived from the range and sigma parameters, and $\mathcal{W}$ is white noise.

Value

If n = 1, returns a list with components:

u

Numeric vector of the simulated Gaussian field values at mesh nodes

edge_number

Integer vector of edge numbers where points were simulated

edge_loc

Numeric vector of locations along edges (normalized coordinates)

If n > 1, returns a list of length n, where each element is a list with the above components.

See Also

lgcp_graph for fitting LGCP models, precompute_lgcp_graph for efficient model fitting

Examples

## Not run: 
# Create a metric graph and build mesh
graph <- metric_graph$new()
graph$build_mesh(h = 0.1)
graph$compute_fem()

# Simulate a single point pattern
lgcp_data <- graph_lgcp_sim(
  intercept = -1, 
  sigma = 0.5, 
  range = 2, 
  alpha = 2, 
  graph = graph
)

# Simulate multiple replicates
lgcp_replicates <- graph_lgcp_sim(
  n = 10,
  intercept = -1, 
  sigma = 0.5, 
  range = 2, 
  alpha = 2, 
  graph = graph
)

# Plot the simulated intensity
graph$plot_function(X = exp(lgcp_data$u), vertex_size = 0)

## End(Not run)

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,
  LGCP = FALSE,
  directional = FALSE,
  stationary_endpoints = "all",
  parameterization = c("matern", "spde"),
  start_range = NULL,
  prior_range = NULL,
  range_lower_bound = NULL,
  range_upper_bound = NULL,
  range_prec_inc = 1,
  start_kappa = NULL,
  prior_kappa = NULL,
  kappa_lower_bound = NULL,
  kappa_upper_bound = NULL,
  kappa_prec_inc = 1,
  start_sigma = NULL,
  prior_sigma = NULL,
  sigma_lower_bound = NULL,
  sigma_upper_bound = NULL,
  sigma_prec_inc = 1,
  start_tau = NULL,
  prior_tau = NULL,
  tau_lower_bound = NULL,
  tau_upper_bound = NULL,
  tau_prec_inc = 1,
  factor_start_range = 0.3,
  type_start_range_bbox = "diag",
  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,
  type_start_range_bbox = "diag"
)

Arguments

Value

A vector, c(start_sigma_e, start_sigma, start_kappa)

Description

This function fits log-Gaussian Cox process (LGCP) models for point pattern data on metric graphs using R-INLA. It handles the complex setup required for LGCP modeling, including creation of integration points, data preparation, and interface with INLA's Poisson likelihood framework. The function supports both exact and rational SPDE approximations, multiple replicates, and efficient refitting using precomputed quantities.

Usage

lgcp_graph(
  formula,
  graph,
  interpolate = TRUE,
  manual_integration_points = NULL,
  manual_covariates = NULL,
  use_current_mesh = TRUE,
  new_h = NULL,
  new_n = NULL,
  repl = ".all",
  repl_col = ".group",
  clone_graph = TRUE,
  precomputed_data = NULL,
  ...
)

Arguments

Details

The function implements LGCP modeling using the approach of Simpson et al. (2016), where the log-Gaussian Cox process with intensity $\lambda(s) = exp(\eta(s))$ is approximated using a Poisson likelihood with carefully constructed integration points and weights.

The key steps are:

1. Create integration points (typically mesh nodes) across the graph

2. Set up data with observed points (response = 1, weights = 0) and integration points (response = 0, weights = integration weights)

3. Fit using Poisson regression with the constructed weights as exposure

The spatial component can be modeled using:

• Exact SPDE models via graph_spde() (slower setup, exact likelihood)

• Rational SPDE approximations via rspde.metric_graph() (faster, approximate)

Value

An object of class "inla" containing the fitted LGCP model. This includes posterior marginal distributions for model parameters, fitted values, and other standard INLA output components. Use spde_metric_graph_result() to extract spatial parameter estimates in their original scale.

Performance

For fitting multiple models with the same spatial structure:

• Use precompute_lgcp_graph() first, then lgcp_graph() with precomputed_data for substantial speedups

• Set clone_graph = FALSE for additional performance gains when you don't need to preserve the original graph

References

Simpson, D., Illian, J., Lindgren, F., Sørbye, S., & Rue, H. (2016). Going off grid: Computationally efficient inference for log-Gaussian Cox processes. Biometrika, 103(1), 49-70.

See Also

graph_lgcp_sim for simulating LGCP data, precompute_lgcp_graph for efficient model refitting, graph_spde for exact SPDE models, spde_metric_graph_result for extracting spatial parameter estimates

Examples

## Not run: 
# Setup: Create graph with mesh and add point pattern data
graph <- metric_graph$new()
graph$build_mesh(h = 0.1)
graph$add_observations(data = your_point_data, 
                       edge_number = "edge_id", 
                       distance_on_edge = "location")

# Create SPDE model
spde_model <- graph_spde(graph, alpha = 1)
# or: rspde_model <- rspde.metric_graph(graph, nu = 1.5)

# Fit basic LGCP model
fit1 <- lgcp_graph(y ~ 1 + f(field, model = spde_model), 
                   graph = graph)

# Fit model with covariates
fit2 <- lgcp_graph(y ~ elevation + temperature + 
                       f(field, model = spde_model), 
                   graph = graph)

# Extract spatial parameter estimates
spde_result <- spde_metric_graph_result(fit2, "field", spde_model)
summary(spde_result)

# Efficient fitting of multiple models
precomputed <- precompute_lgcp_graph(
  graph = graph,
  resp_variable_name = "y",
  model_name = "field", 
  spde_model = spde_model,
  covariates = c("elevation", "temperature", "slope")
)

# Now fit multiple models efficiently
fit_a <- lgcp_graph(y ~ elevation + f(field, model = spde_model), 
                    graph = graph, precomputed_data = precomputed)
fit_b <- lgcp_graph(y ~ elevation + temperature + f(field, model = spde_model), 
                    graph = graph, precomputed_data = precomputed)
fit_c <- lgcp_graph(y ~ slope + f(field, model = spde_model), 
                    graph = graph, precomputed_data = precomputed)

# Model with replicates
fit_rep <- lgcp_graph(y ~ covariate + f(field, model = spde_model, 
                                       replicate = field.repl), 
                      graph = graph)

## End(Not run)

Description

This function converts a linnet object (from the spatstat package) into a metric graph object.

Usage

linnet.to.graph(linnet.object, crs, ...)

Arguments

Value

A metric graph object with edges defined by the network.

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

Reorders the rows of a data frame to align with the specific ordering of points along the edges of a metric graph's mesh. This ensures that data associated with locations on the graph are correctly aligned with the graph's internal mesh structure, which is essential for spatial operations and visualizations.

Usage

match_mesh_data(
  graph,
  data,
  edge_col = ".edge_number",
  dist_col = ".distance_on_edge"
)

Arguments

Value

A reordered data.frame where rows correspond to the order of points in graph$mesh$VtE. If the input data was an sf object, the returned object will also be an sf object with its geometry reordered accordingly.

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$get_version()

• metric_graph$is_disconnected()

• metric_graph$get_components()

• metric_graph$which_component()

• metric_graph$compute_fem()

• metric_graph$compute_mesh_weights()

• 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$update_graph()

• metric_graph$coordinates()

• metric_graph$clone()

metric_graph$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(),
  .assemble = NULL
)

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.

metric_graph$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.

metric_graph$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.

metric_graph$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

metric_graph$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.

metric_graph$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.

metric_graph$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

metric_graph$mapview()

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

Usage

metric_graph$mapview(...)

Arguments

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$print()

Prints various characteristics of the graph

Usage

metric_graph$print()

Returns

No return value. Called for its side effects.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$compute_geodist()

Computes shortest path distances between the vertices in the graph

Usage

metric_graph$compute_geodist(
  obs = TRUE,
  include_vertices = FALSE,
  all_groups = FALSE,
  group = NULL,
  verbose = 0,
  full = lifecycle::deprecated()
)

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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$get_PtE()

Gets PtE from the data.

Usage

metric_graph$get_PtE()

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.

metric_graph$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).

metric_graph$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.

metric_graph$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.

metric_graph$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

metric_graph$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.

metric_graph$clear_observations()

Clear all observations from the metric_graph object.

Usage

metric_graph$clear_observations()

Returns

No return value. Called for its side effects.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$get_version()

Get the version of MetricGraph package used to build the graph

Usage

metric_graph$get_version()

Returns

A character string with the version number

metric_graph$is_disconnected()

Does this graph have more than one connected component? The decomposition is computed and cached at construction time, so this is an O(1) lookup.

Usage

metric_graph$is_disconnected()

Returns

TRUE if the graph has two or more connected components, FALSE otherwise.

metric_graph$get_components()

Return the connected components of the graph as a list of metric_graph objects. For a connected graph this is simply list(self). For a disconnected graph, the components are returned in order of decreasing total edge length and any observations stored on self are routed to the appropriate component. The result is cached internally; subsequent calls are O(1) until observations change (which invalidates the cache).

Usage

metric_graph$get_components(verbose = 0)

Arguments

Returns

A list of metric_graph objects.

metric_graph$which_component()

For each spatial point, determine which connected component of the graph it belongs to. The component is the one whose nearest edge is closest in Euclidean distance to the point.

Usage

metric_graph$which_component(XY)

Arguments

Returns

An integer vector of length n with the component index for each point. Indices match those of get_components() (i.e. components are sorted by total edge length, descending).

metric_graph$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.

metric_graph$compute_mesh_weights()

Compute the weights of the mesh nodes.

Usage

metric_graph$compute_mesh_weights()

Details

Compute the weights of the mesh nodes.

Returns

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

metric_graph$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.

metric_graph$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.

metric_graph$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.

metric_graph$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(),
  components = FALSE,
  ...
)

Arguments

Returns

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

metric_graph$plot_connections()

Plots the connections in the graph

Usage

metric_graph$plot_connections()

Returns

No return value. Called for its side effects.

metric_graph$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.

metric_graph$plot_function()

Plots continuous function on the graph.

Usage

metric_graph$plot_function(
  data = NULL,
  newdata = NULL,
  group = 1,
  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(),
  X = deprecated(),
  ...
)

Arguments

Returns

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

metric_graph$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.

metric_graph$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.

metric_graph$get_initial_graph()

Returns a copy of the initial metric graph.

Usage

metric_graph$get_initial_graph()

Returns

A metric_graph object.

metric_graph$update_graph()

Update an older version metric graph to the current package version.

Usage

metric_graph$update_graph(verbose = TRUE)

Arguments

Details

This function creates a new metric_graph object from an existing one, preserving all data, edge weights, mesh, distances, and other components while ensuring compatibility with the current package version. The new graph is created with minimal changes by disabling merges and other transformations.

Returns

A new metric_graph object compatible with the current package version.

metric_graph$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.

metric_graph$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

This function performs cross-validation by computing predictions for test data using either the posterior distribution from a fitted model (pseudo-CV) or by refitting the model for each fold (true CV).

Usage

posterior_crossvalidation(
  object,
  scores = c("logscore", "crps", "scrps", "mae", "rmse"),
  mode = "k-fold",
  k = 10,
  percentage = 20,
  number_folds = 10,
  train_test_indices = NULL,
  true_CV = FALSE,
  factor = 1,
  tibble = TRUE,
  parallel_folds = FALSE,
  parallel_fitting = FALSE,
  n_cores = parallel::detectCores() - 1,
  print = FALSE,
  seed = NULL,
  return_indices = FALSE,
  use_precomputed = 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

This function performs pseudo-crossvalidation by computing leave-one-out predictions using the posterior distribution from a fitted model. In pseudo-crossvalidation, the model parameters are kept fixed at the values estimated from the full dataset (those provided in the object), rather than re-estimating them for each fold.

Usage

posterior_crossvalidation_loo(
  object,
  factor = 1,
  tibble = TRUE,
  which_repl = NULL
)

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

This function precomputes the computationally expensive quantities needed for fitting log-Gaussian Cox process (LGCP) models on metric graphs. It enables efficient refitting of multiple models with different formulas while reusing the same spatial structure, integration points, and covariates. This is particularly beneficial for model selection, cross-validation, or sensitivity analysis scenarios.

Usage

precompute_lgcp_graph(
  graph,
  resp_variable_name,
  model_name,
  spde_model,
  covariates = NULL,
  interpolate = TRUE,
  manual_integration_points = NULL,
  manual_covariates = NULL,
  use_current_mesh = TRUE,
  new_h = NULL,
  new_n = NULL,
  repl = ".all",
  repl_col = ".group",
  clone_graph = TRUE
)

Arguments

Details

This function is most beneficial when:

• Fitting multiple models with different covariate combinations

• Performing model selection or cross-validation

• Using exact SPDE models (which have higher setup costs)

• Working with large graphs or complex spatial structures

The speedup typically becomes apparent when fitting 3 or more models, with greater benefits for more complex spatial structures and exact SPDE models.

Value

A list of class "precomputed_lgcp" containing:

graph

The modified metric_graph object with integration points

covariates

Vector of available covariate names

stk

Precomputed INLA stack object

resp_variable_name

Name of the response variable

aux_spde_model

The SPDE model object prepared for the graph

type_model

Type of SPDE model ("exact" or "rational")

model_name

Name of the spatial field for formulas

Note

• All covariates you plan to use must be specified in the initial precomputation

• The spatial structure (mesh, integration points) is fixed during precomputation

• Manual covariate values should correspond to mesh nodes in graph$mesh$VtE when interpolate = FALSE

See Also

lgcp_graph for fitting LGCP models with precomputed data, graph_lgcp_sim for simulating LGCP data, graph_spde for exact SPDE models, spde_metric_graph_result for extracting spatial parameter estimates

Examples

## Not run: 
# Setup: Create graph with mesh and add point pattern data
graph <- metric_graph$new()
graph$build_mesh(h = 0.1)

# Add point pattern data with covariates
point_data <- data.frame(
  y = 1,  # All observed locations have y = 1
  edge_number = c(1, 2, 3, 1, 2),
  distance_on_edge = c(0.1, 0.3, 0.8, 0.9, 0.2),
  elevation = c(100, 150, 200, 120, 180),
  temperature = c(15, 12, 8, 14, 10)
)
graph$add_observations(point_data, normalized = TRUE)

# Create SPDE model
spde_model <- graph_spde(graph, alpha = 1)

# Precompute for multiple model fitting scenarios
precomputed_data <- precompute_lgcp_graph(
  graph = graph,
  resp_variable_name = "y",
  model_name = "field",
  spde_model = spde_model,
  covariates = c("elevation", "temperature"),
  use_current_mesh = TRUE
)

# Now fit multiple models efficiently
# Model selection: compare different covariate combinations
fit1 <- lgcp_graph(y ~ elevation + f(field, model = spde_model),
                   graph = graph, precomputed_data = precomputed_data)

fit2 <- lgcp_graph(y ~ temperature + f(field, model = spde_model),
                   graph = graph, precomputed_data = precomputed_data)

fit3 <- lgcp_graph(y ~ elevation + temperature + f(field, model = spde_model),
                   graph = graph, precomputed_data = precomputed_data)

# Compare models using log marginal likelihood
c(fit1$mlik[1], fit2$mlik[1], fit3$mlik[1])

# Using manual covariates (exact values at mesh nodes)
manual_covs <- data.frame(
  elevation = graph$mesh$VtE[,1] * 50 + 100,  # Synthetic elevation
  temperature = 20 - graph$mesh$VtE[,1] * 10, # Synthetic temperature
  .group = 1
)

precomputed_manual <- precompute_lgcp_graph(
  graph = graph,
  resp_variable_name = "y", 
  model_name = "field",
  spde_model = spde_model,
  covariates = c("elevation", "temperature"),
  manual_covariates = manual_covs,
  interpolate = FALSE
)

# For maximum performance (modifies original graph)
precomputed_fast <- precompute_lgcp_graph(
  graph = graph,
  resp_variable_name = "y",
  model_name = "field", 
  spde_model = spde_model,
  covariates = c("elevation", "temperature"),
  clone_graph = FALSE
)

# Example with replicates
replicate_data <- data.frame(
  y = 1,
  edge_number = c(1, 2, 1, 3, 2, 3),
  distance_on_edge = c(0.2, 0.4, 0.7, 0.1, 0.8, 0.6),
  elevation = c(110, 160, 130, 190, 170, 210),
  replicate_id = c(1, 1, 1, 2, 2, 2)
)

graph$clear_observations()
graph$add_observations(replicate_data, normalized = TRUE, group = "replicate_id")

precomputed_reps <- precompute_lgcp_graph(
  graph = graph,
  resp_variable_name = "y",
  model_name = "field",
  spde_model = spde_model, 
  covariates = "elevation",
  repl = ".all",
  repl_col = "replicate_id"
)

fit_reps <- lgcp_graph(y ~ elevation + f(field, model = spde_model, 
                                        replicate = field.repl),
                       graph = graph, precomputed_data = precomputed_reps)

## End(Not run)

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,
  advanced_options = list(),
  ...,
  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,
  tolerance_merge = 1e-05,
  ...,
  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()
)