popframe.models.region

Classes

Region(region, districts, settlements, ...)

A class representing a geographical region that includes districts, settlements, towns, and optionally territories.

class popframe.models.region.Region(region: GeoDataFrame, districts: GeoDataFrame, settlements: GeoDataFrame, towns: GeoDataFrame, accessibility_matrix: DataFrame, territories: GeoDataFrame | None = None)[source]

Bases: object

A class representing a geographical region that includes districts, settlements, towns, and optionally territories. Provides methods for validating and visualizing spatial data, as well as for calculating accessibility between towns.

Attributes

crspyproj.CRS: Coordinate Reference System of the region.
regiongpd.GeoDataFrame: GeoDataFrame representing the boundaries of the region.
districtsgpd.GeoDataFrame: GeoDataFrame containing information about districts.
settlementsgpd.GeoDataFrame: GeoDataFrame containing information about settlements.
_townsdict: Dictionary containing Town objects indexed by their IDs.
accessibility_matrixpd.DataFrame: DataFrame containing accessibility data between towns.
_territoriesdict: Dictionary containing Territory objects indexed by their IDs (optional).

Methods

validate_districts(gdf: gpd.GeoDataFrame) -> gpd.GeoDataFrame: Validates the structure and content of a districts GeoDataFrame.
validate_settlements(gdf: gpd.GeoDataFrame) -> gpd.GeoDataFrame: Validates the structure and content of a settlements GeoDataFrame.
validate_towns(gdf: gpd.GeoDataFrame) -> gpd.GeoDataFrame: Validates the structure and content of a towns GeoDataFrame.
validate_region(gdf: gpd.GeoDataFrame) -> gpd.GeoDataFrame: Validates the structure and content of a region GeoDataFrame.
validate_accessibility_matrix(df: pd.DataFrame) -> pd.DataFrame: Validates the structure and content of the accessibility matrix.
plot(figsize=(15, 15)): Visualizes the region, including districts, settlements, towns, and optionally territories.
get_territory(territory_id: int) -> Territory: Retrieves a territory by its ID.
towns() -> list[Town]: Returns a list of all towns in the region.
territories() -> list[Territory]: Returns a list of all territories in the region.
geometry() -> shapely.Polygon | shapely.MultiPolygon: Returns the unified geometry of all districts in the region.
get_territories_gdf() -> gpd.GeoDataFrame: Returns a GeoDataFrame representing all territories in the region.
get_towns_gdf() -> gpd.GeoDataFrame: Returns a GeoDataFrame representing all towns in the region.
__getitem__(arg): Overloads the subscript operator to access a town or accessibility data based on the argument type.
from_pickle(file_path: str) -> Region: Loads a Region object from a .pickle file.
to_pickle(file_path: str): Saves the Region object to a .pickle file.

static validate_districts(gdf: GeoDataFrame) → GeoDataFrame[source]

Validates the districts GeoDataFrame to ensure it has the correct structure and data types.

Parameters

gdfgpd.GeoDataFrame: The GeoDataFrame containing district data.

Returns

gpd.GeoDataFrame: Validated GeoDataFrame with ‘geometry’ and ‘name’ columns.

Raises

AssertionError: If the GeoDataFrame is not of the expected format or types.

static validate_settlements(gdf: GeoDataFrame) → GeoDataFrame[source]: Validates the settlements GeoDataFrame to ensure it has the correct structure and data types.

static validate_towns(gdf: GeoDataFrame) → GeoDataFrame[source]: Validates the towns GeoDataFrame.

static validate_region(gdf: GeoDataFrame) → GeoDataFrame[source]: Validates the region GeoDataFrame to ensure it has the correct structure and data types.

static validate_accessibility_matrix(df: DataFrame) → DataFrame[source]: Validates the accessibility matrix, ensuring it has non-negative float values and matching row and column indices.

plot(figsize=(15, 15))[source]

Plots the region, including districts, settlements, towns, and optionally territories, on a map.

Parameters

figsizetuple, optional: The size of the plot (default is (15, 15)).

get_territory(territory_id: int)[source]

Retrieves a specific territory by its ID.

Parameters

territory_idint: The ID of the territory.

Returns

Territory: The requested territory.

Raises

KeyError: If the territory with the given ID is not found.

property towns: list[popframe.models.town.Town]

Returns a list of all towns in the region.

Returns

list[Town]: List of Town objects.

property territories: list[popframe.models.territory.Territory]

Returns a list of all territories in the region.

Returns

list[Territory]: List of Territory objects.

property geometry: Polygon | MultiPolygon

4326).

Returns

shapely.Polygon or shapely.MultiPolygon: The unified geometry of the region.

type:: Returns the unified geometry of all districts in the region, transformed to the WGS84 CRS (EPSG

get_territories_gdf() → GeoDataFrame[source]

Returns a GeoDataFrame representing all territories in the region.

Returns

gpd.GeoDataFrame: GeoDataFrame with territory data.

get_towns_gdf() → GeoDataFrame[source]

Returns a GeoDataFrame representing all towns in the region, including their relationships with settlements and districts.

Returns

gpd.GeoDataFrame: GeoDataFrame with town data.

__getitem__(arg)[source]

__getitem__(town_id: int)

__getitem__(towns: tuple)

Overloaded subscript operator to access a town or accessibility data based on the argument type.

Parameters

argint or tuple: Integer to access a town by its ID, or tuple to retrieve accessibility data between two towns.

Raises

NotImplementedError: If the argument type is unsupported.

static from_pickle(file_path: str)[source]

Load a Region object from a .pickle file.

Parameters

file_pathstr: Path to the .pickle file.

Returns

Region: The loaded Region object.

to_pickle(file_path: str)[source]

Save the Region object to a .pickle file.

Parameters

file_pathstr: Path to the .pickle file.