Urban Network Analysis: Tools and Workflows for Analyzing Accessibility and Flow

UNA Tools

madina.una.tools.accessibility(zonal: Zonal, search_radius: float | int, destination_weight: str = None, alpha: float = 1, beta: float = None, save_reach_as: str = None, save_gravity_as: str = None, knn_weights: list | str = None, knn_plateau: int | float = None, save_knn_access_as: str = None, closest_facility: bool = False, save_closest_facility_as: str = None, save_closest_facility_distance_as: str = None, turn_penalty: bool = False, num_cores: int = 1) → None

Measures accessibility metrics like reach and gravity to reachable destinations within a search radius to all origins in the network.

Parameters:

zonal (Zonal) – A zonal object populated with a network, origins, destinations and a graph
search_radius (float | int, optional) – the maximum search distance for accessible destinations from an origin, measured as a network distance in the same units as the network’s CRS, defaults to None
destination_weight – destination weight, must be an attribute in the destination layer, defaults to None: equal weight of 1 for all destinations by default.
alpha (float, optional) – in gravity calculations, the alpha term increases the importance of destination weight by applying a power. default is 1, destination weight is not adjusted, defaults to 1
beta (float, optional) – In gravity calculations, the beta parameter represent the sensitivity to walk. a smaller beta value means that people are less sensitive to walking. When units are in meters, a typical beta value ranges between 0.001 (Low sensitivity) and 0.004 (High sensitivity), defaults to None
save_reach_as (str, optional) – Save the reach metric back to the origin layer as a column with this name, defaults to None
save_gravity_as (str, optional) – Save the gravity metric back to the origin layer as a column with this name, defaults to None
knn_weights (list | str, optional) – A list of the form [0.5, 0.25, 0.25], where the length of the list represent the number of suffecient destinations. the values in the list represent each weight the nth destination is given in the KNN access score. , defaults to None
knn_plateau (float | int, optional) – apply a decay penalty for destinations that are further than the specified plateau. if set to 0, a distance penalty is applied to all destinations. Cannot be larger than the search radius. Defaults to be equal to the search radius which means no penalty is applied.
save_knn_access_as – Save the KNN Access metric back to the origin layer as a column with this name, defaults to None
closest_facility (bool, optional) – restrict reach and access such that a destination is assigned its closest origin, defaults to False
save_closest_facility_as (str, optional) – if closest_facility=True, save the closest origin ID as a column in the destination layer with this name, defaults to None
save_closest_facility_distance_as (str, optional) – if closest_facility=True, save thw distance to the closest origin as a column in the destination layer with this name, defaults to None
turn_penalty (bool, optional) – If True, turn penalty is enabled, defaults to False. Uses the turn penalty amount and turn degree threshold specified in the network
num_cores (int, optional) – By default, only use a single core, set to as many cores as you want to use for running parallel calculations., defaults to 1

madina.una.tools.alternative_paths(zonal: Zonal, origin_id: int, search_radius: float | int, detour_ratio: float | int = 1, turn_penalty: bool = False)

Generates all alternative patha between an origin and all reachable destinations within a detour from the shortest path

Parameters:

zonal (Zonal) – A zonal object populated with a network, origins, destinations and a graph
origin_id (int) – an ID for the origin used as a start. Must be an ID from the origin layer.
search_radius (float | int) – The maximum distance to search for reachable destinatations. In the same unit as the network CRS.
detour_ratio (float | int, optional) – A percentage of detour over the shortest path between an origin and a destination when generating alternative paths. , defaults to 1 and only generates the shortest path. Must be greater than or equal to one. if set to a large number, could result in severe performance issues and memory overflow
turn_penalty (bool, optional) – If True, turn penalty is enabled, defaults to False

Returns:

This function returns a GeoDataFrame of all paths generated to all reachable destinations. The GeoDataFrame has three columns: - destination: the destination ID where a path ends - distance: the weight of this path: reflecting the network settings for network weight, and turn penalty. ` geometry a column of Shapely GeometryCollection containing all network segments along the path. origin and destination segments are not trimmed but returned whole.

Return type:

GeoDataFrame

madina.una.tools.betweenness(zonal: Zonal, search_radius: float, detour_ratio: float = 1, decay: bool = False, decay_method: str = 'exponent', beta: float = 0.003, num_cores: int = 1, closest_destination: bool = True, elastic_weight: bool = False, knn_weight: str | list = None, knn_plateau: float | int = 0, turn_penalty: bool = False, save_betweenness_as: str = None, save_reach_as: str = None, save_gravity_as: str = None, save_elastic_weight_as: str = None, keep_diagnostics: bool = False, path_exposure_attribute: str = None, save_path_exposure_as: str = None)

Generate trips between origins and destinations along network segment, accounting for a search radius, decay, detour, destination competition, turn penalty and elastic trip generation.

Parameters:

zonal (Zonal) – A zonal object populated with a network, origins, destinations and a graph
search_radius (float) – The maximum distance to search for reachable destinatations. In the same unit as the network CRS.
detour_ratio (float, optional) – A percentage of detour over the shortest path between an origin and a destination when allocating trips across alternative paths. Defaults to 1 and only allocate trips along the shortest path. Must be greater than or equal to one. if set to a large number, could result in severe performance issues and memory overflow
decay (bool, optional) – If ennabled, trip generation is decayed according to the chosen decay function and beta parameter, defaults to False
decay_method (str, optional) – the function that applies distance decay to trips. could be one of [‘exponent’, ‘power’], defaults to “exponent”
beta (float, optional) – When applying decay to trip generation, the beta parameter represent the sensitivity to walk. a smaller beta value means that people are less sensitive to walking. When units are in meters, a typical beta value ranges between 0.001 (Low sensitivity) and 0.004 (High sensitivity), defaults to 0.003
num_cores (int, optional) – By default, only use a single core, set to as many cores as you want to use for running parallel calculations., defaults to 1
closest_destination (bool, optional) – If set to true, trips are only routed to the closest destination. if set to false, destinations compete to attract trips based on the Huff model that factors in destination attractivenes and distance, defaults to True
elastic_weight (bool, optional) – If set to false, origins generate theur full trip potential irrespective of how many destinations they can access. if set to true, origins generate more trips as they have access to more destinations, as defined by the K-nearest neighbor access, defaults to False
knn_weight (str | list, optional) – The K-nesrest neighbor access array, should be of the form [0.5, 0.25, …, 0.01] to assign partial score foe each reachable destination. Should add up to one so it controls trip generation appropriatly, defaults to None
knn_plateau (float | int, optional) – A distance penalty could be applied to the KNN access score depending on how close the destination is. the KNN plateau gives a penalty-free score sccumilation for destinations that are closer than the plateau, and applies penalty on the distance that exceeds the plateau, defaults to 0
turn_penalty (bool, optional) – _description_, defaults to False
save_betweenness_as (str, optional) – Specify a name for the column in the network layer where the betweenness flow is stored, defaults to None
save_reach_as (str, optional) – Specify a name for thecolumn in the origin layer where the reach accessibility score is stored , defaults to None
save_gravity_as (str, optional) – Specify a name for the column in the origin layer where the gravity score is stored, defaults to None
save_elastic_weight_as (str, optional) – specify a name for the column in the origin layer where the KNN-adjusted origin weight is stored, defaults to None
keep_diagnostics (bool, optional) – If set to true, store performance and memory statistics in the network, defaults to False
path_exposure_attribute (str, optional) – If provided, calculates an exposure to a network value for trips originatinbg from an origin en route to destinations, defaults to None
save_path_exposure_as (str, optional) – if path exposure attribute is proviided, this is a name for a column in the origin layer that captures origin’s exposure to the network exposure attribute, defaults to None

madina.una.tools.service_area(zonal: Zonal, search_radius: float, origin_ids: int | list = None, turn_penalty: bool = False)

For each origin, generate a polygon of its service area, defined by the boundary around the destinations it could reach within a specified searchj radius. A list of destinations is returned, as well as the network geometry inside the service area

Parameters:

zonal (Zonal) – A zonal object populated with a network, origins, destinations and a graph
origin_ids (int | list) – If not provided, the service area for all origins is generated. This parameter can either be the id of an origin as an integer, or a list of origin IDs
search_radius (float | int) – the maximum search distance for accessible destinations from an origin, measured as a network distance in the same units as the network’s CRS, defaults to None
turn_penalty (bool, optional) – If True, turn penalty is enabled, defaults to False

Raises:

ValueError – if an origin id is not for an origin in the origin layer.

Returns:

destinations: A dataframe howing a list of destinations for each origin that falls within the search radius
network_edges: The network geometry that falls withn the service area of all origins
scope_gdf: for each origin, a polygon of its service ares

Return type:

GeoDataFrame

UNA Workflows

madina.una.workflows.KNN_accessibility(city_name=None, data_folder=None, output_folder=None, pairings_file='pairing.csv', num_cores=8)

A workflow to generate accessibility metrics: reach, gravity and KNN access for an origin to all its paired destinations in the pairing table.

Parameters:

city_name (str, optional) – a city name that correspond to a folder inside the “Cities” folder in the current working directory, defaults to None
data_folder (str, optional) – If the parameter city_name was provided, this parameter is optional if the data and pairing table were stored in a folder “Cities/city_name/Data” relative to the current working directory, defaults to None
output_folder (str, optional) – if the parameter city_name was provided, this prameter is optional, and all output would be stored in a folder inside “Citiescity_nameSimulations” relatie to the current working directory, defaults to None
pairings_file (str, optional) – the name of the file containing the pairing table inside the data folder, defaults to “pairings.csv”
num_cores (int, optional) – the number of cores to be used in multiprocessing to speed up the simulation, defaults to 8

madina.una.workflows.betweenness_flow_simulation(city_name=None, data_folder=None, output_folder=None, pairings_file='pairings.csv', num_cores=8) → None

A workflow to generate trips between pairs of origins and destonations along a network. for detailed description of the workflow, please reference this page: https://madinadocs.readthedocs.io/en/latest/ped_flow.html to learn more about preparing data and constructing a pairing table needed for this workflow

Parameters:

city_name (str, optional) – a city name that correspond to a folder inside the “Cities” folder in the current working directory, defaults to None
data_folder (str, optional) – If the parameter city_name was provided, this parameter is optional if the data and pairing table were stored in a folder “Cities/city_name/Data” relative to the current working directory, defaults to None
output_folder (str, optional) – if the parameter city_name was provided, this prameter is optional, and all output would be stored in a folder inside “Citiescity_nameSimulations” relatie to the current working directory, defaults to None
pairings_file (str, optional) – the name of the file containing the pairing table inside the data folder, defaults to “pairings.csv”
num_cores (int, optional) – the number of cores to be used in multiprocessing to speed up the simulation, defaults to 8