RA2CE basics: set up RA2CE and configure a road network

This notebook contains examples for the RA2CE tool. This requires the right folder setup, and the correct settings in the configuration files (network.ini and analyses.ini).

In this notebook, we will guide you through the basics of RA2CE: configuring a road network from OSM.

First of all, we will import the packages we need to execute this notebook:

import geopandas as gpd
import matplotlib.pyplot as plt
from pathlib import Path

from ra2ce.ra2ce_handler import Ra2ceHandler # import the ra2cehandler to run ra2ce analyses

Folder structure

Before starting the examples, it is vital that you familiarize yourself with the RA2CE folder structure. RA2CE requires this folder structure to succesfully perform analyses. You can find the folder structure in the documentation.

A project folder must contain the subfolders ‘output’ and ‘static’. An ‘input’ folder is optional for additional data sets but we will not use that in our example. It must also contain the network.ini and/or analyses.ini files. Within the subfolder ‘static’, RA2CE expects three subfolders: hazard, network, and output_graph. See below an example folder structure of “Project A”. This folder structure must be created by the user before running RA2CE.

Configuring RA2CE to create a road network from OSM

One of the RA2CE functionalities is extracting road networks from OpenStreetMaps (OSM)* for any place in the world. You can do this, by creating a polygon of the area you would like to extract the road network from.

An easy way to use this option is by drawing a polygon at the location of choice at geojson.io. Another option is creating a polygon layer in a GIS and saving it as a .geojson.

Bear in mind that RA2CE requires a polygon in .geojson format and that the projection should be set to WGS84 EPSG:4326.

The created polygon should be saved in the static/network folder.

**OSM files are usually neater because they are checked before uploading. These files usually have a good (realistic) connectivity, but still it is required to check the network carefully.*

Filling the network.ini file

Now, we will fill the network.ini file with our configurations.

Under [project], we simply specify the project name.

We then move on to the [network] section, where we will first mention the most important settings for this example. First, we specify the source of road network extraction. In the case, you want to perform an OSM download (source = OSM download). Specify the created geojson’s name in the ‘polygon’ parameter. Make sure you saved this geojson in your static/network folder.

With the road_types parameter, you can specify the types of roads (motorway - residential) you want to extract from OSM. Bear in mind that the more road types you include, the larger your road network will be. This can increase downloading and computational time, but can also increase the accuracy and connectivity of your road network.

Some other important settings in the [network] section are: - directed: Used together with OSM download - False if you want to have an undirected graph and True if you want to have a directed graph. - primary_file: Used to specify the shapefile name of the (road) network to do the analysis with, when creating a network from a shapefile. - diversion_file: Used to specify a shapefile name of the (road) network to only use for diversion (i.e., no analysis), when creating a network from a shapefile. - file_id: The field name in the shapefile/OSM data that holds the unique ID of the data. When this ID attribute is not unique, RA2CE will create a new attribute in the data with the name ‘rfid_c’ (RA2CE feature ID complex) that contains the unique ID. For more information, the documentation on this is coming soon… - network_type: The type of network to download from OSM, in the case of road networks, this is must be set to ‘drive’. - save_gpkg: True if you want to save the shapefile of the resulting road network in the output_graph folder.

The other settings [origins_destinations], [hazard], and [cleanup], are not relevant for this example and will be introduced in other examples. However, the parameters need to be in the network.ini file in order for RA2CE to run.

[project] name = insert your project name [network] directed = False source = OSM download primary_file = None diversion_file = None file_id = rfid_c polygon = map.geojson network_type = drive road_types = motorway,motorway_link,primary,primary_link,secondary,secondary_link,tertiary,tertiary_link,residential save_gpkg = True *[origins_destinations] origins = None destinations = None origins_names = A destinations_names = B id_name_origin_destination = OBJECTID origin_count = PEOPLE origin_out_fraction = 1 [hazard] hazard_map = None hazard_id = None hazard_field_name = waterdepth aggregate_wl = max hazard_crs = None $EPSG:4326 [cleanup] snapping_threshold = None segmentation_length = None merge_lines = True merge_on_id = False cut_at_intersections = False *

Now, we tell the program where to find our project folder (by specifying the path to the project folder). Now that we introduced a polygon of a region and provided the right network.ini settings, RA2CE can download from OSM.

For this action we only need the network.ini file, no analysis.ini file is needed.

# specify the name of the path to the project folder where you created the RA2CE folder setup
root_dir = Path("data", "base_network")
assert root_dir.exists()

_network_ini_name = "network.ini" # set the name for the network.ini settings file
network_ini = root_dir / _network_ini_name #let RA2CE find the network.ini
assert network_ini.is_file() # check whether the network.ini file exists

Creating the network with RA2CE

Initiate the RA2CE model through the Ra2ceHandler and configure (create) the network. Because we do not input the analysis.ini for now, we set that to None.

handler = Ra2ceHandler(network=network_ini, analysis=None)
handler.configure()

Inspecting the resulting network

Now, let’s inspect the created network. Note: the road network is always saved in the static/output_graph folder.

First, we load the right geopackage. There are many geopackages created in the static / output_graph folder if you specify save_gpkg = True in the network.ini. These all represent some properties of the network. Let’s inspect some of these.

Notice the different files in the output_graph folder. You can inspect them all and see what their differences are.

# Set the path to your output_graph folder to find the network/graph creation:
path_output_graph = root_dir / "static" / "output_graph"

# Now we find and inspect the file 'base_graph_edges.gpkg' which holds the 'edges' of the network.
# An edge (or link) of a network (or graph) represents a connection between two nodes (or vertices) of the network. More information on: https://mathinsight.org/definition/network_edge#:~:text=An%20edge%20(or%20link)%20of,in%20the%20first%20figure%20below.
base_graph_edges = path_output_graph / "base_graph_edges.gpkg"
edges_gdf = gpd.read_file(base_graph_edges, driver = "GPKG")
edges_gdf.head()

Notice how the road network that is downloaded holds the attributes of all these road types that are specified in the network.ini: motorway, motorway_link, primary, primary_link, secondary, secondary_link, tertiary, tertiary_link, and residential.

If you want to customize this yourself, you can pick the type of roads you are interested in by choosing from this list. For example, using only motorway and motorway_link.

edges_gdf.explore(column='highway', tiles="CartoDB positron")

If you want to get a bit more advanced, use the ‘Disconnected Islands’ plugin in QGIS to check whether the road network is completely connected. If there are disconnected islands in the road network, this can impact more advanced RA2CE analyses (such as Origin-Destination analyses which are introduced in another example).

Now we find and inspect the file ‘base_graph_nodes.gpkg’ which holds the ‘nodes’ of the network. A node is represents the beginning and end point of an edge and can connect to one or multiple edges. Together, the nodes and edges make up the graph/network.

base_graph_nodes = path_output_graph / "base_graph_nodes.gpkg" #specify where to find the nodes file
nodes_gdf = gpd.read_file(base_graph_nodes, driver = "GPKG") #read in the nodes file

#Plotting nodes and edges together
fig, ax = plt.subplots(figsize=(15, 15))  # Set the figsize as desired

# Set the edges as the base plot
baseplot = edges_gdf.plot(ax=ax, color='grey')
nodes_gdf.plot(ax=baseplot, color='blue', markersize=20)
plt.show()

Advanced

If you want to further inspect the network and it’s properties, load the files in the output_graph folder into a GIS or using Python and explore!

To check whether the OSM data is complete and up-to-date, overlay the roads with a (recent) satellite image or use Google Earth. Where does the data match and where not?