prepare_geodata module

prepare_geodata.adjust_num_of_dwelling(gdf_in: GeoDataFrame)

Set the number of dwellings to 0 for non residential buildings and limit the number of dwellings to a maximum of 500.

The number of dwellings is set to 0 for non residential buildings (e.g. PCI) and the number of dwellings is limited to a maximum of 500. This is done to avoid unrealistic values for the number of dwellings. In the subsequent analysis, the number of dwellings is used to calculate the specific heating demand and the yearly heating demand.

Parameters:

gdf_in (gpd.GeoDataFrame) -- GeoDataFrame containing the building data.

prepare_geodata.calc_heating_hours(case_study_name: str, config: dict, Tset=21.0, Tsetback=18.0) → float

Calculate the heating degree hours based on the outside temperature and the setpoint temperature.

The heating degree hours are calculated for the whole year, for a reference actitive occupancy profile.

Parameters:

• case_study_name (str) -- Name of the case study, used to load the temperature data

• config (dict) -- Config dictionary

• Tset (float, optional) -- Setpoint temperature for buildings, defaults to 21

• Tsetback (float, optional) -- Setback temperature for buildings, defaults to 18

Returns:

Number of heating degree hours for the whole year in °C*h

Return type:

float

prepare_geodata.define_setpontTemp(gdf_in: GeoDataFrame, temp_setpoint=22.0, std_setpoint=2.0, temp_setback=17.0, std_setback=2.0)

Define the setpoint temperature and the setback temperature for the buildings.

The values are randomly generated based on a normal distribution around the mean values. If real data is available, this function can be replaced by the real data.

Parameters:

• gdf_in (gpd.GeoDataFrame) -- GeoDataFrame containing the building data.

• temp_setpoint (float, optional) -- mean value for the setpoint temperature, defaults to 22.0

• std_setpoint (float, optional) -- standard deviation for the setpoint temperature, defaults to 2.0

• temp_setback (float, optional) -- mean value for the setback temperature, defaults to 17.0

• std_setback (float, optional) -- standard deviation for the setback temperature, defaults to 2.0

prepare_geodata.estimate_data_osm(gdf_in: GeoDataFrame) → GeoDataFrame

Estimate the required data for the subsequent analysis (e.g. number of floors) just from the OSM data.

The function estimates the required data for subsequent analysis. Where not sufficient data is available, the data is estimated from the available data. The estimation is based on the OSM data and might not be accurate, depending on the quality of the OSM data.

Parameters:

gdf_in (gpd.GeoDataFrame) -- GeoDataFrame containing the relevant data, exracted from the raw geodata.

Returns:

A new GeoDataFrame containing the estimated building properties for further analysis.

Return type:

gpd.GeoDataFrame

prepare_geodata.estimate_internal_gainfactor(gdf_in: GeoDataFrame, gain_per_dwelling=0.12)

Estimate the internal gain factor for the buildings.

The gain is scaled per dwelling, with the input parameter gain_per_dwelling.

Parameters:

• gdf_in (gpd.GeoDataFrame) -- GeoDataFrame containing the building data.

• gain_per_dwelling (float, optional) -- value for the internal gain per dwelling in kW/dwelling, defaults to 0.2

prepare_geodata.estimate_local_heat_prod_costs(gdf_in: GeoDataFrame, cost_per_kWh=0.15)

Estimate the local heating production costs based on the cost per kWh.

The costs are randomly generated based on a normal distribution around the mean value. If real data is available, this function can be replaced by the real data.

Parameters:

• gdf_in (gpd.GeoDataFrame) -- GeoDataFrame containing the building data.

• cost_per_kWh (float, optional) -- mean value for the heating costs per kWh, defaults to 0.15

prepare_geodata.estimate_solar_gainfactor(gdf_in: GeoDataFrame, window_fraction=0.08)

Estimate the solar gain factor for the buildings.

The gain is scaled per dwelling, with the input parameter window_fraction. If more accurate data is available, this function can be replaced by the real data.

Parameters:

• gdf_in (gpd.GeoDataFrame) -- GeoDataFrame containing the building data.

• window_fraction (float, optional) -- share of window area of total facade area, defaults to 0.1

prepare_geodata.estimate_thermal_properties(gdf_in: GeoDataFrame, heatinghours=50000.0, speHeatStorCap=0.04, surface_to_area=2.5)

Estimate the thermal properties of the buildings based on the specific heating demand and the heated area.

The estimated thermal properties are scaled up for the whole building, that means all parameters refere to the total building.

Parameters:

• gdf_in (gpd.GeoDataFrame) -- GeoDataFrame containing the building data.

• heatinghours (float, optional) -- Number of heating hours per year. Sumed up the temperature difference between setpoint and outside temperature for all hours of the year., defaults to 50000

• speHeatStorCap (float, optional) -- specific heat storage capacity of the building material in kWh/m²K of a wall of average thickness, defaults to 0.04

• surface_to_area (float, optional) -- float ratio of thermal active area of the building (i.e. walls, roof, floor) to the ground area of the building (avoid double counting of indoor walls), defaults to 2.5

prepare_geodata.extract_relevat_data(gdf_in: GeoDataFrame) → GeoDataFrame

Extract the relevant data from the raw geodata that are needed for further analysis.

Data that are not available are set to a default value, and a warning is printed. Observe the output in the console to check for missing data and data quality.

Parameters:

gdf_in (gpd.GeoDataFrame) -- GeoDataFrame with the raw geodata obtained from OSM

Returns:

A new GeoDataFrame containing the relevant data for further analysis.

Return type:

gpd.GeoDataFrame

prepare_geodata.generate_complete_geodataset(casstudy_name: str, location) → GeoDataFrame

Run a complete case study for a given location.

The function generates a new case study folder if the folder does not exist yet. It then loads the building data from OpenStreetMap and processes it to get the relevant data. The function estimates the thermal properties of the buildings and writes the data to disk. The function returns the processed building data as a GeoDataFrame.

Parameters:

• casstudy_name (str) -- Name of the case study

• location (str or shapely.geometry.polygon.Polygon) -- Geographical location of the case study. Can be a polygon (must be polygon) or a place name (string).

Returns:

A GeoDataFrame containing the building data for the case study with all properites.

Return type:

gpd.GeoDataFrame

prepare_geodata.geodesic_point_buffer(lat: float, lon: float, km: float) → list

Perform a geodesic point buffer around a given latitude and longitude.

Parameters:

• lat (float) -- Latitude of the center point.

• lon (float) -- Longitude of the center point.

• km (float) -- Radius of the buffer in kilometers.

Returns:

A list of coordinates representing the buffer around the point.

Return type:

list

prepare_geodata.get_geodata_from_place(place_name: str) → GeoDataFrame

Get geodata from a place name using the OSMnx library.

This function retrieves geodata from a place name using the OSMnx library. The data is filtered for buildings.

Parameters:

place_name (str) -- Location/Place name to get the geodata for. The name of the place must be a valid OSM place name.

Returns:

A GeoDataFrame containing building data for the specified place. If no data is found, None is returned.

Return type:

gpd.GeoDataFrame

prepare_geodata.get_geodata_from_polygon(polygon: Polygon) → GeoDataFrame

Get geodata from a polygon using the OSMnx library.

This function retrieves geodata from a polygon using the OSMnx library. The data is filtered for buildings.

Parameters:

polygon (shapely.geometry.polygon.Polygon) -- A shapely polygon object representing the area of interest. The polygon must be a valid shapely polygon.

Returns:

A GeoDataFrame containing building data for the specified polygon. If no data is found, None is returned.

Return type:

_type_

prepare_geodata.get_spec_HD(gdf_in: GeoDataFrame, path_spec_HD: str)

Get the specific heating demand of the buildings.

The specific heating demand is obtained from the excel file containing the specific heating demand data. The country speccific data can be obtained from the TABULA webtool: https://webtool.building-typology.eu/#bm and has to be adjusted to the format of the excel file.

Parameters:

• gdf_in (gpd.GeoDataFrame) -- GeoDataFrame containing the building data, including the year of construction and the building category.

• path_spec_HD (str) -- Path to the excel file containing the specific heating demand data.

prepare_geodata.get_yearly_HD(gdf_in: GeoDataFrame)

Calculate the yearly heating demand based on the specific heating demand and the heated area

Parameters:

gdf_in (gpd.GeoDataFrame) -- GeoDataFrame containing specific heating demand and heated area.

prepare_geodata.merge_other_data(gdf_in: GeoDataFrame) → GeoDataFrame

This function is a dummy to merge in other data sources like cadastre data if available.

If more accurate building data is available, it can be merged in here. The function is a placeholder for future development and does not do anything at the moment.

Parameters:

gdf_in (gpd.GeoDataFrame) -- GeoDataFrame containing the building data.

Returns:

A new GeoDataFrame containing the updated and merged building data.

Return type:

gpd.GeoDataFrame

prepare_geodata.polygon_by_circle(lat: float, lon: float, radius: float) → Polygon

Generate a polygon representing a circle around a given latitude and longitude.

Parameters:

• lat (float) -- Latitude of the center point.

• lon (float) -- Longitude of the center point.

• radius (float) -- Radius of the circle in kilometers.

Raises:

ValueError -- If the radius is negative or greater than 20 km.

Returns:

Returns a polygon representing the circle in the format of a shapely polygon.

Return type:

shapely.geometry.polygon.Polygon

prepare_geodata.remove_zero_area_buildings(gdf_in: GeoDataFrame) → GeoDataFrame

Removes buildings with a projected area of 0.

For buildings with zero area, no further analysis is possible. The buildings are removed from the GeoDataFrame to avoid errors in the subsequent analysis. Most buildings without a projected area might be buildings that are not residential or not heated.

Parameters:

gdf_in (gpd.GeoDataFrame) -- GeoDataFrame containing the building data.

Returns:

A new GeoDataFrame containing the building data without buildings with a projected area of 0.

Return type:

gpd.GeoDataFrame

prepare_geodata.write_buildingdata_to_disk(gdf_in: GeoDataFrame, casestudy: str, config: dict)

Write the building data to disk as a GeoJSON file.

The function checks if the directory for the case study exists and creates it if not. The building data is then written to disk in the specified format. :param gdf_in: GeoDataFrame containing the building data :type gdf_in: gpd.GeoDataFrame :param casestudy: name of the casestudy :type casestudy: str :param config: configuration dictionary :type config: dict