ebm.model.construction module

class ConstructionCalculator[source]

Bases: object

A class used to calculate various construction metrics for residential and commercial buildings.

The main method to use is calculate_construction

Methods

calculate_construction(building_category, demolition_floor_area, database_manager)

Calculate constructed floor area for buildings using provided demolition floor area and input data from
database manager.

calculate_construction_as_list(building_category, demolition_floor_area, database_manager=None)

Calculate constructed floor area for buildings using provided demolition floor area and input data: from database manager.

calculate_industrial_construction(building_category, total_floor_area, constructed_floor_area=None, demolition_floor_area=None, population=None)

Calculate the commercial construction metrics over a given period.

calculate_residential_construction(population, household_size, building_category_share, build_area_sum, yearly_demolished_floor_area, average_floor_area=175)

Calculate various residential construction metrics based on population, household size, and building data.

calculate_yearly_new_building_floor_area_sum(yearly_new_building_floor_area_house)

Calculate the accumulated constructed floor area over the years.

calculate_yearly_constructed_floor_area(build_area_sum, yearly_floor_area_change, yearly_demolished_floor_area)

Calculate the yearly constructed floor area based on changes and demolitions.

calculate_yearly_floor_area_change(building_change, average_floor_area=175)

Calculate the yearly floor area change based on building changes and average floor area.

calculate_population_growth(population)

Calculate the annual growth in population.

calculate_building_growth(building_category_share, households_change)

Calculate the annual growth in building categories based on household changes.

calculate_household_change(households)

Calculate the annual change in the number of households.

calculate_households_by_year(household_size, population)

Calculate the number of households by year based on household size and population.

calculate_residential_construction(population: Series, household_size: Series, building_category_share: Series, build_area_sum: Series, yearly_demolished_floor_area: Series, average_floor_area: Series | int = 175, period=YearRange(start=2010, end=2050)) → DataFrame[source]

Calculate various residential construction metrics based on population, household size, and building data.

Parameters

populationpd.Series: A pandas Series representing the population indexed by year.
household_sizepd.Series: A pandas Series representing the average household size over time.
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.
yearly_demolished_floor_areapd.Series: A pandas Series representing the yearly demolished floor area.
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 population growth, household changes, building growth, yearly constructed floor area, and accumulated constructed floor area.

static calculate_yearly_new_building_floor_area_sum(yearly_new_building_floor_area_house: 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.

static calculate_yearly_constructed_floor_area(build_area_sum: Series, yearly_floor_area_change: Series, yearly_demolished_floor_area: 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.
yearly_demolished_floor_areapd.Series: A pandas Series representing the yearly demolished 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.

static 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.

static calculate_population_growth(population: Series) → Series[source]

Calculate the annual growth in building categories based on household changes.

Parameters

populationpd.Series: A pandas Series representing the population indexed by year.

Returns

pd.Series: A pandas Series representing the annual growth population.

static 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’.

static 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’.

static 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.

static calculate_industrial_construction(building_category: BuildingCategory, total_floor_area: Series | int, constructed_floor_area: Series = None, demolition_floor_area: Series = None, population: Series = None, period=YearRange(start=2010, end=2050)) → DataFrame[source]

Calculate the industrial construction metrics over a given period.

Parameters

building_categoryBuildingCategory, optional: The category of the building.
total_floor_areapd.Series | int: The total floor area at the start of the period.
constructed_floor_areapd.Series, optional: Series containing the constructed floor area for each year.
demolition_floor_areapd.Series, optional: Series containing the demolished floor area for each year.
populationpd.DataFrame, optional: DataFrame containing the population data for each year.
periodYearRange: start and end of model in years

Returns

pd.DataFrame: DataFrame containing the calculated construction metrics: - total_floor_area: Total floor area for each year. - building_growth: Growth rate of the building floor area. - demolished_floor_area: Demolished floor area for each year. - constructed_floor_area: Constructed floor area for each year. - accumulated_constructed_floor_area: Cumulative constructed floor area. - floor_area_over_population_growth: Ratio of floor area growth over population growth.

Notes

If building_category is BuildingCategory.STORAGE_REPAIRS, the total floor area remains constant from 2010
to 2051.
The function assumes that the input Series and DataFrame have appropriate indices corresponding to the years.

static calculate_total_floor_area(floor_area_over_population_growth: Series, population_growth: Series, total_floor_area: Series, period: YearRange)[source]

Calculate the total floor area over a given period based on population growth.

Parameters

floor_area_over_population_growthpd.Series: A pandas Series containing the floor area change over population growth for each year.
population_growthpd.Series: A pandas Series containing the population growth for each year.
total_floor_areapd.Series: A pandas Series containing the total floor area for each year.
periodYearRange: A named tuple containing the start and end years of the period.

Returns

pd.Series: Updated pandas Series with the total floor area for each year in the given period.

Notes

The calculation starts from period.start + 5 to period.end. For each year, the total floor area is updated based on the formula:

total_floor_area[year] = ((change_ratio * pop_growth) + 1) * previous_floor_area

static calculate_constructed_floor_area(constructed_floor_area: Series, demolition_floor_area: Series, total_floor_area: Series, period: YearRange) → Series[source]

Calculate the constructed floor area over a specified period.

Parameters

constructed_floor_areapd.Series: A pandas Series to store the constructed floor area for each previous year.
demolition_floor_areapd.Series: A pandas Series containing the demolition floor area for each year.
total_floor_areapd.Series: A pandas Series containing the total floor area for each year.
periodYearRange: An object containing the start year, end year, and the range of years.

Returns

pd.Series: A pandas Series containing the constructed floor area for each year in the period.

Notes

The constructed floor area is calculated from year 6 onwards by subtracting the previous year’s floor area from the current year’s floor area and adding the previous year’s demolition floor area.

Examples

>>> construction = pd.Series({2020: 0, 2021: 0, 2022: 0, 2023: 0, 2024: 0, 2025: 0})
>>> demolition = pd.Series({2020: 50, 2021: 60, 2022: 70, 2023: 80, 2024: 90, 2025: 100})
>>> total = pd.Series({2020: 1000, 2021: 1100, 2022: 1200, 2023: 1300, 2024: 1400, 2025: 1500})
>>> years = YearRange(2020, 2025)
>>> ConstructionCalculator.calculate_constructed_floor_area(construction, demolition, total, years)
2020      0.0
2021      0.0
2022      0.0
2023      0.0
2024      0.0
2025    200.0
dtype: float64

static calculate_floor_area_growth(total_floor_area: Series, period: YearRange) → Series[source]

Calculate the growth of floor area over a specified period.

Parameters

total_floor_areapd.Series: A pandas Series containing the total floor area for each year.
periodYearRange: An object containing the start year, end year, and the range of years.

Returns

pd.Series: A pandas Series containing the floor area growth for each year in the period.

Notes

The growth for the first year in the period is set to NaN. The growth for the next four years is calculated based on the change in total floor area from the previous year.

Examples

>>> total_floor_area = pd.Series({2020: 1000, 2021: 1100, 2022: 1210, 2023: 1331, 2024: 1464})
>>> period = YearRange(2020, 2024)
>>> ConstructionCalculator.calculate_floor_area_growth(total_floor_area, period)
2020       NaN
2021    0.1000
2022    0.1000
2023    0.1000
2024    0.1000
dtype: float64

static calculate_floor_area_over_building_growth(building_growth: Series, population_growth: Series, years: YearRange) → Series[source]

Calculate the floor area over building growth for a given range of years.

Parameters

building_growthpd.Series: A pandas Series representing the building growth over the years.
population_growthpd.Series: A pandas Series representing the population growth over the years.
yearsYearRange: An object representing the range of years for the calculation.

Returns

pd.Series: A pandas Series representing the floor area over building growth for each year in the specified range.

Notes

The first year in the range is initialized with NaN.
For the first 4 years, the floor area over building growth is calculated directly from the building and population growth.
For the next 5 years, the mean floor area over building growth is used.
From the 11th year onwards, the value is set to 1.
For the years between the 11th and 21st, the value is interpolated linearly.

Examples

>>> building_growth = pd.Series([1.2, 1.3, 1.4, 1.5, 1.6], index=[2010, 2011, 2012, 2013, 2014])
>>> pd.Series([1.1, 1.2, 1.3, 1.4, 1.5], index=[2010, 2011, 2012, 2013, 2014])
>>> years = YearRange(start=2010, end=2050)
>>> ConstructionCalculator.calculate_floor_area_over_building_growth(building_growth, population_growth, years)
2010         NaN
2011    1.083333
2012    1.076923
2013    1.071429
2014    1.066667
2015    1.074588
2016    1.074588
…
2050    1.000000
2051    1.000000
dtype: float64

static calculate_construction_as_list(building_category: BuildingCategory, demolition_floor_area: Series | list, database_manager: DatabaseManager = None, period: YearRange = YearRange(start=2010, end=2050)) → List[float][source]

Calculates constructed floor area for buildings based using provided demolition_floor_area: and input data from database_manager

Parameters

building_category: BuildingCategory demolition_floor_area: pd.Series expects index=2010..2050 database_manager: DatabaseManager (optional) period : YearRange

Returns

accumulated_constructed_floor_area: List

static calculate_commercial_construction(building_category: BuildingCategory, population: Series, area_by_person: float | Series, demolition: Series) → DataFrame[source]

Calculate a projection of contructed floor area by building_category. The calculation makes the assumption that all demolished floor area will be replaced with construction.

Parameters

building_categoryBuildingCategory: possibly redundant building_category for the construction projection
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 accumalated contructed floor area

static calculate_construction(building_category: BuildingCategory, demolition_floor_area: Series | list, database_manager: DatabaseManager, period: YearRange) → DataFrame[source]

Calculates constructed floor area for buildings based using provided demolition_floor_area: and input data from database_manager

Parameters

building_category: BuildingCategory demolition_floor_area: pd.Series expects index=2010..2050 database_manager: DatabaseManager period : YearRange

Returns

calculated_construction: pd.DataFrame: dataframe columns include; (building_growth) (demolished_floor_area) (constructed_floor_area) (accumulated_constructed_floor_area) (total_floor_area) (floor_area_over_population_growth) (households) (household_size) (population) (population_growth)

static calculate_all_construction(demolition_by_year: Series | list, database_manager: DatabaseManager, period: YearRange) → DataFrame[source]

Parameters

demolition_by_year : pd.Series, List[float] database_manager : DatabaseManager period : YearRange

Returns

DataFrame:: with building_category and area