User Reference

User Reference#

This is the User Reference for the NxTransit package. This guide describes the usage of NxTransit public API.

NxTransit.loaders module#

Load combined GTFS and OSM data into a graph.

nxtransit.loaders.feed_to_graph(GTFSpath: str, departure_time_input: str, day_of_week: str, duration_seconds: int, read_shapes: bool = False, multiprocessing: bool = True, input_graph_path: str = None, output_graph_path: str = None, save_graphml: bool = False, load_graphml: bool = False) → DiGraph[source]#

Creates a directed graph (DiGraph) based on General Transit Feed Specification (GTFS) and OpenStreetMap (OSM) data.

Parameters:

GTFSpath (str) – Path to the GTFS files.
departure_time_input (str) – Departure time in ‘HH:MM:SS’ format.
day_of_week (str) – Day of the week in lowercase (e.g., ‘monday’).
duration_seconds (int) – Time period from departure for which the graph will be loaded.
read_shapes (bool, optional) – Flag for reading geometry from shapes.txt file. Default is False. This parameter is currently not working as intended.
multiprocessing (bool, optional) – Flag for using multiprocessing. Default is False.
input_graph_path (str, optional) – Path to the OSM graph file in GraphML format. Default is None.
output_graph_path (str, optional) – Path for saving the OSM graph in GraphML format. Default is None.
save_graphml (bool, optional) – Flag for saving the OSM graph in GraphML format. Default is False.
load_graphml (bool, optional) – Flag for loading the OSM graph from a GraphML file. Default is False.

Returns:

G_combined – Combined multimodal graph representing transit network.

Return type:

nx.DiGraph

nxtransit.loaders.load_stops_gdf(path) → GeoDataFrame[source]#

Load stops data from a specified path and return a GeoDataFrame.

Parameters:: path (str) – The path to the directory containing the stops data.
Returns:: stops_gdf – GeoDataFrame containing the stops data with geometry information.
Return type:: gpd.GeoDataFrame

NxTransit.routers module#

Main routing algorithms for time-dependent graphs.

nxtransit.routers.single_source_time_dependent_dijkstra(graph: DiGraph, source: str, start_time: int, hashtable: Dict | None = None) → Tuple[Dict[str, float], Dict[str, str], Dict[str, float]][source]#

Compute the shortest paths and travel times from a single source node to all other nodes in a time-dependent graph. You can use the process_graph_to_hash_table function to create the hash table.

Parameters:

graph (nx.DiGraph) – The time-dependent graph.
source (Node) – The source node of the graph.
start_time (int) – The starting time in seconds since midnight.
hashtable (dict, optional) – A hashtable for storing precomputed values. Enables faster access to sorted schedules.

Returns:

A tuple containing three dictionaries:

arrival_times: A dictionary mapping each node to the earliest arrival time from the source node.
predecessors: A dictionary mapping each node to its predecessor on the shortest path from the source node.
travel_times: A dictionary mapping each node to the travel time from the source node.

Return type:

tuple

Implementation#

This function uses a priority queue to explore the graph with almost classic Dijkstra’s algorithm. The main difference is that the delay between two nodes is calculated based on the current time and the sorted schedules of the edge. The function also keeps track of the routes used in the path if the track_used_routes parameter is set to True.

>>> G = nx.DiGraph()
>>> G.add_edge('A', 'B')
>>> G.edges['A', 'B']['sorted_schedules'] = [(10, 20, 'route_1', None),(30, 40, 'route_2', None), (50, 60, 'route_3', None)]

So the edge from ‘A’ to ‘B’ has three schedules: route_1 departs at 10 and arrives at 20, route_2 departs at 30 and arrives at 40, and route_3 departs at 50 and arrives at 60. Internal function _calculate_delay will return the delay and the route for the next departure from ‘A’ to ‘B’ at a given time. i.e. if the current time is 25, the next departure is at 30, so the delay is 5 and time to arrival is 5 + (40 - 30) = 10.

References

NxTransit.accessibility module#

Tools for calculating accessibility metrics

nxtransit.accessibility.calculate_od_matrix(graph: DiGraph, nodes: list, departure_time: float, hashtable: dict = None, algorithm='sorted')[source]#

Calculates the Origin-Destination (OD) matrix for a given graph, nodes, and departure time.

Parameters:

graph (networkx.DiGraph) – The graph representing the transit network.
nodes (list) – A list of node IDs in the graph.
departure_time (float) – The departure time in seconds since midnight.
hashtable (dict, optional) – Hash table for the graph.

Returns:

A DataFrame containing the OD matrix with the following columns:

source_node: The ID of the origin node.
destination_node: The ID of the destination node.
arrival_time: The arrival time at the destination node in seconds since midnight.
travel_time: The travel time from the origin node to the destination node in seconds.

Return type:

pandas.DataFrame

nxtransit.accessibility.calculate_od_matrix_parallel(graph: DiGraph, nodes, departure_time: float, target_nodes: list = None, num_processes: int = 2, hashtable: dict = None) → DataFrame[source]#

Calculates the Origin-Destination (OD) matrix for a given graph, nodes, and departure time using parallel processing.

Parameters:

graph (networkx.DiGraph) – The graph representing the transit network.
nodes (list) – A list of node IDs in the graph.
departure_time (int) – The departure time in seconds since midnight.
target_nodes (list, optional) – A list of target node IDs in the graph. If not specified, source nodes are used.
num_processes (int) – Number of parallel processes to use for computation.
hashtable (dict, optional) – Optional hash table for the graph.

Returns:

results_df – A DataFrame containing the OD matrix.

Return type:

pandas.DataFrame

nxtransit.accessibility.last_service(graph: DiGraph)[source]#

Calculate the last service time for each stop in the graph. Populates the ‘last_service’ attribute of each transit stop.

Parameters:: graph (networkx.DiGraph) – The graph representing the transit network.
Return type:: None

nxtransit.accessibility.percent_access_service_area(graph: DiGraph, source: Any, start_time: int, end_time: int, sample_interval: int, cutoff: int, buffer_radius: float, threshold: float, algorithm: str = 'sorted', hashtable: Dict | None = None) → GeoDataFrame[source]#

Calculate service area reachable with specified chance within the given time period.

This tool rasterize service areas for each time step and overlays them. Part of the raster that is covered by at least the threshold of the service areas is returned as a vectorized GeoDataFrame.

Parameters:

graph (networkx.DiGraph) – The graph representing the transit network.
source (Any) – The source node from which to service areas.
start_time (int) – The start time of the time period in seconds from midnight.
end_time (int) – The end time of the time period in seconds from midnight.
sample_interval (int) – The interval between samples.
cutoff (int) – The maximum travel time allowed to reach the service area.
buffer_radius (float) – The radius of the buffer around the service area.
threshold (float) – The threshold value for rasterizing the service areas.
algorithm (str) – optional. Algorithm to use for the service area calculation (default: ‘sorted’).
hashtable (dict, optional) – Hashtable required for the algorithm (default: None).

Returns:

GeoDataFrame containing the vectorized result.

Return type:

gpd.GeoDataFrame

nxtransit.accessibility.service_area(graph: DiGraph, source: Any, start_time: int, cutoff: float, buffer_radius: float = 100, algorithm: str = 'sorted', hashtable: Dict | None = None) → GeoDataFrame[source]#

Creates a service area by buffering around all street edges within a travel time cutoff.

Parameters:

graph (networkx.DiGraph) – The graph to search.
source (node) – The graph node to start the search from.
start_time (int) – The time to start the search from.
cutoff (float) – The travel time cutoff for including nodes in the service area.
buffer_radius (float) – The radius in meters for buffering around each point.
algorithm (str, optional) – Algorithm to use for the service area calculation (default: “sorted”).
hashtable (dict, optional) – Hashtable required for the “hashed” algorithm.

Returns:

A GeoDataFrame containing the service area polygon.

Return type:

geopandas.GeoDataFrame

Notes

Output crs is EPSG:4087 (World Equidistant Cylindrical).

NxTransit.frequency module#

Tools for calculating various frequency of transit service metrics in a network.

nxtransit.frequency.connectivity_frequency(graph, source, target, start_time, end_time, sampling_interval=60)[source]#

Calculates the connectivity frequency between a source and target node in a graph over a specified time period.

Parameters:

graph (networkx.DiGraph) – The graph object representing the network.
source (hashable) – The source node.
target (hashable) – The target node.
start_time (int or float) – The start time of the analysis period.
end_time (int or float) – The end time of the analysis period.
sampling_interval (int or float) – The time interval at which to sample the connectivity.

Returns:

The mean interval between peaks in the connectivity.

Return type:

float

nxtransit.frequency.edge_frequency(graph, start_time, end_time)[source]#

Calculates the frequency of edges in a graph based on the schedules between start_time and end_time.

Parameters:

graph (networkx.DiGraph) – The graph containing the edges and schedules.
start_time (int) – The start time in seconds from midnight.
end_time (int) – The end time in seconds from midnight.

Return type:

None

nxtransit.frequency.node_frequency(graph, start_time, end_time)[source]#

Calculates the frequency of departures at nodes in a graph based on the schedules of adjacent edges between start_time and end_time.

Parameters:

graph (networkx.DiGraph) – The graph containing the nodes and adjacent edges with schedules.
start_time (int) – The start time in seconds from midnight.
end_time (int) – The end time in seconds from midnight.

Return type:

None

nxtransit.frequency.single_source_connectivity_frequency(graph, source, start_time, end_time, sampling_interval=60, hashtable=None, algorithm='sorted')[source]#

Calculates the mean interval between peaks in travel times from a source node to all other nodes in a graph over a specified time period.

Parameters:

graph (networkx.DiGraph) – The graph object representing the network.
source (hashable) – The source node.
start_time (int or float) – The start time of the analysis period.
end_time (int or float) – The end time of the analysis period.
sampling_interval (int or float) – The time interval at which to sample the connectivity.
algorithm (str, optional) – The algorithm to use for the shortest path calculation. Options are ‘sorted’ and ‘hashed’.
hashtable (dict, optional) – Hashtable to use for the ‘hashed’ algorithm.

Returns:

A dictionary mapping each node to the mean interval between peaks in travel times.

Return type:

dict

NxTransit.functions module#

nxtransit.functions.aggregate_to_grid(gdf: GeoDataFrame, cell_size: float) → GeoDataFrame[source]#

Creates a grid of square cells covering the extent of the input GeoDataFrame, and keeps cells that contain at least one feature from the source GeoDataFrame.

Parameters:

gdf (gpd.GeoDataFrame) – The input GeoDataFrame representing the spatial extent and features.
cell_size (float) – The size of each square cell in the grid in meters.

Returns:

The resulting grid GeoDataFrame, with cells containing at least one feature from the source GeoDataFrame, and a ‘id’ for each cell.

Return type:

gpd.GeoDataFrame

nxtransit.functions.create_centroids_dataframe(polygon_gdf: GeoDataFrame) → GeoDataFrame[source]#

Creates a GeoDataFrame with the centroids of polygons from the given GeoDataFrame.

Parameters:: polygon_gdf (gpd.GeoDataFrame) – GeoDataFrame containing polygons.
Returns:: GeoDataFrame with Point geometries of the centroids.
Return type:: gpd.GeoDataFrame

nxtransit.functions.process_graph_to_hash_table(graph) → dict[source]#

Process a graph and convert it into a hash table mapping edges to their sorted schedules or static weights.

Parameters:: graph (networkx.DiGraph) – The input graph.
Returns:: A dict mapping edges to their sorted schedules or static weights.
Return type:: dict

nxtransit.functions.separate_travel_times(graph, predecessors: dict, travel_times: dict, source) → DataFrame[source]#

Separate the travel times into transit time and pedestrian time for each node in the graph.

It calculates the pedestrian time by reconstructing the path from the source node to each destination node and then estimating the time spent walking.

Parameters:

graph (networkx.DiGraph) – The graph representing the transit network.
predecessors (dict) – A dictionary containing the predecessors of each node in the graph.
travel_times (dict) – A dictionary containing the travel times for each node in the graph.
source (hashable) – The source node from which to calculate the travel times.

Returns:

A DataFrame containing the transit time and pedestrian time for each node.

Return type:

pandas.DataFrame

nxtransit.functions.validate_feed(gtfs_path: str) → bool[source]#

Validates the GTFS feed located at the specified path.

Parameters:: gtfs_path (str) – Path to the GTFS dataset directory.
Returns:: True if the GTFS feed is valid, False otherwise.
Return type:: bool

NxTransit.connectors module#

Tools for connecting GTFS stops to the nearest street node in the graph.

nxtransit.connectors.connect_stops_to_streets(graph: DiGraph, stops: DataFrame)[source]#: Connects GTFS stops to the nearest street node in the graph using projected coordinates in EPSG:4087.

nxtransit.connectors.snap_points_to_network(graph: DiGraph, points: GeoDataFrame)[source]#

Snaps point features from GeoDataFrame to the nearest street node in the graph.

Parameters:

graph (networkx.Graph) – NetworkX graph representing the transit system.
points (geopandas.GeoDataFrame) – GeoDataFrame containing point geometries.

Return type:

None. The input graph is modified in-place with added snapped points as nodes.

NxTransit.converters module#

Utility functions for converting between different data types.

nxtransit.converters.parse_seconds_to_time(seconds: int) → str[source]#: Converts the number of seconds since midnight to a time string.

nxtransit.converters.parse_time_to_seconds(time_str: str) → int[source]#: Converts a time string to the number of seconds since midnight

NxTransit.other module#

This module is in prototyping stage and is not used in the main program.

User Reference

Contents

User Reference#

NxTransit.loaders module#

NxTransit.routers module#

Implementation#

NxTransit.accessibility module#

NxTransit.frequency module#

NxTransit.functions module#

NxTransit.connectors module#

NxTransit.converters module#

NxTransit.other module#