rename deadhead functions for clarity; format

Author: dan-mccabe

docs/examples/Utah_Transit_Agency_example.py

@@ -8,9 +8,9 @@
 import os
 
 from nrel.routee.transit import (
+    aggregate_results_by_trip,
     build_routee_features_with_osm,
     predict_for_all_trips,
-    aggregate_results_by_trip,
     repo_root,
 )
 
@@ -76,9 +76,13 @@
 energy_by_trip = aggregate_results_by_trip(routee_results, routee_vehicle_model)
 
 # Merge HVAC energy
-energy_by_trip = energy_by_trip.merge(temp_energy_df, on='trip_id', how='left')
-energy_by_trip["kwh_per_mi_winter"] = (energy_by_trip["kWhs"] + energy_by_trip["Winter_HVAC_Energy"]) / energy_by_trip["miles"]
-energy_by_trip["kwh_per_mi_summer"] = (energy_by_trip["kWhs"] + energy_by_trip["Summer_HVAC_Energy"]) / energy_by_trip["miles"]
+energy_by_trip = energy_by_trip.merge(temp_energy_df, on="trip_id", how="left")
+energy_by_trip["kwh_per_mi_winter"] = (
+    energy_by_trip["kWhs"] + energy_by_trip["Winter_HVAC_Energy"]
+) / energy_by_trip["miles"]
+energy_by_trip["kwh_per_mi_summer"] = (
+    energy_by_trip["kWhs"] + energy_by_trip["Summer_HVAC_Energy"]
+) / energy_by_trip["miles"]
 
 # Check the results for some random trips
 energy_by_trip

docs/examples/_convert_examples.py

@@ -1,7 +1,8 @@
-from pathlib import Path
-import nbformat
 import argparse
 import sys
+from pathlib import Path
+
+import nbformat
 
 
 def script_to_notebook(script_path: Path, notebook_path: Path) -> None:

nrel/routee/transit/__init__.py

@@ -7,7 +7,7 @@
 ]
 
 from .prediction.gtfs_feature_processing import build_routee_features_with_osm
-from .prediction.routee import predict_for_all_trips, aggregate_results_by_trip
+from .prediction.routee import aggregate_results_by_trip, predict_for_all_trips
 
 
 def package_root() -> Path:

nrel/routee/transit/prediction/add_temp_feature.py

@@ -1,11 +1,12 @@
+import os
+from typing import Any
+
+import boto3
 import geopandas as gpd
+import numpy as np
 import pandas as pd
-import boto3
 from botocore import UNSIGNED
 from botocore.config import Config
-import os
-import numpy as np
-from typing import Any
 
 
 def add_HVAC_energy(feed: Any, trips_df: pd.DataFrame) -> Any:

nrel/routee/transit/prediction/between_trip_deadhead.py

@@ -6,7 +6,7 @@
 from geopy.distance import geodesic
 
 
-def create_betweenTrip_deadhead_trips(
+def create_between_trip_deadhead_trips(
     trips_df: pd.DataFrame, stop_times_df: pd.DataFrame
 ) -> pd.DataFrame:
     """Create deadhead trips between consecutive trips for each block.
@@ -66,7 +66,7 @@ def create_betweenTrip_deadhead_trips(
     return deadhead_trips
 
 
-def create_betweenTrip_deadhead_stops(
+def create_between_trip_deadhead_stops(
     feed: Any, deadhead_trips: pd.DataFrame
 ) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
     """Create stop_times and stops for deadhead trips between consecutive trips to generate the feed object for between trip deadhead trips.
@@ -75,7 +75,7 @@ def create_betweenTrip_deadhead_stops(
     feed: Any
         GTFS feed object (e.g. result from read_in_gtfs).
     deadhead_trips: pd.DataFrame
-        deadhead trip results from create_betweenTrip_deadhead_trips.py.
+        deadhead trip results from create_between_trip_deadhead_trips.py.
     Returns
     -------
     pd.DataFrame
@@ -186,7 +186,7 @@ def create_betweenTrip_deadhead_stops(
     ]
     stop_times_df["stop_id"] = range(1, len(stop_times_df) + 1)
     stop_times_df["stop_id"] = stop_times_df["stop_id"].apply(
-        lambda x: f"betweenTrip_deadhead_{x}"
+        lambda x: f"between_trip_deadhead_{x}"
     )
     stop_times_df["departure_time"] = stop_times_df["arrival_time"]
     stop_times_df["shape_dist_traveled"] = 0.0

nrel/routee/transit/prediction/create_betweenTrip_deadhead_stops.py

@@ -11,6 +11,11 @@
 
 def create_depot_deadhead_trips(trips_df: pd.DataFrame) -> pd.DataFrame:
     """Create deadhead trips from and to depots for each block.
+
+    This function essentially creates rows for the trips.txt DataFrame.
+    It does not generate shape traces for them (that is handled by other
+    functions in this module).
+
     Parameters
     ----------
     trips_df : pd.DataFrame
@@ -92,10 +97,10 @@ def create_depot_deadhead_trips(trips_df: pd.DataFrame) -> pd.DataFrame:
     return deadhead_trips_df
 
 
-def add_depot_to_blocks(
+def infer_depot_trip_endpoints(
     trips_df: pd.DataFrame, feed: Any, path_to_depots: str | Path
 ) -> tuple[Any, Any]:
-    """Add origin/destination depot geometry to each block id.
+    """Add origin/destination depot geometry for each block.
 
     Parameters
     ----------
@@ -221,7 +226,8 @@ def create_depot_deadhead_stops(
     last_stops_gdf: gpd.GeoDataFrame,
     deadhead_trips: pd.DataFrame,
 ) -> tuple[pd.DataFrame, pd.DataFrame]:
-    """Creat stop_times and stops for deadhead trips from and to depots for each block to generate the feed object for depot deadhead trips.
+    """Create stop_times and stops for deadhead trips from and to depots.
+
     Parameters
     ----------
     first_stops_gdf: gpd.GeoDataFrame

nrel/routee/transit/prediction/depot_deadhead.py

@@ -1,25 +1,20 @@
-import pandas as pd
-import geopandas as gpd
-import osmnx as ox
-import networkx as nx
-from shapely.geometry import LineString
-from shapely.ops import linemerge, unary_union
 import math
 
 # single-global-graph approach; per-row cached graphs removed
 import multiprocessing as mp
-from typing import Tuple, Any
+from typing import Any, Tuple
 
+import geopandas as gpd
+import networkx as nx
+import osmnx as ox
+import pandas as pd
+from shapely.geometry import LineString
+from shapely.ops import linemerge, unary_union
 
 # Optionally hold a single pre-fetched graph for the whole study area.
 GLOBAL_GRAPH = None
 
 
-# Note: per-row cached graph fetch removed. This module now requires a single
-# pre-fetched study-area graph assigned to GLOBAL_GRAPH (via bbox in
-# `add_deadhead_trips`) and all routing workers use that graph.
-
-
 def _parallel_map(
     func: Any, iterable: Any, n_processes: int | None, chunksize: int = 8
 ) -> list[Any]:
@@ -32,6 +27,7 @@ def _parallel_map(
             results.append(item)
     return results
 
+
 def _haversine_km(lat1: Any, lon1: Any, lat2: Any, lon2: Any) -> float:
     """Get the haversine distance between two points in kilometers."""
     R = 6371.0
@@ -153,7 +149,7 @@ def _process_deadhead_trip_row(args: Tuple[Any, ...]) -> list[Any]:
         return []
 
 
-def add_deadhead_trips(
+def create_deadhead_shapes(
     df: gpd.GeoDataFrame,
     o_col: str = "geometry_origin",
     d_col: str = "geometry_destination",
@@ -171,9 +167,7 @@ def add_deadhead_trips(
     global GLOBAL_GRAPH
 
     # Create bounding box around for osmnx graph based on O/D geometry
-    all_points = pd.concat(
-        [df["geometry_origin"], df["geometry_destination"]]
-    )
+    all_points = pd.concat([df["geometry_origin"], df["geometry_destination"]])
     lons = all_points.apply(lambda p: p.x)
     lats = all_points.apply(lambda p: p.y)
     min_lon, max_lon = lons.min(), lons.max()  # Bounding box

nrel/routee/transit/prediction/generate_deadhead_traces.py

@@ -1,8 +1,7 @@
 from __future__ import annotations
 
-from pathlib import Path
-
 import logging
+from pathlib import Path
 
 import requests