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.
- building_condition_scurves(scurve_parameters: DataFrame) DataFrame[source]
Calculate yearly rate for building_condition s-curves for building_category, building_code and year.
Parameters
- scurve_parameterspd.DataFrame
Scurve parameters as define in the scurve.csv.
Returns
- pd.DataFrame
Yearly accumulated scurves by building_category, building_code, and building_code
- building_condition_accumulated_scurves(scurve_parameters: DataFrame) DataFrame[source]
Calculate accumulated building_condition s-curves for building_category, building_code and year.
Parameters
- scurve_parameterspd.DataFrame
Scurve parameters as define in the scurve.csv.
Returns
- pd.DataFrame
Yearly accumulated scurves by building_category, building_code, and building_code
- multiply_s_curves_with_floor_area(s_curves_by_condition: DataFrame, with_area: DataFrame) DataFrame[source]
Multiply existing area with s_curves_by_condition to figure out building condition by year.
Parameters
- s_curves_by_conditionpd.DataFrame
s_curves dataframe with building_category, building_condition and year.
- with_area :
Total floor area for building_category and building_code.
Returns
- pd.DataFrame
yearly floor area for each building_category, building_code and building_condition
- merge_total_area_by_year(construction_by_building_category_yearly: Series, existing_area: DataFrame) DataFrame[source]
Merge Constructed area with existing area.
Parameters
- construction_by_building_category_yearlypd.Series
Floor area constructed by year with columns building_category, year.
- existing_areapd.DataFrame
Existing area by year with columns building_category, year.
Returns
- pd.DataFrame
Dataframe with constructed and existing area
- calculate_existing_area(area_parameters: DataFrame, building_code_parameters: DataFrame, years: YearRange) DataFrame[source]
Calculate the existing building area over a range of years based on area parameters and building codes.
Parameters
- area_parameterspd.DataFrame
A DataFrame indexed by ‘building_category’ and ‘building_code’, containing area-related data.
- building_code_parameterspd.DataFrame
A DataFrame containing at least a ‘building_code’ column, used to define valid codes.
- yearsYearRange
A sequence of years (e.g., list, range, or array-like) over which to compute the existing area.
Returns
- pd.DataFrame
A DataFrame indexed by [‘building_category’, ‘building_code’, ‘year’] with merged area data, including all combinations of categories, codes, and years.
- construction_with_building_code(building_category_demolition_by_year: Series, building_code: DataFrame, construction_floor_area_by_year: DataFrame, years: YearRange) DataFrame[source]
Merge building_category demolition floor area by year with building_code.
Parameters
- building_category_demolition_by_yearpd.Series
floor area demolished by year
- building_codepd.DataFrame
building_code_parameters dataframe
- construction_floor_area_by_yearpd.DataFrame
floor area constructed by building_category and year
- yearsYearRange
period years
Returns
- pd.DataFrame
Merged building_category demolition floor area by year with building_code
- sum_building_category_demolition_by_year(demolition_by_year: Series) Series[source]
Return sum of demolition by building_category and year.
Parameters
- demolition_by_yearpd.Series
Yearly demolition with building_category, year and optional column building_code
Returns
- pd.Series
Demolished floor area by building_category and year
- calculate_demolition_floor_area_by_year(area_parameters: DataFrame, s_curve_demolition: Series, years: YearRange = YearRange(start=2020, end=2050)) Series[source]
Calculate the demolition floor area by year multiplying area parameters and the S-curve.
Parameters
- area_parameterspandas.DataFrame
A multi-indexed DataFrame containing floor area data. Expected to include an ‘area’ column. The index should include year information to filter between 2020 and 2050.
- s_curve_demolitionpandas.Series
A Series representing the demolition S-curve values indexed by year.
- yearsYearRange
YearRange of all years that will to present in demolition_by_year
Returns
- pandas.Series
A Series named ‘demolition’ representing the calculated demolition floor area for each year between 2020 and 2050.
- calculate_commercial_construction(population: Series, area_by_person: float | Series, demolition: Series) DataFrame[source]
Calculate a projection of constructed floor area by using population and floor_area_by_person.
Parameters
- populationpd.Series
population by year
- area_by_personpd.Series
float or pd.Series containing the floor area per person for the building_category
- demolitionpd.Series
yearly demolition to be added to the floor area.
Returns
- pd.Dataframe
floor area constructed by year accumulated contracted floor area
- calculate_residential_construction(households_by_year: Series, building_category_share: Series, build_area_sum: Series, average_floor_area: Series | int = 175, period: YearRange = YearRange(start=2010, end=2050)) DataFrame[source]
Calculate various residential construction metrics based on population, household size, and building data.
Parameters
- households_by_yearpd.Series
A pandas Series representing the total number of households by year.
- building_category_sharepd.Series
A pandas Series representing the share of each building category.
- build_area_sumpd.Series
A pandas Series representing the accumulated building area sum.
- average_floor_areapd.Series|int
Average floor area of each building of this type
- periodYearRange
contains start and end year for the model
Returns
- pd.DataFrame
A pandas DataFrame containing various residential construction metrics.
Notes
The function calculates several metrics including yearly constructed floor area, accumulated constructed floor area.
- calculate_yearly_new_building_floor_area_sum(yearly_new_building_floor_area_house: Series) Series[source]
Calculate the accumulated constructed floor area over the years.
Parameters
- yearly_new_building_floor_area_housepd.Series
A pandas Series representing the yearly new building floor area.
Returns
- pd.Series
- A pandas Series representing the accumulated constructed floor area, named
‘accumulated_constructed_floor_area’.
Notes
The function calculates the cumulative sum of the yearly new building floor area.
- calculate_yearly_constructed_floor_area(build_area_sum: Series, yearly_floor_area_change: Series) Series[source]
Calculate the yearly constructed floor area based on changes and demolitions.
Parameters
- build_area_sumpd.Series
A pandas Series representing the accumulated building area sum.
- yearly_floor_area_changepd.Series
A pandas Series representing the yearly change in floor area.
Returns
- pd.Series
A pandas Series representing the yearly constructed floor area, named ‘constructed_floor_area’.
Notes
The function calculates the yearly new building floor area by adding the yearly floor area change to the yearly demolished floor area. It then updates the values based on the build_area_sum index.
- calculate_yearly_floor_area_change(building_change: Series, average_floor_area: Series | int = 175) Series[source]
Calculate the yearly floor area change based on building changes and average floor area.
Parameters
- building_changepd.Series
A pandas Series representing the change in the number of buildings.
- average_floor_areatyping.Union[pd.Series, int], optional
The average floor area per building. Can be a pandas Series or an integer. Default is 175.
Returns
- pd.Series
A pandas Series representing the yearly floor area change, named ‘house_floor_area_change’.
Notes
- The function calculates the yearly floor area change by multiplying the building change by the average floor
area.
The floor area change for the first two years set to 0.
- calculate_building_growth(building_category_share: Series, households_change: Series) Series[source]
Calculate the annual growth in building categories based on household changes.
Parameters
- building_category_sharepd.Series
A pandas Series representing the share (0 to 1 ) of each building category.
- households_changepd.Series
A pandas Series representing the annual change in the number of households.
Returns
- pd.Series
A pandas Series representing the annual growth in building categories, named ‘building_growth’.
- calculate_household_change(households: Series) Series[source]
Calculate the annual change in the number of households.
Parameters
- householdspd.Series
A pandas Series representing the number of households over time.
Returns
- pd.Series
A pandas Series representing the annual change in the number of households, named ‘household_change’.
- calculate_households_by_year(household_size: Series, population: Series) Series[source]
Calculate the number of households by year based on household size and population.
Parameters
- household_sizepd.Series
A pandas Series representing the average household size over time.
- populationpd.Series
A pandas Series representing the population over time.
Returns
- pd.Series
A pandas Series representing the number of households by year, named ‘households’.
Notes
The function calculates the number of households by dividing the population by the average household size.
- calculate_construction_with_demolition(construction_by_building_category_and_year: DataFrame, demolition_floor_area_by_year: Series) DataFrame[source]
- calculate_construction(building_category_demolition_by_year: Series, years: YearRange, area_per_person: Series, yearly_construction_floor_area: Series, new_buildings_population: DataFrame, new_buildings_category_shares) DataFrame[source]
Calculate construction for different building_categories.
Parameters
new_buildings_category_shares : new_buildings_population : yearly_construction_floor_area : area_per_person : building_category_demolition_by_year : pd.DataFrame
yearly demolition for building categories
- yearsYearRange
period for construction
Returns
- pd.DataFrame
dataframe with columns constructed_floor_area, accumulated_constructed_floor_area, demolished_floor_area