Compute travel times with a detailed breakdown of the routing results

Compute travel times with a detailed breakdown of the routing results#

Detailed itineraries#

In case you are interested in more detailed routing results, you can use DetailedItineraries. In contrast to TravelTimeMatrix, it reports individual trip segments, and possibly multiple alternative routes for each trip.

As such, DetailedItineraries are structured in a different way, too. It provides one row per trip segment, multiple trip segments together constitute a trip option, of which there might be several per from_id/to_id pair. The results also include information on the public transport routes (e.g., bus line numbers) used on the trip, as well as a shapely.geometry for each segment.

Detailed itineraries are computationally expensive

Computing detailed itineraries is significantly more time-consuming than calculating simple travel times. As such, think twice whether you actually need the detailed information output from this function, and how you might be able to limit the number of origins and destinations you need to compute.

For the examples below, to reduce computation effort, we use a sample of 3 origin points and one single destination (the railway station) in our sample data of Helsinki.

import geopandas
import r5py
import r5py.sampledata.helsinki
import shapely

population_grid = geopandas.read_file(r5py.sampledata.helsinki.population_grid)
RAILWAY_STATION = shapely.Point(24.941521, 60.170666)

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

import datetime
import r5py

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

destinations = geopandas.GeoDataFrame(
        {
            "id": [1],
            "geometry": [RAILWAY_STATION]
        },
        crs="EPSG:4326",
)

detailed_itineraries = r5py.DetailedItineraries(
    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,
)

Snap to network

If you read the code block above especially carefully, you may have noticed that we added an option snap_to_network=True to DetailedItineraries. This option does exactly what it says on the outside: it attempts to snap all origin and destination points to the transport network before routing. This can help with points that come to lie in an otherwise inaccessible area, such as a fenced area, a swamp, or the middle of a lake.

For a detailed description of the functionality, see the Advanced use page.

detailed_itineraries

	from_id	to_id	option	segment	transport_mode	departure_time	distance	travel_time	wait_time	feed	agency_id	route_id	start_stop_id	end_stop_id	geometry
0	31	1	0	0	TransportMode.WALK	NaT	1177.448000	0 days 00:20:14	0 days 00:00:00	None	None	None	None	None	LINESTRING (24.92558 60.16645, 24.92548 60.166...
1	31	1	1	0	TransportMode.WALK	2022-02-22 08:38:53	224.595000	0 days 00:03:48	0 days 00:00:00	None	None	None	None	None	LINESTRING (24.92558 60.16645, 24.92548 60.166...
2	31	1	1	1	TransportMode.BUS	2022-02-22 08:44:00	352.155637	0 days 00:00:00	0 days 00:01:28	helsinki_gtfs	HSL	7192T	1040234	1040289	LINESTRING (24.92688 60.16628, 24.92723 60.166...
3	31	1	1	2	TransportMode.WALK	2022-02-22 08:45:00	754.679000	0 days 00:12:56	0 days 00:00:00	None	None	None	None	None	LINESTRING (24.93012 60.1688, 24.93012 60.1688...
4	31	1	2	0	TransportMode.WALK	2022-02-22 08:38:53	224.595000	0 days 00:03:48	0 days 00:00:00	None	None	None	None	None	LINESTRING (24.92558 60.16645, 24.92548 60.166...
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
523	63	1	59	1	TransportMode.TRAM	2022-02-22 08:42:00	312.943364	0 days 00:02:00	0 days 00:01:04	helsinki_gtfs	HSL	1001	1040437	1020463	LINESTRING (24.94212 60.1661, 24.94341 60.1665...
524	63	1	59	2	TransportMode.WALK	2022-02-22 08:45:00	375.562000	0 days 00:06:29	0 days 00:00:00	None	None	None	None	None	LINESTRING (24.9411 60.16823, 24.9411 60.16822...
525	63	1	60	0	TransportMode.WALK	2022-02-22 08:32:12	248.964000	0 days 00:04:16	0 days 00:00:00	None	None	None	None	None	LINESTRING (24.94389 60.16627, 24.94383 60.166...
526	63	1	60	1	TransportMode.TRAM	2022-02-22 08:41:00	310.789273	0 days 00:02:00	0 days 00:04:32	helsinki_gtfs	HSL	1010	1020463	1020444	LINESTRING (24.94102 60.1682, 24.94071 60.1684...
527	63	1	60	2	TransportMode.WALK	2022-02-22 08:44:00	282.429000	0 days 00:04:49	0 days 00:00:00	None	None	None	None	None	LINESTRING (24.9377 60.17045, 24.9377 60.17047...

528 rows × 15 columns

As you can see, the result contains much more information than earlier. Depending on your screen size, you might even have to scroll further right to see all columns.

For public transport routes or when a variety of transport_modes are used, the structure of the results is more complex: For each origin-destination pair, one or more possible option is reported, which in turn can consist of one or more segments. Both options and segments are numbered sequentially, starting at 0.

Each segment, then, represents one row in the results table, and provides information about the transport mode used for a segment, time travelled, possible wait time (before the departure of a public transport vehicle), information about the feed and agency, the route identifier, the starting and ending stop used, and finally a line geometry representing the travelled path.

See the following table for a complete list of columns contained in DetailedItineraries:

from_id (same type as origins["id"]): the origin of the trip this segment belongs to
to_id (same type as destinations["id"]): the destination of the trip this segment belongs to
option (int): sequential number enumerating the the different trip options found. Each trip option consists of one or more trip segments. (starts with 0)
segment (int): sequential number enumerating the segments the current trip option consists of. (starts with 0)
transport_mode (r5py.TransportMode): the transport mode used on the current segment
departure_time (datetime.datetime): the departure date and time of the public transport vehicle used for the current segment; NaT in case of other modes of transport
distance (float): the distance travelled on the current segment, in metres. For public transport, see note below.
travel_time (datetime.timedelta): The time spent travelling on the current segment
wait_time (datetime.timedelta): if the current segment is a public transport vehicle: wait time between the arrival of the previous trip segment and the departure of the current segment.
feed (str): if the current segment is a public transport vehicle: the GTFS feed identifier used for this trip, which should match the filename provided. This is useful when a given transport network consists of multiple GTFS feeds.
agency_id (str): if the current segment is a public transport vehicle: the GTFS agency identifier found in the agency.txt file in the provided GTFS feed. Most feeds have just one agency, but multiple are possible.
route_id (str): if the current segment is a public transport vehicle: the GTFS route id found in the routes.txt file in the provided GTFS feed.
start_stop_id (str): if the current segment is a public transport vehicle: the GTFS stop id found in the stops.txt which was used as the boarding stop for that vehicle.
end_stop_id (str): if the current segment is a public transport vehicle: the GTFS stop id found in the stops.txt which was used as the alighting stop for that vehicle.
geometry (shapely.LineString): the path travelled on the current segment. For public transport, see note below.

Geometries of public transport routes, and distances travelled

The default upstream version of R⁵ is compiled with com.conveyal.r5.transit.TransitLayer.SAVE_SHAPES = false, which improves performance by not reading the geometries included in GTFS data sets.

As a consequence, the geometry reported in DetailedItineraries are straight lines in-between the stops of a public transport line, and do not reflect the actual path travelled in public transport modes.

With this in mind, r5py does not attempt to compute the distance of public transport segments if SAVE_SHAPES = false, as distances would be very crude approximations, only. Instead it reports NaN/None.

R⁵py ships with a version of R⁵ that has been patched to retain geometries. Unless you use a custom R⁵ jar, you should not be bothered by this.

Visualise travel details#

It’s not difficult to plot the detailed routes in a map, however, a couple more steps are needed than with simple travel times. GeoDataFrame.explore() cannot handle the column types r5py.TransportMode and datetime.timedelta - the conversion is quick and easy, though:

detailed_itineraries["mode"] = detailed_itineraries.transport_mode.astype(str)
detailed_itineraries["travel time (min)"] = detailed_itineraries.travel_time.apply(
    lambda t: round(t.total_seconds() / 60.0, 2)
)
detailed_itineraries["trip"] = detailed_itineraries.apply(
    lambda row: f"{row.from_id} → railway station",
    axis=1
)

detailed_routes_map = (
    detailed_itineraries[
        [
            "geometry",
            "distance",
            "mode",
            "travel time (min)",
            "from_id",
            "to_id",
            "trip",
            "option",
            "segment",
        ]
    ]
    .explore(
        tooltip=["trip", "option", "segment", "mode", "travel time (min)", "distance"],
        column="mode",
        tiles="CartoDB.Positron",
        style_kwds={
            "weight": 3,
            "opacity": 0.8,
        },
        highlight_kwds={
            "weight": 6,
            "opacity": 1,
        },

    )
)

Let’s also add the origins and the destination to the map:

import folium
import folium.plugins
import pandas

folium.Marker(
    (RAILWAY_STATION.y, RAILWAY_STATION.x),
    icon=folium.Icon(
        color="green",
        icon="train",
        prefix="fa",
    )
).add_to(detailed_routes_map)

points = geopandas.GeoDataFrame(
    pandas.DataFrame(
        {"id": detailed_itineraries.od_pairs["id_origin"].unique()}
    )
    .set_index("id")
    .join(population_grid.set_index("id"))
    .reset_index()
)
points.geometry = points.geometry.to_crs("EPSG:3875").centroid.to_crs("EPSG:4326")

points.apply(
    lambda row: (
        folium.Marker(
            (row["geometry"].y, row["geometry"].x),
            icon=folium.plugins.BeautifyIcon(
                icon_shape="marker",
                number=row["id"],
                border_color="#728224",
                text_color="#728224",
            ),
        ).add_to(detailed_routes_map)
    ),
    axis=1,
)

detailed_routes_map

Make this Notebook Trusted to load map: File -> Trust Notebook

Export the detailed routes#

If you want to further analyse the resulting routes, for instance, in a desktop GIS, you can export the GeoDataFrame to a wide range of file formats, using the to_file() method.

Note that many geospatial file formats do not support datetime.timedelta columns, or columns with custom objects, such as the r5py.TransportMode data. Similar to the above example, with a few simple steps we can convert the values accordingly:

detailed_itineraries["transport_mode"] = detailed_itineraries.transport_mode.astype(str)
detailed_itineraries["travel time (min)"] = detailed_itineraries.travel_time.apply(
    lambda t: round(t.total_seconds() / 60.0, 2)
)
detailed_itineraries["wait time (min)"] = detailed_itineraries.wait_time.apply(
    lambda t: round(t.total_seconds() / 60.0, 2)
)

# keep all columns except travel time and wait time (which we renamed to
# reflect the unit of measurement)
detailed_itineraries = detailed_itineraries[
    [
        "from_id",
        "to_id",
        "option",
        "segment",
        "transport_mode",
        "departure_time",
        "distance",
        "travel time (min)",
        "wait time (min)",
        "feed",
        "agency_id",
        "route_id",
        "geometry",
    ]
]

detailed_itineraries.to_file("detailed_itineraries.gpkg")

Deprecated interface

Prior to r5py version 1.0.0, detailed itineraries had to be computed by first initialising a DetailedItinerariesComputer(), then calling its compute_travel_details().

This interface has now been deprecated and will be removed in a future version.

Compute travel times with a detailed breakdown of the routing results

Contents

Compute travel times with a detailed breakdown of the routing results#

Detailed itineraries#

Visualise travel details#

Export the detailed routes#