r5py 0.1.1.dev0__py3-none-any.whl → 0.1.2__py3-none-any.whl

r5py/__init__.py

@@ -2,7 +2,8 @@
 
 """Python wrapper for the R5 routing analysis engine."""
 
-__version__ = "0.1.1.dev0"
+__version__ = "0.1.2"
+
 
 from .r5 import (
     DetailedItinerariesComputer,

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,37 @@
 
 """R5 classes."""
 
+from .access_leg import AccessLeg
 from .breakdown_stat import BreakdownStat
 from .detailed_itineraries_computer import 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 .trip import Trip
+from .trip_planner import TripPlanner
 
 __all__ = [
+    "AccessLeg",
     "BreakdownStat",
     "DetailedItinerariesComputer",
+    "DirectLeg",
+    "EgressLeg",
     "RegionalTask",
     "Scenario",
     "SpeedConfig",
     "StreetLayer",
+    "TransferLeg",
+    "TransitLeg",
     "TransportMode",
     "TransportNetwork",
     "TravelTimeMatrixComputer",
+    "Trip",
+    "TripPlanner",
 ]

r5py/r5/base_travel_time_matrix_computer.py

@@ -91,6 +91,7 @@ class BaseTravelTimeMatrixComputer:
 
     @property
     def destinations(self):
+        """The destinations of this travel time matrix (`geopandas.GeoDataFrame`)."""
         return self._destinations
 
     @destinations.setter
@@ -117,13 +118,10 @@ class BaseTravelTimeMatrixComputer:
         pandas.DataFrame
             Data frame in which all MAX_INT32 have been replaced by `numpy.nan`.
         """
-        return data_set.applymap(lambda x: numpy.nan if x == MAX_INT32 else x)
+        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:
@@ -165,6 +163,7 @@ class BaseTravelTimeMatrixComputer:
 
     @property
     def origins(self):
+        """The origins of this travel time matrix (`geopandas.GeoDataFrame`)."""
         return self._origins
 
     @origins.setter

r5py/r5/detailed_itineraries_computer.py

@@ -124,7 +124,6 @@ class DetailedItinerariesComputer(BaseTravelTimeMatrixComputer):
             route number or name), `geometry` (`shapely.LineString`)
             TODO: Add description of output data frame columns and format
         """
-
         self._prepare_origins_destinations()
 
         # warn if public transport routes are requested, but R5 has been
@@ -150,11 +149,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 +162,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:

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

@@ -57,8 +57,9 @@ class RegionalTask:
 
         In **r5py**, there is usually no need to explicitely create a
         `RegionalTask`. Rather, the constructors to the computation classes
-        (`TravelTimeMatrixComputer`, `AccessibilityEstimator`, ...) accept
-        the arguments, and pass them through to an internally handled `RegionalTask`.
+        (`TravelTimeMatrixComputer`, `AccessibilityEstimator`, ...) accept the
+        arguments, and pass them through to an internally handled
+        `RegionalTask`.
 
         Arguments
         ---------
@@ -67,31 +68,30 @@ class RegionalTask:
         origin : shapely.geometry.Point
             Point to route from
         destinations : geopandas.GeoDataFrame
-            Points to route to, has to have at least an ``id`` column
-            and a geometry
+            Points to route to, has to have at least an ``id`` column and a
+            geometry
         departure : datetime.datetime
             Find public transport connections leaving every minute within
-            ``departure_time_window`` after ``departure``.
-            Default: current date and time
+            ``departure_time_window`` after ``departure``. Default: current date
+            and time
         departure_time_window : datetime.timedelta
-            (see ``departure``)
-            Default: 10 minutes
+            (see ``departure``) Default: 10 minutes
         percentiles : list[int]
             Return the travel time for these percentiles of all computed trips,
-            by travel time. By default, return the median travel time.
-            Default: [50]
+            by travel time. By default, return the median travel time. Default:
+            [50]
         transport_modes : list[r5py.TransportMode] or list[str]
-            The mode of transport to use for routing. Can be a r5py mode enumerable, or a string representation (e.g. "TRANSIT")
-            Default: [r5py.TransportMode.TRANSIT] (all public transport)
+            The mode of transport to use for routing. Can be a r5py mode
+            enumerable, or a string representation (e.g. "TRANSIT") Default:
+            [r5py.TransportMode.TRANSIT] (all public transport)
         access_modes : list[r5py.TransportMode] or list[str]
-            Mode of transport to public transport stops. Can be a r5py mode object, or a string representation (e.g. "WALK")
-            Default: [r5py.TransportMode.WALK]
+            Mode of transport to public transport stops. Can be a r5py mode
+            object, or a string representation (e.g. "WALK") Default:
+            [r5py.TransportMode.WALK]
         egress_modes : list[r5py.TransportMode]
-            Mode of transport from public transport stops.
-            Default: access_modes
+            Mode of transport from public transport stops. Default: access_modes
         max_time : datetime.timedelta
-            Maximum trip duration.
-            Default: 2 hours
+            Maximum trip duration. Default: 2 hours
         max_time_walking : datetime.timedelta
             Maximum time spent walking, potentially including access and egress
             Default: max_time
@@ -99,24 +99,19 @@ class RegionalTask:
             Maximum time spent cycling, potentially including access and egress
             Default: max_time
         max_time_driving : datetime.timedelta
-            Maximum time spent driving
-            Default: max_time
+            Maximum time spent driving Default: max_time
         speed_walking : float
-            Mean walking speed for routing, km/h.
-            Default: 3.6 km/h
+            Mean walking speed for routing, km/h. Default: 3.6 km/h
         speed_cycling : float
-            Mean cycling speed for routing, km/h.
-            Default: 12.0 km/h
+            Mean cycling speed for routing, km/h. Default: 12.0 km/h
         max_public_transport_rides : int
-            Use at most ``max_public_transport_rides`` consecutive public transport
-            connections. Default: 8
+            Use at most ``max_public_transport_rides`` consecutive public
+            transport connections. Default: 8
         max_bicycle_traffic_stress : int
-            Maximum stress level for cyclist routing, ranges from 1-4
-            see https://docs.conveyal.com/learn-more/traffic-stress
-            Default: 3
+            Maximum stress level for cyclist routing, ranges from 1-4 see
+            https://docs.conveyal.com/learn-more/traffic-stress Default: 3
         breakdown : bool
-            Compute a more detailed breakdown of the routes.
-            Default: False
+            Compute a more detailed breakdown of the routes. Default: False
         """
         self._regional_task = com.conveyal.r5.analyst.cluster.RegionalTask()
         self.scenario = Scenario()
@@ -205,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):
@@ -251,14 +250,21 @@ 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
+        in the studied transit network may lead to routing problems. See `this
+        GitHub discussion <https://github.com/r5py/r5py/issues/292>`_ for
+        details.
+        """
         return self._departure_time_window
 
     @departure_time_window.setter
     def departure_time_window(self, departure_time_window: datetime.timedelta):
         if departure_time_window.total_seconds() < 300:
             warnings.warn(
-                "The provided departure time window is below 5 minutes. This may cause adverse effects with headway-based GTFS datasets.",
+                "The provided departure time window is below 5 minutes. This may cause adverse effects with routing.",
                 RuntimeWarning,
             )
         self._departure_time_window = departure_time_window

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,10 +90,12 @@ 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)
 
 

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

@@ -43,12 +43,14 @@ class TransportNetwork:
 
         Arguments
         ---------
-        osm_pbf : str
+        osm_pbf : str | pathlib.Path
             file path of an OpenStreetMap extract in PBF format
-        gtfs : list[str]
-            paths to public transport schedule information in GTFS format
+        gtfs : str | pathlib.Path | list[str] | list[pathlib.Path]
+            path(s) to public transport schedule information in GTFS format
         """
         osm_pbf = self._working_copy(pathlib.Path(osm_pbf)).absolute()
+        if isinstance(gtfs, (str, pathlib.Path)):
+            gtfs = [gtfs]
         gtfs = [str(self._working_copy(path).absolute()) for path in gtfs]
 
         transport_network = com.conveyal.r5.transit.TransportNetwork()
@@ -87,15 +89,17 @@ 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,
         # delete Java objects, and
         # trigger Java garbage collection
-        self.osm_file.close()
+        try:
+            self.osm_file.close()
+        except jpype.JVMNotRunning:
+            # JVM was stopped already, file should be closed
+            pass
         try:
             del self.street_layer
         except AttributeError:  # might not have been accessed a single time
@@ -104,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:
@@ -200,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

r5py/r5/travel_time_matrix_computer.py

@@ -4,7 +4,6 @@
 
 import copy
 
-import joblib
 import pandas
 
 from .base_travel_time_matrix_computer import BaseTravelTimeMatrixComputer
@@ -40,20 +39,10 @@ class TravelTimeMatrixComputer(BaseTravelTimeMatrixComputer):
         self._prepare_origins_destinations()
         self.request.destinations = self.destinations
 
-        # loop over all origins, modify the request, and compute the times
-        # to all destinations.
-        with joblib.Parallel(
-            prefer="threads",
-            verbose=(10 * self.verbose),  # joblib has a funny verbosity scale
-            n_jobs=self.NUM_THREADS,
-        ) as parallel:
-            od_matrix = pandas.concat(
-                parallel(
-                    joblib.delayed(self._travel_times_per_origin)(from_id)
-                    for from_id in self.origins.id
-                ),
-                ignore_index=True,
-            )
+        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)

r5py/r5/trip.py

@@ -15,9 +15,7 @@ __all__ = ["Trip"]
 
 
 class Trip:
-    """
-    Represent one trip, consisting of one or more `TripLeg`s.
-    """
+    """Represent one trip, consisting of one or more `r5py.r5.TripLeg`."""
 
     COLUMNS = [
         "segment",
@@ -25,7 +23,7 @@ class Trip:
 
     def __init__(self, legs=[]):
         """
-        Represent one trip, consisting of one of more `TripLeg`s.
+        Represent one trip, consisting of one of more `r5py.r5.TripLeg`.
 
         Arguments
         =========
@@ -34,7 +32,13 @@ class 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__}: "

r5py/r5/trip_leg.py

@@ -4,6 +4,11 @@
 """Represent one leg of a trip."""
 
 
+import datetime
+import numpy
+import shapely
+
+
 __all__ = ["TripLeg"]
 
 
@@ -28,12 +33,12 @@ class TripLeg:
     def __init__(
         self,
         transport_mode=None,
-        departure_time=None,
+        departure_time=numpy.datetime64("NaT"),
         distance=None,
-        travel_time=None,
-        wait_time=None,
+        travel_time=datetime.timedelta(seconds=0),
+        wait_time=datetime.timedelta(seconds=0),
         route=None,
-        geometry=None,
+        geometry=shapely.LineString(),
     ):
         """
         Represent one leg of a trip.
@@ -66,6 +71,7 @@ class TripLeg:
         self.geometry = geometry
 
     def __add__(self, other):
+        """Trip-chain `other` to `self`."""
         from .trip import Trip
 
         if isinstance(other, self.__class__):
@@ -80,6 +86,7 @@ class TripLeg:
             )
 
     def __radd__(self, other):
+        """Trip-chain `self` to `other`."""
         from .trip import Trip
 
         if other == 0:  # first iteration of sum()
@@ -90,31 +97,43 @@ class TripLeg:
         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]
@@ -127,10 +146,30 @@ class TripLeg:
                 f"{first_point} -> {last_point}"
                 ">"
             )
-        except AttributeError:
+        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.