--- title: "Working with metric graphs" author: "David Bolin, Alexandre B. Simas, and Jonas Wallin" date: "Created: 2022-11-23. Last modified: `r Sys.Date()`." output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Working with metric graphs} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} knitr::opts_chunk$set(echo = TRUE) library(MetricGraph) set.seed(1) ``` # Introduction Networks such as street or river networks are examples of metric graphs. A compact metric graph $\Gamma$ consists of a set of finitely many vertices $\mathcal{V}=\{v_i\}$ and a finite set $\mathcal{E}=\{e_j\}$ of edges connecting the vertices. Each edge $e$ is a curve of finite length $l_e$ that connects two vertices. These curves are parameterized by arc length and a location $s\in \Gamma$ is a position on an edge, and can thus be represented as a tuple $(e,t)$ where $t\in[0,l_e]$. Compared to regular graphs, where one typically defines functions on the vertices, we are for metric graphs interested in function that are defined on both the vertices and the edges. In this vignette we will introduce the `metric_graph` class of the `MetricGraph` package. This class provides a user friendly representation of metric graphs, and we will show how to use the class to construct and visualize metric graphs, add data to them, and work with functions defined on the graphs. For details about Gaussian processes and inference on metric graphs, we refer to the Vignettes * [Gaussian random fields on metric graphs](random_fields.html) * [INLA interface of Whittle--Matérn fields](inla_interface.html) * [inlabru interface of Whittle--Matérn fields](inlabru_interface.html) * [Whittle--Matérn fields with general smoothness](fem_models.html) # Constructing metric graphs ## Basic constructions and properties A metric graph can be constructed in two ways. The first is to specify all edges in the graph as a `list` object, where each entry is a matrix. To illustrate this, we first construct the following edges ```{r} edge1 <- rbind(c(0,0),c(1,0)) edge2 <- rbind(c(0,0),c(0,1)) edge3 <- rbind(c(0,1),c(-1,1)) theta <- seq(from=pi,to=3*pi/2,length.out = 50) edge4 <- cbind(sin(theta),1+ cos(theta)) edges = list(edge1, edge2, edge3, edge4) ``` We can now create the graph based on the `edges` object as follows ```{r, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} graph <- metric_graph$new(edges = edges) graph$plot() ``` The plot function that was used to create the plot above has various parameters to set the sizes and colors of the vertices and edges, and it has a `plotly` argument to visualize the graph in 3D. For this to work, the `plotly` library must be installed. ```{r, message=FALSE, fig.show='hold',fig.align = "center",echo=TRUE} graph$plot(type = "plotly", vertex_size = 5, vertex_color = "blue", edge_color = "red", edge_width = 2) ``` It is also important to know that the `2d` version of the `plot()` method returns a `ggplot2` object and can be modified as such. For instance: ```{r} p <- graph$plot() p + ggplot2::labs(title = "Metric graph", x = "long", y = "lat") ``` Similarly, the `3d` version of the `plot()` method returns a `plotly` object that can also be modified. For instance: ```{r} p <- graph$plot(type = "plotly") p <- plotly::layout(p, title = "Metric graph", scene = list(xaxis= list(title = "Long"),yaxis=list(title = "Lat"))) p ``` We can now obtain various properties of the graph: The vertex matrix, which specifies the Euclidian coordinates of the vertices is ```{r} graph$V ``` and the edge matrix that specified the edges of the graph (i.e., which vertices that are connected by edges) is ```{r} graph$E ``` To obtain the geodesic (shortest path) distance between the vertices, we can use the function `compute_geodist`: ```{r} graph$compute_geodist() graph$geo_dist ``` The second option it to construct the graph using two matrices `V` and `E` that specify the locations (in Euclidean space) of the vertices and the edges. In this case, it is assumed that the graph only has straight edges: ```{r, fig.show='hold',fig.align = "center",echo=TRUE} V <- rbind(c(0, 0), c(1, 0), c(0, 1), c(-1, 1)) E <- rbind(c(1, 2), c(1, 3), c(3, 4), c(4, 1)) graph2 <- metric_graph$new(V = V, E = E) graph2$plot() ``` A third option is to create a graph from a `SpatialLines` object: ```{r, message=FALSE, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} library(sp) line1 <- Line(rbind(c(0,0),c(1,0))) line2 <- Line(rbind(c(0,0),c(0,1))) line3 <- Line(rbind(c(0,1),c(-1,1))) theta <- seq(from=pi,to=3*pi/2,length.out = 50) line4 <- Line(cbind(sin(theta),1+ cos(theta))) Lines = sp::SpatialLines(list(Lines(list(line1),ID="1"), Lines(list(line2),ID="2"), Lines(list(line3),ID="3"), Lines(list(line4),ID="4"))) graph <- metric_graph$new(edges = Lines) graph$plot() ``` A final option is to create from a `MULTILINESTRING` object: ```{r, message=FALSE, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} library(sf) line1 <- st_linestring(rbind(c(0,0),c(1,0))) line2 <- st_linestring(rbind(c(0,0),c(0,1))) line3 <- st_linestring(rbind(c(0,1),c(-1,1))) theta <- seq(from=pi,to=3*pi/2,length.out = 50) line4 <- st_linestring(cbind(sin(theta),1+ cos(theta))) multilinestring = st_multilinestring(list(line1, line2, line3, line4)) graph <- metric_graph$new(edges = multilinestring) graph$plot() ``` ## Tolerances for merging vertices and edges The constructor of the graph has one argument, `perform_merges` and an additional argument `tolerance` which is used for connecting edges that are close in Euclidean space. Specifically, the `tolerance` argument is given as a list with three elements: * `vertex_vertex` vertices that are closer than this number are merged (the default value is `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 (the default value is `1e-7`) * `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 (the default value is `0` which means that the option is not used) These options are often needed when constructing graphs based on real data, for example from OpenStreetMap as we will see later. To illustrate these options, suppose that we want to construct a graph from the following three edges. We will set `perform_merges` to `TRUE`, to show how they are merged with the default choice of tolerances. ```{r, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} edge1 <- rbind(c(0,0),c(1,0)) edge2 <- rbind(c(0,0.03),c(0,0.75)) edge3 <- rbind(c(-1,1),c(0.5,0.03)) edge4 <- rbind(c(0,0.75), c(0,1)) edge5 <- rbind(c(-1,0), c(-1, 0.9995)) edges = list(edge1, edge2, edge3, edge4, edge5) graph3 <- metric_graph$new(edges = edges, perform_merges = TRUE) graph3$plot(degree = TRUE) print(graph3$nV) ``` We added the option `degree=TRUE` to the plot here to visualize the degrees of each vertex. As expected, one sees that all vertices have degree 1, and none of the three edges are connected. If these are streets in a street network, one might suspect that the two vertices at $(0,0)$ and $(0,0.03)$ really should be the same vertex so that the two edges are connected. This can be adjusted by increasing the `vertex_vertex` tolerance: ```{r, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} graph3 <- metric_graph$new(edges = edges, perform_merges = TRUE, tolerance = list(vertex_vertex = 0.05)) graph3$plot(degree = TRUE) ``` One might also want to add the vertex at $(0.5, 0.03)$ as a vertex on the first edge, so that the two edges there are connected. This can be done by adjusting the `vertex_edge` tolerance: ```{r, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} graph3 <- metric_graph$new(edges = edges, perform_merges = TRUE, tolerance = list(vertex_vertex = 0.05, vertex_edge = 0.1)) graph3$plot(degree = TRUE) ``` We can see that the vertex at $(0.5,0)$ was indeed connected with the edge from $(0,0)$ to $(1,0)$ and that vertex now has degree 3 since it is connected with three edges. One can also note that the `edges` object that was used to create the graph is modified internally in the `metric_graph` object so that the connections are visualized correctly in the sense that all edges are actually shown as connected edges. Finally, to add a vertex at the intersection between `edge2` and `edge3` we can adjust the `edge_edge` tolerance: ```{r, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} graph3 <- metric_graph$new(edges = edges, perform_merges = TRUE, tolerance = list(vertex_vertex = 0.2, vertex_edge = 0.1, edge_edge = 0.001)) graph3$plot(degree = TRUE) ``` Now, the structure of the metric graph does not change if we add or remove vertices of degree 2. Because of this,one might want to remove vertices of degree 2 since this can reduce computational costs. This can be done by setting the `remove_deg2` argument while creating the graph: ```{r, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} graph3 <- metric_graph$new(edges = edges, perform_merges = TRUE, tolerance = list(vertex_vertex = 0.2, vertex_edge = 0.1, edge_edge = 0.001), remove_deg2 = TRUE) graph3$plot(degree = TRUE) ``` Observe that one vertex of degree 2 was not removed. This is due to the fact that if we consider the direction, this vertex has directions incompatible for removal. We can see this by setting the argument `direction=TRUE` in the `plot()` method: ```{r, fig.show='hold',fig.align = "center",echo=TRUE} graph3$plot(direction = TRUE) ``` We can also avoid performing these merges by setting using the default constructor (which is equivalent to set the `perform_merges` argument to `FALSE`): ```{r, message=FALSE, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} graph4 <- metric_graph$new(edges = edges) graph4$plot(degree = TRUE) ``` Observe that the two vertices around the point $(-1,1)$ were merged. This is because there is an additional step to merge close vertices that is performed even with `perform_merges` set to `FALSE`. To also skip this merge, we can also set `merge_close_vertices` to `FALSE`: ```{r, message=FALSE, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} graph4 <- metric_graph$new(edges = edges, merge_close_vertices=FALSE) graph4$plot(degree = TRUE) ``` We can see now that the two vertices around the point $(-1,1)$ were not merged. ## Edge lengths Whenever we create a metric graph, the edge lengths will be automatically computed by obtaining the lengths of the edges. However, sometimes one might want to provide manual edge lengths. Let us consider the following example: ```{r, message=FALSE, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} library(sp) line1 <- Line(rbind(c(0,0),c(1,0))) line2 <- Line(rbind(c(0,0),c(0,1))) line3 <- Line(rbind(c(0,1),c(-1,1))) theta <- seq(from=pi,to=3*pi/2,length.out = 25) line4 <- Line(cbind(sin(theta),1+ cos(theta))) Lines = sp::SpatialLines(list(Lines(list(line1),ID="1"), Lines(list(line2),ID="2"), Lines(list(line3),ID="3"), Lines(list(line4),ID="4"))) graph <- metric_graph$new(edges = Lines) graph$plot() ``` We can obtain the edge lenghts by using the `get_edge_lengths()` method: ```{r, message=FALSE, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} graph$get_edge_lengths() ``` Observer that we know that the actual length of edge 4 is $\pi/2$, which is not quite right (observe that edge 4 is an approximation of a quarter of a circle by a polygon with 25 points): ```{r, message=FALSE, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} pi/2 - graph$get_edge_lengths()[4] ``` We can provide the actual edge lengths, by using the `set_manual_edge_lengths()` method: ```{r, message=FALSE, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} graph$set_manual_edge_lengths(c(1,1,1,pi/2)) graph$get_edge_lengths() ``` We can also manually provide the edge lengths when creating the metric graph: ```{r, message=FALSE, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} graph <- metric_graph$new(edges = Lines, manual_edge_lengths = c(1,1,1,pi/2)) graph$get_edge_lengths() ``` However, it is important to note that if one passes the manual_edge_lengths when creating the graph, it will automatically set `perform_merges` to `FALSE`, as there is no consistent way to obtain the edge lengths after the merges from the manual edge lengths. Nevertheless, `merge_close_vertices` can be set to `TRUE`. ## Characteristics of the graph A brief summary of the main characteristics of the graph can be obtained by the `compute_characteristics()` method: ```{r} graph3$compute_characteristics() ``` We can, then, view those characteristics by simply printing the `metric_graph` object: ```{r} graph3 ``` Observe that we do not know that the graph has Euclidean edges. We can check by using the `check_euclidean()` method: ```{r} graph3$check_euclidean() ``` Let us view the characteristics again: ```{r} graph3 ``` It can happen that we have that the graph does not have Euclidean edges without the need to check the distance consistency. However, if one wants to check if the graph satisfies the distance consistency assumption, one can run the `check_distance_consistency()` function: ```{r} graph3$check_distance_consistency() ``` Further, the individual characteristics can be accessed (after running the `compute_characteristics()` method) through the `characteristics` component of the graph object: ```{r} graph3$characteristics ``` ## Summaries of metric graphs We can also obtain a summary of the informations contained on a metric graph object by using the `summary()` method. Let us obtain a summary of informations of `graph3`: ```{r} summary(graph3) ``` Observe that there are some quantities that were not computed on the summary. We can see how to compute them by setting the argument `messages` to `TRUE`: ```{r} summary(graph3, messages = TRUE) ``` Finally, the `summary()` can also be accessed from the metric graph object: ```{r} graph3$summary() ``` ## Vertices and edges The metric graph object has the `edges` and `vertices` elements in its list. We can get a quick summary from them by calling these elements: ```{r} graph3$vertices ``` and ```{r} graph3$edges ``` We can also look at individual edges and vertices. For example, let us look at vertice number 2: ```{r} graph3$vertices[[2]] ``` Similarly, let us look at edge number 4: ```{r} graph3$edges[[4]] ``` We have a message informing us that the relative positions of the edges were not computed. They are used to produce better plots when using the `plot_function()` method, see the section "Improving the plot obtained by `plot_function`" below. To compute the relative positions, we run the `compute_PtE_edges()` method: ```{r} graph3$compute_PtE_edges() ``` Now, we take a look at edge number 4 again: ```{r} graph3$edges[[4]] ``` ## Understanding coordinates on graphs The locations of the vertices are specified in Euclidean coordinates. However, when specifying a position on the graph, it is not practical to work with Euclidean coordinates since not all locations in Euclidean space are locations on the graph. It is instead better to specify a location on the graph by the tuple $(i, t)$, where $i$ denotes the number of the edge and $t$ is the location on the edge. The location $t$ can either be specified as the distance from the start of the edge (and then takes values between 0 and the length of the edge) or as the normalized distance from the start of the edge (and then takes values between 0 and 1). The function `coordinates` can be used to convert between coordinates in Euclidean space and locations on the graph. For example the location at distance 0.2 from the start of the second edge is: ```{r} graph$coordinates(PtE = matrix(c(2, 0.2), 1,2), normalized = FALSE) ``` In this case, since the edge has length 1, the location of the point at normalized distance 0.2 from the start of the edge is the same: ```{r} graph$coordinates(PtE = matrix(c(2, 0.2), 1,2), normalized = TRUE) ``` The function can also be used to find the closest location on the graph for a location in Euclidean space: ```{r} graph$coordinates(XY = matrix(c(0, 0.2), 1,2)) ``` In this case, the `normalized` argument decides whether the returned value should be given in normalized distance or not. ## Methods for working with real data To illustrate the useage of `metric_graph` on some real data, we download OSM data with the `fetch_osm()` helper. In the following code we extract highways for a part of the city of Copenhagen: ```{r, eval=FALSE} bbox <- c(12.5900, 55.6000, 12.6850, 55.6450) data_sf <- fetch_osm(bbox = bbox, value = c("motorway", "primary", "secondary", "tertiary")) ``` ```{r, include=FALSE} # Same call as above, but reading a saved Overpass response so that building # the vignette does not depend on the Overpass API being available. bbox <- c(12.5900, 55.6000, 12.6850, 55.6450) data_sf <- fetch_osm(bbox = bbox, value = c("motorway", "primary", "secondary", "tertiary"), cache_path = "osm_data/copenhagen.osm") ``` ```{r, fig.show='hold',fig.align = "center",fig.height = 7, echo=TRUE, message=FALSE} graph5 <- metric_graph$new(lapply(data_sf$osm_lines$geometry, function(dat){sf::st_coordinates(dat)[,1:2]})) graph5$plot(vertex_size = 0) ``` There are a few things to note about data like this. The first is that the coordinates are given in Longitude and Latitude. Because of this, the edge lengths are by default given in degrees, which may result in very small numbers: ```{r} range(graph5$get_edge_lengths()) ``` This may cause numerical instabilities when dealing with random fields on the graph, and it also makes it difficult to interpret results (unless one has a good intuition about distances in degrees). To avoid such problems, it is better to set the `longlat` argument when constructing the graph: ```{r, message=FALSE} graph5 <- metric_graph$new(lapply(data_sf$osm_lines$geometry, function(dat){sf::st_coordinates(dat)[,1:2]}), longlat = TRUE) ``` This tells the constructor that the coordinates are given in Longitude and Latitude and that distances should be calculated in km. So if we now look at the edge lengths, they are given in km: ```{r} range(graph5$get_edge_lengths()) ``` Alternatively, and more conveniently, whenever the `sf` object has a valid `crs`, it will automatically use this `crs` to set the correct coordinate reference system (CRS) in the metric graph. Above, we ended up removing the `crs` when we created the `linestring` object from the resulting `osm_lines`. Let us, instead, build the graph directly using the `osmdata_sf` object: ```{r, message=FALSE} graph5 <- metric_graph$new(data_sf) ``` We can see now that `graph5` automatically has the correct CRS: ```{r} graph5 ``` As a shortcut, the OSM download and the graph construction can be done in a single call with `metric_graph_from_osm()`: ```{r, eval=FALSE} graph5 <- metric_graph_from_osm(bbox = c(12.5900, 55.6000, 12.6850, 55.6450), value = c("motorway", "primary", "secondary", "tertiary")) ``` This also allows us to plot the graph interactively with the underlying world map, if the data has a coordinate reference system, by setting `type = "mapview"` in the `plot()` method: ```{r, message=FALSE, warning=FALSE} graph5$plot(type = "mapview", vertex_size = 0) ``` We can also check the edge lengths: ```{r} range(graph5$get_edge_lengths()) ``` Another advantage of adding the `osmdata` object, is that the metric graph automatically adds the edge observations as `edge_weights`: ```{r} graph5$get_edge_weights() ``` We can also let the color of the edges be determined by some edge weight. For example, let us take `maxspeed`: ```{r} graph5$plot(vertex_size = 0, edge_weight = "maxspeed", type="mapview") ``` Similarly, we can also set the edge width based on an edge weight (for this case, we can only use `type = "ggplot"`, which is the default). In this example we will choose the column `lanes` to determine the edge widths. If the number of lanes is not available, the edge will be removed (we will replace the `NA`s by zero). ```{r} graph5$set_edge_weights(weights = graph5$mutate_weights(lanes = ifelse(is.na(lanes),0,lanes), lanes = as.numeric(lanes))) graph5$plot(vertex_size = 0, edge_weight = "maxspeed", edge_width_weight = "lanes") ``` However, observe that the edge widths are always relative, with the largest being set to `edge_width`. So, let us set `edge_width` to 4 to make it easier to perceive the differences: ```{r} graph5$set_edge_weights(weights = graph5$mutate_weights(lanes = ifelse(is.na(lanes),0,lanes), lanes = as.numeric(lanes))) graph5$plot(vertex_size = 0, edge_weight = "maxspeed", edge_width_weight = "lanes", edge_width = 4) ``` If one does not want to have the edge weights added, one must set `include_edge_weights` to `FALSE`: ```{r, message=FALSE} graph5 <- metric_graph$new(data_sf, include_edge_weights=FALSE) graph5$get_edge_weights() ``` Similarly, if one wants just to add some columns of the `osmdata` object as edge weights, one can pass a vector with the column names as the `include_edge_weights` argument. For example, let us only get the columns `highway` and `lanes`: ```{r, message=FALSE} graph5 <- metric_graph$new(data_sf, include_edge_weights=c("highway", "lanes")) graph5$get_edge_weights() ``` The same idea also works is one has an `sf` object instead. Let us obtain the `sf` version from the `osmdata` object by extracting the `osm_lines` element: ```{r} data_sf <- data_sf$osm_lines ``` We can now directly create the metric graph object: ```{r, message=FALSE} graph5 <- metric_graph$new(data_sf) ``` Let us check that `graph5` still has the correct CRS: ```{r} graph5 ``` and the correct edge lengths: ```{r} range(graph5$get_edge_lengths()) ``` Also, that it has the edge weights: ```{r} graph5$get_edge_weights() ``` The argument `include_edge_weights` can also be used in same manner for `osmdata_sf` objects. The second thing to note is that the constructor gave a warning that the graph is not connected. This might not be ideal for modeling and we may want to study the different connected components separately. If this is not a concern, one can set the argument `check_connected = FALSE` while creating the graph. In this case the check is skipped and no warning is printed; the resulting `metric_graph` works exactly as a connected one (see [Working with disconnected metric graphs](graph_components.html) for a focused walkthrough). To inspect the components we can use `get_components()`, which returns a list of `metric_graph` objects sorted by total edge length: ```{r} comps <- graph5$get_components() length(comps) sapply(comps, function(g) sum(as.numeric(g$edge_lengths))) ``` To draw every component in its own colour we pass `components = TRUE` to `plot()`: ```{r, message=FALSE, warning = FALSE, fig.show='hold',fig.align = "center",fig.height = 7,echo=TRUE} graph5$plot(vertex_size = 0, type = "mapview", components = TRUE) ``` One reason for having multiple components here might be that we set the tolerance for merging nodes too low. In fact, by looking at the edge lengths we see that we have vertices that are as close as ```{r} min(graph5$get_edge_lengths(unit='m')) ``` meters. Let us increase the tolerances so that vertices that are at most a distance of 100 meters (0.1km) apart should be merged: ```{r, message=FALSE, warning = FALSE, fig.show='hold',fig.align = "center",fig.height = 7,echo=TRUE, message=FALSE} graph5 <- metric_graph$new(data_sf, tolerance = list(vertex_vertex = 0.1), check_connected = FALSE) graph5$plot(vertex_size = 0, type = "mapview", components = TRUE) ``` With this choice, let us check the number of connected components: ```{r} length(graph5$get_components()) ``` If we want to keep only the largest connected component for further analysis, we can take the first entry of `get_components()` (components are sorted by total edge length, descending): ```{r} graph5 <- graph5$get_components()[[1]] ``` Let us take a quick look at its vertices and edges: ```{r} graph5$vertices ``` and ```{r} graph5$edges ``` Also observe that it has the corresponding edge weights: ```{r} graph5$get_edge_weights() ``` It is also relevant to obtain a summary of this graph: ```{r} summary(graph5) ``` We have that this graph does not have Euclidean edges. Also observe that we have the units for the vertices and lengths, and also the coordinate reference system being used by this object. Alternatively, one can also add create metric graphs from `SSN` objects. All one needs to do is to directly pass the `SSN` object as `edges`. This will also ensure that the correct `CRS` is used. For example: ```{r, message=FALSE} library(SSN2) copy_lsn_to_temp() path <- file.path(tempdir(), "MiddleFork04.ssn") mf04p <- ssn_import( path = path, predpts = c("pred1km", "CapeHorn"), overwrite = TRUE ) river_graph <- metric_graph$new(mf04p) ``` Let us take a look at the graph: ```{r} river_graph$plot() ``` Let us also look at the interactive plot with the underlying map: ```{r, warning=FALSE} river_graph$plot(vertex_size = 0, type = "mapview") ``` Similarly to `osmdata` objects, when using `SSN` objects, the edge observations are also added as edge weights: ```{r} river_graph$get_edge_weights() ``` The argument `include_edge_weights` can also be used in same manner for `SSN` objects. However, for `SSN` objects, observations are also automatically added in the metric graph creation: ```{r} river_graph$get_data() ``` With respect to addition of data in `SSN` objects, we have the option `include_obs` that acts in the same manner as the `include_edge_weights` argument. For example, one can choose to not include the data by setting `include_obs` to `FALSE`: ```{r, message=FALSE} river_graph <- metric_graph$new(mf04p, include_obs = FALSE) ``` Let us confirm that no data was added: ```{r, error=TRUE} river_graph$get_data() ``` Finally, one can select which columns to add, by passing the names (or numbers) of the columns as the `include_edge_weights` argument. ```{r, message=FALSE} river_graph <- metric_graph$new(mf04p, include_obs = c("SLOPE", "Summer_mn")) ``` and the data: ```{r} river_graph$get_data() ``` # Adding data to the graph Given that we have constructed the metric graph, we can now add data to it. For further details on data manipulation on metric graphs, see [Data manipulation on metric graphs](metric_graph_data.html). As an example, let us consider the first graph again and suppose that we have observations at a distance 0.5 from the start of each edge. One way of specifying this is as follows ```{r, fig.show='hold',fig.align = "center",echo=TRUE} obs.loc <- cbind(1:4, rep(0.5, 4)) obs <- c(1,2,3,4) df_graph <- data.frame(y = obs, edge_number = obs.loc[,1], distance_on_edge = obs.loc[,2]) graph$add_observations(data = df_graph) graph$plot(data = "y", data_size = 2) ``` In certain situations, it might be easier to specify the relative distances on the edges, so that 0 represents the start and 1 the end of the edge (instead of the edge length). To do so, we can simply specify `normalized = TRUE` when adding the observations. For example, let us add one more observation at the midpoint of the fourth edge: ```{r, fig.show='hold',fig.align = "center",echo=TRUE} obs.loc <- matrix(c(4, 0.5),1,2) obs <- c(5) df_new <- data.frame(y=obs, edge_number = obs.loc[,1], distance_on_edge = obs.loc[,2]) graph$add_observations(data=df_new, normalized = TRUE) graph$plot(data = "y") ``` An alternative method is to specify the observations as spatial points objects, where the locations are given in Euclidean coordinates. In this case the observations are added to the closes location on the graph: ```{r, fig.show='hold',fig.align = "center",echo=TRUE} obs.loc <- rbind(c(0.7, 0), c(0, 0.2)) obs <- c(6,7) points <- SpatialPointsDataFrame(coords = obs.loc, data = data.frame(y = obs)) graph$add_observations(points) graph$plot(data = "y") ``` If we want to replace the data in the object, we can use `clear_observations()` to remove all current data: ```{r} graph$clear_observations() ``` The `metric_graph` object can hold multiple variables of data, and one can also specify a `group` argument that it useful for specifying that data is grouped, which for example is the case with data observed at different time points. As an example, let us add two variables observed at two separate time points: ```{r} obs.loc <- cbind(c(1:4, 1:4), c(rep(0.5, 4), rep(0.7, 4))) df_rep <- data.frame(y = c(1, 2, NA, 3, 4, 6, 5, 7), x = c(NA, 8, 9, 10, 11, 12, 13, NA), edge_number = obs.loc[,1], distance_on_edge = obs.loc[,2], time = c(rep(1, 4), rep(2, 4))) graph$add_observations(data = df_rep, group = "time") ``` If `NA` is given in some variable, this indicates that this specific variable is not measured at that location and group. We can now plot the individual variables by specifying their names in the plot function together with the group number that we want to see. By default the first group is shown. ```{r, fig.show='hold',fig.align = "center",echo=TRUE} graph$plot(data = "y", group = 2) ``` In some cases, we might want to add the observation locations as vertices in the graph. This can be done as follows: ```{r, fig.show='hold',fig.align = "center",echo=TRUE} graph$observation_to_vertex() graph$plot(data = "x", group = 1) ``` One can note that the command adds all observation locations, from all groups as vertices. Finally, let us obtain a summary of the graph containing data: ```{r} summary(graph) ``` When dealing with `SSN` objects, one can also directly add the `SSN` object as data: ```{r, message=FALSE} river_graph$clear_observations() river_graph$add_observations(data = mf04p) ``` We can see that the data has been added correctly: ```{r} river_graph$get_data() ``` We can also plot the data: ```{r} river_graph$plot(data = "Summer_mn", vertex_size = 0.25) ``` Let us clear the observations from the river graph: ```{r} river_graph$clear_observations() ``` One can also directly add `sf` objects into the metric graph. For example, the object `mf04p$obs` is an `sf` object. We can also add the obsevations as: ```{r, message=FALSE} river_graph$add_observations(data = mf04p$obs) ``` We can see that the observations have been added accordingly: ```{r} river_graph$get_data() ``` # Working with functions on metric graphs When working with data on metric graphs, one often wants to display functions on the graph. The best way to visualize functions on the graph is to evaluate them on a fine mesh over the graph and then use `plot_function`. To illustrate this procedure, let us consider the following graph: ```{r, fig.show='hold',fig.align = "center",echo=TRUE, message=FALSE} V <- rbind(c(0, 0), c(1, 0), c(1, 1), c(0, 1), c(-1, 1), c(-1, 0), c(0, -1)) E <- rbind(c(1, 2), c(2, 3), c(3, 4), c(4, 5), c(5, 6), c(6, 1), c(4, 1),c(1, 7)) graph <- metric_graph$new(V = V, E = E) graph$build_mesh(h = 0.5) graph$plot(mesh=TRUE) ``` In the command `build_mesh`, the argument `h` decides the largest spacing between nodes in the mesh. As can be seen in the plot, the mesh is very coarse, so let's reduce the value of `h` and rebuild the mesh: ```{r} graph$build_mesh(h = 0.01) ``` Suppose now that we want to display the function $f(x, y) = x^2 - y^2$ on this graph. We then first evaluate it on the vertices of the mesh and then use the function `plot_function` to display it: ```{r, fig.show='hold',fig.align = "center",echo=TRUE} x <- graph$mesh$V[, 1] y <- graph$mesh$V[, 2] f <- x^2 - y^2 graph$plot_function(X = f) ``` Alternatively, we can set `type = "plotly"` in the plot command to get a 3D visualization of the function: ```{r, fig.show='hold',fig.align = "center",fig.height=7,echo=TRUE} graph$plot_function(X = f, type = "plotly") ``` When the first argument of `plot_function` is a vector, the function assumes that the values in the vector are the values of the function evaluated at the vertices of the mesh. As an alternative, one can also provide a new dataset. To illustrate this, let us first construct a set of locations that are evenly spaced over each edge. Then, we will convert the data to Euclidean coordinates so that we can evaluate the function above. Then, process the data and finally plot the result: ```{r, fig.show='hold',fig.align = "center",fig.height=7,echo=TRUE} n.e <- 30 PtE <- cbind(rep(1:graph$nE, each = n.e), rep(seq(from = 0, to = 1, length.out = n.e), graph$nE)) XY <- graph$coordinates(PtE) f <- XY[, 1]^2 - XY[, 2]^2 data_f <- data.frame(f = f, "edge_number" = PtE[,1], "distance_on_edge" = PtE[,2]) data_f <- graph$process_data(data = data_f, normalized=TRUE) graph$plot_function(data = "f", newdata = data_f, type = "plotly") ``` Alternatively, we can add the data to the graph, and directly plot by using the `data` argument. To illustration purposes, we will build this next plot as a 2d plot: ```{r, fig.show='hold',fig.align = "center",fig.height=7,echo=TRUE} graph$add_observations(data = data_f, clear_obs = TRUE, normalized = TRUE) graph$plot_function(data = "f") ``` ## Further details on `plot_function` By default, the values along the edges are interpolated try to provide a better plot. This behavior can be disabled by setting `interpolate_plot` to `FALSE`. We begin by recreating the first graph we used in this vignette: ```{r, message=FALSE} edge1 <- rbind(c(0,0),c(1,0)) edge2 <- rbind(c(0,0),c(0,1)) edge3 <- rbind(c(0,1),c(-1,1)) theta <- seq(from=pi,to=3*pi/2,length.out = 50) edge4 <- cbind(sin(theta),1+ cos(theta)) edges = list(edge1, edge2, edge3, edge4) graph <- metric_graph$new(edges = edges) ``` Let us create a coarse mesh, so the interpolation can be easily seen. ```{r} graph$build_mesh(h=0.8) graph$plot(mesh=TRUE) ``` Let us compute the function the same function as before on this mesh: ```{r} XY <- graph$mesh$V f <- XY[, 1]^2 - XY[, 2]^2 ``` We can directly plot from the mesh values. Let us start with the default, the interpolated plot: ```{r} graph$plot_function(f) ``` We can, now, turn off the interpolation by setting `interpolate_plot` to `FALSE`: ```{r} graph$plot_function(f, interpolate_plot = FALSE) ``` Alternatively, we can supply the data through the `newdata` argument. To such an end, we will need to supply the `data.frame`. So let us build it: ```{r} df_f <- data.frame(edge_number = graph$mesh$VtE[,1], distance_on_edge = graph$mesh$VtE[,2], f = f) ``` Let us now process the `data.frame` to the graph's internal data format using the `process_data()` method: ```{r} df_f <- graph$process_data(data = df_f, normalized=TRUE) ``` We will now plot this function. First, let us do the default plot from `plot_function`: ```{r} graph$plot_function(data = "f", newdata= df_f) ``` Let us now, create the same plot with `interpolate_plot=FALSE`: ```{r} graph$plot_function(data = "f", newdata= df_f, interpolate_plot=FALSE) ``` Let us now obtain a 3d plot. First, of the default version: ```{r} graph$plot_function(data = "f", newdata= df_f, type = "plotly") ``` Now, of the non-interpolated version: ```{r} graph$plot_function(data = "f", newdata= df_f, type = "plotly", interpolate_plot = FALSE) ``` ### Note about continuity However, it is important to observe that `plot_function` assumes continuity of the function by default. Let us see an example of a discontinuous function, and observe the effect of `plot_function`. For example, let us consider the function that takes the edge number (normalized). Let us also refine the mesh a bit, so it is easier to observe what is happening. ```{r} graph$build_mesh(h=0.2) f <- graph$mesh$VtE[,1]/4 ``` Let us proceed with the creation of the `data.frame` and processing of the data: ```{r} df_f <- data.frame(edge_number = graph$mesh$VtE[,1], distance_on_edge = graph$mesh$VtE[,2], f = f) df_f <- graph$process_data(data = df_f, normalized=TRUE) ``` We will now plot this function with the default plot from `plot_function`: ```{r} graph$plot_function(data = "f", newdata= df_f) ``` Let us now, create the same plot with `interpolate_plot=FALSE`: ```{r} graph$plot_function(data = "f", newdata= df_f, interpolate_plot=FALSE) ``` Let us now obtain a 3d plot. First, of the default version: ```{r} graph$plot_function(data = "f", newdata= df_f, type = "plotly") ``` Now, of the non-interpolated version: ```{r} graph$plot_function(data = "f", newdata= df_f, type = "plotly", interpolate_plot = FALSE) ``` Observe that for both versions we have the same behavior around the vertices (which are the discontinuity points). To work with discontinuous functions, the simplest option is to create a mesh that does not assume continuity: ```{r} graph$build_mesh(h=0.8, continuous = FALSE) ``` In this mesh, each vertex is split into one vertex per edge connecting to the vertex, which allows for discontinuous functions. ```{r} f <- graph$mesh$PtE[,1]/4 graph$plot_function(f) ``` Similarly to the case for continuous meshes, we have the `interpolate_plot` option: ```{r} graph$plot_function(f, interpolate_plot = FALSE) ``` Now, the 3d plot: ```{r} graph$plot_function(f, type = "plotly", interpolate_plot = FALSE) ``` Alternatively, we can similarly plot by setting the `data.frame` and passing the `newdata` argument: ```{r} df_f <- data.frame(edge_number = graph$mesh$VtE[,1], distance_on_edge = graph$mesh$VtE[,2], f = f) df_f <- graph$process_data(data = df_f, normalized=TRUE) ``` Let us now build the plots. In this case, we need to set the `continuous` argument to `FALSE`. First the 2d plot: ```{r} graph$plot_function(data = "f", newdata= df_f, continuous = FALSE) ``` Now, the 3d plot: ```{r} graph$plot_function(data = "f", newdata= df_f, type = "plotly", continuous = FALSE) ```