PyHeatDemand API Reference#

PyHeatDemand - Processing#

The API reference provides an overview of all functions and methods implemented in PyHeatDemand.

Contributors: Alexander Jüstel, Elias Khashfe, Eileen Herbst

pyheatdemand.processing.calculate_hd(hd_gdf: geopandas.geodataframe.GeoDataFrame, mask_gdf: Union[geopandas.geodataframe.GeoDataFrame, shapely.geometry.polygon.Polygon], hd_data_column: str = '') → geopandas.geodataframe.GeoDataFrame#

Calculate Heat Demand.

Parameters

  • hd_gdf (gpd.GeoDataFrame) – Heat demand data as GeoDataFrame.

  • mask_gdf (Union[gpd.GeoDataFrame, shapely.geometry.Polygon]) – Mask for the output Heat Demand Data.

  • hd_data_column (str, default: '') – Name of the column that contains the Heat Demand Data, e.g. hd_data_column='HD'.

Returns

gdf_hd – Output GeoDataFrame with Heat Demand Data. Data columns are as follows:

Index

Index of each heat demand cell

HD

Heat demand of each cell

geometry

Geometry of the heat demand cell

Other columns

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> gdf_hd = processing.calculate_hd(hd_gdf=hd_gdf, mask_gdf=mask_gdf, hd_data_column='HD')
>>> gdf_hd

Index

HD

geometry

0

111.620963

POLYGON ((3726770.877 2671399.353, 3726870.877…

1

142.831789

POLYGON ((3726770.877 2671499.353, 3726870.877…

2

20.780601

POLYGON ((3726770.877 2671699.353, 3726870.877…

See also

calculate_hd_sindex

Calculate Heat Demand using Spatial Indices.

pyheatdemand.processing.calculate_hd_sindex(hd_gdf: geopandas.geodataframe.GeoDataFrame, mask_gdf: Union[geopandas.geodataframe.GeoDataFrame, shapely.geometry.polygon.Polygon], hd_data_column: str = '') → geopandas.geodataframe.GeoDataFrame#

Calculate Heat Demand using Spatial Indices.

Parameters

  • hd_gdf (gpd.GeoDataFrame) – Heat demand data as GeoDataFrame.

  • mask_gdf (Union[gpd.GeoDataFrame, shapely.geometry.Polygon]) – Mask for the output Heat Demand Data.

  • hd_data_column (str, default: '') – Name of the column that contains the Heat Demand Data, e.g. hd_data_column='HD'.

Returns

gdf_hd – Output GeoDataFrame with Heat Demand Data. Data columns are as follows:

Index

Index of each heat demand cell

HD

Heat demand of each cell

geometry

Geometry of the heat demand cell

Other columns

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> gdf_hd = processing.calculate_hd_sindex(hd_gdf=hd_gdf, mask_gdf=mask_gdf, hd_data_column='HD')
>>> gdf_hd

Index

HD

geometry

0

111.620963

POLYGON ((3726770.877 2671399.353, 3726870.877…

1

142.831789

POLYGON ((3726770.877 2671499.353, 3726870.877…

2

20.780601

POLYGON ((3726770.877 2671699.353, 3726870.877…
pyheatdemand.processing.calculate_hd_street_segments(gdf_buildings: geopandas.geodataframe.GeoDataFrame, gdf_roads: geopandas.geodataframe.GeoDataFrame, hd_data_column: str) → geopandas.geodataframe.GeoDataFrame#

Calculate heat demand for street segments based on the heat demand of the nearest houses.

Parameters

  • gdf_buildings (gpd.GeoDataFrame) – GeoDataFrame holding the building footprints.

  • gdf_roads (gpd.GeoDataFrame) – GeoDataFrame holding the street segments.

  • hd_data_column (str) – Name of the column that contains the Heat Demand Data, e.g. hd_data_column='HD'.

Returns

gdf_hd – GeoDataFrame consisting of the street segments and the cumulated heat demand. Data columns are as follows:

Index

Index of each heat demand cell

HD_normalized

Heat demand of each LineString

geometry

Geometry of the heat demand LineString

Other columns

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

New in version 0.0.9.

Examples

>>> gdf_hd = calculate_hd_street_segments(gdf_buildings=buildings, gdf_roads=roads, hd_data_column='HD')
>>> gdf_hd

Index

HD_normalized

geometry

0

111.620963

LINESTRING ((3726770.877 2671399.353, 3726870.877…

1

142.831789

LINESTRING ((3726770.877 2671499.353, 3726870.877…

2

20.780601

LINESTRING ((3726770.877 2671699.353, 3726870.877…
pyheatdemand.processing.calculate_zonal_stats(path_mask: str, path_raster: str, crs: Union[str, pyproj.crs.crs.CRS], calculate_heated_area: bool = True) → geopandas.geodataframe.GeoDataFrame#

Calculate zonal statistics and return GeoDataFrame.

Parameters

  • path_mask (str) – Path to the mask for the zonal statistics, e.g. path_mask='mask.shp'.

  • path_raster (str) – Path to the raster for the zonal statistics, e.g. path_raster='raster.tif'.

  • crs (str, pyproj.crs.crs.CRS) – Coordinate Reference System to pass to the GeoDataFrame, e.g. crs='EPSG:3034'.

  • calculate_heated_area (bool, default: True) – Boolean value to calculate the heated area, e.g. calculate_heated_area=True.

Returns

gdf – Output GeoDataFrame containing the input geometries and the output zonal statistics.

Index

Index of each geometry

geometry

Geometry of the input Vector Data Set

min

Minimum Heat Demand value within the geometry

max

Maximum Heat Demand value within the geometry

std

Standard Deviation of the Heat Demand values within the geometry

median

Median Heat Demand value within the geometry

Area (planimetric)

Area of the geometry

Total Heat Demand

Total Heat Demand of the geometry

Average Heat demand per unit area

Average Heat Demand per unit area

Share of Total HD [%]

Share of the total Heat Demand of this geometry

Share of Total Area [%]

Share of the total area of this geometry

Heated Area

Area that actually contains heat demand values within the geometry

Share of Heated Area [%]

Share of the area that actually contains heat demand values

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> gdf_stats = calculate_zonal_stats(path_mask='mask.shp', path_raster='raster.tif', crs='EPSG:3034')
>>> gdf_stats

Index

geometry

min

max

std

median

Area (planimetric)

Total Heat Demand

Average Heat demand per unit area

Share of Total HD [%]

Share of Total Area [%]

Heated Area

Share of Heated Area [%]

0

POLYGON ((3854043.358 2686588.658, 3854042.704…

3.024974e-06

21699.841028

351.107975

88.114117

7.471599e+09

4.689531e+07

206.001944

21.437292

23.485618

2.276161e+09

30.464174

1

POLYGON ((3922577.630 2751867.434, 3922590.877…

6.662710e-08

40566.944918

265.277509

46.066755

6.086689e+09

2.959064e+07

134.484551

13.526791

19.132405

2.200020e+09

36.144783

2

MULTIPOLYGON (((3815551.417 2711668.010, 38155…

3.148388e-06

71665.631370

382.872868

106.194020

6.866552e+09

5.063581e+07

217.321986

23.147186

21.583762

2.329694e+09

33.928151
pyheatdemand.processing.convert_dtype(path_in: str, path_out: str)#

Convert dtype of raster.

Parameters

  • path_in (str) – Input path of the raster, e.g. path_in='input.tif'.

  • path_out (str) – Output path of the converted raster, e.g. path_out='output.tif'

Examples

>>> processing.convert_dtype(path_in='input.tif', path_out='output.tif')

New in version 0.0.9.

pyheatdemand.processing.create_connection(linestring: shapely.geometry.linestring.LineString, point: shapely.geometry.point.Point) → shapely.geometry.linestring.LineString#

Create LineString between Point and LineString.

Parameters

  • linestring (shapely.geometry.LineString) – LineString representing a street segment.

  • point (shapely.geometry.Point) – Point representing the centroid of a building footprint, e.g. point= POINT(100, 100).

Returns

linestring_connection – Shortest connection between the centroid of a building footprint and a street segment.

Return type

shapely.geometry.LineString

Raises

TypeError – If the wrong input data types are provided.

New in version 0.0.9.

Examples

>>> linestring_connection = processing.create_connection(linestring=linestring, point=point)
>>> linestring_connection.wkt
'LINESTRING (292607.59635341103 5627766.391411121, 292597.58816236566 5627776.171055705)'
pyheatdemand.processing.create_connections(gdf_buildings: geopandas.geodataframe.GeoDataFrame, gdf_roads: geopandas.geodataframe.GeoDataFrame, hd_data_column: str = None) → geopandas.geodataframe.GeoDataFrame#

Create LineString between Points and LineStrings.

Parameters

  • gdf_buildings (gpd.GeoDataFrame) – GeoDataFrame holding the building footprints.

  • gdf_roads (gpd.GeoDataFrame) – GeoDataFrame holding the street segments.

  • hd_data_column (str, default: None) – Name of the column that contains the Heat Demand Data, e.g. hd_data_column='HD'.

Returns

gdf_connections – GeoDataFrame holding the connections between the houses and the street segments. Data columns are as follows:

Index

Index of each connection

geometry

Geometry of each connection

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

New in version 0.0.9.

Examples

>>> gdf_connections = create_connections(gdf_buildings=buildings, gdf_roads=roads)
>>> gdf_connections

Index

geometry

0

LINESTRING (292726.502 5627866.823, 292705.144…

1

LINESTRING (292725.657 5627862.826, 292705.613…

2

LINESTRING (292726.502 5627866.823, 292705.144…
pyheatdemand.processing.create_outline(gdf: geopandas.geodataframe.GeoDataFrame) → geopandas.geodataframe.GeoDataFrame#

Create outline from GeoDataFrame.

Parameters

gdf (gpd.GeoDataFrame) – GeoDataFrame holding the Heat Demand Data.

Returns

outline – Outline GeoDataFrame. Data columns are as follows:

Index

Index of the outline

geometry

Geometry of the outline

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> gdf = processing.create_outline(gdf=gdf)
>>> gdf

Index

geometry

0

POLYGON ((3744005.190 2671457.082, 3744005.190…
pyheatdemand.processing.create_polygon_mask(gdf: Union[geopandas.geodataframe.GeoDataFrame, shapely.geometry.polygon.Polygon], step_size: int, crop_gdf: bool = False, crs: Union[str, pyproj.crs.crs.CRS] = None) → geopandas.geodataframe.GeoDataFrame#

Create a mask GeoDataFrame consisting of squares with a defined step_size.

Parameters

  • gdf (Union[gpd.GeoDataFrame, shapely.geometry.Polygon]) – GeoDataFrame/Polygon over which a mask is created.

  • step_size (int) – Size of the rasterized squares in meters, e.g. step_size=100.

  • crop_gdf (bool, default: False) – Boolean to either crop the GeoDataFrame to the outline or return it as is, e.g. crop_gdf=False.

  • crs (Union[str, pyproj.crs.crs.CRS], default: None) – Coordinate Reference System when providing Shapely Polygons as input.

Returns

gdf_mask – GeoDataFrame containing the masked polygons.

Index

Index of each mask polygon

geometry

Geometry of each mask polygon

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> mask = create_polygon_mask(gdf=gdf, step_size=100, crop_gdf=True)
>>> mask

Index

geometry

0

POLYGON ((2651470.877 2135999.353, 2661470.877…

1

POLYGON ((2651470.877 2145999.353, 2661470.877…

2

POLYGON ((2651470.877 2155999.353, 2661470.877…
pyheatdemand.processing.get_building_footprint(point: shapely.geometry.point.Point, dist: int) → geopandas.geodataframe.GeoDataFrame#

Get Building footprint from Shapely Point.

Parameters

  • point (shapely.geometry.Point) – Point that corresponds to a building. CRS must be ‘EPSG:4326’, e.g. point=Point(6.54, 51.23).

  • dist (int) – Distance around the point to get features, e.g. dist=25.

Returns

gdf – GeoDataFrame containing the building footprint. Data columns are as follows:

Index

Index of the building footprint

element_type

Element type of bulding gootprint

osmid

OpenStreetMap ID number

nodes

Nodes of the building footprint

addr:city

City where the building footprint is located

addr:housenumber

Housenumber of the building footpring

addr:postcode

Post code of the building footprint

addr:street

Street of the building footprint

amenity

Feature of the building footprint

geometry

Geometry of the building footprint

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> gdf_building = get_building_footprint(point=Point(6.54, 51.23), dist=25)
>>> gdf_building

Index

element_type

osmid

nodes

addr:city

addr:housenumber

addr:postcode

addr:street

amenity

0

way

60170820

[747404971, 1128780263, 1128780085, 1128780530…

Kamen

1

59174

Rathausplatz

townhall
pyheatdemand.processing.get_building_footprints(points: geopandas.geodataframe.GeoDataFrame, dist: int, perform_sjoin: bool = True) → geopandas.geodataframe.GeoDataFrame#

Get Building footprints from GeoDataFrame.

Parameters

  • points (gpd.GeoDataFrame) – GeoDataFrame containing the Points.

  • dist (int) – Distance around the points to get features, e.g. dist=25.

  • perform_sjoin (bool, default: True) – Boolean to perform a spatial join to filter out additional buildings, e.g. perform_sjoin=True.

Returns

gdf – GeoDataFrame containing the building footprints. Data columns are as follows:

Index

Index of the building footprint

element_type

Element type of bulding gootprint

osmid

OpenStreetMap ID number

nodes

Nodes of the building footprint

addr:city

City where the building footprint is located

addr:housenumber

Housenumber of the building footpring

addr:postcode

Post code of the building footprint

addr:street

Street of the building footprint

amenity

Feature of the building footprint

geometry

Geometry of the building footprint

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> gdf_buildings = get_building_footprints(points=gdf_addresses, dist=25)
>>> gdf_buildings

Index

element_type

osmid

nodes

addr:city

addr:housenumber

addr:postcode

addr:street

amenity

0

way

60170820

[747404971, 1128780263, 1128780085, 1128780530…

Kamen

1

59174

Rathausplatz

townhall

1

way

60170821

[747405971, 1128781263, 1128784085, 1128786530…

Kamen

5

59174

Rathausplatz

townhall
pyheatdemand.processing.merge_rasters(file_names: list, path_out: str) → rasterio.io.DatasetReader#

Merge rasters.

Parameters

  • file_names (list) – List of file names, e.g. file_names=['raster1.tif', 'raster2.tif'].

  • path_out (str) – Output path for merged raster, e.g. path_out='raster_merged.tif'.

Returns

mosaic – Merged raster.

Return type

rasterio.io.DatasetReader

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> merge_rasters(file_names=['raster1.tif', 'raster2.tif'], path_out='raster_merged.tif')
pyheatdemand.processing.obtain_coordinates_from_addresses(df: pandas.core.frame.DataFrame, street_column: str, house_number_column: str, postal_code_column: str, location_column: str, output_crs: Union[str, pyproj.crs.crs.CRS]) → geopandas.geodataframe.GeoDataFrame#

Obtain coordinates from building addresses.

Parameters

  • df (pd.DataFrame) – DataFrame containing the address data.

  • street_column (str) – Name for the column containing the street name, e.g. street_column='Street'.

  • house_number_column (str) – Name for the column containing the house number, e.g. house_number_column='Number'.

  • postal_code_column (str) – Name for the column containing the postal code, e.g. postal_code_column='Postal Code'.

  • location_column (str) – Name for the column containing the location name, e.g. location_column='City'.

  • output_crs (str, pyproj.crs.crs.CRS) – Output coordinate reference system, e.g. crs='EPSG:3034'

Returns

gdf – Output GeoDataFrame containing the Coordinates of the street addresses. Data columns are as follows:

Index

Index of each address

Unnamed: 0

Index of each address

HeatDemand

Heat Demand of each address

Street

Street name of each address

Number

House number of each address

Postal Code

Postal code of each address

City

City of each address

address

Address

geometry

Geometry of each address

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> gdf_addresses = obtain_coordinates_from_addresses(df=df, street_column='Street',
... house_number_column='Number', postal_code_column='Postal Code', location_column='City',
... output_crs='EPSG:3034')
>>> gdf_addresses

Index

Unnamed: 0

HeatDemand

Street

Number

Postal Code

City

address

geometry

0

0

431905.208696

Rathausplatz

1

59174

Kamen

Rathausplatz 1 59174 Kamen

POINT (3843562.447 2758094.896)

1

1

1858.465217

Rathausplatz

1

59174

Kamen

Rathausplatz 1 59174 Kamen

POINT (3843562.447 2758094.896)

2

2

28594.673913

Rathausplatz

4

59174

Kamen

Rathausplatz 4 59174 Kamen

POINT (3843569.733 2758193.784)
pyheatdemand.processing.quad_tree_mask_refinement(mask: geopandas.geodataframe.GeoDataFrame, data: geopandas.geodataframe.GeoDataFrame, max_depth: int = 4, num_of_points: Union[int, list] = 100) → geopandas.geodataframe.GeoDataFrame#

Quad Tree Mask Refinement.

Parameters

  • mask (gpd.GeoDataFrame) – Original mask.

  • data (gpd.GeoDataFrame) – Heat demand data, usually polygons.

  • max_depth (int, default: 4) – Number of refinements, e.g. max_depth=4.

  • num_of_points (Union[int, list], default: 100) – Number of points that need to be in one cell for refinement, e.g. num_of_points=100.

Returns

grid_refs – GeoDataFrame containing the refined mask polygons. Data columns are as follows:

Index

Index of each mask polygon

geometry

Geometry of each mask polygon

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

New in version 0.0.9.

Examples

>>> mask = quad_tree_mask_refinement(mask=mask, data=data, max_depth=4, num_of_points=[150, 150, 100, 50])
>>> mask

Index

geometry

0

POLYGON ((2651470.877 2135999.353, 2661470.877…

1

POLYGON ((2651470.877 2145999.353, 2661470.877…

2

POLYGON ((2651470.877 2155999.353, 2661470.877…
pyheatdemand.processing.rasterize_gdf_hd(gdf_hd: geopandas.geodataframe.GeoDataFrame, path_out: str, crs: Union[str, pyproj.crs.crs.CRS] = 'EPSG:3034', xsize: int = 100, ysize: int = 100, flip_raster: bool = True)#

Rasterize Heat Demand GeoDataFrame and save as raster.

Parameters

  • gdf_hd (GeoDataFrame) – GeoDataFrame with Heat Demand Data.

  • path_out (str) – Output file path for the heat demand raster, e.g. path_out='raster.tif'.

  • crs (str, pyproj.crs.crs.CRS, default: 'EPSG:3034') – Output coordinate reference system, e.g. crs='EPSG:3034'.

  • xsize (int, default: 100) – Cell size of the output raster, e.g. xsize=100.

  • ysize (int, default: 100) – Cell size of the output raster, e.g. ysize=100.

  • flip_raster (bool, default: True) – Boolean value to flip the raster.

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> rasterize_gdf_hd(gdf_hd=gdf_hd, path_out='raster.tif', crs='EPSG:3034', xsize=100, ysize=100)
pyheatdemand.processing.refine_mask(mask: geopandas.geodataframe.GeoDataFrame, data: geopandas.geodataframe.GeoDataFrame, num_of_points: int, cell_size: int, area_limit: Union[float, int] = None) → geopandas.geodataframe.GeoDataFrame#

Refine polygon mask.

Parameters

  • mask (gpd.GeoDataFrame) – Original mask.

  • data (gpd.GeoDataFrame) – Heat demand data, usually polygons.

  • num_of_points (int) – Number of points that need to be in one cell for refinement, e.g. num_of_points=100.

  • cell_size (int) – Cell size of the new cells, cell size should be a divisor of the original cell size, e.g. cell_size=1000.

  • area_limit (Union[float, int]) – For multiple refinements, the area limit can be defined to only further refine already refined cells, e.g. area_limit=10000.

Returns

grid_refs – GeoDataFrame containing the refined mask polygons. Data columns are as follows:

Index

Index of each mask polygon

geometry

Geometry of each mask polygon

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

New in version 0.0.9.

Examples

>>> mask = refine_mask(mask=mask, data=data, num_of_points=100, cell_size=1000)
>>> mask

Index

geometry

0

POLYGON ((2651470.877 2135999.353, 2661470.877…

1

POLYGON ((2651470.877 2145999.353, 2661470.877…

2

POLYGON ((2651470.877 2155999.353, 2661470.877…
pyheatdemand.processing.vectorize_raster(path: str, merge_polygons: bool = True) → geopandas.geodataframe.GeoDataFrame#

Vectorize Raster.

Parameters

  • path (str) – Path to raster file, e.g. path='raster.tif'.

  • merge_polygons (bool, default: True) – Boolean to state if the polygons should be merged or if every single pixel should be return as polygon, e.g. merge_polygons=True.

Returns

gdf – GeoDataFrame containing the Polygons of the vectorized raster. Data columns are as follows:

Index

Index of each raster cell

geometry

Geometry of each raster cell

class

Value of each raster cell

Return type

gpd.GeoDataFrame

Raises

TypeError – If the wrong input data types are provided.

Changed in version 0.0.9.

Examples

>>> gdf = vectorize_raster(path='raster.tif')
>>> gdf

Index

geometry

class

0

POLYGON ((4038305.864 3086142.360, 4038305.864…

0.292106

1

POLYGON ((4038405.844 3086142.360, 4038405.844…

41.289803

2

POLYGON ((4038505.823 3086142.360, 4038505.823…

61.701653