ebm 0.99.3__py3-none-any.whl

ebm/model/dataframemodels.py

@@ -0,0 +1,115 @@
+from typing import cast, Optional
+
+import pandas as pd
+import pandera as pa
+from pandera.typing import DataFrame, Series
+from pandera.typing.common import DataFrameBase
+
+from ebm.model.column_operations import explode_unique_columns, explode_column_alias
+from ebm.model.energy_purpose import EnergyPurpose
+
+
+class EnergyNeedYearlyImprovements(pa.DataFrameModel):
+    building_category: Series[str]
+    building_code: Series[str]
+    purpose: Series[str]
+    value: Series[float] = pa.Field(ge=0.0, coerce=True)
+    start_year: Optional[Series[int]] = pa.Field(coerce=True, default=2020)
+    function: Series[str]
+    end_year: Optional[Series[int]] = pa.Field(coerce=True, default=2050)
+    _filename = 'energy_need_improvements'
+
+    class Config:
+        unique = ['building_category', 'building_code', 'purpose', 'start_year', 'function', 'end_year']
+
+
+class YearlyReduction(pa.DataFrameModel):
+    building_category: Series[str]
+    building_code: Series[str]
+    purpose: Series[str]
+    start_year: Series[int] = pa.Field(coerce=True, default=2020)
+    end_year: Series[int] = pa.Field(coerce=True, default=2050)
+    yearly_efficiency_improvement: Series[float] = pa.Field(ge=0.0, coerce=True)
+
+    class Config:
+        unique = ['building_category', 'building_code', 'purpose', 'start_year', 'function', 'end_year']
+
+
+    @staticmethod
+    def from_energy_need_yearly_improvements(
+            en_yearly_improvement: DataFrameBase[EnergyNeedYearlyImprovements]|EnergyNeedYearlyImprovements) -> 'DataFrameBase[YearlyReduction]':
+        """
+        Transforms a EnergyNeedYearlyImprovement DataFrame into a EnergyNeedYearlyReduction DataFrame.
+
+        Parameters
+        ----------
+        en_yearly_improvement : DataFrame[EnergyNeedYearlyImprovements]
+
+        Returns
+        -------
+        DataFrameBase[YearlyReduction]
+
+        Raises
+        ------
+        pa.errors.SchemaError
+            When the resulting dataframe fails to validate
+        pa.errors.SchemaErrors
+            When the resulting dataframe fails to validate
+
+        """
+        unique_columns = ['building_category', 'building_code', 'purpose', 'start_year', 'end_year']
+
+        # Casting en_yearly_improvement to DataFrame so that type checkers complaining about datatype
+        df = cast(pd.DataFrame, en_yearly_improvement)
+        if 'start_year' not in df.columns:
+            df['start_year'] = 2020
+        if 'end_year' not in df.columns:
+            df['end_year'] = 2050
+        df = df.query('function=="yearly_reduction"')
+        df = explode_unique_columns(df,
+                                                       unique_columns=unique_columns)
+
+        df = explode_column_alias(df,
+                                                     column='purpose',
+                                                     values=[p for p in EnergyPurpose],
+                                                     alias='default',
+                                                     de_dup_by=unique_columns)
+        df['yearly_efficiency_improvement'] = df['value']
+        df = df[['building_category', 'building_code', 'purpose', 'start_year', 'end_year', 'yearly_efficiency_improvement']]
+        df = df.reset_index()
+        return YearlyReduction.validate(df, lazy=True)
+
+
+class PolicyImprovement(pa.DataFrameModel):
+    building_category: Series[str]
+    building_code: Series[str]
+    purpose: Series[str]
+    start_year: Series[int] = pa.Field(ge=0, coerce=True)
+    end_year: Series[int] = pa.Field(ge=0, coerce=True)
+    improvement_at_end_year: Series[float] = pa.Field(ge=0.0, lt=2.0, coerce=True)
+
+    class Config:
+        unique = ['building_category', 'building_code', 'purpose', 'start_year', 'end_year']
+
+    @pa.dataframe_check
+    def start_year_before_end_year(cls, df: pd.DataFrame) -> Series[bool]:
+        return df.start_year < df.end_year
+
+    @staticmethod
+    def from_energy_need_yearly_improvements(
+            energy_need_improvements: DataFrameBase[EnergyNeedYearlyImprovements] | EnergyNeedYearlyImprovements) -> 'DataFrameBase[PolicyImprovement]':
+
+        energy_need_improvements = cast(pd.DataFrame, energy_need_improvements)
+        df = energy_need_improvements.query('function=="improvement_at_end_year"')
+        if 'start_year' not in df.columns:
+            df['start_year'] = 2020
+        if 'end_year' not in df.columns:
+            df['end_year'] = 2050
+        unique_columns = ('building_category', 'building_code', 'purpose', 'start_year', 'function', 'end_year',)
+        df = explode_unique_columns(df, unique_columns=unique_columns)
+        df = explode_column_alias(df, column='purpose', values=[p for p in EnergyPurpose], alias='default',
+                                  de_dup_by=unique_columns)
+
+        df['improvement_at_end_year'] = df['value']
+
+        return PolicyImprovement.validate(df)

ebm/model/defaults.py

@@ -0,0 +1,30 @@
+import pandas as pd
+
+def default_calibrate_heating_rv() -> pd.DataFrame:
+    """Creates a default dataframe for heating_rv calibration. The factor is set to 1.0 (no change)
+
+    Returns
+    -------
+    pd.DataFrame
+    """
+    df = pd.DataFrame({
+        'building_category': ['non_residential', 'residential'],
+        'purpose': ['heating_rv', 'heating_rv'],
+        'heating_rv_factor': [1.0, 1.0]})
+    return df
+
+def default_calibrate_energy_consumption() -> pd.DataFrame:
+    """
+    Creates an empty dataframe for energy consumption calibration.
+
+    Returns
+    -------
+    pd.DataFrame
+    """
+    df = pd.DataFrame({
+        'building_category': [],
+        'to': [],
+        'from': [],
+        'factor': []}
+    )
+    return df

ebm/model/energy_need.py

@@ -0,0 +1,6 @@
+def transform_total_energy_need(energy_need_kwh_m2, area_forecast):
+    total_energy_need = area_forecast.reset_index().set_index(
+        ['building_category', 'building_code', 'building_condition', 'year']).merge(energy_need_kwh_m2, left_index=True,
+                                                                          right_index=True)
+    total_energy_need['energy_requirement'] = total_energy_need.kwh_m2 * total_energy_need.m2
+    return total_energy_need

ebm/model/energy_need_filter.py

@@ -0,0 +1,182 @@
+from typing import Optional
+
+import pandas as pd
+
+from ebm.model.building_category import BuildingCategory
+from ebm.model.building_condition import BuildingCondition
+from ebm.model.column_operations import replace_column_alias
+from ebm.model.energy_purpose import EnergyPurpose
+
+
+def filter_original_condition(df: pd.DataFrame, building_category: BuildingCategory|str, tek:str, purpose: str) -> pd.DataFrame:
+    """
+    Explode and deduplicates DataFrame df and returns rows matching building_category, tek, and purpose
+
+    Convenience function that does
+
+    ```python
+
+    exploded = explode_dataframe(df)
+    de_duped = de_dupe_dataframe(exploded)
+    filtered = de_duped[(de_duped.building_category==building_category) & (de_duped.building_code==tek) & (de_duped.purpose == purpose)]
+
+    ```
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+    building_category : BuildingCategory | str
+    tek : str
+    purpose : str
+
+    Returns
+    -------
+    pd.DataFrame
+
+    """
+    exploded = explode_dataframe(df)
+    de_duped = de_dupe_dataframe(exploded)
+    return de_duped[(de_duped.building_category==building_category) & (de_duped.building_code==tek) & (de_duped.purpose == purpose)]
+
+
+def filter_improvement_building_upgrade(df: pd.DataFrame, building_category: BuildingCategory|str, tek:str, purpose: str) -> pd.DataFrame:
+    """
+    Explode and deduplicates DataFrame df and returns rows matching building_category, tek, and purpose
+
+    Convenience function that does
+
+    ```python
+
+    exploded = explode_dataframe(df)
+    de_duped = de_dupe_dataframe(exploded)
+    filtered = de_duped[(de_duped.building_category==building_category) & (de_duped.building_code==tek) & (de_duped.purpose == purpose)]
+
+    ```
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+    building_category : BuildingCategory | str
+    tek : str
+    purpose : str
+
+    Returns
+    -------
+    pd.DataFrame
+
+    """
+    exploded = explode_dataframe(df)
+    de_duped = de_dupe_dataframe(exploded, unique_columns=['building_category', 'building_code', 'purpose', 'building_condition'])
+    filtered=de_duped[(de_duped.building_category==building_category) & (de_duped.building_code==tek) & (de_duped.purpose == purpose)]
+
+    filler_frame = pd.DataFrame([(building_category, tek, purpose, bc, 0.0) for bc in BuildingCondition.existing_conditions()],
+                                columns=['building_category', 'building_code', 'purpose', 'building_condition', 'reduction_share'])
+
+    return pd.concat([filtered, filler_frame]).drop_duplicates(['building_category', 'building_code', 'purpose', 'building_condition'], keep='first')
+
+
+def de_dupe_dataframe(df: pd.DataFrame, unique_columns: Optional[list[str]]=None) -> pd.DataFrame:
+    """
+    Drops duplicate rows in df based on building_category, TEK and purpose
+    same as
+        df.drop_duplicates(unique_columns)
+    Parameters
+    ----------
+    df : pd.DataFrame
+    unique_columns : list[str], optional
+                     default= ['building_category', 'building_code', 'purpose']
+
+    Returns
+    -------
+    pd.DataFrame
+
+    """
+    de_dupe_by = unique_columns if unique_columns else ['building_category', 'building_code', 'purpose']
+
+    de_duped = df.drop_duplicates(de_dupe_by)
+    return de_duped
+
+
+def explode_dataframe(df: pd.DataFrame, building_code_list:Optional[list[str]]=None) -> pd.DataFrame:
+    """
+    Explode column aliases for building_category, TEK, purpose in dataframe.
+
+    default in building_category is replaced with all options from BuildingCategory enum
+    default in TEK is replaced with all elements in optional building_code_list parameter
+    default in purpose is replaced with all options from EnergyPurpose enum
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+    building_code_list : list of TEK to replace default, Optional
+               default TEK49 PRE_TEK49 PRE_TEK49_RES_1950 TEK69 TEK87 TEK97 TEK07 TEK10 TEK17
+
+    Returns
+    -------
+    pd.DataFrame
+
+    """
+    if not building_code_list:
+        building_code_list = 'TEK49 PRE_TEK49 PRE_TEK49_RES_1950 TEK69 TEK87 TEK97 TEK07 TEK10 TEK17 TEK21 TEK01'.split(' ')
+    # expand building_category
+    df = replace_column_alias(df,
+                              column='building_category',
+                              values={'default': [b for b in BuildingCategory],
+                                      'residential': [b for b in BuildingCategory if b.is_residential()],
+                                      'non_residential': [b for b in BuildingCategory if not b.is_residential()]})
+    # expand tek
+    df = replace_column_alias(df, 'building_code', values=building_code_list, alias='default')
+
+    # expand purpose
+    df = replace_column_alias(df, 'purpose', values=[p for p in EnergyPurpose], alias='default')
+
+    # Add priorty column and sort
+    df['bc_priority'] = df.building_category.apply(lambda x: 0 if '+' not in x else len(x.split('+')))
+    df['t_priority'] = df.building_code.apply(lambda x: 0 if '+' not in x else len(x.split('+')))
+    df['p_priority'] = df.purpose.apply(lambda x: 0 if '+' not in x else len(x.split('+')))
+
+    if not 'priority' in df.columns:
+        df['priority'] = 0
+    df['priority'] = df.bc_priority + df.t_priority + df.p_priority
+
+    # Explode
+    df = df.assign(**{'building_category': df['building_category'].str.split('+'), }).explode('building_category')
+    df = df.assign(**{'building_code': df['building_code'].str.split('+')}).explode('building_code')
+    df = df.assign(**{'purpose': df['purpose'].str.split('+'), }).explode('purpose')
+    # dedupe
+    deduped = df.sort_values(by=['building_category', 'building_code', 'purpose', 'priority'])
+    deduped['dupe'] = deduped.duplicated(['building_category', 'building_code', 'purpose'], keep=False)
+    return deduped
+
+
+def main():
+    """
+    Explode and prints all files listed in command line arguments. Default is reading files from input/
+
+    """
+    import pathlib
+    import sys
+    def _load_file(infile):
+        df = pd.read_csv(infile)
+        building_code_list = 'TEK49 PRE_TEK49 TEK69 TEK87 TEK97 TEK07 TEK10 TEK17'.split(' ')
+
+        return explode_dataframe(df, building_code_list=building_code_list).sort_values(
+            by=['dupe', 'building_category', 'building_code', 'purpose', 'priority'])
+    pd.set_option('display.max_rows', None)
+    pd.set_option('display.max_columns', None)
+    pd.set_option('display.width', None)
+    if len(sys.argv) < 2:
+        files = list(pathlib.Path('input').glob('*.csv'))
+    else:
+        files = [pathlib.Path(f) for f in sys.argv[1:]]
+    for filename in files:
+        print(f'# {filename}')
+        try:
+            df = _load_file(filename)
+            print(df)
+        except KeyError as key_error:
+            print('KeyError: missing ', str(key_error), sys.stderr)
+
+
+if __name__ == '__main__':
+    main()

ebm/model/energy_purpose.py

@@ -0,0 +1,115 @@
+import typing
+
+from enum import StrEnum, unique, auto
+
+import pandas as pd
+
+from ebm.model.bema import BUILDING_CATEGORY_ORDER
+from ebm.model.bema import TEK_ORDER
+
+
+@unique
+class EnergyPurpose(StrEnum):
+    HEATING_RV = auto()
+    HEATING_DHW = auto()
+    FANS_AND_PUMPS = auto()
+    LIGHTING = auto()
+    ELECTRICAL_EQUIPMENT = auto()
+    COOLING = auto()
+
+    @classmethod
+    def _missing_(cls, value: str):
+        """
+        Attempts to create an enum member from a given value by normalizing the string.
+
+        This method is called when a value is not found in the enumeration. It converts the input value 
+        to lowercase, replaces spaces and hyphens with underscores, and then checks if this transformed 
+        value matches the value of any existing enum member.
+
+        Parameters
+        ----------
+        value : str
+            The input value to convert and check against existing enum members.
+
+        Returns
+        -------
+        Enum member
+            The corresponding enum member if a match is found.
+
+        Raises
+        ------
+        ValueError
+            If no matching enum member is found.
+        """
+        value = value.lower().replace(' ', '_').replace('-', '_')
+        for member in cls:
+            if member.value == value:
+                return member
+        return ValueError(f'Invalid purpose given: {value}')
+
+    def __repr__(self):
+        return f'{self.__class__.__name__}.{self.name}'
+
+    @classmethod
+    def other(cls) -> typing.Iterable['EnergyPurpose']:
+        return [cls.LIGHTING, cls.ELECTRICAL_EQUIPMENT, cls.FANS_AND_PUMPS]
+
+    @classmethod
+    def heating(cls) -> typing.Iterable['EnergyPurpose']:
+        return [cls.HEATING_RV, cls.HEATING_DHW]
+
+    @classmethod
+    def cooling(cls) -> typing.Iterable['EnergyPurpose']:
+        return [cls.COOLING]
+
+
+def group_energy_use_kwh_by_building_group_purpose_year_wide(energy_use_kwh: pd.DataFrame) -> pd.DataFrame:
+    df = (energy_use_kwh
+          .copy()
+          .reset_index()
+          .set_index(['building_category', 'building_condition', 'building_code', 'purpose', 'heating_systems', 'load', 'year'])
+          .sort_index())
+
+    df.loc[:, 'GWh'] = df.loc[:, 'kwh'] / 1_000_000
+    df.loc[:, ('building_code', 'building_condition')] = ('all', 'all')
+
+    df['building_group'] = 'non_residential'
+    df.loc['house', 'building_group'] = 'house'
+    df.loc['apartment_block', 'building_group'] = 'apartment_block'
+
+    summed = df.groupby(by=['building_group', 'purpose', 'year']).sum().reset_index()
+    summed = summed[['building_group', 'purpose', 'year', 'GWh']]
+
+    hz = summed.pivot(columns=['year'], index=['building_group', 'purpose'], values=['GWh']).reset_index()
+    hz = hz.sort_values(by=['building_group', 'purpose'],
+                        key=lambda x: x.map(BUILDING_CATEGORY_ORDER) if x.name == 'building_group' else x.map(
+                            TEK_ORDER) if x.name == 'building_code' else x.map(
+                            {'heating_rv': 1, 'heating_dhw': 2, 'fans_and_pumps': 3, 'lighting': 4,
+                             'electrical_equipment': 5, 'cooling': 6}) if x.name == 'purpose' else x)
+
+    hz.insert(2, 'U', 'GWh')
+    hz.columns = ['building_group', 'purpose', 'U'] + [y for y in range(2020, 2051)]
+
+    return hz.rename(columns={'building_group': 'building_category'})
+
+
+def group_energy_use_by_year_category_building_code_purpose(energy_use_kwh: pd.DataFrame) -> pd.DataFrame:
+    df = (energy_use_kwh.copy().reset_index()
+          .set_index(['building_category', 'building_condition', 'building_code', 'purpose', 'heating_systems', 'load', 'year'])
+          .sort_index())
+
+    df.loc[:, 'GWh'] = (df['m2'] * df['kwh_m2']) / 1_000_000
+
+    df = df.reset_index().groupby(by=['year', 'building_category', 'building_code', 'purpose'], as_index=False).sum()
+    df = df[['year', 'building_category', 'building_code', 'purpose', 'GWh']]
+    df = df.sort_values(by=['year', 'building_category', 'building_code', 'purpose'],
+                        key=lambda x: x.map(BUILDING_CATEGORY_ORDER) if x.name == 'building_category' else x.map(
+                            TEK_ORDER) if x.name == 'building_category' else x.map(
+                            TEK_ORDER) if x.name == 'building_code' else x.map(
+                            {'heating_rv': 1, 'heating_dhw': 2, 'fans_and_pumps': 3, 'lighting': 4,
+                             'electrical_equipment': 5, 'cooling': 6}) if x.name == 'purpose' else x)
+
+    df = df.rename(columns={'GWh': 'energy_use [GWh]'})
+
+    df.reset_index(inplace=True, drop=True)
+    return df