transport_frames.criteria

Module for getting grade and criteroa of territories

Functions

assign_grades(graded_territories, ...)

Assign accessibility-based grades to territories.

calculate_quartiles(df, column)

Calculate quartile rankings for a given column in a DataFrame.

find_median(city_points, adj_mx)

Compute the median travel time from each city to all other cities.

get_criteria(graded_terr, points, polygons)

Compute criteria scores for graded territories based on transport accessibility.

grade_territory(frame, gdf_poly[, ...])

Grade territories based on proximity to key transport infrastructure.

interpret_gdf(gdf)

Interprets geographic accessibility data for each criterion in the criteria DataFrame.

interpretation(grade, weight_r_stops, ...)

Generate a textual interpretation of an area's transport accessibility.

weight_territory(territories, railway_stops, ...)

Assign weights to territories based on accessibility to key transport services.

Classes

PointSchema(*args, **kwargs)

Schema for validating points.

PolygonSchema(*args, **kwargs)

Schema for validating polygons.
class transport_frames.criteria.PolygonSchema(*args, **kwargs)[source]

Bases: BaseSchema

Schema for validating polygons.

Variables:

  • name (str) – Name pf the polygon. Default to None

  • _geom_types (list) – List of allowed geometry types for the points, default is [shapely.Point]

name: Series[str] = 'name'
class Config

Bases: Config

name = 'PolygonSchema'
class transport_frames.criteria.PointSchema(*args, **kwargs)[source]

Bases: BaseSchema

Schema for validating points.

Variables:

_geom_types (list) – List of allowed geometry types for the points, default is [shapely.Point]

class Config

Bases: Config

name = 'PointSchema'
transport_frames.criteria.grade_territory(frame: MultiDiGraph, gdf_poly: GeoDataFrame, include_priority: bool = True) → GeoDataFrame[source]

Grade territories based on proximity to key transport infrastructure.

This function evaluates territories by computing distances to major road networks (reg1, reg2), edges, and priority roads. The grading system assigns scores based on proximity thresholds.

Parameters:

  • frame (nx.MultiDiGraph) – The transport network graph containing road connections.

  • gdf_poly (gpd.GeoDataFrame) – A GeoDataFrame containing the polygons of the territories to be graded.

  • include_priority (bool, optional) – Whether to include priority road networks in the grading system (default: True).

Returns:

A GeoDataFrame containing the graded territories with an added ‘grade’ column.

Return type:

gpd.GeoDataFrame

transport_frames.criteria._grade_polygon(row: GeoDataFrame, include_priority: bool = True) → float[source]

Compute a grade for a territory based on its distances to transport infrastructure.

The grading system follows predefined thresholds for distances to key road networks and priority transport corridors.

Parameters:

  • row (gpd.GeoDataFrame) – A single row from the territory GeoDataFrame, containing distance metrics.

  • include_priority (bool, optional) – Whether to consider priority road networks in the grading system (default: True).

Returns:

The computed grade for the given territory.

Return type:

float

transport_frames.criteria.find_median(city_points: GeoDataFrame, adj_mx: DataFrame) → GeoDataFrame[source]

Compute the median travel time from each city to all other cities.

Parameters:

  • city_points (gpd.GeoDataFrame) – GeoDataFrame containing city locations.

  • adj_mx (pd.DataFrame) – Adjacency matrix representing pairwise travel times between cities.

Returns:

Updated city points with a ‘to_service’ column representing median travel times.

Return type:

gpd.GeoDataFrame

transport_frames.criteria.weight_territory(territories: GeoDataFrame, railway_stops: GeoDataFrame, bus_stops: GeoDataFrame, ferry_stops: GeoDataFrame, airports: GeoDataFrame, local_crs: int) → GeoDataFrame[source]

Assign weights to territories based on accessibility to key transport services.

This function calculates accessibility scores for each territory based on distances to railway stops, bus stops, ferry terminals, and airports. A weighted sum is computed using predefined importance coefficients.

Parameters:

  • territories (gpd.GeoDataFrame) – GeoDataFrame containing territory geometries.

  • railway_stops (gpd.GeoDataFrame) – GeoDataFrame of railway stops.

  • bus_stops (gpd.GeoDataFrame) – GeoDataFrame of bus stops.

  • ferry_stops (gpd.GeoDataFrame) – GeoDataFrame of ferry terminals.

  • airports (gpd.GeoDataFrame) – GeoDataFrame of airport locations.

  • local_crs (int) – Coordinate reference system to be used for spatial calculations.

Returns:

Territories GeoDataFrame with assigned accessibility weights.

Return type:

gpd.GeoDataFrame

transport_frames.criteria._get_nearest_distances(territories: GeoDataFrame, stops: GeoDataFrame, distance_col: str) → GeoDataFrame[source]

Compute the nearest distance between each territory and a set of transport stops.

Parameters:

  • territories (gpd.GeoDataFrame) – GeoDataFrame containing the territory geometries.

  • stops (gpd.GeoDataFrame) – GeoDataFrame containing the stop locations.

  • distance_col (str) – The name of the column where computed distances will be stored.

Returns:

Territories GeoDataFrame updated with nearest distances to stops.

Return type:

gpd.GeoDataFrame

transport_frames.criteria.calculate_quartiles(df: DataFrame, column: str) → Series[source]

Calculate quartile rankings for a given column in a DataFrame.

This function divides the values of the specified column into four quartiles and assigns ranks from 1 to 4, where 1 represents the lowest quartile and 4 represents the highest.

Parameters:

  • df (pd.DataFrame) – The DataFrame containing the column to be ranked.

  • column (str) – The name of the column for which quartiles should be calculated.

Returns:

A pandas Series with assigned quartile ranks (1 to 4) for each row.

Return type:

pd.Series

transport_frames.criteria.assign_grades(graded_territories: GeoDataFrame, accessibility_data: GeoDataFrame, local_crs: int) → GeoDataFrame[source]

Assign accessibility-based grades to territories.

This function assigns grades based on quartile rankings of car and public transport accessibility within the dataset.

Parameters:

  • graded_territories (gpd.GeoDataFrame) – GeoDataFrame containing already graded territories.

  • accessibility_data (gpd.GeoDataFrame) – GeoDataFrame with accessibility metrics.

  • local_crs (int) – Coordinate reference system for spatial consistency.

Returns:

Updated territories with assigned transport accessibility grades.

Return type:

gpd.GeoDataFrame

transport_frames.criteria.get_criteria(graded_terr: GeoDataFrame, points: GeoDataFrame, polygons: GeoDataFrame, drive_graph: MultiDiGraph | None = None, PT_graph: MultiDiGraph | None = None, r_stops: GeoDataFrame | None = None, b_stops: GeoDataFrame | None = None, ferry: GeoDataFrame | None = None, aero: GeoDataFrame | None = None, adj_mx_drive: DataFrame | None = None, adj_mx_PT: DataFrame | None = None, local_crs: int = 3857) → GeoDataFrame[source]

Compute criteria scores for graded territories based on transport accessibility.

This function evaluates the connectivity and accessibility of territories by calculating travel times, distance-based weights, and spatial join operations.

Parameters:

  • graded_terr (gpd.GeoDataFrame) – GeoDataFrame of graded territories.

  • points (gpd.GeoDataFrame) – GeoDataFrame of city and settlement points.

  • polygons (gpd.GeoDataFrame) – GeoDataFrame containing area boundaries for spatial joins.

  • drive_graph (nx.MultiDiGraph, optional) – MultiDiGraph representing the drive network.

  • PT_graph (nx.MultiDiGraph, optional) – MultiDiGraph representing the public transport network.

  • r_stops (gpd.GeoDataFrame, optional) – GeoDataFrame of railway stops.

  • b_stops (gpd.GeoDataFrame, optional) – GeoDataFrame of bus stops.

  • ferry (gpd.GeoDataFrame, optional) – GeoDataFrame of ferry stops.

  • aero (gpd.GeoDataFrame, optional) – GeoDataFrame of airports.

  • adj_mx_drive (pd.DataFrame, optional) – Adjacency matrix for road travel.

  • adj_mx_PT (pd.DataFrame, optional) – Adjacency matrix for public transport.

  • local_crs (int, optional) – Coordinate reference system for spatial calculations (default: 3857).

Returns:

GeoDataFrame containing computed transport criteria scores for each territory.

Return type:

gpd.GeoDataFrame

transport_frames.criteria.interpret_gdf(gdf: GeoDataFrame)[source]

Interprets geographic accessibility data for each criterion in the criteria DataFrame.

This method iterates through the criteria DataFrame, extracts relevant weights and quartiles for each criterion, and generates an interpretation of the accessibility based on transport services availability and accessibility quartiles.

Parameters:

  • gdf (gpd.GeoDataGrame) – gdf with pre-calculated criteria

  • Returns –

  • -------- –

    list: A list of tuples, each containing the name of the criterion and its corresponding

    interpretation as a list of strings.

transport_frames.criteria.interpretation(grade: int, weight_r_stops: float, weight_b_stops: float, weight_ferry: float, weight_aero: float, car_access_quartile: int, public_access_quartile: int) → list[source]

Generate a textual interpretation of an area’s transport accessibility.

This function evaluates an area’s accessibility by analyzing transport services (rail stops, bus stops, ferry services, and airports) and accessibility quartiles (for car and public transport). The result is a structured textual interpretation.

Parameters:

  • grade (int) – The grade of the area, representing its general transport accessibility.

  • weight_r_stops (float) – Weight indicating the presence of railway stations.

  • weight_b_stops (float) – Weight indicating the presence of bus stops.

  • weight_ferry (float) – Weight indicating the presence of ferry terminals.

  • weight_aero (float) – Weight indicating the presence of airports.

  • car_access_quartile (int) – Quartile score for car access (0-4), where 0 indicates the worst access and 4 the best.

  • public_access_quartile (int) – Quartile score for public transport access (0-4), where 0 indicates the worst access and 4 the best.

Returns:

A list of strings providing an interpretation of the area’s transport accessibility based on its grade, service availability, and quartile scores.

Return type:

list