Reference

class exposurelib.AbstractExposure[source]

Bases: AbstractDatabase, ABC

The AbstractExposure class contains all functions and properties that are common to the derived exposure classes SpatiaLiteExposure and PostGISExposure.

__init__()[source]: Constructor for the AbstractExposure class. This function only calls the constructor of the parent class.

aggregate(min_number_buildings: int = 5, min_zoom_level: int = 15, batch_size: int = 1000)[source]

Aggregates entities with fewer buildings in their assets than min_number_buildings into parent entities and deletes their child (and grandchild) entities and assets. The aggregation process stops at min_zoom_level even if entities exist that contain fewer buildings than min_number_buildings.

Parameters:

(int (batch_size) – 5): Minimum number of buildings below which an entity gets aggregated with its neighbors into a parent tile entity.
optional – 5): Minimum number of buildings below which an entity gets aggregated with its neighbors into a parent tile entity.
default – 5): Minimum number of buildings below which an entity gets aggregated with its neighbors into a parent tile entity.
(int – 15): Minimum zoom level to be reached in the aggregation process. At this zoom level no further aggregation will take place even if an entity contains fewer buildings than min_number_buildings.
optional – 15): Minimum zoom level to be reached in the aggregation process. At this zoom level no further aggregation will take place even if an entity contains fewer buildings than min_number_buildings.
default – 15): Minimum zoom level to be reached in the aggregation process. At this zoom level no further aggregation will take place even if an entity contains fewer buildings than min_number_buildings.
(int – 1000): The number of features that should be processed at once.
optional – 1000): The number of features that should be processed at once.
default – 1000): The number of features that should be processed at once.

aggregate_on_boundaries(source_database: AbstractExposure, boundaries: dict, batch_size: int = 1000, entities_batch_size: int = 50000)[source]

Exports exposure data based on input WKT geometries. Takes a dictionary of WKT geometries as values and boundary IDs as keys, and uses the boundaries to aggregate all entities inside the boundaries. The input geometries are inserted into the boundaries table, along with their given ID, and the aggregated entity assets are added to the district assets table, with the same boundary ID.

Parameters:

source_database (AbstractExposure) – The database containing the exposure data that should be copied.
boundaries (dict[str, str]) – Dictionary with boundary IDs and WKT boundary geometries by which the exposure data is to be aggregated.
(int (entities_batch_size) – 1000): The number of features that should be committed at once.
optional – 1000): The number of features that should be committed at once.
default – 1000): The number of features that should be committed at once.
(int – 50_000): Number of entities to be inserted into a boundary in a single batch. If the batch size is in the hundreds of thousands, it will lead to a crash. In the case of boundaries covering a large area (e.g. Saxony in Germany), the number of entities it holds is becoming too large for a single insert.
optional – 50_000): Number of entities to be inserted into a boundary in a single batch. If the batch size is in the hundreds of thousands, it will lead to a crash. In the case of boundaries covering a large area (e.g. Saxony in Germany), the number of entities it holds is becoming too large for a single insert.
default – 50_000): Number of entities to be inserted into a boundary in a single batch. If the batch size is in the hundreds of thousands, it will lead to a crash. In the case of boundaries covering a large area (e.g. Saxony in Germany), the number of entities it holds is becoming too large for a single insert.

calibrate_asset_attributes(iso_3166: str, calibration_factors: dict[str, float])[source]

Updates the attributes column of the assets table with a factor times the values in the baseline_attributes column.

Parameters:

iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
calibration_factors (dict[str, float]) – A dictionary with the attribute names as keys and the calibration factors as values.

compute_district_builtup_area(iso_3166: str, boundary_id: str) → float | None[source]

Sums the built-up area of all tile entities whose centroids fall within the boundary geometry and have the provided country/territory ISO code.

Parameters:

iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
boundary_id (str) – ID of the district boundary.

Returns:

Total built-up area inside the district boundary. If no built-up area is found, None is returned.

Return type:

float | None

compute_ghsl_built_area_in_geometry(geometry_wkt: str) → float[source]

Calculates the total area of intersection between an input geometry and the geometries of features in the ghsl_characteristics table.

Parameters:: geometry_wkt (str) – The geometry of interest (in WKT format) for the calculation.
Returns:: The total GHSL built area that falls within the geometry.
Return type:: float

copy_country_boundaries(source_database: AbstractExposure, iso_3166: str, batch_size: int = 500)[source]

Retrieves the district boundaries at all administrative levels within a country/territory based on its ISO 3166 code. The boundaries are retrieved from a source database and stored in the current database.

Parameters:

source_database (AbstractExposure) – The database holding the boundaries to be selected.
iso_3166 (str) – ISO 3166 code of the country/territory to retrieve boundaries from.
(str (batch_size) – 500): The number of features that should be committed at once.
optional – 500): The number of features that should be committed at once.
default – 500): The number of features that should be committed at once.

copy_from_database(source_database: AbstractExposure, iso_3166: str | None = None, quadkeys: list[str] | None = None, bbox: list[float] | None = None, wkt_geometry: str | None = None, boundary_ids: list[str] | None = None, aggregate: bool = False, batch_size: int = 500, **kwargs)[source]

Copy exposure information from a source database into the current database. A specification of the area to be imported needs to be provided. If multiple options are chosen, the area imported should meet all constraints. The options are an ISO 3166-1 alpha-3 code, a list of Quadkey tiles, a bounding box, a WKT geometry or a list of boundary IDs.

Parameters:

source_database (AbstractExposure) – The database containing the exposure data that should be copied.
None (boundary_ids (list[str] |) – None): ISO 3166-1 alpha-3 code of the country/territory of the exposure to be used for the spatial filter.
optional – None): ISO 3166-1 alpha-3 code of the country/territory of the exposure to be used for the spatial filter.
default – None): ISO 3166-1 alpha-3 code of the country/territory of the exposure to be used for the spatial filter.
None – None): A list of Quadkeys of tiles to be used for the spatial filter.
optional – None): A list of Quadkeys of tiles to be used for the spatial filter.
default – None): A list of Quadkeys of tiles to be used for the spatial filter.
None – None): A bounding box in the format min_lon, min_lat, max_lon, max_lat to be used for the spatial filter.
optional – None): A bounding box in the format min_lon, min_lat, max_lon, max_lat to be used for the spatial filter.
default – None): A bounding box in the format min_lon, min_lat, max_lon, max_lat to be used for the spatial filter.
None – None): A WKT geometry to be used for the spatial filter.
optional – None): A WKT geometry to be used for the spatial filter.
default – None): A WKT geometry to be used for the spatial filter.
None – None): A list of boundary IDs that exist in the source database to be used for the spatial filter.
optional – None): A list of boundary IDs that exist in the source database to be used for the spatial filter.
default – None): A list of boundary IDs that exist in the source database to be used for the spatial filter.
(bool (aggregate) – False): If set to True, the buildings entity assets are aggregated into their tile entity.
optional – False): If set to True, the buildings entity assets are aggregated into their tile entity.
default – False): If set to True, the buildings entity assets are aggregated into their tile entity.
(str (batch_size) – 500): The number of features that should be committed at once.
optional – 500): The number of features that should be committed at once.
default – 500): The number of features that should be committed at once.

Raises:

DatabaseNotEmptyError – Raised if the database is not empty and the copied data is supposed to be aggregated.
ValueError – Raised if no spatial filter has been given.

copy_aggregated_country(source_database: AbstractExposure, iso_3166: str, batch_size: int = 500, min_number_buildings: int = 5, min_zoom_level: int = 15)[source]

Copy aggregated exposure information of a country/territory from a source database into the current database. The aggregation takes place first at zoom-level 18 tiles. If min_zoom_level is lower than 18, the function then aggregates entities with fewer buildings than min_number_buildings until the desired zoom level is reached.

Parameters:

source_database (AbstractExposure) – The database containing the exposure data that should be copied.
iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory of the exposure to be aggregated and copied into a SpatiaLite database.
(int (min_zoom_level) – 500): The number of features that should be committed at once.
optional – 500): The number of features that should be committed at once.
default – 500): The number of features that should be committed at once.
(int – 5): Minimum number of buildings below which a tile entity gets aggregated with its neighbors into a parent tile entity.
optional – 5): Minimum number of buildings below which a tile entity gets aggregated with its neighbors into a parent tile entity.
default – 5): Minimum number of buildings below which a tile entity gets aggregated with its neighbors into a parent tile entity.
(int – 15): Minimum zoom level to be reached in the aggregation process. At this zoom level no further aggregation will take place even if an entity contains fewer buildings than min_number_buildings.
optional – 15): Minimum zoom level to be reached in the aggregation process. At this zoom level no further aggregation will take place even if an entity contains fewer buildings than min_number_buildings.
default – 15): Minimum zoom level to be reached in the aggregation process. At this zoom level no further aggregation will take place even if an entity contains fewer buildings than min_number_buildings.

district_assets_exist(iso_3166: str) → bool[source]

Checks if district assets exist with the given ISO code for a country/territory.

Parameters:: iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
Returns:: True if district assets exist with the given ISO code for the country/territory.
Return type:: district_assets_exist (bool)

entity_assets_exist(iso_3166: str) → bool[source]

Checks if entity-asset pairs exist with the given ISO code for a country/territory.

Parameters:: iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
Returns:: True if entity-assets pairs exist for entities with the given ISO code for a country/territory.
Return type:: entity_assets_exist (bool)

entities_exist(iso_3166: str) → bool[source]

Checks if entities exist with the given ISO code for a country/territory.

Parameters:: iso_3166 (str) – ISO 3166-1 alpha-3 code of the country.
Returns:: True if entities exist for entities with the given ISO code for the country/territory.
Return type:: entities_exist (bool)

entities_exist_in_tile(quadkey: str) → bool[source]

Checks if entities exist in a given tile (of any zoom level).

Parameters:: quadkey (str) – Quadkey of the tile.
Returns:: True if entities exists in the given tile, False otherwise.
Return type:: bool

get_all_tiles() → list[str][source]

Retrieves a list of all tiles (unique Quadkeys) from the entities table.

Returns:: A list of all tiles in the entities table.
Return type:: list[str]

get_asset(asset_id: int) → list[source]

Retrieves an asset by its ID.

Parameters:: asset_id (int) – ID of the asset.
Returns:: The ISO 3166-1 alpha-3 code of the country/territory, the taxonomy ID, the tabula taxonomy ID, the average net floor area, the baseline attributes and the attributes of the asset.
Return type:: asset (list)

get_asset_id(iso_3166: str, taxonomy_id: int, tabula_taxonomy_id: int | None, average_net_floor_area: float | None, attributes: dict) → int | None[source]

Retrieves the ID of an asset, based on all its columns.

Parameters:

iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory of the asset.
taxonomy_id (int) – ID of the taxonomy.
tabula_taxonomy_id (int | None) – ID of the TABULA taxonomy.
average_net_floor_area (float | None) – The average net floor area of a building.
attributes (dict[str, float]) – The attributes of the asset. This includes population and replacement costs.

Returns:

ID of the entry with the given asset information or None if not found.

Return type:

int | None

get_asset_taxonomy_ids(asset_ids: list[int]) → list[int][source]

Retrieve the unique Taxonomy IDs from a list of assets by their ID.

Parameters:: asset_ids (list[int]) – The IDs of the assets which taxonomy ID should be retrieved.
Returns:: A unique list of taxonomy IDs.
Return type:: taxonomy_ids (list[int])

get_boundary_geometry(boundary_id: str) → str[source]

Retrieves a boundary geometry based on the boundary ID.

Parameters:: boundary_id (str) – ID of the country/territory or district boundary.
Returns:: The WKT geometry of the country/territory or district as a string.
Return type:: str

get_building_ids_in_boundary(table_name: str, boundary_id: str | None = None, geom_wkt: str | None = None, feature_column: str = 'id') → list[tuple[int]][source]

Extract the IDs of building geometries from a given source table that lie within a boundary. The boundary can be provided either with a boundary ID, or a WKT geometry.

Parameters:

table_name (str) – Name of the table with the building IDs. The table names should be a simple string representing a constant, defined within the postgis.py file of the exposure-lib, those that have the prefix table_.
(str (feature_column) – None): ID of the country/territory or district boundary.
optional – None): ID of the country/territory or district boundary.
default – None): ID of the country/territory or district boundary.
(str – None): The boundary geometry of interest (in WKT format) for the selection.
optional – None): The boundary geometry of interest (in WKT format) for the selection.
default – None): The boundary geometry of interest (in WKT format) for the selection.
(str – ‘id’): Name of the column with the requested feature.
optional – ‘id’): Name of the column with the requested feature.
default – ‘id’): Name of the column with the requested feature.

Returns:

List of tuples with all the IDs that correspond to the building geometries that lie within the boundary geometry.

Return type:

list[tuple[int]]

Raises:

ValueError – Raised if neither boundary_id nor geom_wkt are provided, because no filtering can be done for the requested features or if both boundary_id and geom_wkt are provided. to avoid assigning preference, the user must decide which to use.

get_buildings_in_tile(quadkey: str) → list[source]

Get all buildings, including building footprint, net floor area, and building type inside the given tile.

Parameters:: quadkey (str) – The Quadkey of the building entities that are being retrieved.
Returns:: A list of building entities, including the entity ID, the building footprint, the building net floor area, and the building taxonomy.
Return type:: buildings (list)

get_country_baseline_assets(iso_3166: str) → list[tuple[int, dict]][source]

Retrieve all existing baseline assets in a country/territory based on its ISO 3166-1 alpha-3 code.

Parameters:: iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory whose baseline assets are being retrieved.
Returns:: A list of baseline assets that each contain an asset ID and a baseline attribute dictionary.
Return type:: baseline_assets (list[tuple[int, dict]])

get_country_boundary_ids(iso_3166: str, return_country_id: bool = True) → list[str][source]

Retrieve the list of boundary IDs for a given country/territory based on its ISO 3166-1 alpha-3 code.

Parameters:

iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory whose boundary IDs are being retrieved.
(bool (return_country_id) – True): If True, includes the country-level boundary ID (e.g. ‘XXX-COUNTRY’) in the returned list.
optional – True): If True, includes the country-level boundary ID (e.g. ‘XXX-COUNTRY’) in the returned list.
default – True): If True, includes the country-level boundary ID (e.g. ‘XXX-COUNTRY’) in the returned list.

Returns:

A list of boundary IDs that are located inside the country.

Return type:

list[str]

get_country_asset_ids(iso_3166: str) → list[int][source]

Retrieve all asset IDs related to the country/territory, based on the ISO 3166-1 alpha-3 code.

Parameters:: iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
Returns:: A list of asset IDs of the country/territory.
Return type:: asset_ids (list[int])

get_country_assets(iso_3166: str) → list[source]

Retrieve all assets related to the country/territory, based on the ISO 3166-1 alpha-3 code.

Parameters:: iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
Returns:: A list of district assets.
Return type:: country_assets (list)

get_country_baseline_exposure_attribute_sum(iso_3166: str, attribute: str) → float | None[source]

Retrieve the sum of all existing attributes in the (baseline) exposure of a country. Attributes can be the average number of occupants, or the replacement costs. A full list of attributes can be found in the EXPOSURE_ATTRIBUTES constant.

Parameters:

iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
attribute (str) – The attribute key.

Returns:

The total sum of the attribute values in the country.

Return type:

attribute_sum (float | None)

get_country_entity_ids(iso_3166: str) → list[int][source]

Retrieve all entity IDs related to the country/territory, based on the ISO 3166-1 alpha-3 code.

Parameters:: iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
Returns:: A list of entity IDs of the country/territory.
Return type:: entity_ids (list[int])

get_entity(entity_id: int) → tuple[str, str, str, int, int, dict | None, str, str, dict][source]

Retrieves an entity by its ID.

Parameters:: entity_id (int) – ID of the asset.
Returns:: The quadkey, WKT Geometry, ISO 3166-1 alpha-3 code of the country/territory, source ID, category, attributes, building ID, WKB 3D Geometry and taxonomy of the entity.
Return type:: asset (list)

get_entity_asset_pair_asset_ids(entity_ids: list[int]) → list[int][source]

Get the unique asset IDs in the entity-assets table from a set of entity IDs.

Parameters:: entity_ids (list[int]) – Entity IDs.
Returns:: Unique list of asset IDs.
Return type:: asset_ids (list[int])

get_entity_asset_pairs(entity_ids: list[int]) → list[source]

Get all entity-asset pairs of a list of entity IDs.

Parameters:: entity_ids (list[int]) – Entity IDs.
Returns:: A list of entity-asset pairs with the entity ID, asset ID, the number and the relative size.
Return type:: entity_asset_pairs (list)

get_entity_ids_from_quadkeys(quadkeys: list[str]) → list[int][source]

Retrieve all IDs of entities that contain one of the provided Quadkey IDs.

Parameters:: quadkeys (list[str]) – Quadkey IDs.
Returns:: A list of IDs of entities that contain one of the provided quadkey IDs.

get_district_assets(iso_3166: str) → defaultdict[str, list[list, float]][source]

Retrieve all assets related to each district in a country/territory, based on the ISO 3166-1 alpha-3 code, as well as the total built-up area per district.

Parameters:: iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
Returns:: A list of district assets and the total number of buildings per district, organized as a dictionary with the boundary ID as the key.
Return type:: district_assets (defaultdict[str, list[list, float]])

get_ghsl_ids_in_boundary(boundary_id: str) → list[tuple[int]][source]

Extract the IDs of Global Human Settlement Layer geometries that lie within a boundary.

Parameters:: boundary_id (str) – ID of the country/territory or district boundary.
Returns:: List of tuples with all the IDs that correspond to the geometries that lie within the boundary geometry.
Return type:: list[tuple[int]]

get_sources() → list[int, str, str, str][source]

Retrieve all sources currently existing in the database.

Returns:: A list of the sources by ID, name, URI and publication date.
Return type:: sources (list[int, str, str, str])

get_source_id(source_name: str) → int[source]

Retrieves the ID of a data source based on its name from the sources table. If the source name is not found, an error will be raised.

Parameters:: source_name (str) – Name of the data source whose ID is being requested.
Returns:: The integer ID of the target source.
Return type:: source_id (int)
Raises:: SourceNotFoundError – If the source name is not found in the sources table.

Compute the sum of attributes for a given entity ID and/or asset ID. The computation accounts for the relative size of each entity and the number of buildings per entity.

The aggregation can be performed over: - All entity–asset pairs sharing the same asset ID (entity_id is None). - All entity–asset pairs sharing the same entity ID (asset_id is None). - A single entity–asset pair (when both entity ID and asset ID are provided).

Attributes can be selected using one of the following methods: - By attribute key (slow): attribute values are retrieved directly from the database. - By attribute value (fast): only one value per attribute may be provided. Use with

caution. When combined with providing only an entity ID, this may yield inconsistent results, in which case a warning is raised.

All exposure attributes, if no attribute keys or values are specified.

The computation can be applied to: - baseline_attributes (uncalibrated), when use_baseline=True. - attributes (calibrated), when use_baseline=False.

Parameters:

None (attribute_values (list[float] |) – None): The ID of the asset.
optional – None): The ID of the asset.
default – None): The ID of the asset.
None – None): The ID of the entity.
default – None): The ID of the entity.
None – None): A list of attribute keys that should be summed. This is a subset of the EXPOSURE_ATTRIBUTES. For example: [“OPA”, “OPD”, “OPN”, “OPT”, “OAV”], if only the population values are needed.
default – None): A list of attribute keys that should be summed. This is a subset of the EXPOSURE_ATTRIBUTES. For example: [“OPA”, “OPD”, “OPN”, “OPT”, “OAV”], if only the population values are needed.
None – None): A list of attribute values that should be summed. This can be faster, as no inner join is needed anymore. For example: [4.2, 4.5, 3.3, 2.6, 5.5].
default – None): A list of attribute values that should be summed. This can be faster, as no inner join is needed anymore. For example: [4.2, 4.5, 3.3, 2.6, 5.5].
(bool (use_baseline) – False): If set to True, the attribute keys are taken from the baseline_attributes column instead of the default attributes column.
default – False): If set to True, the attribute keys are taken from the baseline_attributes column instead of the default attributes column.

Returns:

The sum of each of the attributes of the entity/asset combination, in the same order as the attribute keys/values are provided. If no keys/values are provided, it is the same order as the EXPOSURE_ATTRIBUTES.

Return type:

sum_entity_asset_attributes (list[float | None])

Raises:

ValueError – If no asset ID or entity ID is provided.
ValueError – If both attribute_keys and attribute_values are provided.
Warning – If there is no asset ID given, while the attribute_values are.

get_tabula_values(tabula_taxonomy: str) → dict | None[source]

Function which retrieves all the energy efficiency values related to a building type based on that building’s TABULA taxonomy.

Parameters:: tabula_taxonomy (str) – The TABULA taxonomy string of the building.
Returns:: A dictionary containing all the values associated with the building type. These values include the U-values for the different building elements/components, cost of heating, CO2 emissions, and energy required for heating.
Return type:: dict | None

get_taxonomy(taxonomy_id: int) → tuple[int, dict, dict | None][source]

Retrieves a taxonomy feature by its ID.

Parameters:: taxonomy_id (int) – ID of the taxonomy feature.
Returns:: The category (0 for exposure, 1 for TABULA), taxonomy attributes and other attributes (such as U-values) of the taxonomy feature.
Return type:: taxonomy (tuple[int, dict, dict | None])

get_taxonomy_id(taxonomy: Taxonomy) → int | None[source]

Retrieves the ID of a taxonomy given a Taxonomy object.

Parameters:: taxonomy (Taxonomy) – Taxonomy object to search for in the table.
Returns:: ID of the entry with the given taxonomy or None if not found.
Return type:: int | None

get_taxonomy_id_from_dict(category: int, taxonomy_dict: dict[str, Any]) → int | None[source]

Retrieves the ID of a taxonomy given the Taxonomy as a dictionary.

Parameters:

category (int) – Category of the taxonomy, whether 1 or 0.
taxonomy_dict (dict[str, Any]) – Taxonomy as dictionary to search for in the table.

Returns:

ID of the entry with the given taxonomy or None if not found.

Return type:

int | None

get_tile_boundary_ids(quadkey: str) → list[str][source]

Return all boundary IDs where the tile entity centroid lies inside the boundary, the ISO 3166-1 alpha-3 code is the same as in the tile entity, and the returned boundary is not the country boundary.

Parameters:: quadkey (str) – The Quadkey of the tile entity.
Returns:: A list of boundary IDs that contain the entity.
Return type:: boundaries (list[str])

get_tile_entity_id(quadkey: str) → int | None[source]

Retrieves the tile entity ID from the entities table based on its Quadkey.

Parameters:: quadkey (str) – The Quadkey of the entity tile ID that is being retrieved.
Returns:: The entity ID of the tile or None if the tile is not found.
Return type:: int | None

get_tile_id_attributes(quadkey: str) → tuple[int, dict[str, Any]] | None[source]

Retrieves the tile entity ID and tile attributes as the dictionary from the entities table based on its Quadkey.

Parameters:: quadkey (str) – The Quadkey of the tile-entity ID that is being retrieved.
Returns:: A tuple of the tile-entity ID and tile attributes or None if the tile is not found.
Return type:: tuple[int, dict[str, Any]] | None

get_tiles_from_ghsl_feature(feature_id: int, zoom_level: int = 18)[source]

Create a tile and get its Quadkey value based on a geometry from the ghsl_characteristics table storing the Global Human Settlement Layer.

Parameters:

feature_id (int) – ID of the feature whose quadkey and tile geometry is being retrieved.
zoom_level (int) – Zoom level for the Quadkey value and consequently the size of its respective geometry.

Returns:

A list of tuples with the Quadkey and the tile geometries for the Quadkeys with which the GHSL geometry intersects.

Return type:

list[tuple[str, str]]

get_tiles_in_country(iso_3166: str, return_completeness_attribute: bool = False, return_builtup_area_attribute: bool = False) → list[source]

Get all tile entities that are in country or territory. It is also possible to return the completeness and/or the built-up area of the tile.

Parameters:

iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
(bool (return_builtup_area_attribute) – False): If True, the completeness of the tile is returned.
default – False): If True, the completeness of the tile is returned.
(bool – False): If True, the total built-up area in the tile is returned.
default – False): If True, the total built-up area in the tile is returned.

Returns:

A list of tile entity ids and Quadkeys, optionally with completeness and/or built-up area.

Return type:

tiles (list)

Get all tiles that meet multiple spatial constraints. The options are an ISO 3166-1 alpha-3 code, a list of Quadtree tiles, a bounding box, a WKT geometry or a list of boundary IDs.

Parameters:

None (boundary_ids (list[str] |) – None): ISO 3166-1 alpha-3 code of the country/territory of the exposure to be used for the spatial filter.
optional – None): ISO 3166-1 alpha-3 code of the country/territory of the exposure to be used for the spatial filter.
default – None): ISO 3166-1 alpha-3 code of the country/territory of the exposure to be used for the spatial filter.
None – None): A list of Quadkeys of tiles to be used for the spatial filter.
optional – None): A list of Quadkeys of tiles to be used for the spatial filter.
default – None): A list of Quadkeys of tiles to be used for the spatial filter.
None – None): A bounding box in the format min_lon, min_lat, max_lon, max_lat to be used for the spatial filter.
optional – None): A bounding box in the format min_lon, min_lat, max_lon, max_lat to be used for the spatial filter.
default – None): A bounding box in the format min_lon, min_lat, max_lon, max_lat to be used for the spatial filter.
None – None): A WKT geometry to be used for the spatial filter.
optional – None): A WKT geometry to be used for the spatial filter.
default – None): A WKT geometry to be used for the spatial filter.
None – None): A list of boundary IDs that exist in the source database to be used for the spatial filter.
optional – None): A list of boundary IDs that exist in the source database to be used for the spatial filter.
default – None): A list of boundary IDs that exist in the source database to be used for the spatial filter.

Returns:

A list of tiles by Quadkey.

Return type:

tiles (list[str])

Raises:

ValueError – If there is no spatial filter given.
ValueError – If no tiles are returned due to the spatial filters.

insert_asset(iso_3166: str, taxonomy_id: int, tabula_taxonomy_id: int | None, average_net_floor_area: float | None, baseline_attributes: dict, attributes: dict | None = None) → int[source]

Inserts a list of one or more assets to the assets table.

Parameters:

iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
taxonomy_id (int) – ID of the taxonomy.
tabula_taxonomy_id (int | None) – ID of the TABULA taxonomy.
average_net_floor_area (float | None) – The average net floor area of a building.
baseline_attributes (dict[str, float]) – The initial attributes of the asset. This includes population and replacement costs.
(dict[str (attributes) – None): The calibrated attributes of the asset. This includes population and replacement costs. During the insert of the baseline model, the attributes should be None.
None (float] |) – None): The calibrated attributes of the asset. This includes population and replacement costs. During the insert of the baseline model, the attributes should be None.
optional – None): The calibrated attributes of the asset. This includes population and replacement costs. During the insert of the baseline model, the attributes should be None.
default – None): The calibrated attributes of the asset. This includes population and replacement costs. During the insert of the baseline model, the attributes should be None.

Returns:

ID of the asset.

Return type:

int

insert_baseline_tile(quadkey: str, iso_3166: str, source_id: int, baseline_built_area: float) → int[source]

Insert a baseline tile, including its Quadkey, geometry, ISO code of the country/territory, source ID and baseline built area into the entities table.

Parameters:

quadkey (str) – Quadkey of the tile being inserted.
iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
source_id (int) – ID of the source dataset on which the tile being inserted is based on.
baseline_built_area (float) – Total built area inside the baseline tile geometry.

Returns:

ID of the tile with the baseline information.

Return type:

int

Raises:

InvalidBaselineBuiltAreaError – If the input value for the baseline tile geometry is invalid.

insert_district_assets(district_assets: list)[source]

Inserts a list of one or more district assets to the district_assets table.

Parameters:

district_assets (list) –

List of assets, each containing:

Boundary ID (str).
Asset ID (int).
Number of buildings in the entity (float).

insert_district_builtup_area(boundary_id: str, builtup_area: float)[source]

Inserts the built-up area of a district into the boundaries table.

Parameters:

boundary_id (str) – ID of the district boundary.
builtup_area (float) – Total (estimated) footprint size of buildings in the district in square meters.

insert_entity_assets(assets: list)[source]

Inserts a list of one or more asset-entity pairs to the entity_assets table.

Parameters:

assets (list) –

List of assets, each containing:

ID of the entity (int).
ID of the asset (int).
Number of buildings in the entity (float).
Relative size compared to the average asset (float).

insert_source(source_name: str, uri: str = '', publication_date: str = '') → int[source]

Inserts a source into the sources table.

Parameters:

source_name (str) – Name of the source.
(str (publication_date) – ‘’): Uniform Resource Identifier of the source, like a DOI or a URL.
optional – ‘’): Uniform Resource Identifier of the source, like a DOI or a URL.
default – ‘’): Uniform Resource Identifier of the source, like a DOI or a URL.
(str – ‘’): Date of publication of the source.
optional – ‘’): Date of publication of the source.
default – ‘’): Date of publication of the source.

Returns:

ID of the source in the table.

Return type:

source_id (int)

insert_taxonomy(category: int, taxonomy: Taxonomy, attributes: dict[str, Any]) → int[source]

Inserts a taxonomy to the taxonomies table. The function first checks if the taxonomy is already present in the taxonomies table. If so, it will return the respective ID, if not, it will insert the provided taxonomy and return its assigned ID.

Parameters:

category (int) – Category of the taxonomy information.
taxonomy (Taxonomy) – Taxonomy object.
attributes (dict[str, Any]) – Additional attributes as dictionary.

Returns:

ID of the taxonomy dataset in the table.

Return type:

taxonomy_id (int)

insert_taxonomy_from_dict(category: int, taxonomy_dict: dict[str, Any], attributes: dict[str, Any]) → int[source]

Inserts a taxonomy to the taxonomies table. The function first checks if the taxonomy is already present in the taxonomies table. If so, it will return the respective ID, if not, it will insert the provided taxonomy and return its assigned ID.

Parameters:

category (int) – Category of the taxonomy information.
taxonomy_dict (dict[str, Any]) – Taxonomy attributes as dictionary.
attributes (dict[str, Any]) – Additional attributes as dictionary.

Returns:

ID of the taxonomy dataset in the table.

Return type:

taxonomy_id (int)

upsert_tile(quadkey: str, iso_3166: str, source_id: int | None, attributes: dict[str, Any]) → int[source]

Insert or update a tile entity, including its Quadkey, geometry, ISO code of the country/territory, source ID and attributes into the entities table. Its geometry is implicitly created from the Quadkey. If a tile with the same Quadkey already exists, its attributes are updated.

Parameters:

quadkey (str) – Quadkey of the tile being inserted.
iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
source_id (int | None) – ID of the source dataset on which the tile being inserted is based on when the tile is inserted as found built area in GHSL or other datasets. If the tile is inserted due to a building from rabotnik-rules, the source ID of the tile is set to NULL.
attributes (dict[str, Any]) – Additional attributes relevant to the tile in the form of a dictionary.

Returns:

ID of the inserted or already existing tile.

Return type:

int

update_tile_attributes(quadkey: str, tile_attributes: dict[str, Any])[source]

Updates the attributes of an existing tile in the entities table based on its Quadkey.

Parameters:

quadkey (str) – The Quadkey of the tile.
tile_attributes (dict[str, Any]) – The new attribute of tile entity that should be updated in the database.

upsert_building_entity(quadkey: str, iso_3166: str, source_id: int, building_id: str, attributes: dict[str, Any], geometry: str, geometry3d: str = 'NULL', taxonomy: Taxonomy | None = None, is_building_part: bool = False)[source]

Insert or update a building entity, including its Quadkey, geometry, geometry3d, ISO code of the country/territory, source ID, attributes and taxonomy into the entities table.

Parameters:

quadkey (str) – Quadkey of the tile that the building is located in.
iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
source_id (int) – ID of the source dataset on which the building entity being inserted is based on.
building_id (string) – The ID of the building at the source (such as the OSM ID).
attributes (dict[str, Any]) – Additional attributes relevant to the building in the form of a dictionary.
geometry (str) – A SQL expression that creates a geometry of the building. For example the WKT formatted geometry using the ST_GeomFromText() function.
(str (geometry3d) – NULL): A SQL expression that creates a 3D geometry. This can be a WKB hex string that is cast to a 3D geometry using the ::geometry expression, a WKT string or NULL if there is no 3D geometry.
optional – NULL): A SQL expression that creates a 3D geometry. This can be a WKB hex string that is cast to a 3D geometry using the ::geometry expression, a WKT string or NULL if there is no 3D geometry.
default – NULL): A SQL expression that creates a 3D geometry. This can be a WKB hex string that is cast to a 3D geometry using the ::geometry expression, a WKT string or NULL if there is no 3D geometry.
(dict[str (taxonomy) – None): Additional taxonomy relevant to the building in the form of a dictionary.
None (Any] |) – None): Additional taxonomy relevant to the building in the form of a dictionary.
optional – None): Additional taxonomy relevant to the building in the form of a dictionary.
default – None): Additional taxonomy relevant to the building in the form of a dictionary.
(bool (is_building_part) – False): Set to True if the entity is a building part, rather than a full building.
optional – False): Set to True if the entity is a building part, rather than a full building.
default – False): Set to True if the entity is a building part, rather than a full building.

upsert_key_value_pair(key: str, value: str, comment: str = '', overwrite: bool = False)[source]

Inserts or updates a key-value pair in the metadata table. If the key does not yet exist, the key-value is inserted. Otherwise, the value of the existing key will be updated if overwrite is set to True. If overwrite is set to False, the function will keep the existing key-value pair.

Parameters:

key (str) – The key describing the metadata topic.
value (str) – The metadata value of the given topic.
(str (comment) – Empty string): Optional comment to be added to the key-value pair.
optional – Empty string): Optional comment to be added to the key-value pair.
default – Empty string): Optional comment to be added to the key-value pair.
(bool (overwrite) – True): If set, an existing metadata value for the given key will be overwritten. If not set, the function will keep the existing key-value pair. In case the key does not yet exist in the table, this option has no effect.
optional – True): If set, an existing metadata value for the given key will be overwritten. If not set, the function will keep the existing key-value pair. In case the key does not yet exist in the table, this option has no effect.
default – True): If set, an existing metadata value for the given key will be overwritten. If not set, the function will keep the existing key-value pair. In case the key does not yet exist in the table, this option has no effect.

update_tabula(iso_3166: str)[source]

Inserts TABULA taxonomy values into the taxonomies table based on the alpha-2 ISO code of the country/territory. The function first all relevant TABULA taxonomies from a country/territory based on the ISO code, then iterates over these to retrieve the relevant values from the tabula table and then updates the taxonomies table with these values.

Parameters:: iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.

get_value_of_key(key: str) → str | None[source]

Retrieves the value of a key-value pair from the metadata table given the key.

Parameters:: key (str) – The key describing the metadata topic for which the value should be retrieved.

Returns

str | None:: The metadata value of the given topic if it exists, else None.

remove_assets(iso_3166: str, number_items_per_commit: int = 500)[source]

Remove all assets from entities for the given ISO code for a country/territory.

Parameters:

iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
(int (number_items_per_commit) – 500): Commit frequency per asset ID. Note that each asset ID may remove many entity-asset pairs.
optional – 500): Commit frequency per asset ID. Note that each asset ID may remove many entity-asset pairs.
default – 500): Commit frequency per asset ID. Note that each asset ID may remove many entity-asset pairs.

remove_district_assets(boundary_id: str)[source]

Removes all district assets for the given district boundary ID.

Parameters:: boundary_id (str) – ID of the district boundary.

remove_entity_assets_by_id(entity_id: int | None = None, asset_id: int | None = None)[source]

Removes all entity-asset pairs for the given entity and/or asset ID.

Parameters:

None (asset_id (int |) – None): Entity ID of the entity-asset pair(s).
optional – None): Entity ID of the entity-asset pair(s).
default – None): Entity ID of the entity-asset pair(s).
None – None): Asset ID of the entity-asset pair(s).
optional – None): Asset ID of the entity-asset pair(s).
default – None): Asset ID of the entity-asset pair(s).

Raises:

ValueError – If no entity or asset ID has been provided.

remove_entity_assets(iso_3166: str, number_items_per_commit: int = 500)[source]

Removes all entity-asset pairs for the given ISO code for a country/territory.

Parameters:

iso_3166 (str) – ISO 3166-1 alpha-3 code of the country/territory.
(int (number_items_per_commit) – 500): Commit frequency per asset ID. Note that each asset ID may remove many entity-asset pairs.
optional – 500): Commit frequency per asset ID. Note that each asset ID may remove many entity-asset pairs.
default – 500): Commit frequency per asset ID. Note that each asset ID may remove many entity-asset pairs.

class exposurelib.SpatiaLiteExposure(database_filepath: str, spatialite_filepath: str = 'mod_spatialite')[source]

Bases: SpatiaLiteDatabase, AbstractExposure

The SpatiaLiteExposure class represents a database for exposure models. It is derived from the generic SpatiaLiteDatabase class for providing functionality related to SpatiaLite databases and the AbstractExposure class for database-type independent functionality regarding handling of exposure data.

__init__(database_filepath: str, spatialite_filepath: str = 'mod_spatialite')[source]

Initializes a SpatiaLite database.

Parameters:

database_filepath (str) – Filepath of the exposure database file.
(str (spatialite_filepath) – mod_spatialite): Filepath of the SpatiaLite extension.
optional – mod_spatialite): Filepath of the SpatiaLite extension.
default – mod_spatialite): Filepath of the SpatiaLite extension.

aggregate_on_boundaries(source_database: AbstractExposure, boundaries: dict, batch_size: int = 1000)[source]

Exports exposure data based on input WKT geometries. Takes a dictionary of WKT geometries as values and boundary IDs as keys, and uses the boundaries to aggregate all entities inside the boundaries. The input geometries are inserted into the boundaries table, along with their given ID, and the aggregated entity assets are added to the district assets table, with the same boundary ID.

Parameters:

source_database (AbstractExposure) – The database containing the exposure data that should be copied.
boundaries (dict[str, str]) – Dictionary with boundary IDs and WKT boundary geometries by which the exposure data is to be aggregated.
(str (batch_size) – 1000): The number of features that should be committed at once.
optional – 1000): The number of features that should be committed at once.
default – 1000): The number of features that should be committed at once.

create_tables()[source]

Creates all necessary tables in the database. These are:: entities : Stores data to identify entities (buildings or tiles). assets : Stores assets of an entity (either of a building or tile). taxonomies : Stores taxonomy definitions. metadata : Stores metadata as key-value pairs. sources : Stores the data sources used to create the exposure data. district_assets : Stores the assets of districts (can also be a country). entity_assets : Stores the assets of one entity. boundaries : Stores boundary geometries and their OSM IDs. ghsl_characteristics: Stores the GHSL geometries used as an exposure tile source.

Raises:: DatabaseNotEmptyError – If one of the tables listed above exists in the database, the function will raise this exception.

create_view_aggregated_exposure()[source]: Create a view which takes boundaries inserted in the function aggregate_on_boundaries() the districts assets and assets related to these for the visualization of the aggregation.

static get_tiles_in_boundary(geometry_wkt: str, zoom_level: int) → list[str][source]

Takes a boundary geometry and based on it and a given zoom level, selects all the Quadkeys that fall within it, creates the Quadtree tile geometries, and returns those that have a non-zero size overlap with the boundary.

Parameters:

geometry_wkt (str) – The boundary geometry of interest (in WKT format) for the selection.
zoom_level (int) – Zoom level for the Quadkey value and consequently the size of its respective geometry.

Returns:

A list of Quadtree geometries of the tiles at the provided zoom_level that have a non-zero size overlap with the boundary of the provided geometry.

Return type:

list[str]

Raises:

TilesNotFoundError – If no tiles are found and selected within the given boundary geometry at the provided zoom level.

class exposurelib.PostGISExposure(host: str, dbname: str, port: str, username: str, password: str, timeout: int = 0, itersize: int = 10000)[source]

Bases: PostGISDatabase, AbstractExposure

The PostGISExposure class represents a database for exposure models. It is derived from the generic PostGISDatabase class for providing functionality related to PostGIS databases and the AbstractExposure class for database-type independent functionality regarding handling of exposure data.

__init__(host: str, dbname: str, port: str, username: str, password: str, timeout: int = 0, itersize: int = 10000)[source]

Initializes a PostGIS database.

Parameters:

host (str) – Host name of the database server.
dbname (str) – Name of the PostGIS database.
port (str) – Port to access the database server.
username (str) – Name of the user to access the database.
password (str) – Password of the user to access the database.
(int (itersize) – 0): Default timeout for SQL queries in milliseconds (0 equals to no timeout).
optional – 0): Default timeout for SQL queries in milliseconds (0 equals to no timeout).
default – 0): Default timeout for SQL queries in milliseconds (0 equals to no timeout).
(int – 10000): Number of rows fetched from the server at one call.
optional – 10000): Number of rows fetched from the server at one call.
default – 10000): Number of rows fetched from the server at one call.

get_tiles_in_boundary(geometry_wkt: str, zoom_level: int) → list[str][source]

Takes a boundary geometry and based on it and a given zoom level, selects all the Quadkeys that fall within it, creates the Quadtree tile geometries, and returns those that have a non-zero size overlap with the boundary.

Parameters:

geometry_wkt (str) – The boundary geometry (in WKT format) for the selection.
zoom_level (int) – Zoom level for the Quadkey and consequently the size of its respective geometry.

Returns:

A list of Quadtree geometries of the tiles at the provided zoom_level that have a non-zero size overlap with the boundary of the provided geometry.

Return type:

list[str]

Raises:

TilesNotFoundError – If no tiles are found and selected within the given boundary geometry at the provided zoom level.

exception exposurelib.DatabaseNotEmptyError[source]

Bases: Exception

Exception that is raised in the create_tables() function in case that one or more tables already exist.