r5py 0.1.1.dev2__py3-none-any.whl → 1.0.0.dev0__py3-none-any.whl

r5py/__init__.py

@@ -2,21 +2,26 @@
 
 """Python wrapper for the R5 routing analysis engine."""
 
-__version__ = "0.1.1.dev2"
+__version__ = "1.0.0dev0"
+
 
 from .r5 import (
+    DetailedItineraries,
     DetailedItinerariesComputer,
     RegionalTask,
     TransportMode,
     TransportNetwork,
+    TravelTimeMatrix,
     TravelTimeMatrixComputer,
 )
 
 __all__ = [
+    "DetailedItineraries",
     "DetailedItinerariesComputer",
     "RegionalTask",
     "TransportMode",
     "TransportNetwork",
+    "TravelTimeMatrix",
     "TravelTimeMatrixComputer",
     "__version__",
 ]

r5py/__main__.py

@@ -1,16 +1,3 @@
 #!/usr/bin/env python3
 
-
-"""A Python wrapper for the R5 routing analysis engine."""
-
-
-from .util import Config
-
-
-def main():
-    config = Config()
-    arguments = config.get_arguments()  # noqa F401
-
-
-if __name__ == "__main__":
-    main()
+"""Python wrapper for the R5 routing analysis engine."""

r5py/r5/__init__.py

@@ -2,23 +2,39 @@
 
 """R5 classes."""
 
+from .access_leg import AccessLeg
 from .breakdown_stat import BreakdownStat
-from .detailed_itineraries_computer import DetailedItinerariesComputer
+from .detailed_itineraries import DetailedItineraries, DetailedItinerariesComputer
+from .direct_leg import DirectLeg
+from .egress_leg import EgressLeg
 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_computer import TravelTimeMatrixComputer
+from .travel_time_matrix import TravelTimeMatrix, TravelTimeMatrixComputer
+from .trip import Trip
+from .trip_planner import TripPlanner
 
 __all__ = [
+    "AccessLeg",
     "BreakdownStat",
+    "DetailedItineraries",
     "DetailedItinerariesComputer",
+    "DirectLeg",
+    "EgressLeg",
     "RegionalTask",
     "Scenario",
     "SpeedConfig",
     "StreetLayer",
+    "TransferLeg",
+    "TransitLeg",
     "TransportMode",
     "TransportNetwork",
+    "TravelTimeMatrix",
     "TravelTimeMatrixComputer",
+    "Trip",
+    "TripPlanner",
 ]

r5py/r5/{base_travel_time_matrix_computer.py → base_travel_time_matrix.py}

@@ -6,6 +6,7 @@ import math
 import multiprocessing
 import warnings
 
+import geopandas
 import numpy
 import shapely
 
@@ -14,7 +15,7 @@ from .regional_task import RegionalTask
 from .transport_network import TransportNetwork
 
 
-__all__ = ["BaseTravelTimeMatrixComputer"]
+__all__ = ["BaseTravelTimeMatrix"]
 
 
 # R5 fills cut-off (NULL) values with MAX_INT32
@@ -26,13 +27,26 @@ MAX_INT32 = (2**31) - 1
 NUM_THREADS = math.ceil(multiprocessing.cpu_count() * 0.5)
 
 
-class BaseTravelTimeMatrixComputer:
+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",
+    ]
+
     def __init__(
         self,
         transport_network,
@@ -71,6 +85,8 @@ class BaseTravelTimeMatrixComputer:
             ``max_time_cycling``, ``max_time_driving``, ``speed_cycling``, ``speed_walking``,
             ``max_public_transport_rides``, ``max_bicycle_traffic_stress``
         """
+        geopandas.GeoDataFrame.__init__(self)
+
         if not isinstance(transport_network, TransportNetwork):
             transport_network = TransportNetwork(*transport_network)
         self.transport_network = transport_network
@@ -89,8 +105,16 @@ class BaseTravelTimeMatrixComputer:
 
         self.verbose = Config().arguments.verbose
 
+    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
@@ -120,10 +144,7 @@ class BaseTravelTimeMatrixComputer:
         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 to route from origins to
-        destinations.
-        """
+        """Make sure we received enough information to route from origins to destinations."""
         try:
             self.origins
         except AttributeError as exception:
@@ -161,10 +182,9 @@ class BaseTravelTimeMatrixComputer:
 
                 setattr(self, f"_{which_end}", points.copy())
 
-            self.snap_to_network = False  # prevent repeated snapping on same point sets
-
     @property
     def origins(self):
+        """The origins of this travel time matrix (`geopandas.GeoDataFrame`)."""
         return self._origins
 
     @origins.setter

r5py/r5/{detailed_itineraries_computer.py → detailed_itineraries.py}

@@ -7,23 +7,33 @@
 import copy
 import warnings
 
+try:
+    from warnings import deprecated
+except ImportError:  # Python<=3.12
+    from typing_extensions import deprecated
+
 import geopandas
 import joblib
 import pandas
 
-from .base_travel_time_matrix_computer import BaseTravelTimeMatrixComputer
+from .base_travel_time_matrix import BaseTravelTimeMatrix
 from .trip import Trip
 from .trip_planner import ACCURATE_GEOMETRIES, TripPlanner
 
 
-__all__ = ["DetailedItinerariesComputer"]
+__all__ = ["DetailedItineraries", "DetailedItinerariesComputer"]
 
 
-class DetailedItinerariesComputer(BaseTravelTimeMatrixComputer):
+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,
@@ -36,6 +46,10 @@ class DetailedItinerariesComputer(BaseTravelTimeMatrixComputer):
         """
         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)
@@ -58,10 +72,10 @@ class DetailedItinerariesComputer(BaseTravelTimeMatrixComputer):
             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, ``DetailedItinerariesComputer`` finds routes between pairs
+            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 ``all_to_all=True`` to route from each origin to all
+            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
@@ -106,7 +120,14 @@ class DetailedItinerariesComputer(BaseTravelTimeMatrixComputer):
         else:
             self.all_to_all = force_all_to_all
 
-    def compute_travel_details(self):
+        data = self._compute()
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=FutureWarning)
+            for column in data.columns:
+                self[column] = data[column]
+            self.set_geometry("geometry")
+
+    def _compute(self):
         """
         Compute travel times from all origins to all destinations.
 
@@ -114,17 +135,21 @@ class DetailedItinerariesComputer(BaseTravelTimeMatrixComputer):
         -------
         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`), `route` (`str`, public transport
-            route number or name), `geometry` (`shapely.LineString`)
-            TODO: Add description of output data frame columns and format
+            `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()
 
         # warn if public transport routes are requested, but R5 has been
@@ -150,11 +175,12 @@ class DetailedItinerariesComputer(BaseTravelTimeMatrixComputer):
             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(
-                parallel(
-                    joblib.delayed(self._travel_details_per_od_pair)(from_id, to_id)
-                    for _, (from_id, to_id) in self.od_pairs.iterrows()
-                ),
+                [matrix.astype(matrices[0].dtypes) for matrix in matrices],
                 ignore_index=True,
             )
 
@@ -162,11 +188,7 @@ class DetailedItinerariesComputer(BaseTravelTimeMatrixComputer):
         return od_matrix
 
     def _prepare_origins_destinations(self):
-        """
-        Make sure we received enough information to route from origins to
-        destinations.
-        """
-
+        """Make sure we received enough information to route from origins to destinations."""
         super()._prepare_origins_destinations()
 
         if self.all_to_all:
@@ -208,3 +230,34 @@ class DetailedItinerariesComputer(BaseTravelTimeMatrixComputer):
         # fmt: on
 
         return pandas.DataFrame(trips, columns=self.COLUMNS)
+
+
+@deprecated(
+    "Use `DetailedItineraries` instead, `DetailedItinerariesComputer will be deprecated in a future release."
+)
+class DetailedItinerariesComputer:
+    """Compute detailed itineraries between many origins and destinations."""
+
+    def __init__(self, *args, **kwargs):
+        """Compute detailed itineraries between many origins and destinations."""
+        self._detailed_itineraries = DetailedItineraries(*args, **kwargs)
+
+    def compute_travel_details(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.
+            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`), `route` (`str`, public transport
+            route number or name), `geometry` (`shapely.LineString`)
+            TODO: Add description of output data frame columns and format
+        """
+        return self._detailed_itineraries

r5py/r5/direct_leg.py

@@ -15,9 +15,7 @@ __all__ = ["DirectLeg"]
 
 
 class DirectLeg(TripLeg):
-    """
-    Represent one leg of a public transport trip.
-    """
+    """Represent one leg of a public transport trip."""
 
     def __init__(self, transport_mode, street_segment):
         """

r5py/r5/regional_task.py

@@ -53,11 +53,11 @@ class RegionalTask:
         A RegionalTask wraps a `com.conveyal.r5.analyst.cluster.RegionalTask`,
         which is used to specify the details of a requested computation.
         RegionalTasks underlie virtually all major computations carried out,
-        such as, e.g., `TravelTimeMatrixComputer` or `AccessibilityEstimator`.
+        such as, e.g., `TravelTimeMatrix` or `AccessibilityEstimator`.
 
         In **r5py**, there is usually no need to explicitely create a
         `RegionalTask`. Rather, the constructors to the computation classes
-        (`TravelTimeMatrixComputer`, `AccessibilityEstimator`, ...) accept the
+        (`TravelTimeMatrix`, `AccessibilityEstimator`, ...) accept the
         arguments, and pass them through to an internally handled
         `RegionalTask`.
 
@@ -200,12 +200,16 @@ class RegionalTask:
         # The value is a static property of com.conveyal.r5.analyst.cluster.PathResult;
         # static properites of Java classes can be modified in a singleton kind of way
         try:
-            com.conveyal.r5.analyst.cluster.PathResult.maxDestinations = max(
-                com.conveyal.r5.analyst.cluster.PathResult.maxDestinations,
-                len(self.destinations) + 1,
-            )
+            num_destinations = len(self.destinations)
         except AttributeError:
-            pass
+            num_destinations = 0
+        if (
+            num_destinations
+            > com.conveyal.r5.analyst.cluster.PathResult.MAX_PATH_DESTINATIONS
+        ):
+            com.conveyal.r5.analyst.cluster.PathResult.MAX_PATH_DESTINATIONS = (
+                num_destinations + 1
+            )
 
     @property
     def departure(self):
@@ -246,8 +250,7 @@ class RegionalTask:
 
     @property
     def departure_time_window(self):
-        """Find public transport connections leaving within
-        ``departure_time_window`` after ``departure`` (datetime.timedelta).
+        """Find public transport connections leaving within ``departure_time_window`` after ``departure`` (datetime.timedelta).
 
         **Note:** The value of ``departure_time_window`` should be set with some
         caution. Specifically, setting values near or below the typical headways

r5py/r5/street_layer.py

@@ -40,6 +40,7 @@ class StreetLayer:
 
     @functools.cached_property
     def extent(self):
+        """The geographic area covered, as a `shapely.box`."""
         envelope = self._street_layer.envelope
         return shapely.box(
             envelope.getMinX(),

r5py/r5/transfer_leg.py

@@ -1,8 +1,7 @@
 #!/usr/bin/env python3
 
 
-"""Represent one leg of a trip, specifically transfers between public transport
-vehicles."""
+"""Represent one leg of a trip, specifically transfers between public transport vehicles."""
 
 
 from .direct_leg import DirectLeg
@@ -12,7 +11,4 @@ __all__ = ["TransferLeg"]
 
 
 class TransferLeg(DirectLeg):
-    """
-    Represent one leg of a trip, specifically transfers between public transport
-    vehicles.
-    """
+    """Represent one leg of a trip, specifically transfers between public transport vehicles."""

r5py/r5/transit_layer.py

@@ -90,12 +90,18 @@ class TransitLayer:
 
     @functools.cached_property
     def routes(self):
+        """Return a list of GTFS routes."""
         return list(self._transit_layer.routes)
 
     @functools.cached_property
     def trip_patterns(self):
+        """Return a list of GTFS trip patterns."""
         return list(self._transit_layer.tripPatterns)
 
+    def get_stop_id_from_index(self, stop_index):
+        """Get the GTFS stop id for the `stop_index`-th stop of this transit layer."""
+        return self._transit_layer.stopIdForIndex[stop_index]
+
 
 @jpype._jcustomizer.JConversion(
     "com.conveyal.r5.transit.TransitLayer", exact=TransitLayer

r5py/r5/transit_leg.py

@@ -11,8 +11,4 @@ __all__ = ["TransitLeg"]
 
 
 class TransitLeg(TripLeg):
-    """
-    Represent one leg of a public transport trip.
-    """
-
-    pass
+    """Represent one leg of a public transport trip."""

r5py/r5/transport_mode.py

@@ -68,6 +68,7 @@ class TransportMode(enum.Enum):
         return None
 
     def __add__(self, other):
+        """Combine two transport modes."""
         if isinstance(other, self.__class__):
             return [self, other]
         elif isinstance(other, list):
@@ -78,6 +79,7 @@ class TransportMode(enum.Enum):
             )
 
     def __radd__(self, other):
+        """Combine two transport modes."""
         if other == 0:  # first iteration of sum()
             return self
         elif isinstance(other, list):
@@ -87,17 +89,17 @@ class TransportMode(enum.Enum):
 
     @property
     def is_leg_mode(self):
-        """Can this TransportMode function as a LegMode?"""
+        """Can this TransportMode function as a LegMode?."""
         return self.name in LEG_MODES
 
     @property
     def is_street_mode(self):
-        """Can this TransportMode function as a StreetMode?"""
+        """Can this TransportMode function as a StreetMode?."""
         return self.name in STREET_MODES
 
     @property
     def is_transit_mode(self):
-        """Can this TransportMode function as a TransitMode?"""
+        """Can this TransportMode function as a TransitMode?."""
         return self.name in TRANSIT_MODES
 
     AIR = "AIR"

r5py/r5/transport_network.py

@@ -89,9 +89,7 @@ class TransportNetwork:
         self._transport_network = transport_network
 
     def __del__(self):
-        """
-        Delete all temporary files upon destruction.
-        """
+        """Delete all temporary files upon destruction."""
         MAX_TRIES = 10
 
         # first, close the open osm_file,
@@ -110,13 +108,23 @@ class TransportNetwork:
             del self.transit_layer
         except AttributeError:
             pass
-        del self._transport_network
+        try:
+            del self._transport_network
+        except AttributeError:
+            pass
 
-        time.sleep(0.5)
-        jpype.java.lang.System.gc()
+        time.sleep(1.0)
+        try:
+            jpype.java.lang.System.gc()
+        except jpype.JVMNotRunning:
+            pass
 
         # then, try to delete all files in cache directory
-        temporary_files = [child for child in self._cache_directory.iterdir()]
+        try:
+            temporary_files = [child for child in self._cache_directory.iterdir()]
+        except FileNotFoundError:  # deleted in the meantime/race condition
+            temporary_files = []
+
         for _ in range(MAX_TRIES):
             for temporary_file in temporary_files:
                 try:
@@ -206,6 +214,7 @@ class TransportNetwork:
 
     @property
     def extent(self):
+        """The geographic area covered, as a `shapely.box`."""
         # TODO: figure out how to get the extent of the GTFS schedule,
         # then find the smaller extent of the two (or the larger one?)
         return self.street_layer.extent