Quickstart

Quickstart#

One of the core functionalities of r5py is to compute travel time matrices efficiently, and for large extents such as entire cities or countries. This page walks you through the - pleasantly few - steps required to do so.

In our example below, we work with sample data from Helsinki, the capital of Finland. We calculate the travel times on public transport or on foot from all cells in a population grid data set to the city’s main railway station.

Origins and destination#

As we intend to compute the travel times from the centre points of population grid cells to the railway station, we need to know the locations of these places.

Sample data set

For this example, we prepared the data ahead of time. If you repeat the code examples independently, install r5py.sampledata.helsinki.

r5py.sampledata.helsinki.population_grid is a vector data set in GeoPackage (GPKG) format containing a 250 ⨉ 250 m grid covering parts of downtown Helsinki, and obtained from the Helsinki Region Environmental Services (HSY).

We open the sample data set file using geopandas.GeoDataFrame.read_file().

Because, in our example, we only use one destination, the railway station, we define its location as a geopandas.GeoDataFrame containing one geometry, a shapely.Point, the coordinates of which refer to Helsinki’s main railway station in the EPSG:4326 reference system.

import geopandas
import r5py.sampledata.helsinki
import shapely

population_grid = geopandas.read_file(r5py.sampledata.helsinki.population_grid)

railway_station = geopandas.GeoDataFrame(
    {
        "id": ["railway_station"],
        "geometry": [shapely.Point(24.94152, 60.17066)]
    },
    crs="EPSG:4326",
)

overview_map = population_grid.explore("population", cmap="Reds")
overview_map = railway_station.explore(m=overview_map, marker_type="marker")
overview_map
Make this Notebook Trusted to load map: File -> Trust Notebook

Transport network#

Virtually all operations of r5py require a transport network. R5py understands and reads the following types of data that relates to transport networks:

  • a street network, including infrastructure for cycling and walking, is loaded from an OpenStreetMap extract in Protocol Buffer (.pbf) format (mandatory)

  • a public transport schedule from one or more GTFS files (optional).

  • a digital elevation model (DEM), in GeoTIFF format, to estimate the impact of topography on active transport modes (optional).

For the quickstart example, you find sample data sets in the r5py.sampledata.helsinki package (see above).

To import the street and public transport networks, instantiate an r5py.TransportNetwork with the file paths to the OSM extract and to zero or more GTFS files. With the sample data set, the file paths are in the r5py.sampledata.helsinki namespace:

import r5py
import r5py.sampledata.helsinki

transport_network = r5py.TransportNetwork(
    r5py.sampledata.helsinki.osm_pbf,
    [r5py.sampledata.helsinki.gtfs],
    r5py.sampledata.helsinki.elevation_model,
)

At this stage, r5py has created a routable transport network, that is stored in the transport_network variable. We can now use this network for travel time calculations. Depending on the extent of the network, this step can take up to several minutes. Once loaded, you can reuse the same TransportNetwork instance in subsequent analyses.

Compute a travel time matrix#

A travel time matrix is a dataset of the travel costs (typically, time) between given locations (origins and destinations) in a study area. In r5py, TravelTimeMatrixs calculate these matrices. A TravelTimeMatrix is a child instance of pandas.DataFrame: once values have been computed, it can be used just like the data frames you are used to work with.

A TravelTimeMatrix needs (at least) the following input arguments:

import datetime

origins = population_grid.copy()
origins.geometry = origins.geometry.centroid

destinations = railway_station.copy()

travel_times = r5py.TravelTimeMatrix(
    transport_network,
    origins=origins,
    destinations=destinations,
    departure=datetime.datetime(2022, 2, 22, 8, 30),
    transport_modes=[
        r5py.TransportMode.TRANSIT,
        r5py.TransportMode.WALK,
    ],
    snap_to_network=True,
)

travel_times
from_id to_id travel_time
0 0 railway_station 16
1 1 railway_station 19
2 2 railway_station 20
3 3 railway_station 22
4 4 railway_station 17
... ... ... ...
87 87 railway_station 16
88 88 railway_station 14
89 89 railway_station 17
90 90 railway_station 20
91 91 railway_station 22

92 rows × 3 columns

As mentioned above, a TravelTimeMatrix is also a pandas.DataFrame, all methods of the latter can be used. The values in its travel_time column are travel times in minutes between the points identified by from_id and to_id (the IDs of the origins and destinations, respectively). As you can see, the id value in the to_id column is the same for all rows because our example used only one destination point (the railway station).

Save results#

If you want to continue analysis later, in a different environment, or simply retain a clean copy of the results, save the travel time matrix to a CSV file. Simply use the to_csv() method of pandas data frames:

travel_times.to_csv("travel_times_to_helsinki_railway_station.csv")

Plot a result map#

To quickly plot the results in a map, join the travel_times with the input data set population_grid and explore() the joint data frame’s data.

travel_times = population_grid.merge(travel_times, left_on="id", right_on="from_id")
travel_times.head()
id population geometry from_id to_id travel_time
0 0 389 POLYGON ((24.90545 60.16086, 24.90545 60.16311... 0 railway_station 16
1 1 296 POLYGON ((24.90546 60.15862, 24.90545 60.16086... 1 railway_station 19
2 2 636 POLYGON ((24.90547 60.15638, 24.90546 60.15862... 2 railway_station 20
3 3 1476 POLYGON ((24.90547 60.15413, 24.90547 60.15638... 3 railway_station 22
4 4 23 POLYGON ((24.90994 60.16535, 24.90994 60.1676,... 4 railway_station 17 
travel_times.explore("travel_time", cmap="Greens")
Make this Notebook Trusted to load map: File -> Trust Notebook