blocksnet.method.provision

Service type provisions assessment module.

Classes

`Provision`(*, city_model[, verbose])	Class for assessing provision of services to urban areas.
`ProvisionMethod`(value)	Enum for different methods of service provision assessment.

class blocksnet.method.provision.ProvisionMethod(value)[source]

Bases: Enum

Enum for different methods of service provision assessment.

Variables:

GREEDY (str) – Greedy method for service provision.
GRAVITATIONAL (str) – Linear method for service provision, where distances are taken into account as squares.
LINEAR (str) – Linear method for service provision, where distances are taken into account linearly.

GREEDY = 'greedy'

GRAVITATIONAL = 'gravitational'

LINEAR = 'linear'

class blocksnet.method.provision.Provision(*, city_model: City, verbose: bool = True)[source]

Bases: BaseMethod

Class for assessing provision of services to urban areas.

This class provides various methods to evaluate the provision of services such as healthcare, education, etc., for a given city model. The provision can be assessed using multiple methods like gravitational models, greedy allocation, and linear programming-based transportation problem solutions.

plot(gdf: gpd.GeoDataFrame, linewidth: float = 0.1, figsize: tuple[int, int] = (10, 10)) → None[source]: Visualizes provision assessment results for a given GeoDataFrame.

stat(gdf: gpd.GeoDataFrame) → dict[str, float][source]: Computes basic statistics of provision (mean, median, min, max) from a GeoDataFrame.

total(gdf: gpd.GeoDataFrame) → float[source]: Calculates the total provision ratio from the given GeoDataFrame.

get_bounds(service_type: ServiceType | str, update_df: pd.DataFrame = None) → tuple[float, float][source]: Returns the lower and upper bounds of provision for a given service type.

calculate(service_type: ServiceType | str, update_df: pd.DataFrame | None = None, method: ProvisionMethod = ProvisionMethod.GRAVITATIONAL, self_supply: bool = False) → gpd.GeoDataFrame[source]: Performs provision assessment for a specified service type and method.

plot(gdf: GeoDataFrame, linewidth: float = 0.1, figsize: tuple[int, int] = (10, 10))[source]

Visualizes provision assessment results for a given GeoDataFrame.

Parameters:

gdf (geopandas.GeoDataFrame) – GeoDataFrame containing spatial data with provision assessment results.
linewidth (float) – Size of polygons’ borders, by default 0.1.
figsize (tuple of int, optional) – Size of the plot in inches, by default (10, 10).

Return type:

None

_get_blocks_gdf(service_type: ServiceType, update_df: DataFrame | None = None) → GeoDataFrame[source]

Generates a GeoDataFrame of city blocks with updated service capacities and demands.

Parameters:

service_type (ServiceType) – The service type for which provision assessment is being calculated.
update_df (pandas.DataFrame, optional) – DataFrame containing updates to population or capacity, by default None.

Returns:

GeoDataFrame containing the geometry, demand, and capacity for each block.

Return type:

geopandas.GeoDataFrame

classmethod stat(gdf: GeoDataFrame) → dict[str, float][source]

Computes basic statistics of provision (mean, median, min, max) from a GeoDataFrame.

Parameters:: gdf (geopandas.GeoDataFrame) – GeoDataFrame containing provision data.
Returns:: Dictionary with keys ‘mean’, ‘median’, ‘min’, and ‘max’ representing provision statistics.
Return type:: dict

classmethod total(gdf: GeoDataFrame) → float[source]

Calculates the total provision by dividing the sum of met demand by the total demand for all blocks in the GeoDataFrame.

Parameters:: gdf (geopandas.GeoDataFrame) – GeoDataFrame containing the columns ‘demand_within’ and ‘demand’, representing the met demand and total demand for each block.
Returns:: The ratio of total met demand to total demand, representing overall provision.
Return type:: float

static _get_lower_bound(gdf: GeoDataFrame) → float[source]

Calculates the lower bound of provision, assuming each block meets its demand up to its capacity.

Parameters:: gdf (geopandas.GeoDataFrame) – GeoDataFrame containing ‘capacity’ and ‘demand’ columns.
Returns:: The lower bound of provision as the ratio of the total met demand (limited by capacity) to the total demand.
Return type:: float

static _get_upper_bound(gdf: GeoDataFrame) → float[source]

Calculates the upper bound of provision, assuming total capacity can be fully allocated to meet total demand.

Parameters:: gdf (geopandas.GeoDataFrame) – GeoDataFrame containing ‘capacity’ and ‘demand’ columns.
Returns:: The upper bound of provision, calculated as the minimum of the total capacity-to-demand ratio or 1 (full provision).
Return type:: float

get_bounds(service_type: ServiceType | str, update_df: DataFrame | None = None) → tuple[float, float][source]

Returns the lower and upper bounds of provision for a given service type.

Parameters:

service_type (ServiceType or str) – The service type for which provision bounds are calculated.
update_df (pandas.DataFrame, optional) – DataFrame containing updates to population or capacity, by default None.

Returns:

A tuple (lower_bound, upper_bound) representing the lower and upper bounds of provision.

Return type:

tuple of float

calculate(service_type: ServiceType | str, update_df: DataFrame | None = None, method: ProvisionMethod = ProvisionMethod.GRAVITATIONAL, self_supply: bool = False) → GeoDataFrame[source]

Performs provision assessment for a specified service type and method.

Parameters:

service_type (ServiceType or str) – The type of service for which the provision is calculated.
update_df (pandas.DataFrame, optional) – Updated DataFrame for blocks (demand or capacity changes), by default None.
method (ProvisionMethod, optional) – The provision method to be used (GRAVITATIONAL by default).
self_supply (bool, optional) – If True, blocks are allowed to meet their own demand directly using their own capacity, by default False.

Returns:

GeoDataFrame with provision data, including ‘demand_within’, ‘demand_left’, ‘capacity_left’, and ‘provision’.

Return type:

geopandas.GeoDataFrame

_lp_provision(gdf: GeoDataFrame, service_type: ServiceType, method: ProvisionMethod, selection_range: float | None = None) → GeoDataFrame[source]

Solves the provision problem using a Linear Programming (LP) solver. Loops itself till capacity or demand left meet 0.

Parameters:

gdf (geopandas.GeoDataFrame) – GeoDataFrame containing blocks with demand and capacity.
service_type (ServiceType) – The type of service for which provision is being calculated.
method (ProvisionMethod) – The method used to calculate provision (LINEAR or GRAVITATIONAL).
selection_range (float | None) – The accessibility range defining maximum distance between living blocks and service blocks in the current problem loop, default None (actually service type accessibility).

Returns:

Updated GeoDataFrame with provision results, including updates to ‘demand_within’, ‘demand_without’, ‘demand_left’, and ‘capacity_left’.

Return type:

geopandas.GeoDataFrame

_greedy_provision(gdf: GeoDataFrame, service_type: ServiceType) → GeoDataFrame[source]

Iteratively assigns demand to the closest available capacity using a greedy method.

Parameters:

gdf (geopandas.GeoDataFrame) – GeoDataFrame containing blocks with demand and capacity.
service_type (ServiceType) – The type of service for which provision is being calculated.

Returns:

Updated GeoDataFrame with provision results, including updates to ‘demand_within’, ‘demand_without’, ‘demand_left’, and ‘capacity_left’.

Return type:

geopandas.GeoDataFrame

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.