r5py 1.1.0__py3-none-any.whl

r5py/r5/travel_time_matrix.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+
+"""Calculate travel times between many origins and destinations."""
+
+import copy
+
+import pandas
+
+from .base_travel_time_matrix import BaseTravelTimeMatrix
+from ..util import start_jvm
+
+import com.conveyal.r5
+
+__all__ = ["TravelTimeMatrix"]
+
+
+start_jvm()
+
+
+class TravelTimeMatrix(BaseTravelTimeMatrix):
+    """Compute travel times between many origins and destinations."""
+
+    def __init__(
+        self,
+        transport_network,
+        origins=None,
+        destinations=None,
+        snap_to_network=False,
+        **kwargs,
+    ):
+        """
+        Compute travel times between many origins and destinations.
+
+        ``r5py.TravelTimeMatrix`` are child classes of ``pandas.DataFrame`` and
+        support all of their methods and properties,
+        see https://pandas.pydata.org/docs/
+
+        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().__init__(
+            transport_network,
+            origins,
+            destinations,
+            snap_to_network,
+            **kwargs,
+        )
+        data = self._compute()
+        for column in data.columns:
+            self[column] = data[column]
+        del self.transport_network
+
+    def _compute(self):
+        """
+        Compute travel times from all origins to all destinations.
+
+        Returns
+        -------
+        pandas.DataFrame
+            A data frame containing the columns ``from_id``, ``to_id``, and
+            ``travel_time``, where ``travel_time`` is the median calculated
+            travel time between ``from_id`` and ``to_id`` or ``numpy.nan``
+            if no connection with the given parameters was found.
+            If non-default ``percentiles`` were requested: one or more columns
+            ``travel_time_p{:02d}`` representing the particular percentile of
+            travel time.
+        """
+        self._prepare_origins_destinations()
+        self.request.destinations = self.destinations
+
+        od_matrix = pandas.concat(
+            [self._travel_times_per_origin(from_id) for from_id in self.origins.id],
+            ignore_index=True,
+        )
+
+        try:
+            od_matrix = od_matrix.to_crs(self._origins_crs)
+        except AttributeError:  # (not a GeoDataFrame)
+            pass
+        return od_matrix
+
+    def _parse_results(self, from_id, results):
+        """
+        Parse the results of an R5 TravelTimeMatrix.
+
+        Parse data as returned from
+        `com.conveyal.r5.analyst.TravelTimeComputer.computeTravelTimes()`, cast
+        data to Python types, and return as a `pandas.Dataframe`. Because of the
+        way r5py and R5 interact, this parses the results of routing from one
+        origin to many (all) destinations.
+
+        Arguments
+        ---------
+        from_id : mixed
+            The value of the ID column of the origin record to report on.
+        results : `com.conveyal.r5.OneOriginResult` (Java object)
+
+        Returns
+        -------
+        pandas.DataFrame
+            A data frame containing the columns ``from_id``, ``to_id``, and
+            ``travel_time``, where ``travel_time`` is the median calculated
+            travel time between ``from_id`` and ``to_id`` or ``numpy.nan``
+            if no connection with the given parameters was found.
+            If non-default ``percentiles`` were requested: one or more columns
+            ``travel_time_p{:02d}`` representing the particular percentile of
+            travel time.
+        """
+        # First, create an empty DataFrame (this forces column types)
+        od_matrix = pandas.DataFrame(
+            {
+                "from_id": pandas.Series(dtype=str),
+                "to_id": pandas.Series(dtype=str),
+            }
+            | {
+                f"travel_time_p{percentile:d}": pandas.Series(dtype=float)
+                for percentile in self.request.percentiles
+            }
+        )
+
+        # first assign columns with correct length (`to_id`),
+        # only then fill `from_id` (it’s a scalar)
+        od_matrix["to_id"] = self.destinations.id
+        od_matrix["from_id"] = from_id
+
+        for p, percentile in enumerate(self.request.percentiles):
+            travel_times = results.travelTimes.getValues()[p]
+            od_matrix[f"travel_time_p{percentile:d}"] = travel_times
+
+            # R5 always routes from/to next street segment
+            # (results in >0 travel time for from_id==to_id)
+            od_matrix.loc[
+                (od_matrix.from_id == od_matrix.to_id),
+                f"travel_time_p{percentile:d}",
+            ] = 0
+
+        # rename percentile column if only median requested (the default)
+        if self.request.percentiles == [50]:
+            od_matrix = od_matrix.rename(columns={"travel_time_p50": "travel_time"})
+
+        # R5’s NULL value is MAX_INT32
+        od_matrix = self._fill_nulls(od_matrix)
+
+        # re-index (and don’t keep the old index as a new column)
+        od_matrix = od_matrix.reset_index(drop=True)
+
+        return od_matrix
+
+    def _travel_times_per_origin(self, from_id):
+        request = copy.copy(self.request)
+        request.origin = self.origins[self.origins.id == from_id].geometry.item()
+
+        travel_time_computer = com.conveyal.r5.analyst.TravelTimeComputer(
+            request, self.transport_network
+        )
+        results = travel_time_computer.computeTravelTimes()
+
+        od_matrix = self._parse_results(from_id, results)
+
+        return od_matrix

r5py/r5/trip.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+
+
+"""Represent one trip, consisting of one or more `TripLeg`s."""
+
+import datetime
+
+import shapely
+
+from .trip_leg import TripLeg
+
+__all__ = ["Trip"]
+
+
+class Trip:
+    """Represent one trip, consisting of one or more `r5py.r5.TripLeg`."""
+
+    COLUMNS = [
+        "segment",
+    ] + TripLeg.COLUMNS
+
+    def __init__(self, legs=[]):  # noqa: B006
+        """
+        Represent one trip, consisting of one of more `r5py.r5.TripLeg`.
+
+        Arguments
+        =========
+        legs : collections.abc.Iterable
+            optional list of trip legs with which to initialise this trip
+        """
+        self.legs = legs
+
+    def __eq__(self, other):
+        """Check whether `self` and `other` are equal."""
+        if isinstance(other, self.__class__):
+            return self.legs == other.legs
+
+    def __repr__(self):
+        """Return a string representation of `self`."""
+        legs = ", ".join([str(leg) for leg in self.legs])
+        return (
+            f"<{self.__class__.__name__}: "
+            f"{self.distance}m, "
+            f"{self.travel_time.total_seconds()}s, "
+            f"{legs}>"
+        )
+
+    def as_table(self):
+        """
+        Return a table (list of lists) of this trip’s legs.
+
+        Returns
+        =======
+        list : detailed information about this trip and its legs (segments):
+            ``segment``, ``transport_mode``, ``departure_time``, ``distance``,
+            ``travel_time``, ``wait_time``, ``feed``, ``agency_id``, ``route_id``,
+            ``start_stop_id``, ``end_stop_id``, ``geometry``
+        """
+        return [[segment] + leg.as_table_row() for segment, leg in enumerate(self.legs)]
+
+    @property
+    def distance(self):
+        """Overall distance of this trip in metres (float)."""
+        try:
+            distance = sum([leg.distance for leg in self.legs])
+        except TypeError:  # distance of a leg can be None
+            distance = None
+        return distance
+
+    @property
+    def geometry(self):
+        """Joined geometries of all legs of this trip."""
+        return shapely.line_merge(
+            shapely.MultiLineString([leg.geometry for leg in self.legs])
+        )
+
+    @property
+    def route_ids(self):
+        """The public transport route(s) used on this trip."""
+        return [leg.route_id for leg in self.legs]
+
+    @property
+    def transport_modes(self):
+        """The transport mode(s) used on this trip."""
+        return [leg.transport_mode for leg in self.legs]
+
+    @property
+    def travel_time(self):
+        """Overall travel_time of this trip (datetime.timedelta)."""
+        return sum(
+            [leg.travel_time for leg in self.legs], datetime.timedelta(seconds=0)
+        )
+
+    @property
+    def wait_time(self):
+        """Overall wait_time of this trip (datetime.timedelta)."""
+        return sum([leg.wait_time for leg in self.legs], datetime.timedelta(seconds=0))

r5py/r5/trip_leg.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+
+
+"""Represent one leg of a trip."""
+
+import datetime
+import numpy
+import shapely
+
+__all__ = ["TripLeg"]
+
+
+class TripLeg:
+    """
+    Represent one leg of a trip.
+
+    This is a base class, use one the specific classes,
+    e.g., TransitLeg, or DirectLeg
+    """
+
+    COLUMNS = [
+        "transport_mode",
+        "departure_time",
+        "distance",
+        "travel_time",
+        "wait_time",
+        "feed",
+        "agency_id",
+        "route_id",
+        "start_stop_id",
+        "end_stop_id",
+        "geometry",
+    ]
+
+    def __init__(
+        self,
+        transport_mode=None,
+        departure_time=numpy.datetime64("NaT"),  # noqa: B008
+        distance=None,
+        travel_time=datetime.timedelta(seconds=0),  # noqa: B008
+        wait_time=datetime.timedelta(seconds=0),  # noqa: B008
+        feed=None,
+        agency_id=None,
+        route_id=None,
+        start_stop_id=None,
+        end_stop_id=None,
+        geometry=shapely.LineString(),  # noqa: B008
+    ):
+        """
+        Represent one leg of a trip.
+
+        This is a base class, use one of the more specific classes, e.g.,
+        TransitLeg, or DirectLeg
+
+        Arguments
+        =========
+        transport_mode : r5py.TransportMode
+            mode of transport this trip leg was travelled
+        departure_time : datetime.datetime
+            departure time of this trip leg
+        distance : float
+            distance covered by this trip leg, in metres
+        travel_time : datetime.timedelta
+            time spent travelling on this trip leg
+        wait_time : datetime.timedelta
+            time spent waiting for a connection on this trip leg
+        feed : str
+            the GTFS feed identifier used for this trip leg
+        agency_id : str
+            the GTFS id the agency used for this trip leg
+        route_id : str
+            the GTFS id of the public transport route used for this trip leg
+        start_stop_id : str
+            the GTFS stop_id of the boarding stop used for this trip leg
+        end_stop_id : str
+            the GTFS stop_id of the aligning stop used for this trip leg
+        geometry : shapely.LineString
+            spatial representation of this trip leg
+        """
+        self.transport_mode = transport_mode
+        self.departure_time = departure_time
+        self.distance = distance
+        self.travel_time = travel_time
+        self.wait_time = wait_time
+        self.feed = feed
+        self.agency_id = agency_id
+        self.route_id = route_id
+        self.start_stop_id = start_stop_id
+        self.end_stop_id = end_stop_id
+        self.geometry = geometry
+
+    def __add__(self, other):
+        """Trip-chain `other` to `self`."""
+        from .trip import Trip
+
+        if isinstance(other, self.__class__):
+            trip = Trip([self, other])
+            return trip
+        elif isinstance(other, Trip):
+            other.legs = [self] + other.legs
+            return other
+        else:
+            raise TypeError(
+                "unsupported operand type(s) for '+': "
+                f"'{type(other)}' and '{type(self)}'"
+            )
+
+    def __radd__(self, other):
+        """Trip-chain `self` to `other`."""
+        from .trip import Trip
+
+        if other == 0:  # first iteration of sum()
+            return self
+        elif isinstance(other, Trip):
+            other.legs.append(self)
+            return other
+        else:
+            return self.__add__(other)
+
+    def __eq__(self, other):
+        """Check if `other` is an equal `TripLeg`."""
+        if isinstance(other, self.__class__):
+            return False not in [
+                self._are_columns_equal(other, column) for column in self.COLUMNS
+            ]
+
+    def __gt__(self, other):
+        """Check if `other` has a longer travel time."""
+        if isinstance(other, TripLeg):
+            return (self.travel_time + self.wait_time) > (
+                other.travel_time + other.wait_time
+            )
+
+    def __ge__(self, other):
+        """Check if `other` has a longer or equal travel time."""
+        if isinstance(other, TripLeg):
+            return (self.travel_time + self.wait_time) >= (
+                other.travel_time + other.wait_time
+            )
+
+    def __lt__(self, other):
+        """Check if `other` has a shorter travel time."""
+        if isinstance(other, TripLeg):
+            return (self.travel_time + self.wait_time) < (
+                other.travel_time + other.wait_time
+            )
+
+    def __le__(self, other):
+        """Check if `other` has a shorter or equal travel time."""
+        if isinstance(other, TripLeg):
+            return (self.travel_time + self.wait_time) <= (
+                other.travel_time + other.wait_time
+            )
+
+    def __repr__(self):
+        """Return a string representation."""
+        try:
+            first_point = self.geometry.coords[0]
+            last_point = self.geometry.coords[-1]
+            _repr = (
+                "<"
+                f"{self.__class__.__name__}: "
+                f"{self.transport_mode}, "
+                f"{self.distance}m, "
+                f"{self.travel_time.total_seconds():0.1f}s, "
+                f"{first_point} -> {last_point}"
+                ">"
+            )
+        except (AttributeError, IndexError):
+            _repr = f"<{self.__class__.__name__}>"
+        return _repr
+
+    def _are_columns_equal(self, other, column):
+        """
+        Check if a column equals the same column of a different `Trip`.
+
+        Compare if attribute `column` of self equals attribute `column` of
+        other. Also True if both values are None or NaN or NaT.
+        """
+        self_column = getattr(self, column)
+        other_column = getattr(other, column)
+
+        return (
+            self_column == other_column
+            or (self_column is None and other_column is None)
+            or (self_column == numpy.nan and other_column == numpy.nan)
+            or (
+                self_column == numpy.datetime64("NaT")
+                and other_column == numpy.datetime64("NaT")
+            )
+        )
+
+    def as_table_row(self):
+        """
+        Return a table row (list) of this trip leg’s details.
+
+        Returns
+        =======
+        list : detailed information about this trip leg: ``transport_mode``,
+            ``departure_time``, ``distance``, ``travel_time``, ``wait_time``,
+            ``feed``, ``agency_id`` ``route_id``, ``start_stop_id``,
+            ``end_stop_id``, ``geometry``
+        """
+        return [getattr(self, column) for column in self.COLUMNS]