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
Transport network#
Virtually all operations of r5py require a transport network. R5py understands and reads the following types of 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).
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],
)
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,
TravelTimeMatrixComputer
s calculate
these matrices. A
TravelTimeMatrixComputer
, once
initialised, can be used multiple times, for instance, with adjusted parameters,
such as a different departure time.
A TravelTimeMatrixComputer
needs (at least)
the following input arguments:
a
transport_network
(r5py.TransportNetwork
), such as the one we just created,origins
, ageopandas.GeoDataFrame
with one or more points representing the departure points of routes,destinations
, ageopandas.GeoDataFrame
with one or more points representing the destinations of routes,departure
, adatetime.datetime
refering to the departure date and time for routing, andtransport_modes
, a list ofr5py.TransportMode
s: the travel modes that will be used in the calculations
Once instantiated, call
TravelTimeMatrixComputer.compute_travel_times()
to carry out the actual analysis.
import datetime
origins = population_grid.copy()
origins.geometry = origins.geometry.centroid
destinations = railway_station.copy()
travel_time_matrix_computer = r5py.TravelTimeMatrixComputer(
transport_network,
origins=origins,
destinations=destinations,
departure=datetime.datetime(2022, 2, 22, 8, 30),
transport_modes=[
r5py.TransportMode.TRANSIT,
r5py.TransportMode.WALK,
],
)
travel_times = travel_time_matrix_computer.compute_travel_times()
travel_times.head()
from_id | to_id | travel_time | |
---|---|---|---|
0 | 0 | railway_station | 16 |
1 | 1 | railway_station | 18 |
2 | 2 | railway_station | 20 |
3 | 3 | railway_station | 22 |
4 | 4 | railway_station | 18 |
The result of
compute_travel_times()
is a pandas.DataFrame
. 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 | 18 |
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.16760... | 4 | railway_station | 18 |
travel_times.explore("travel_time", cmap="Greens")