r5py 1.1.0__py3-none-any.whl

r5py/__init__.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+
+"""Python wrapper for the R5 routing analysis engine."""
+
+__version__ = "1.1.0"
+
+
+from .r5 import (
+    DetailedItineraries,
+    ElevationCostFunction,
+    Isochrones,
+    RegionalTask,
+    TransportMode,
+    TransportNetwork,
+    TravelTimeMatrix,
+)
+
+__all__ = [
+    "DetailedItineraries",
+    "ElevationCostFunction",
+    "Isochrones",
+    "RegionalTask",
+    "TransportMode",
+    "TransportNetwork",
+    "TravelTimeMatrix",
+    "__version__",
+]

r5py/__main__.py

@@ -0,0 +1,3 @@
+#!/usr/bin/env python3
+
+"""Python wrapper for the R5 routing analysis engine."""

r5py/r5/__init__.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+
+"""R5 classes."""
+
+from .access_leg import AccessLeg
+from .detailed_itineraries import DetailedItineraries
+from .direct_leg import DirectLeg
+from .egress_leg import EgressLeg
+from .elevation_cost_function import ElevationCostFunction
+from .isochrones import Isochrones
+from .regional_task import RegionalTask
+from .scenario import Scenario
+from .street_layer import StreetLayer
+from .transfer_leg import TransferLeg
+from .transit_leg import TransitLeg
+from .transport_mode import TransportMode
+from .transport_network import TransportNetwork
+from .travel_time_matrix import TravelTimeMatrix
+from .trip import Trip
+from .trip_planner import TripPlanner
+
+__all__ = [
+    "AccessLeg",
+    "DetailedItineraries",
+    "DirectLeg",
+    "EgressLeg",
+    "ElevationCostFunction",
+    "Isochrones",
+    "RegionalTask",
+    "Scenario",
+    "StreetLayer",
+    "TransferLeg",
+    "TransitLeg",
+    "TransportMode",
+    "TransportNetwork",
+    "TravelTimeMatrix",
+    "Trip",
+    "TripPlanner",
+]

r5py/r5/access_leg.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+
+
+"""Represent one leg of a trip, specifically access to a public transport stop."""
+
+from .transfer_leg import TransferLeg
+
+__all__ = ["AccessLeg"]
+
+
+class AccessLeg(TransferLeg):
+    """Represent one leg of a trip, specifically access to a public transport stop."""

r5py/r5/base_travel_time_matrix.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+
+"""Calculate travel times between many origins and destinations."""
+
+import collections.abc
+import inspect
+import math
+import multiprocessing
+import pathlib
+import warnings
+
+import geopandas
+import numpy
+import pandas
+import shapely
+
+from ..util import Config, check_od_data_set
+from .regional_task import RegionalTask
+from .transport_network import TransportNetwork
+
+__all__ = ["BaseTravelTimeMatrix"]
+
+
+# R5 fills cut-off (NULL) values with MAX_INT32
+MAX_INT32 = (2**31) - 1
+
+# how many (Python) threads to start
+# (they still run many Java threads, so be careful what you wish for ;) )
+# TODO: benchmark the optimal number of threads
+NUM_THREADS = math.ceil(multiprocessing.cpu_count() * 0.5)
+
+
+class BaseTravelTimeMatrix(geopandas.GeoDataFrame):
+    """Base class for travel time computers between many origins and destinations."""
+
+    MAX_INT32 = MAX_INT32
+
+    NUM_THREADS = NUM_THREADS
+
+    _r5py_attributes = [
+        "_destinations",
+        "_destinations_crs",
+        "_origins",
+        "_origins_crs",
+        "destinations",
+        "origins",
+        "request",
+        "snap_to_network",
+        "transport_network",
+        "verbose",
+    ]
+
+    _constructor = geopandas.GeoDataFrame
+
+    _constructor_sliced = pandas.Series
+
+    @classmethod
+    def _geodataframe_constructor_with_fallback(
+        cls,
+        *args,
+        **kwargs,
+    ):  # pragma: no cover
+        """
+        A flexible constructor for r5py frames.
+
+        Checks whether or not arguments of the child class are used.
+        """
+        # `transport_network` is the only required argument across all r5py
+        # data classes, it can be passed either as an r5py.TransportNetwork
+        # or a tuple (as described in the signature of __init__(), below)
+        if (
+            "transport_network" in kwargs
+            or isinstance(args[0], TransportNetwork)
+            or (
+                isinstance(args[0], tuple)
+                and isinstance(args[0][0], (pathlib.Path, str))
+                and isinstance(args[0][1], collections.abc.Iterable)
+                and all(isinstance(arg, (pathlib.Path, str)) for arg in args[0][1])
+            )
+        ):
+            df = cls(*args, **kwargs)
+
+        else:
+            df = geopandas.GeoDataFrame(*args, **kwargs)
+            geometry_cols_mask = df.dtypes == "geometry"
+            if len(geometry_cols_mask) == 0 or geometry_cols_mask.sum() == 0:
+                df = pandas.DataFrame(df)
+
+        return df
+
+    def __init__(
+        self,
+        transport_network,
+        origins=None,
+        destinations=None,
+        snap_to_network=False,
+        **kwargs,
+    ):
+        """
+        Compute travel times between many origins and destinations.
+
+        Arguments
+        ---------
+        transport_network : r5py.TransportNetwork | tuple(
+        pathlib.Paths | str, list(pathlib.Path | str))
+            The transport network to route on. This can either be a readily
+            initialised r5py.TransportNetwork or a tuple of the parameters
+            passed to ``TransportNetwork.__init__()``: the path to an
+            OpenStreetMap extract in PBF format, and a list of zero of more
+            paths to GTFS transport schedule files.
+        origins : geopandas.GeoDataFrame
+            Places to find a route _from_
+            Has to have a point geometry, and at least an `id` column
+        destinations : geopandas.GeoDataFrame (optional)
+            Places to find a route _to_
+            Has to have a point geometry, and at least an `id` column
+            If omitted, use same data set as for origins
+        snap_to_network : bool or int, default False
+            Should origin an destination points be snapped to the street network
+            before routing? If `True`, the default search radius (defined in
+            `com.conveyal.r5.streets.StreetLayer.LINK_RADIUS_METERS`) is used,
+            if `int`, use `snap_to_network` meters as the search radius.
+        **kwargs : mixed
+            Any arguments than can be passed to r5py.RegionalTask:
+            ``departure``, ``departure_time_window``, ``percentiles``,
+            ``transport_modes``, ``access_modes``, ``egress_modes``,
+            ``max_time``, ``max_time_walking``, ``max_time_cycling``,
+            ``max_time_driving``, ``speed_cycling``, ``speed_walking``,
+            ``max_public_transport_rides``, ``max_bicycle_traffic_stress``
+        """
+
+        super_parameters = inspect.signature(geopandas.GeoDataFrame).parameters
+        super_kwargs = {
+            key: value for key, value in kwargs.items() if key in super_parameters
+        }
+        kwargs = {
+            key: value for key, value in kwargs.items() if key not in super_parameters
+        }
+        super().__init__(**super_kwargs)
+
+        if not isinstance(transport_network, TransportNetwork):
+            transport_network = TransportNetwork(*transport_network)
+        self.transport_network = transport_network
+
+        self.snap_to_network = snap_to_network
+
+        self.origins = origins
+        self.destinations = destinations
+
+        self.request = RegionalTask(
+            transport_network,
+            origin=None,
+            destinations=None,
+            **kwargs,
+        )
+
+        self.verbose = Config().arguments.verbose
+
+    def __repr__(self):
+        """Return a string representation of `self`."""
+        return f"<{self.__class__.__name__}>"
+
+    def __setattr__(self, attr, val):
+        """Catch our own attributes here so we don’t mess with (geo)pandas columns."""
+        if attr in self._r5py_attributes:
+            object.__setattr__(self, attr, val)
+        else:
+            super().__setattr__(attr, val)
+
+    @property
+    def destinations(self):
+        """The destinations of this travel time matrix (`geopandas.GeoDataFrame`)."""
+        return self._destinations
+
+    @destinations.setter
+    def destinations(self, destinations):
+        if destinations is not None:
+            check_od_data_set(destinations)
+            self._destinations_crs = destinations.crs
+            self._destinations = destinations.to_crs("EPSG:4326").copy()
+
+    def _fill_nulls(self, data_set):
+        """
+        Fill NULL values in a data set returned from R5.
+
+        R5 uses `MAX_INT32` as a marker for NULL values, this function
+        replaces those values in `data_set` with `numpy.nan`
+
+        Arguments
+        ---------
+        data_set : pandas.DataFrame
+            Data frame in which NULLs are represented by MAX_INT32
+
+        Returns
+        -------
+        pandas.DataFrame
+            Data frame in which all MAX_INT32 have been replaced by `numpy.nan`.
+        """
+        return data_set.map(lambda x: numpy.nan if x == MAX_INT32 else x)
+
+    def _prepare_origins_destinations(self):
+        """Make sure we received enough information."""
+        try:
+            self.origins
+        except AttributeError as exception:
+            raise ValueError("No routing origins defined") from exception
+
+        try:
+            self.destinations
+            assert self.destinations is not None
+        except (AssertionError, AttributeError):
+            self.destinations = self.origins.copy()
+            if self.verbose:
+                warnings.warn(
+                    "No routing destinations defined, "
+                    "using origins as destinations, too.",
+                    RuntimeWarning,
+                    stacklevel=1,
+                )
+
+        if self.snap_to_network:
+            for which_end in ("origins", "destinations"):
+                points = getattr(self, f"_{which_end}")
+                points.geometry = self.transport_network.snap_to_network(
+                    points.geometry
+                )
+                if len(points[points.geometry == shapely.Point()]):
+                    # if there are origins/destinations for which
+                    # no snapped point could be found
+                    points = points[points.geometry != shapely.Point()]
+                    warnings.warn(
+                        f"Some {which_end[:-1]} points could not be "
+                        "snapped to the street network",
+                        RuntimeWarning,
+                        stacklevel=1,
+                    )
+
+                    if points.empty:
+                        raise ValueError(
+                            f"After snapping, no valid {which_end[:-1]} points remain"
+                        )
+
+                setattr(self, f"_{which_end}", points.copy())
+
+    @property
+    def origins(self):
+        """The origins of this travel time matrix (`geopandas.GeoDataFrame`)."""
+        return self._origins
+
+    @origins.setter
+    def origins(self, origins):
+        if origins is not None:
+            check_od_data_set(origins)
+            self._origins_crs = origins.crs
+            self._origins = origins.to_crs("EPSG:4326").copy()

r5py/r5/detailed_itineraries.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+
+
+"""Calculate detailed itineraries between many origins and destinations."""
+
+import copy
+import warnings
+
+import geopandas
+import joblib
+import pandas
+
+from .base_travel_time_matrix import BaseTravelTimeMatrix
+from .trip import Trip
+from .trip_planner import TripPlanner
+
+__all__ = ["DetailedItineraries"]
+
+
+class DetailedItineraries(BaseTravelTimeMatrix):
+    """Compute detailed itineraries between many origins and destinations."""
+
+    COLUMNS = ["from_id", "to_id", "option"] + Trip.COLUMNS
+
+    _r5py_attributes = BaseTravelTimeMatrix._r5py_attributes + [
+        "all_to_all",
+        "od_pairs",
+    ]
+
+    def __init__(
+        self,
+        transport_network,
+        origins=None,
+        destinations=None,
+        snap_to_network=False,
+        force_all_to_all=False,
+        **kwargs,
+    ):
+        """
+        Compute travel times between many origins and destinations.
+
+        ``r5py.DetailedItineraries`` are child classes of
+        ``geopandas.GeoDataFrame`` and support all of their methods and
+        properties, see https://geopandas.org/en/stable/docs.html
+
+        Arguments
+        ---------
+        transport_network : r5py.TransportNetwork | tuple(str, list(str), dict)
+            The transport network to route on. This can either be a readily
+            initialised r5py.TransportNetwork or a tuple of the parameters
+            passed to ``TransportNetwork.__init__()``: the path to an OpenStreetMap
+            extract in PBF format, a list of zero of more paths to GTFS transport
+            schedule files, and a dict with ``build_config`` options.
+        origins : geopandas.GeoDataFrame
+            Places to find a route _from_
+            Has to have a point geometry, and at least an `id` column
+        destinations : geopandas.GeoDataFrame (optional)
+            Places to find a route _to_
+            Has to have a point geometry, and at least an `id` column
+            If omitted, use same data set as for origins
+        snap_to_network : bool or int, default False
+            Should origin an destination points be snapped to the street network
+            before routing? If `True`, the default search radius (defined in
+            `com.conveyal.r5.streets.StreetLayer.LINK_RADIUS_METERS`) is used,
+            if `int`, use `snap_to_network` meters as the search radius.
+        force_all_to_all : bool, default False
+            If ``origins`` and ``destinations`` have the same length, by
+            default, ``DetailedItineraries`` finds routes between pairs
+            of origins and destinations, i.e., it routes from origin #1 to
+            destination #1, origin #2 to destination #2, ... .
+            Set ``force_all_to_all=True`` to route from each origin to all
+            destinations (this is the default, if ``origins`` and ``destinations``
+            have different lengths, or if ``destinations`` is omitted)
+        **kwargs : mixed
+            Any arguments than can be passed to r5py.RegionalTask:
+            ``departure``, ``departure_time_window``, ``percentiles``,
+            ``transport_modes``, ``access_modes``, ``egress_modes``,
+            ``max_time``, ``max_time_walking``, ``max_time_cycling``,
+            ``max_time_driving``, ``speed_cycling``, ``speed_walking``,
+            ``max_public_transport_rides``, ``max_bicycle_traffic_stress`` Note
+            that not all arguments might make sense in this context, and the
+            underlying R5 engine might ignore some of them.
+        """
+        super().__init__(
+            transport_network,
+            origins,
+            destinations,
+            snap_to_network,
+            **kwargs,
+        )
+
+        if destinations is None:
+            self.all_to_all = True
+            if self.verbose:
+                warnings.warn(
+                    "No destinations specified, computing an all-to-all matrix",
+                    RuntimeWarning,
+                    stacklevel=1,
+                )
+
+        elif len(origins) != len(destinations):
+            self.all_to_all = True
+            if self.verbose:
+                warnings.warn(
+                    "Origins and destinations are of different length, "
+                    "computing an all-to-all matrix",
+                    RuntimeWarning,
+                    stacklevel=1,
+                )
+        elif origins.equals(destinations):
+            self.all_to_all = True
+            if self.verbose:
+                warnings.warn(
+                    "Origins and destinations are identical, "
+                    "computing an all-to-all matrix",
+                    RuntimeWarning,
+                    stacklevel=1,
+                )
+        else:
+            self.all_to_all = force_all_to_all
+
+        self.od_pairs = None
+
+        data = self._compute()
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                message=(
+                    "You are adding a column named 'geometry' to a GeoDataFrame "
+                    "constructed without an active geometry column"
+                ),
+                category=FutureWarning,
+            )
+            for column in data.columns:
+                self[column] = data[column]
+            self.set_geometry("geometry")
+
+        del self.transport_network
+
+    def _compute(self):
+        """
+        Compute travel times from all origins to all destinations.
+
+        Returns
+        -------
+        geopandas.GeoDataFrame
+            The resulting detailed routes. For each origin/destination pair,
+            multiple route alternatives (‘options’) might be reported that each
+            consist of one or more segments. Each segment represents one row.
+            multiple route alternatives (‘options’) might be reported that each
+            consist of one or more segments. Each segment represents one row.
+
+            The data frame comprises of the following columns: `from_id`,
+            `to_id`, `option` (`int`), `segment` (`int`), `transport_mode`
+            (`r5py.TransportMode`), `departure_time` (`datetime.datetime`),
+            `distance` (`float`, metres), `travel_time` (`datetime.timedelta`),
+            `wait_time` (`datetime.timedelta`), `feed` (`str`, the feed name
+            used), `agency_id` (`str` the public transport agency identifier),
+            `route_id` (`str`, public transport route ID), `start_stop_id`
+            (`str`, the GTFS stop_id for boarding), `end_stop_id` (`str`, the
+            GTFS stop_id for alighting), `geometry` (`shapely.LineString`)
+        """
+        self._prepare_origins_destinations()
+
+        # loop over all origin/destination pairs, modify the request, and
+        # compute times, distance, and other details for each trip
+        with joblib.Parallel(
+            prefer="threads",
+            verbose=(10 * self.verbose),  # joblib has a funny verbosity scale
+            n_jobs=self.NUM_THREADS,
+        ) as parallel:
+            matrices = parallel(
+                joblib.delayed(self._travel_details_per_od_pair)(from_id, to_id)
+                for _, (from_id, to_id) in self.od_pairs.iterrows()
+            )
+            od_matrix = pandas.concat(
+                [matrix.astype(matrices[0].dtypes) for matrix in matrices],
+                ignore_index=True,
+            )
+
+        od_matrix = geopandas.GeoDataFrame(od_matrix, crs=self._origins_crs)
+        return od_matrix
+
+    def _prepare_origins_destinations(self):
+        """Make sure we received enough information."""
+        super()._prepare_origins_destinations()
+
+        if self.all_to_all:
+            # manually create a list of all all-to-all permutations
+            self.od_pairs = self.origins[["id"]].join(
+                self.destinations[["id"]],
+                how="cross",
+                lsuffix="_origin",
+                rsuffix="_destination",
+            )
+        else:
+            # origins and destinations are same length, run one-to-one routing
+            self.od_pairs = pandas.DataFrame(
+                {
+                    "id_origin": self.origins.id.values,
+                    "id_destination": self.destinations.id.values,
+                }
+            )
+
+    def _travel_details_per_od_pair(self, from_id, to_id):
+        origin = self.origins[self.origins.id == from_id]
+        destination = self.destinations[self.destinations.id == to_id]
+
+        request = copy.copy(self.request)
+        request._regional_task.fromLat = origin.geometry.item().y
+        request._regional_task.fromLon = origin.geometry.item().x
+        request._regional_task.toLat = destination.geometry.item().y
+        request._regional_task.toLon = destination.geometry.item().x
+
+        trip_planner = TripPlanner(self.transport_network, request)
+        trips = trip_planner.trips
+
+        # fmt: off
+        trips = [
+            [from_id, to_id, option] + segment
+            for option, trip in enumerate(trips)
+            for segment in trip.as_table()
+        ]
+        # fmt: on
+
+        return pandas.DataFrame(trips, columns=self.COLUMNS)

r5py/r5/direct_leg.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+
+
+"""Represent one leg of a direct mode (walk, cycle, car) trip."""
+
+import datetime
+
+import shapely
+
+from .trip_leg import TripLeg
+
+__all__ = ["DirectLeg"]
+
+
+class DirectLeg(TripLeg):
+    """Represent one leg of a public transport trip."""
+
+    def __init__(self, transport_mode, street_segment):
+        """
+        Represent one leg of a public transport trip.
+
+        Arguments
+        =========
+        transport_mode : r5py.TransportMode
+            mode of transport this trip leg was travelled
+        street_segment : com.conveyal.r5.profile.StreetSegment
+            the leg’s data as output by R5’s `StreetRouter`
+        """
+        distance = street_segment.distance / 1000.0  # millimetres!
+        travel_time = datetime.timedelta(seconds=street_segment.duration)
+        geometry = shapely.from_wkt(str(street_segment.geometry))
+
+        super().__init__(
+            transport_mode=transport_mode,
+            distance=distance,
+            travel_time=travel_time,
+            geometry=geometry,
+        )

r5py/r5/egress_leg.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+
+
+"""Represent one leg of a trip, specifically egress from a public transport stop."""
+
+from .transfer_leg import TransferLeg
+
+__all__ = ["EgressLeg"]
+
+
+class EgressLeg(TransferLeg):
+    """Represent one leg of a trip, specifically egress from a public transport stop."""

r5py/r5/elevation_cost_function.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+
+
+"""The elevation cost functions supported by R5 (Tobler, Minetti)."""
+
+import enum
+
+import jpype
+
+from ..util import start_jvm
+
+import com.conveyal.r5
+
+__all__ = ["ElevationCostFunction"]
+
+
+start_jvm()
+
+
+class ElevationCostFunction(enum.Enum):
+    """
+    Elevation cost functions.
+
+    TOBLER: Waldo Tobler’s hiking function,
+        cf. https://en.wikipedia.org/wiki/Tobler%27s_hiking_function
+    MINETTI: Minetti et al.’s perceived effort/energy consumption,
+        cf. https://doi.org/10.1152/japplphysiol.01177.2001
+
+    """
+
+    @classmethod
+    def _missing_(cls, value):
+        value = str(value).upper()
+        for member in cls:
+            if value == member.value:
+                return member
+        return None
+
+    TOBLER = "TOBLER"
+    MINETTI = "MINETTI"
+
+
+@jpype._jcustomizer.JConversion(
+    "com.conveyal.r5.analyst.scenario.RasterCost.CostFunction",
+    exact=ElevationCostFunction,
+)
+def _cast_LegMode(java_class, object_):
+    return com.conveyal.r5.analyst.scenario.RasterCost.CostFunction.valueOf(
+        object_.name
+    )