metric_graph: Metric graph

Description

Class representing a general metric graph.

Arguments

Value

Object of R6Class for creating metric graphs.

Public fields

V: Matrix with positions in Euclidean space of the vertices of the graph.
nV: The number of vertices.
E: Matrix with the edges of the graph, where each row represents an edge, E[i,1] is the vertex at the start of the ith edge and E[i,2] is the vertex at the end of the edge.
nE: The number of edges.
edge_lengths: Vector with the lengths of the edges in the graph.
C: Constraint matrix used to set Kirchhoff constraints.
CoB: Change-of-basis object used for Kirchhoff constraints.
PtV: Vector with the indices of the vertices which are observation locations.
mesh: Mesh object used for plotting.
edges: The coordinates of the edges in the graph.
DirectionalWeightFunction_in: Function for inwards weights in directional models
DirectionalWeightFunction_out: Function for outwards weights in directional models
vertices: The coordinates of the vertices in the graph, along with several attributes.
geo_dist: Geodesic distances between the vertices in the graph.
res_dist: Resistance distances between the observation locations.
Laplacian: The weighted graph Laplacian of the vertices in the graph. The weights are given by the edge lengths.
characteristics: List with various characteristics of the graph.

Methods

Public methods

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

edges: A list containing coordinates as m x 2 matrices (that is, of matrix type) or m x 2 data frames (data.frame type) of sequence of points connected by straightlines. Alternatively, you can also prove an object of type SSN, osmdata_sp, osmdata_sf, SpatialLinesDataFrame or SpatialLines (from sp package) or MULTILINESTRING (from sf package).

V

n x 2 matrix with Euclidean coordinates of the n vertices. If non-NULL, no merges will be performed.

E

m x 2 matrix where each row represents one of the m edges. If non-NULL, no merges will be performed.

vertex_unit

The unit in which the vertices are specified. The options are 'degree' (the great circle distance in km), 'km', 'm' and 'miles'. The default is NULL, which means no unit. However, if you set length_unit, you need to set vertex_unit.

length_unit

The unit in which the lengths will be computed. The options are 'km', 'm' and 'miles'. The default, when longlat is TRUE, or an sf or sp objects are provided, is 'km'.

edge_weights

Either a number, a numerical vector with length given by the number of edges, providing the edge weights, or a data.frame with the number of rows being equal to the number of edges, where each row gives a vector of weights to its corresponding edge. Can be changed by using the set_edge_weights() method.

kirchhoff_weights

If non-null, the name (or number) of the column of edge_weights that contain the Kirchhoff weights. Must be equal to 1 (or TRUE) in case edge_weights is a single number and those are the Kirchhoff weights.

directional_weights

If non-null, the name (or number) of the column of edge_weights that contain the directional weights. The default is the first column of the edge weights.

longlat

There are three options: NULL, TRUE or FALSE. If NULL (the default option), the edges argument will be checked to see if there is a CRS or proj4string available, if so, longlat will be set to TRUE, otherwise, it will be set to FALSE. If TRUE, then it is assumed that the coordinates are given. in Longitude/Latitude and that distances should be computed in meters. If TRUE it takes precedence over vertex_unit and length_unit, and is equivalent to vertex_unit = 'degree' and length_unit = 'm'.

crs

Coordinate reference system to be used in case longlat is set to TRUE and which_longlat is sf. Object of class crs. The default choice, if the edges object does not have CRS nor proj4string, is sf::st_crs(4326).

proj4string

Projection string of class CRS-class to be used in case longlat is set to TRUE and which_longlat is sp. The default choice, if the edges object does not have CRS nor proj4string, is sp::CRS("+proj=longlat +datum=WGS84").

which_longlat

Compute the distance using which package? The options are sp and sf. The default is sp.

include_obs

If the object is of class SSN, should the observations be added? If NULL and the edges are of class SSN, the data will be automatically added. If FALSE, the data will not be added. Alternatively, one can set this argument to the numbers or names of the columns of the observations to be added as observations.

include_edge_weights

If the object is of class SSN, osmdata_sp, osmdata_sf, SpatialLinesDataFrame, MULTILINESTRING, LINESTRING, sfc_LINESTRING, sfc_MULTILINESTRING, should the edge data (if any) be added as edge weights? If NULL, the edge data will be added as edge weights, if FALSE they will not be added. Alternatively, one can set this argument to the numbers or names of the columns of the edge data to be added as edge weights.

project

If longlat is TRUE should a projection be used to compute the distances to be used for the tolerances (see tolerance below)? The default is FALSE. When TRUE, the construction of the graph is faster.

project_data

If longlat is TRUE should the vertices be project to planar coordinates? The default is FALSE. When TRUE, the construction of the graph is faster.

which_projection

Which projection should be used in case project is TRUE? The options are Robinson, Winkel tripel or a proj4string. The default is Winkel tripel.

manual_edge_lengths

If non-NULL, a vector containing the edges lengths, and all the quantities related to edge lengths will be computed in terms of these. If merges are performed, it is likely that the merges will override the manual edge lengths. In such a case, to provide manual edge lengths, one should either set the perform_merges argument to FALSE or use the set_manual_edge_lengths() method.

perform_merges

There are three options, NULL, TRUE or FALSE. The default option is NULL. If NULL, it will be set to FALSE unless 'edges', 'V' and 'E' are NULL, in which case it will be set to TRUE. If FALSE, this will take priority over the other arguments, and no merges (except the optional merge_close_vertices below) will be performed. Note that the merge on the additional merge_close_vertices might still be performed, if it is set to TRUE.

approx_edge_PtE

Should the relative positions on the edges be approximated? The default is TRUE. If FALSE, the speed can be considerably slower, especially for large metric graphs.

tolerance

List that provides tolerances during the construction of the graph:

vertex_vertex Vertices that are closer than this number are merged (default = 1e-7).
vertex_edge If a vertex at the end of one edge is closer than this number to another edge, this vertex is connected to that edge (default = 1e-7). Previously vertex_line, which is now deprecated.
edge_edge If two edges at some point are closer than this number, a new vertex is added at that point and the two edges are connected (default = 0).
vertex_line, Deprecated. Use vertex_edge instead.
line_line, Deprecated. Use edge_edge instead.

In case longlat = TRUE, the tolerances are given in length_unit.

check_connected

If TRUE, it is checked whether the graph is connected and a warning is given if this is not the case.

remove_deg2

Set to TRUE to remove all vertices of degree 2 in the initialization. Default is FALSE.

merge_close_vertices

Should an additional step to merge close vertices be done? The options are NULL (the default), TRUE or FALSE. If NULL, it will be determined automatically. If TRUE this step will be performed even if perfom_merges is set to FALSE.

factor_merge_close_vertices

Which factor to be multiplied by tolerance vertex_vertex when merging close vertices at the additional step?

remove_circles

All circlular edges with a length smaller than this number are removed. If TRUE, the vertex_vertex tolerance will be used. If FALSE, no circles will be removed.

auto_remove_point_edges

Should edges of length zero, that is, edges that are actually points, be automatically removed?

verbose

Print progress of graph creation. There are 3 levels of verbose, level 0, 1 and 2. In level 0, no messages are printed. In level 1, only messages regarding important steps are printed. Finally, in level 2, messages detailing all the steps are printed. The default is 1.

add_obs_options

List containing additional options to be passed to the add_observations() method when adding observations from SSN data?

lines

Use edges instead.

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

tolerance: Tolerance at which circles with length less than this will be removed.

verbose

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

format: The format for the exported object. The options are sf (default), sp and list.

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

format: If the metric graph has a coordinate reference system, the format for the exported object. The options are sf (default), sp and matrix.

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

format: The format for the exported object. The options are sf (default), sp and matrix.

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

format: The format for the exported object. The options are sf (default) and sp.

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

width: the width of the map

height

the height of the map

padding

the padding of the map

options

the map options

elementId

Use an explicit element ID for the widget (rather than an automatically generated one).

sizingPolicy

htmlwidgets sizing policy object. Defaults to leafletSizingPolicy().

Method `mapview()`

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

Usage

metric_graph$mapview(...)

Arguments

...: Additional arguments to be passed to mapview::mapview(). The x argument of mapview, containing the metric graph is already passed internally.

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

weights: Either a number, a numerical vector with length given by the number of edges, providing the edge weights, or a data.frame with the number of rows being equal to the number of edges, where each row gives a vector of weights to its corresponding edge.

kirchhoff_weights

If non-null, the name (or number) of the column of weights that contain the Kirchhoff weights. Must be equal to 1 (or TRUE) in case weights is a single number and those are the Kirchhoff weights.

directional_weights

If non-null, the name (or number) of the column of weights that contain the directional weights.

verbose

There are 3 levels of verbose, level 0, 1 and 2. In level 0, no messages are printed. In level 1, only messages regarding important steps are printed. Finally, in level 2, messages detailing all the steps are printed. The default is 1.

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

data.frame: If the edge weights are given as vectors, should the result be returned as a data.frame?

format

Which format should the data be returned? The options are tibble for tidyr::tibble, sf for POINT, sp for SpatialPointsDataFrame and list for the internal list format.

tibble

Use format instead.

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

messages: Should message explaining how to build the results be given for missing quantities?

compute_characteristics

Should the characteristics of the graph be computed? If NULL it will be determined based on the size of the graph.

check_euclidean

Check if the graph has Euclidean edges? If NULL it will be determined based on the size of the graph.

check_distance_consistency

Check the distance consistency assumption? If NULL it will be determined based on the size of the graph.

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

check_euclidean: Also check if the graph has Euclidean edges? This essentially means that the distance consistency check will also be perfomed. If the graph does not have Euclidean edges due to another reason rather than the distance consistency, then it will already be indicated that the graph does not have Euclidean edges.

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

full: Should the geodesic distances be computed for all the available locations? If FALSE, it will be computed separately for the locations of each group.

obs

Should the geodesic distances be computed at the observation locations?

group

Vector or list containing which groups to compute the distance for. If NULL, it will be computed for all groups.

verbose

Print progress of the computation of the geodesic distances. There are 3 levels of verbose, level 0, 1 and 2. In level 0, no messages are printed. In level 1, only messages regarding important steps are printed. Finally, in level 2, messages detailing all the steps are printed. The default is 1.

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

PtE: Points to compute the metric for.

normalized

are the locations in PtE in normalized distance?

include_vertices

Should the original vertices be included in the distance matrix?

verbose

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

full: Should the resistance distances be computed for all the available locations. If FALSE, it will be computed separately for the locations of each group.

obs

Should the resistance distances be computed at the observation locations?

group

Vector or list containing which groups to compute the distance for. If NULL, it will be computed for all groups.

check_euclidean

Check if the graph used to compute the resistance distance has Euclidean edges? The graph used to compute the resistance distance has the observation locations as vertices.

include_vertices

Should the vertices of the graph be also included in the resulting matrix when using FULL=TRUE?

verbose

Print progress of the computation of the resistance distances. There are 3 levels of verbose, level 0, 1 and 2. In level 0, no messages are printed. In level 1, only messages regarding important steps are printed. Finally, in level 2, messages detailing all the steps are printed. The default is 1.

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

PtE: Points to compute the metric for.

normalized

Are the locations in PtE in normalized distance?

include_vertices

Should the original vertices be included in the Laplacian matrix?

check_euclidean

Check if the graph used to compute the resistance distance has Euclidean edges? The graph used to compute the resistance distance has the observation locations as vertices.

verbose

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

which: If "degree", returns the degree of the vertex. If "indegree", returns the indegree, and if "outdegree", it returns the outdegree.

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

approx: Should the computation of the relative positions be approximate? Default is TRUE. If FALSE, the speed can be considerably slower, especially for large metric graphs.

verbose

Level of verbosity, 0, 1 or 2. The default is 0.

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

full: Should the resistance distances be computed for all the available locations. If FALSE, it will be computed separately for the locations of each group.

obs

Should the resistance distances be computed at the observation locations? It will only compute for locations in which there is at least one observations that is not NA.

group

Vector or list containing which groups to compute the Laplacian for. If NULL, it will be computed for all groups.

verbose

Print progress of the computation of the Laplacian. There are 3 levels of verbose, level 0, 1 and 2. In level 0, no messages are printed. In level 1, only messages regarding important steps are printed. Finally, in level 2, messages detailing all the steps are printed. The default is 1.

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

check_weights: If TRUE will only prune edges with different weights.

check_circles

If TRUE will not prune a vertex such that the resulting edge is a circle.

verbose

Print progress of pruning. There are 3 levels of verbose, level 0, 1 and 2. In level 0, no messages are printed. In level 1, only messages regarding important steps are printed. Finally, in level 2, messages detailing all the steps are printed. The default is 1.

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

edge_lengths: edge lengths to be set to the metric graph edges.

unit

set or override the edge lengths unit.

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

get_cols: Should the names of the columns that created the group variable be returned?

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

group: For which group, should the PtE be returned? NULL means that all PtEs available will be returned.

include_group

Should the group be included as a column? If TRUE, the PtEs for each group will be concatenated, otherwise a single matrix containing the unique PtEs will be returned.

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

unit: If non-NULL, changes from length_unit from the graph construction to unit.

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

mesh_warning: Display a warning if the graph structure change and the metric graph has a mesh object.

verbose

Print progress of the steps when adding observations. There are 3 levels of verbose, level 0, 1 and 2. In level 0, no messages are printed. In level 1, only messages regarding important steps are printed. Finally, in level 2, messages detailing all the steps are printed. The default is 1.

tolerance

. Not used anymore

share_weights

Should the same weight be shared among the split edges? If FALSE, the weights will be removed, and a common weight given by 1 will be given.

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

loc: A matrix or data.frame with two columns containing the locations to generate the data from the edge weights. If data_coords is 'spatial', the first column must be the x-coordinate of the data, and the second column must be the y-coordinate. If data_coords is 'PtE', the first column must be the edge number and the second column must be the distance on edge.

mesh

Should the data be generated to the mesh locations? In this case, the loc argument will be ignored. Observe that the metric graph must have a mesh built for one to use this option. CAUTION: To add edgeweight to data to both the data locations and mesh locations, please, add at the data locations first, then to mesh locations.

data_loc

Should the data be generated to the data locations? In this case, the loc argument will be ignored. Observe that the metric graph must have data for one to use this option. CAUTION: To add edgeweight to data to both the data locations and mesh locations, please, add at the data locations first, then to mesh locations.

weight_col

Which columns of the edge weights should be turned into data? If NULL, all columns will be turned into data.

add

Should the data generated be added to the metric graph internal data?

data_coords

To be used only if mesh is FALSE. It decides which coordinate system to use. If PtE, the user must provide edge_number and distance_on_edge, otherwise if spatial, the user must provide coord_x and coord_y.

normalized

if TRUE, then the distances in distance_on_edge are assumed to be normalized to (0,1). Default FALSE.

tibble

Should the data be returned in a tibble format?

format

If return is TRUE, the format of the output: "tibble", "sf", or "sp". Default is "tibble".

verbose

suppress_warnings

Suppress warnings related to duplicated observations?

return

Should the data be returned? If return_removed is TRUE, only the removed locations will be return (if there is any).

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

bru: Should an 'inlabru'-friendly list be returned?

loc

If bru is set to TRUE, the column names of the location variables. The default name is c('.edge_number', '.distance_on_edge').

loc_name

The name of the location variables. Not needed for rSPDE models.

normalized

If TRUE, then the distances in distance_on_edge are assumed to be normalized to (0,1). Default TRUE.

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

data: A data.frame or named list containing the observations. In case of groups, the data.frames for the groups should be stacked vertically, with a column indicating the index of the group. If data is not NULL, it takes priority over any eventual data in Spoints.

edge_number

Column (or entry on the list) of the data that contains the edge numbers. If not supplied, the column with name "edge_number" will be chosen. Will not be used if Spoints is not NULL.

distance_on_edge

Column (or entry on the list) of the data that contains the edge numbers. If not supplied, the column with name "distance_on_edge" will be chosen. Will not be used if Spoints is not NULL.

coord_x

Column (or entry on the list) of the data that contains the x coordinate. If not supplied, the column with name "coord_x" will be chosen. Will not be used if Spoints is not NULL or if data_coords is PtE.

coord_y

Column (or entry on the list) of the data that contains the y coordinate. If not supplied, the column with name "coord_x" will be chosen. Will not be used if Spoints is not NULL or if data_coords is PtE.

data_coords

It decides which coordinate system to use. If PtE, the user must provide edge_number and distance_on_edge, otherwise if spatial, the user must provide coord_x and coord_y. The option euclidean is . Use spatial instead.

group

Vector. If the data is grouped (for example measured at different time points), this argument specifies the columns (or entries on the list) in which the group variables are stored. It will be stored as a single column .group with the combined entries.

group_sep

separator character for creating the new group variable when grouping two or more variables.

normalized

if TRUE, then the distances in distance_on_edge are assumed to be normalized to (0,1). Default FALSE.

format

Which format should the data be returned? The options are tibble for tidyr::tibble, sf for POINT, sp for SpatialPointsDataFrame and list for the internal list format.

duplicated_strategy

Which strategy to handle observations on the same location on the metric graph (that is, if there are two or more observations projected at the same location). The options are 'closest' and 'jitter'. If 'closest', only the closest observation will be used. If 'jitter', a small perturbation will be performed on the projected observation location. The default is 'closest'.

include_distance_to_graph

When data_coord is 'spatial', should the distance of the observations to the graph be included as a column?

only_return_removed

Should the removed data (if it exists) when using 'closest' duplicated_strategy be returned instead of the processed data?

tolerance

Parameter to control a warning when adding observations. If the distance of some location and the closest point on the graph is greater than the tolerance, the function will display a warning. This helps detecting mistakes on the input locations when adding new data.

verbose

If TRUE, report steps and times.

suppress_warnings

Suppress warnings related to duplicated observations?

Spoints

Use data instead.

tibble

Use format instead.

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

data: A data.frame or named list containing the observations. In case of groups, the data.frames for the groups should be stacked vertically, with a column indicating the index of the group. data can also be an sf object, a SpatialPointsDataFrame

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")

Examples

Run this code

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

Run the code above in your browser using DataLab

Description

Arguments

Value

Public fields

Methods

Public methods

Method new()

Usage

Arguments

Details

Returns

Method remove_small_circles()

Usage

Arguments

Returns

Method get_edges()

Usage

Arguments

Returns

Method get_bounding_box()

Usage

Arguments

Returns

Method get_vertices()

Usage

Arguments

Returns

Method export()

Usage

Arguments

Returns

Method leaflet()

Usage

Arguments

Method mapview()

Usage

Arguments

Method set_edge_weights()

Usage

Arguments

Returns

Method get_edge_weights()

Usage

Arguments

Returns

Method get_vertices_incomp_dir()

Usage

Returns

Method summary()

Usage

Arguments

Returns

Method print()

Usage

Returns

Method compute_characteristics()

Usage

Arguments

Returns

Method check_euclidean()

Usage

Returns

Method check_distance_consistency()

Usage

Returns

Method compute_geodist()

Usage

Arguments

Returns

Method compute_geodist_PtE()

Usage

Arguments

Returns

Method compute_geodist_mesh()

Usage

Returns

Method compute_resdist()

Usage

Arguments

Returns

Method `new()`

Method `remove_small_circles()`

Method `get_edges()`

Method `get_bounding_box()`

Method `get_vertices()`

Method `export()`

Method `leaflet()`

Method `mapview()`

Method `set_edge_weights()`

Method `get_edge_weights()`

Method `get_vertices_incomp_dir()`

Method `summary()`

Method `print()`

Method `compute_characteristics()`

Method `check_euclidean()`

Method `check_distance_consistency()`

Method `compute_geodist()`

Method `compute_geodist_PtE()`

Method `compute_geodist_mesh()`

Method `compute_resdist()`

Method `compute_resdist_PtE()`

Method `get_degrees()`

Method `compute_PtE_edges()`

Method `compute_resdist_mesh()`

Method `compute_laplacian()`

Method `prune_vertices()`

Method `set_manual_edge_lengths()`

Method `get_groups()`

Method `get_PtE()`

Method `get_edge_lengths()`

Method `get_locations()`

Method `observation_to_vertex()`

Method `edgeweight_to_data()`

Method `get_mesh_locations()`

Method `clear_observations()`

Method `process_data()`

Method `add_observations()`