ebm.model.energy_requirement module

yearly_reduction(x: DataFrame) → array[source]

calculate_for_building_category(database_manager: DatabaseManager = None)[source]

energy_need_improvements(energy_need_original_condition: DataFrame, improvement_building_upgrade: DataFrame, energy_need_improvements_policy: DataFrame, energy_need_yearly_reduction: DataFrame) → DataFrame[source]

Calculates energy requirements for a single building category

Parameters

energy_need_original_condition : pd.DataFrame improvement_building_upgrade : pd.DataFrame energy_need_improvements_policy : pd.DataFrame energy_need_yearly_reduction : pd.DataFrame

Returns

Iterable of pd.Series: indexed by year, building_category, TEK, purpose, building_condition column kwh_m2 representing energy requirement

energy_need_improvements_kwh_m2(energy_need_original_condition: DataFrame, reduction_per_condition: DataFrame, policy_improvement: DataFrame, yearly_improvement: DataFrame, df_years: DataFrame) → DataFrame[source]

calculate_energy_reduction(energy_requirements: DataFrame, policy_improvement: DataFrame, reduction_per_condition: DataFrame, yearly_improvement: DataFrame) → DataFrame[source]: Calculate and combine all reduction factors for energy needs into a single Dataframe.

Parameters

energy_requirements : pd.DataFrame policy_improvement : pd.DataFrame reduction_per_condition : pd.DataFrame yearly_improvement : pd.DataFrame

Returns

pd.DataFrame

merge_energy_requirement_reductions(condition_factor: DataFrame, yearly_improvements: DataFrame, reduction_policy: DataFrame) → DataFrame[source]

calculate_reduction_yearly(df_years: DataFrame, yearly_improvement: DataFrame) → DataFrame[source]

Calculate factor for yearly reduction for each entry in the DataFrame yearly_improvement.

This method merges the yearly improvement data with the policy improvement data, adjusts the efficiency start year if the period end year is greater, and calculates the yearly reduction based on the yearly efficiency improvement.

Parameters

df_yearspd.DataFrame: DataFrame containing all years for which to calculate factors. Must include column ‘year’.
yearly_improvementpd.DataFrame: DataFrame containing yearly improvement information. Must include columns ‘yearly_efficiency_improvement’, and ‘efficiency_start_year’.

Returns

pd.DataFrame: DataFrame with the calculated ‘reduction_yearly’ column and updated entries.

calculate_reduction_policy(policy_improvement: DataFrame, all_things: DataFrame) → DataFrame[source]

Calculate the reduction policy for each entry in the DataFrame.

This method computes the reduction policy by first calculating the number of years since the start of the period. It then applies the yearly_reduction function to each relevant entry to determine the reduction policy.

Parameters

policy_improvementpd.DataFrame: DataFrame containing policy improvement information. Must include columns ‘year’ and ‘period_start_year’.
all_things: pd.DataFrame: DataFrame containing every combination of building_category, TEK, purpose, year

Returns

pd.DataFrame: DataFrame with the calculated ‘reduction_policy’ column and updated entries.

calculate_reduction_condition(reduction_per_condition: DataFrame) → DataFrame[source]

Calculate the reduction condition for each entry in the DataFrame.

This method computes the reduction condition by subtracting the reduction share from 1.0. It also fills any NaN values in the ‘reduction_condition’ column with 1.0.

Parameters

reduction_per_conditionpd.DataFrame: DataFrame containing the reduction share information. Must include columns ‘reduction_share’ and ‘building_code’.

Returns

pd.DataFrame: DataFrame with the calculated ‘reduction_condition’ column and filtered entries.

Generate a cross-joined dataframe of building category, building code, purpose, building condition, and year.

This function normalizes all input arguments to single-column DataFrames and performs a series of cross merges to produce the full combinatorial dataset. It is typically used to prepare a structured index for energy modeling or building analytics.

Parameters

periodYearRange or None: A YearRange iterable providing the sequence of years to include. If None, defaults to YearRange(2020, 2050).
building_categoryDataFrame, list of str, or None, optional: Building categories to include. May be a DataFrame with a "building_category" column, a list of category strings, or None. If None, defaults to list(BuildingCategory).
building_codeDataFrame, list of str, or None, optional: Building codes to include. May be a DataFrame with a "building_code" column, a list of code strings, or None. If None, defaults to the predefined TEK code list.
purposeDataFrame, list of str, or None, optional: Energy purposes to include. May be a DataFrame with a "purpose" column, a list of purpose strings, or None. If None, defaults to list(EnergyPurpose).
building_conditionDataFrame, list of str, or None, optional: Building condition categories. May be a DataFrame with a "building_condition" column, a list of condition strings, or None. If None, defaults to BuildingCondition.existing_conditions().

Returns

DataFrame

A DataFrame containing the full Cartesian product of all input dimensions, with columns:

building_category
building_code
purpose
building_condition
year

Notes

All non-DataFrame inputs are converted to single-column DataFrames.
Cross joins are implemented using pandas.DataFrame.merge(..., how="cross").
The output is guaranteed to contain one row per unique combination of the input dimensions.

Examples

Generate a table using default categories and years:

>>> make_df_building_category_code_purpose_yearly(None).head()

Provide custom building codes and a custom year range:

>>> make_df_building_category_code_purpose_yearly(
...     period=YearRange(2025, 2030),
...     building_code=["TEK97", "TEK07"]
... )

main() → None[source]