ebm.model.area module
- transform_area_forecast_to_area_change(area_forecast: DataFrame, building_code_parameters: DataFrame | None = None) DataFrame[source]
Transform area forecast data into yearly area changes due to construction and demolition.
This function processes forecasted area data and optional building_code parameters to compute the net yearly area change. It distinguishes between construction (positive area change) and demolition (negative area change), and returns a combined DataFrame.
Parameters
- area_forecastpandas.DataFrame
A DataFrame containing forecasted building area data, including construction and demolition.
- building_code_parameterspandas.DataFrame, optional
A DataFrame containing building_code-related parameters used to refine construction data. If None, construction is assumed to be of TEK17. (transform_construction_by_year)
Returns
- pandas.DataFrame
A DataFrame with yearly area changes. Columns include: - ‘building_category’: Category of the building. - ‘building_code’: building_code classification. - ‘year’: Year of the area change. - ‘demolition_construction’: Indicates whether the change is due to ‘construction’ or ‘demolition’. - ‘m2’: Area change in square meters (positive for construction, negative for demolition).
Notes
Demolition areas are negated to represent area loss.
Missing values are filled with 0.0.
Assumes helper functions transform_construction_by_year and transform_cumulative_demolition_to_yearly_demolition are defined elsewhere.
- transform_cumulative_demolition_to_yearly_demolition(area_forecast: DataFrame) DataFrame[source]
Convert accumulated demolition area data to yearly demolition values.
This function filters the input DataFrame for rows where the building condition is demolition, and calculates the yearly change in square meters (m2) by computing the difference between consecutive years within each group defined by building category and building_code standard.
Parameters
- area_forecastpandas.DataFrame
A DataFrame containing forecasted building area data. Must include the columns: ‘building_category’, ‘building_code’, ‘year’, ‘building_condition’, and ‘m2’.
Returns
- pandas.DataFrame
A DataFrame with columns [‘building_category’, ‘building_code’, ‘year’, ‘m2’], where ‘m2’ represents the yearly demolition area (difference from the previous year). Missing values are filled with 0.
Notes
The function assumes that the input data is cumulative and sorted by year.
The first year in each group will have a demolition value of 0.
- transform_construction_by_year(area_forecast: DataFrame, building_code_parameters: DataFrame | None = None) DataFrame[source]
Calculate yearly constructed building area based on building_code parameters.
This function filters the input forecast data to include only construction (non-demolition) within the building_code-defined construction period. It then calculates the yearly change in constructed area (m2) for each combination of building category and building_code standard.
Parameters
- area_forecastpandas.DataFrame
A DataFrame containing forecasted building area data. Must include the columns: ‘building_category’, ‘building_code’, ‘year’, ‘building_condition’, and ‘m2’.
- building_code_parameterspandas.DataFrame or None, optional
A DataFrame containing building_code construction period definitions with columns: [‘building_code’, ‘building_year’, ‘period_start_year’, ‘period_end_year’]. If None, a default TEK17 period is used (2020–2050 with building year 2025).
Returns
- pandas.DataFrame
A DataFrame with columns [‘building_category’, ‘building_code’, ‘year’, ‘m2’], where ‘m2’ represents the yearly constructed area in square meters.
Notes
The function assumes that the input data is cumulative and calculates the difference between consecutive years to derive yearly values.
Construction is defined as all building conditions except ‘demolition’.
If no building_codeparameters are provided, a default TEK17 range is used.
- transform_demolition_construction(energy_use: DataFrame, area_change: DataFrame) DataFrame[source]
Calculate energy use in GWh for construction and demolition activities based on area changes.
This function filters energy use data for renovation and small measures, aggregates it by building category, TEK, and year, and merges it with area change data to compute the total energy use in GWh.
Parameters
- energy_usepandas.DataFrame
A DataFrame containing energy use data, including columns: - ‘building_category’ - ‘building_condition’ - ‘building_code’ - ‘year’ - ‘kwh_m2’
- area_changepandas.DataFrame
A DataFrame containing area changes due to construction and demolition, including columns: - ‘building_category’ - ‘building_code’ - ‘year’ - ‘demolition_construction’ - ‘m2’
Returns
- pandas.DataFrame
A DataFrame with the following columns: - ‘year’: Year of the activity. - ‘demolition_construction’: Indicates whether the activity is ‘construction’ or ‘demolition’. - ‘building_category’: Category of the building. - ‘building_code’: building_codeclassification. - ‘m2’: Area change in square meters. - ‘gwh’: Energy use in gigawatt-hours (GWh), calculated as (kWh/m² * m²) / 1,000,000.
Notes
Only energy use data with ‘building_condition’ equal to ‘renovation_and_small_measure’ is considered.
The merge is performed on ‘building_category’, ‘building_code’, and ‘year’.
- merge_building_code_and_condition(area_forecast: DataFrame) DataFrame[source]
Add general building_codeand building condition categories to area forecast data.
This function creates a copy of the input DataFrame and assigns the value ‘all’ to both the ‘building_code’ and ‘building_condition’ columns. This is useful for aggregating or analyzing data across all building_codetypes and building conditions.
Parameters
- area_forecastpandas.DataFrame
A DataFrame containing forecasted building area data, including at least the columns ‘building_code’ and ‘building_condition’.
Returns
- pandas.DataFrame
A modified copy of the input DataFrame where: - ‘building_code’ is set to ‘all’ - ‘building_condition’ is set to ‘all’
Notes
This function does not modify the original DataFrame in place.
Useful for creating aggregate views across all building_codeand condition categories.
- filter_existing_area(area_forecast: DataFrame) DataFrame[source]
Filter out demolition entries from area forecast data to retain only existing areas.
This function removes rows where the building condition is ‘demolition’ and returns a DataFrame containing only the relevant columns for existing building areas.
Parameters
- area_forecastpandas.DataFrame
A DataFrame containing forecasted building area data, including at least the columns: - ‘year’ - ‘building_category’ - ‘building_code’ - ‘building_condition’ - ‘m2’
Returns
- pandas.DataFrame
A filtered DataFrame containing only rows where ‘building_condition’ is not ‘demolition’, with the following columns: - ‘year’ - ‘building_category’ - ‘building_code’ - ‘building_condition’ - ‘m2’
Notes
The function returns a copy of the filtered DataFrame to avoid modifying the original.
Useful for isolating existing building stock from forecast data.