blocksnet.models.city

Classes

`Block`(*, id, geometry[, land_use, ...])	Represents a city block.
`BlockService`(*, service_type, capacity, ...)	Service within a block taking some of a block's site area.
`Building`(*, id, block[, services])	Represents a building within a block.
`BuildingService`(*, service_type, capacity, ...)	Service within a building.
`City`(blocks, acc_mx)	Represents a block-network city information model that manages blocks, buildings, services, and their relationships.
`Service`(*, service_type, capacity, area, ...)	Abstract base class for services.

class blocksnet.models.city.Service(*, service_type: ServiceType, capacity: int, area: float, is_integrated: bool)[source]

Bases: ABC, BaseModel

Abstract base class for services.

Parameters:

service_type (ServiceType) – Type of the service.
capacity (int, optional) – Capacity of the service, must be greater than 0.
area (float, optional) – Service area in square meters, must be greater than 0.
is_integrated (bool) – Whether the service is integrated within a living building.

service_type: ServiceType

capacity: int

area: float

is_integrated: bool

classmethod _get_min_brick(service_type: ServiceType, is_integrated: bool, field: Literal['area', 'capacity'], value: float) → ServiceBrick[source]

Get the minimum service brick based on the service type and integration status.

Parameters:

service_type (ServiceType) – Type of the service.
is_integrated (bool) – Whether the service is integrated within a living building.
field (Literal["area", "capacity"]) – Field to compare, either “area” or “capacity”.
value (float) – Value to compare against.

Returns:

The brick with the minimum difference in the specified field value.

Return type:

Brick

classmethod _fill_capacity_and_area(data: dict) → dict[source]

Fill the capacity and area fields in the data dictionary.

Parameters:: data (dict) – Dictionary containing service data.
Returns:: Updated dictionary with filled capacity and area fields.
Return type:: dict

to_dict() → dict[source]

Convert the service to a dictionary representation.

Returns:: Dictionary containing service data.
Return type:: dict

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

class blocksnet.models.city.BlockService(*, service_type: ServiceType, capacity: int, area: float, is_integrated: bool)[source]

Bases: Service

Service within a block taking some of a block’s site area.

Parameters:

block (Block) – The block containing the service.
geometry (Union[Point, Polygon, MultiPolygon]) – Geometry representing the service location.

block: Block

geometry: Point | Polygon | MultiPolygon

classmethod validate_model(data: dict) → dict[source]

Validate and process the model data before initialization to make sure capacities and areas are filled.

Parameters:: data (dict) – Data dictionary containing service information.
Returns:: Validated and processed data dictionary.
Return type:: dict

to_dict() → dict[source]

Convert the block service to a dictionary representation.

Returns:: Dictionary containing block service data.
Return type:: dict

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

class blocksnet.models.city.BuildingService(*, service_type: ServiceType, capacity: int, area: float, is_integrated: bool)[source]

Bases: Service

Service within a building.

Parameters:

building (Building) – The building containing the service.
geometry (Point) – Point geometry representing the service location.

building: Building

geometry: Point

classmethod validate_model(data: dict) → dict[source]

Validate and process the model data before initialization to figure out integration status and fill capacity and area if needed.

Parameters:: data (dict) – Data dictionary containing service information.
Returns:: Validated and processed data dictionary.
Return type:: dict

classmethod attach_geometry(self) → BuildingService[source]

Attach geometry of the service to the building representative point after initialization.

Parameters:: self (BuildingService) – Instance of the building service.
Returns:: The building service instance with attached geometry.
Return type:: BuildingService

to_dict() → dict[source]

Convert the building service to a dictionary representation.

Returns:: Dictionary containing building service data.
Return type:: dict

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

class blocksnet.models.city.Building(**data: Any)[source]

Bases: BaseModel

Represents a building within a block.

Parameters:

id (int) – Unique identifier across the whole city information model.
block (Block) – Parent block containing the building.
services (list of BuildingService, optional) – List of services inside the building.
geometry (Union[Polygon, MultiPolygon]) – Geometry representing the building.
build_floor_area (float) – Total area of the building in square meters. Must be equal or greater than 0.
living_area (float) – Building’s area dedicated for living in square meters. Must be equal or greater than 0.
non_living_area (float) – Building’s area dedicated for non-living activities in square meters. Must be equal or greater than 0.
footprint_area (float) – Building’s ground floor area in square meters. Must be equal or greater than 0.
number_of_floors (int) – Number of floors (storeys) in the building. Must be equal or greater than 1.
population (int) – Total population of the building. Must be equal or greater than 0.

id: int

block: Block

services: list[BuildingService]

geometry: Polygon | MultiPolygon

build_floor_area: float

living_area: float

non_living_area: float

footprint_area: float

number_of_floors: int

population: int

classmethod validate_model(data: dict) → dict[source]

Validate and process the model data before initialization to fill needed empty fields.

Parameters:: data (dict) – Data dictionary containing building information.
Returns:: Validated and processed data dictionary.
Return type:: dict

property is_living: bool: Indicates if the building is residential.

update_services(service_type: ServiceType, gdf: GeoDataFrame | None = None) → None[source]

Update services of the building.

Parameters:

service_type (ServiceType) – The type of service to be updated.
gdf (GeoDataFrame, optional) – A GeoDataFrame containing service data. If not provided, services of specified type will be removed from the building.

to_dict() → dict[source]

Convert the building object to a dictionary.

Returns:: A dictionary representation of the building.
Return type:: dict

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

class blocksnet.models.city.Block(**data: Any)[source]

Bases: BaseModel

Represents a city block.

Parameters:

id (int) – Unique block identifier across the whole city model.
geometry (Polygon) – Geometry representing the city block.
land_use (LandUse, optional) – Current city block land use.
buildings (list of Building, optional) – List of buildings inside the block.
services (list of BlockService, optional) – Services that occupy some area of the block.
city (City) – Parent city instance that contains the block.

id: int

geometry: Polygon

land_use: LandUse | None

buildings: list[Building]

services: list[BlockService]

city: City

static validate_land_use(land_use: str | LandUse | None) → LandUse | None[source]

Validate and transform the land use value.

Parameters:: land_use (str or LandUse) – The land use value to validate.
Returns:: The validated land use.
Return type:: LandUse or None

property all_services: list[blocksnet.models.city.Service]

Get all services in the block, including those in buildings.

Returns:: List of all services in the block.
Return type:: list of Service

property site_area: float

Calculate the block area in square meters.

Returns:: Block area in square meters.
Return type:: float

property population: int

Calculate the total population of the block.

Returns:: Total population of the block.
Return type:: int

property footprint_area: float

Calculate the total footprint area of the buildings in the block.

Returns:: Total footprint area of the buildings in square meters.
Return type:: float

property build_floor_area: float

Calculate the total build floor area of the buildings in the block.

Returns:: Total build floor area of the buildings in square meters.
Return type:: float

property living_area: float

Calculate the total living area of the buildings in the block.

Returns:: Total living area of the buildings in square meters.
Return type:: float

property non_living_area: float

Calculate the total non-living area of the buildings in the block.

Returns:: Total non-living area of the buildings in square meters.
Return type:: float

property is_living: bool

Check if the block contains any living building and thus can be stated as living.

Returns:: True if there is at least one living building, False otherwise.
Return type:: bool

property living_demand: float | None

Calculate the square meters of living area per person.

Returns:: Living area per person in square meters, or None if the population is 0.
Return type:: float or None

property fsi: float

Calculate the Floor Space Index (FSI).

Returns:: FSI, which is the build floor area per site area.
Return type:: float

property gsi: float

Calculate the Ground Space Index (GSI).

Returns:: GSI, which is the footprint area per site area.
Return type:: float

property mxi: float | None

Calculate the Mixed Use Index (MXI).

Returns:: MXI, which is the living area per build floor area, or None if the build floor area is 0.
Return type:: float or None

property l: float | None

Calculate the mean number of floors.

Returns:: Mean number of floors, or None if the GSI is 0.
Return type:: float or None

property osr: float | None

Calculate the Open Space Ratio (OSR).

Returns:: OSR, or None if the FSI is 0.
Return type:: float or None

property share_living: float | None

Calculate the share of living area, which is living area per footprint area.

Returns:: Share of living area, or None if the footprint area is 0.
Return type:: float or None

property business_area: float

Calculate the business area in the block, which is total business area of buildings inside the block.

Returns:: Business area in square meters.
Return type:: float

property share_business: float | None

Calculate the share of business area, which is business area per footprint area.

Returns:: Share of business area, or None if the footprint area is zero.
Return type:: float or None

property buildings_indicators: dict

Get indicators related to buildings in the block.

Returns:: Dictionary containing various building indicators.
Return type:: dict

property territory_indicators: dict

Get indicators related to the territory of the block.

Returns:: Dictionary containing various territory indicators.
Return type:: dict

property services_indicators: dict

Get indicators related to services in the block.

Returns:: Dictionary containing service capacities by type.
Return type:: dict

property land_use_service_types: list[blocksnet.models.service_type.ServiceType]

Get the service types allowed by the land use of the block.

Returns:: List of service types allowed by the land use.
Return type:: list of ServiceType

get_services_gdf() → GeoDataFrame[source]

Generate a GeoDataFrame of services in the block.

Returns:: GeoDataFrame containing services data.
Return type:: gpd.GeoDataFrame

get_buildings_gdf() → GeoDataFrame[source]

Generate a GeoDataFrame of buildings in the block.

Returns:: GeoDataFrame containing buildings data.
Return type:: gpd.GeoDataFrame

to_dict(simplify=False) → dict[source]

Convert the block to a dictionary representation.

Parameters:: simplify (bool, optional) – If True, exclude service indicators from the dictionary. Default is False.
Returns:: Dictionary representation of the block.
Return type:: dict

update_buildings(gdf: GeoDataFrame | None = None)[source]

Update the buildings within the block.

Parameters:: gdf (gpd.GeoDataFrame, optional) – GeoDataFrame containing building data. If None, clear the list of buildings.

update_services(service_type: ServiceType, gdf: GeoDataFrame | None = None)[source]

Update the services within the block.

Parameters:

service_type (ServiceType) – The type of service to update.
gdf (gpd.GeoDataFrame, optional) – GeoDataFrame containing service data. If None, remove all services of the given type.

classmethod from_gdf(gdf: GeoDataFrame, city: City) → dict[int, blocksnet.models.city.Block][source]

Generate a dictionary of blocks from a GeoDataFrame. Must contain following columns: - index : int - geometry : Polygon - land_use : LandUse or str

For more specified information, please, check the Block class.

Parameters:

gdf (gpd.GeoDataFrame) – GeoDataFrame containing block data.
city (City) – City instance containing the blocks.

Returns:

dict of int – Dictionary mapping block IDs to Block instances.

Return type:

Block

__getitem__(arg)[source]

__getitem__(building_id: int) → Building

Access a building information or instance by a specified argument.

Parameters:: arg (Any) – Argument to access the building.
Raises:: NotImplementedError – If the argument type is not supported.

_(building_id: int) → Building[source]

Access a building within the block by its ID. For example:

>>> block = city[456]
>>> block[123]
Building(id=123, block_id=456, ...)

Parameters:: building_id (int) – ID of the building to access.
Returns:: The building with the specified ID.
Return type:: Building
Raises:: KeyError – If no building with the specified ID is found.

__hash__()[source]

Compute the hash value for the block.

Returns:: Hash value of the block.
Return type:: int

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

class blocksnet.models.city.City(blocks: GeoDataFrame, acc_mx: DataFrame)[source]

Bases: object

Represents a block-network city information model that manages blocks, buildings, services, and their relationships.

Variables:

crs (pyproj.CRS) – Coordinate Reference System (CRS) used by the city model.
accessibility_matrix (pd.DataFrame) – Accessibility matrix representing relationships between city blocks (travel time in minutes by drive, walk, intermodal or another type of city graph).
_blocks (dict[int, Block]) – Dictionary mapping block IDs to Block objects.
_service_types (dict[str, ServiceType]) – Dictionary mapping service type names to ServiceType objects.

plot(figsize: tuple = (15, 15), linewidth: float = 0.1, max_travel_time: float = 15)[source]: Plot the city model, displaying blocks, land use, buildings, and services.

get_land_use_service_types(land_use: LandUse | None)[source]: Retrieve service types allowed by a specific land use.

get_buildings_gdf() → gpd.GeoDataFrame | None[source]: Return a GeoDataFrame of all buildings in the city model.

get_services_gdf() → gpd.GeoDataFrame[source]: Return a GeoDataFrame of all services in the city model.

get_blocks_gdf(simplify=False) → gpd.GeoDataFrame[source]: Return a GeoDataFrame of all blocks in the city model.

update_land_use(gdf: gpd.GeoDataFrame) → None[source]: Update land use of blocks based on a GeoDataFrame.

update_buildings(gdf: gpd.GeoDataFrame) → None[source]: Update buildings in the city model based on a GeoDataFrame.

update_services(service_type: ServiceType | str, gdf: gpd.GeoDataFrame) → None[source]: Update services of a specified type in the city model based on a GeoDataFrame.

add_service_type(service_type: ServiceType) → None[source]: Add a new service type to the city model.

get_distance(block_a: int | Block, block_b: int | Block) → float[source]: Get the distance (travel time) between two blocks.

get_out_edges(block: int | Block)[source]: Get outgoing edges (connections) for a given block.

get_in_edges(block: int | Block)[source]: Get incoming edges (connections) for a given block.

property epsg: int

Property to retrieve the EPSG code of the city model’s CRS.

Returns:: EPSG code of the CRS.
Return type:: int

property blocks: list[blocksnet.models.city.Block]

Return a list of all blocks in the city model.

Returns:: List of Block objects representing the city blocks.
Return type:: list[Block]

property service_types: list[blocksnet.models.service_type.ServiceType]

Return a list of all service types available in the city model.

Returns:: List of ServiceType objects representing different service types.
Return type:: list[ServiceType]

property buildings: list[blocksnet.models.city.Building]

Return a list of all buildings in the city model.

Returns:: List of Building objects representing all buildings in the city.
Return type:: list[Building]

property services: list[blocksnet.models.city.Service]

Return a list of all services in the city model.

Returns:: List of Service objects representing all services available in the city.
Return type:: list[Service]

property loaded_service_types: list[blocksnet.models.service_type.ServiceType]

Return list of service types loaded in the model.

Returns:: List of ServiceTypes existing in the city model.
Return type:: list[ServiceType]

plot(figsize: tuple[float, float] = (15, 15), linewidth: float = 0.1, max_travel_time: float = 15) → None[source]

Plot the city model data including blocks, land use, buildings, and services.

Parameters:

figsize (tuple[float, float], optional) – Size of the plot to be displayed. Default is (15,15).
linewidth (float, optional) – Line width of polygon objects to be displayed. Default is 0.1.
max_travel_time (float, optional) – Max edge weight to be displayed on the plot (in min). Default is 15.

get_land_use_service_types(land_use: LandUse | None) → list[blocksnet.models.service_type.ServiceType][source]

Retrieve service types allowed by a specific land use.

Parameters:: land_use (LandUse | None) – Land use type to filter service types by.
Returns:: List of ServiceType objects associated with the specified land use.
Return type:: list[ServiceType]

get_buildings_gdf() → GeoDataFrame[source]

Return a GeoDataFrame of all buildings in the city model.

Returns:: GeoDataFrame containing all buildings’ geometries and attributes.
Return type:: gpd.GeoDataFrame

get_services_gdf() → GeoDataFrame[source]

Return a GeoDataFrame of all services in the city model.

Returns:: GeoDataFrame containing all services’ geometries and attributes.
Return type:: gpd.GeoDataFrame

get_blocks_gdf(simplify=False) → GeoDataFrame[source]

Return a GeoDataFrame of all blocks in the city model.

Parameters:: simplify (bool, optional) – Whether to simplify block parameters (default is False). If True, services information will not be provided.
Returns:: GeoDataFrame containing all blocks’ geometries and attributes.
Return type:: gpd.GeoDataFrame

update_land_use(gdf: GeoDataFrame) → None[source]

Update land use information for blocks based on a GeoDataFrame.

Parameters:: gdf (gpd.GeoDataFrame) – GeoDataFrame containing updated land use information. It should have the same CRS as the city model, and its index should match the IDs of blocks in the city model. It should have land_use column with value either LandUse, str or None.
Raises:: AssertionError – If the CRS of gdf does not match the city model’s CRS, or if the index of gdf does not match block IDs, or if the length of gdf does not match the number of blocks in the city model.

update_buildings(gdf: GeoDataFrame) → GeoDataFrame[source]

Update buildings information for blocks based on a GeoDataFrame.

Parameters:

gdf (gpd.GeoDataFrame) –

GeoDataFrame containing updated buildings information. It should have the same CRS as the city model. It must contain the following columns:

index : int - unique building id
geometry : Polygon | MultiPolygon
build_floor_area : float >= 0
living_area : float >= 0
non_living_area : float >= 0
footprint_area : float >= 0
number_of_floors : int >= 1
population : int >= 0

Please, do not specify building_id nor block_id columns, as they are used in the method. For more specific information, please, check Building class.

Returns:

GeoDataFrame buildings that did not intersect any block.

Return type:

gpd.GeoDataFrame

Raises:

AssertionError – If the CRS of gdf does not match the city model’s CRS.

update_services(service_type: ServiceType | str, gdf: GeoDataFrame) → None[source]

Update services information for blocks and buildings based on a GeoDataFrame. Based on intersections with city buildings, service may be either BuldingService or BlockService. Please, make sure, that block services (for example, pitch or playground) do not intersect any buildings!

Parameters:

service_type (ServiceType | str) – ServiceType object or name of the service type to update.
gdf (gpd.GeoDataFrame) –
GeoDataFrame containing updated services information. It should have the same CRS as the city model. It must contain the following columns:
- index : int
- geometry : Polygon | MultiPolygon | Point
- capacity : int (optional)
- area : int (optional)
For more specified information, please, check Service class.

Raises:

AssertionError – If the CRS of gdf does not match the city model’s CRS.

add_service_type(service_type: ServiceType) → None[source]

Add a new service type to the city model.

Parameters:: service_type (ServiceType) – ServiceType object to be added.
Raises:: KeyError – If a service type with the same name already exists in the city model.

get_distance(block_a: int | Block, block_b: int | Block) → float[source]

Get the distance (in minutes) between two blocks.

Parameters:

block_a (int | Block) – ID or Block object representing the first block.
block_b (int | Block) – ID or Block object representing the second block.

Returns:

Distance in minutes between the two blocks.

Return type:

float

get_out_edges(block: int | Block) → list[blocksnet.models.city.Block, blocksnet.models.city.Block, float][source]

Get outgoing edges for a specific block.

Parameters:: block (int | Block) – ID or Block object for which outgoing edges are requested.
Returns:: List of tuples representing outgoing edges with weights between blocks.
Return type:: list[(Block, Block, float)]

get_in_edges(block: int | Block) → list[blocksnet.models.city.Block, blocksnet.models.city.Block, float][source]

Get incoming edges for a specific block.

Parameters:: block (int | Block) – ID or Block object for which incoming edges are requested.
Returns:: List of tuples representing incoming edges with weights between blocks.
Return type:: list[(Block, Block, float)]

_(service_type_name: str) → bool[source]

Check if a service type exists in the city model. For example:

>>> 'school' in city
True
>>> 'computer_club' in city
False

Parameters:: service_type_name (str) – Name of the service type to check.
Returns:: True if the service type exists in the city model, False otherwise.
Return type:: bool

__str__() → str[source]

Return a string representation of the city model.

Returns:: String describing the city model, including CRS, number of blocks, service types, buildings, and services.
Return type:: str

static from_pickle(file_path: str)[source]

Load a city model from a .pickle file.

Parameters:: file_path (str) – Path to the .pickle file containing the city model.
Returns:: The loaded City object from the .pickle file.
Return type:: City

to_pickle(file_path: str)[source]

Save the city model to a .pickle file.

Parameters:: file_path (str) – Path to the .pickle file where the city model will be saved.