ecopipeline 1.0.5__py3-none-any.whl → 1.1.1__py3-none-any.whl

ecopipeline/event_tracking/alarms/Boundary.py

@@ -0,0 +1,90 @@
+import pandas as pd
+import numpy as np
+import datetime as datetime
+from ecopipeline import ConfigManager
+import re
+import mysql.connector.errors as mysqlerrors
+from datetime import timedelta
+from ecopipeline.event_tracking.Alarm import Alarm
+
+class Boundary(Alarm):
+    """
+    Detects when variable values fall outside their expected low/high boundary range for a sustained period.
+    An alarm triggers when a value stays below the low_alarm threshold or above the high_alarm threshold
+    for fault_time consecutive minutes.
+
+    Variable_Names.csv columns:
+    variable_name - Name of the variable to monitor
+    low_alarm - Lower bound threshold. Alarm triggers if value stays below this for fault_time minutes.
+    high_alarm - Upper bound threshold. Alarm triggers if value stays above this for fault_time minutes.
+    fault_time - (Optional) Number of consecutive minutes for this variable. Overrides default_fault_time.
+    pretty_name - (Optional) Display name for the variable in alarm messages. Defaults to variable_name.
+
+    Parameters
+    ----------
+    default_fault_time : int
+        Number of consecutive minutes that a value must be outside bounds before triggering an alarm (default 15).
+        Can be overridden per-variable using the fault_time column in Variable_Names.csv.
+    """
+    def __init__(self, bounds_df : pd.DataFrame, default_fault_time : int = 15):
+        self.default_fault_time = default_fault_time
+        super().__init__(bounds_df, None,{}, alarm_db_type='BOUNDARY')
+
+    def _process_bounds_df_alarm_codes(self, og_bounds_df : pd.DataFrame) -> pd.DataFrame:
+        bounds_df = og_bounds_df.copy()
+        required_columns = ["variable_name", "high_alarm", "low_alarm"]
+        for required_column in required_columns:
+            if not required_column in bounds_df.columns:
+                raise Exception(f"{required_column} is not present in Variable_Names.csv")
+        if not 'pretty_name' in bounds_df.columns:
+            bounds_df['pretty_name'] = bounds_df['variable_name']
+        else:
+            bounds_df['pretty_name'] = bounds_df['pretty_name'].fillna(bounds_df['variable_name'])
+        if not 'fault_time' in bounds_df.columns:
+            bounds_df['fault_time'] = self.default_fault_time
+        
+        bounds_df = bounds_df.loc[:, ["variable_name", "high_alarm", "low_alarm", "fault_time", "pretty_name"]]
+        bounds_df.dropna(axis=0, thresh=2, inplace=True)
+        bounds_df.set_index(['variable_name'], inplace=True)
+        # ensure that lower and upper bounds are numbers
+        bounds_df['high_alarm'] = pd.to_numeric(bounds_df['high_alarm'], errors='coerce').astype(float)
+        bounds_df['low_alarm'] = pd.to_numeric(bounds_df['low_alarm'], errors='coerce').astype(float)
+        bounds_df['fault_time'] = pd.to_numeric(bounds_df['fault_time'], errors='coerce').astype('Int64')
+        bounds_df = bounds_df[bounds_df.index.notnull()]
+        return bounds_df
+
+    def specific_alarm_function(self, df: pd.DataFrame, daily_df : pd.DataFrame, config : ConfigManager):
+        idx = df.index
+        full_days = pd.to_datetime(pd.Series(idx).dt.normalize().unique())
+        for bound_var, bounds in self.bounds_df.iterrows():
+            if bound_var in df.columns:
+                lower_mask = df[bound_var] < bounds["low_alarm"]
+                upper_mask = df[bound_var] > bounds["high_alarm"]
+                if pd.isna(bounds['fault_time']):
+                    bounds['fault_time'] = self.default_fault_time
+                for day in full_days:
+                    if bounds['fault_time'] < 1 :
+                        print(f"Could not process alarm for {bound_var}. Fault time must be greater than or equal to 1 minute.")
+                    self._check_and_add_alarm(lower_mask, day, bounds["fault_time"], bound_var, bounds['pretty_name'])
+                    self._check_and_add_alarm(upper_mask, day, bounds["fault_time"], bound_var, bounds['pretty_name'])
+    
+    def _check_and_add_alarm(self, mask : pd.Series, day, fault_time : int, var_name : str, pretty_name : str):
+        next_day = day + pd.Timedelta(days=1)
+        filtered_df = mask.loc[(mask.index >= day) & (mask.index < next_day)]
+        consecutive_condition = filtered_df.rolling(window=fault_time).min() == 1
+        if consecutive_condition.any():
+            group = (consecutive_condition != consecutive_condition.shift()).cumsum()
+
+            # Iterate through each streak and add an alarm for each
+            for group_id in consecutive_condition.groupby(group).first()[lambda x: x].index:
+                streak_indices = consecutive_condition[group == group_id].index
+                # streak_length = len(streak_indices)
+
+                # Adjust start time because first (fault_time-1) minutes don't count in window
+                start_time = streak_indices[0] - pd.Timedelta(minutes=fault_time-1)
+                end_time = streak_indices[-1]
+
+                alarm_string = f"Boundary alarm for {pretty_name}"
+
+                # if start_time in alarms_dict:
+                self._add_an_alarm(start_time, end_time, var_name, alarm_string)

ecopipeline/event_tracking/alarms/HPWHInlet.py

@@ -0,0 +1,73 @@
+import pandas as pd
+import numpy as np
+import datetime as datetime
+from ecopipeline import ConfigManager
+import re
+import mysql.connector.errors as mysqlerrors
+from datetime import timedelta
+from ecopipeline.event_tracking.Alarm import Alarm
+
+class HPWHInlet(Alarm):
+    """
+    Function will take a pandas dataframe and location of alarm information in a csv,
+    and create an dataframe with applicable alarm events
+
+    VarNames syntax:
+    HPINLET_POW_[OPTIONAL ID]:### - Indicates a power variable for the heat pump. ### is the power threshold (default 1.0) above which
+        the heat pump is considered 'on'
+    HPINLET_T_[OPTIONAL ID]:### - Indicates heat pump inlet temperature variable. ### is the temperature threshold (default 120.0)
+        that should not be exceeded while the heat pump is on
+
+    Parameters
+    ----------
+    default_power_threshold : float
+        Default power threshold for POW alarm codes when no custom bound is specified (default 0.4). Heat pump is considered 'on'
+        when power exceeds this value.
+    default_temp_threshold : float
+        Default temperature threshold for T alarm codes when no custom bound is specified (default 120.0). Alarm triggers when
+        temperature exceeds this value while heat pump is on.
+    fault_time : int
+        Number of consecutive minutes that both power and temperature must exceed their thresholds before triggering an alarm (default 10).
+
+    """
+    def __init__(self, bounds_df : pd.DataFrame, default_power_threshold : float = 1.0, default_temp_threshold : float = 115.0, fault_time : int = 5):
+        alarm_tag = 'HPINLET'
+        type_default_dict = {
+                'POW' : default_power_threshold,
+                'T' : default_temp_threshold
+            }
+        self.fault_time = fault_time
+        super().__init__(bounds_df, alarm_tag,type_default_dict, two_part_tag = True, alarm_db_type='HPWH_INLET')
+
+    def specific_alarm_function(self, df: pd.DataFrame, daily_df : pd.DataFrame, config : ConfigManager):
+        for alarm_id in self.bounds_df['alarm_code_id'].unique():
+            for day in daily_df.index:
+                next_day = day + pd.Timedelta(days=1)
+                filtered_df = df.loc[(df.index >= day) & (df.index < next_day)]
+                id_group = self.bounds_df[self.bounds_df['alarm_code_id'] == alarm_id]
+                pow_codes = id_group[id_group['alarm_code_type'] == 'POW']
+                pow_var_name = pow_codes.iloc[0]['variable_name']
+                pow_thresh = pow_codes.iloc[0]['bound']
+                t_codes = id_group[id_group['alarm_code_type'] == 'T']
+                t_var_name = t_codes.iloc[0]['variable_name']
+                t_pretty_name = t_codes.iloc[0]['pretty_name']
+                t_thresh = t_codes.iloc[0]['bound']
+                if len(t_codes) != 1 or len(pow_codes) != 1:
+                    raise Exception(f"Improper alarm codes for balancing valve with id {alarm_id}")
+                if pow_var_name in filtered_df.columns and t_var_name in filtered_df.columns:
+                    # Check for consecutive minutes where both power and temp exceed thresholds
+                    power_mask = filtered_df[pow_var_name] > pow_thresh
+                    temp_mask = filtered_df[t_var_name] > t_thresh
+                    combined_mask = power_mask & temp_mask
+
+                    # Check for fault_time consecutive minutes
+                    consecutive_condition = combined_mask.rolling(window=self.fault_time).min() == 1
+                    if consecutive_condition.any():
+                        group = (consecutive_condition != consecutive_condition.shift()).cumsum()
+                        for group_id in consecutive_condition.groupby(group).first()[lambda x: x].index:
+                            streak_indices = consecutive_condition[group == group_id].index
+                            start_time = streak_indices[0] - pd.Timedelta(minutes=self.fault_time - 1)
+                            end_time = streak_indices[-1]
+                            streak_length = len(streak_indices) + self.fault_time - 1
+                            self._add_an_alarm(start_time, end_time, t_var_name,
+                                f"High heat pump inlet temperature: {t_pretty_name} was above {t_thresh:.1f} F for {streak_length} minutes while HP was ON starting at {start_time}.")

ecopipeline/event_tracking/alarms/HPWHOutage.py

@@ -0,0 +1,96 @@
+import pandas as pd
+import numpy as np
+import datetime as datetime
+from ecopipeline import ConfigManager
+import re
+import mysql.connector.errors as mysqlerrors
+from datetime import timedelta
+from ecopipeline.event_tracking.Alarm import Alarm
+
+class HPWHOutage(Alarm):
+    """
+    Detects possible heat pump failures or outages by checking if heat pump power consumption falls below
+    an expected ratio of total system power over a rolling period, or by checking for non-zero values in
+    a direct alarm variable from the heat pump controller.
+
+    VarNames syntax:
+    HPOUTGE_POW_[OPTIONAL ID]:### - Heat pump power variable. ### is the minimum expected ratio of HP power to total power
+        (default 0.3 for 30%). Must be in same power units as total system power.
+    HPOUTGE_TP_[OPTIONAL ID] - Total system power variable for ratio comparison. Required when using POW codes.
+    HPOUTGE_ALRM_[OPTIONAL ID] - Direct alarm variable from HP controller. Alarm triggers if any non-zero value is detected.
+
+    Parameters
+    ----------
+    day_table_name : str
+        Name of the site's daily agregate value table in the database
+    default_power_ratio : float
+        Default minimum power ratio threshold (as decimal, e.g., 0.3 for 30%) for POW alarm codes when no custom bound is specified (default 0.3).
+        An alarm triggers if HP power falls below this ratio of total power over the rolling period.
+    ratio_period_days : int
+        Number of days to use for the rolling power ratio calculation (default 7). Must be greater than 1.
+    """
+    def __init__(self, bounds_df : pd.DataFrame, day_table_name : str, default_power_ratio : float = 0.3,
+                   ratio_period_days : int = 7):
+        alarm_tag = 'HPOUTGE'
+        type_default_dict = {
+                'POW': default_power_ratio,
+                'TP': None,
+                'ALRM': None
+            }
+        self.day_table_name = day_table_name # TODO this could be a security issue. Swap it for config manager
+        self.default_power_ratio = default_power_ratio
+        self.ratio_period_days = ratio_period_days
+        super().__init__(bounds_df, alarm_tag,type_default_dict, two_part_tag = True, alarm_db_type='HPWH_INLET')
+
+    def specific_alarm_function(self, df: pd.DataFrame, daily_df : pd.DataFrame, config : ConfigManager):
+        for alarm_id in self.bounds_df['alarm_code_id'].unique():
+            id_group = self.bounds_df[self.bounds_df['alarm_code_id'] == alarm_id]
+            # Get T and SP alarm codes for this ID
+            pow_codes = id_group[id_group['alarm_code_type'] == 'POW']
+            tp_codes = id_group[id_group['alarm_code_type'] == 'TP']
+            alrm_codes = id_group[id_group['alarm_code_type'] == 'ALRM']
+            if len(alrm_codes) > 0:
+                for i in range(len(alrm_codes)):
+                    alrm_var_name = alrm_codes.iloc[i]['variable_name']
+                    alrm_pretty_name = alrm_codes.iloc[i]['pretty_name']
+                    if alrm_var_name in df.columns:
+                        for day in daily_df.index:
+                            next_day = day + pd.Timedelta(days=1)
+                            filtered_df = df.loc[(df.index >= day) & (df.index < next_day)]
+                            if not filtered_df.empty:
+                                # Find all consecutive blocks where alarm variable is non-zero
+                                alarm_mask = filtered_df[alrm_var_name] != 0
+                                if alarm_mask.any():
+                                    # Find consecutive groups
+                                    group = (alarm_mask != alarm_mask.shift()).cumsum()
+
+                                    # Iterate through each consecutive block of non-zero values
+                                    for group_id in alarm_mask.groupby(group).first()[lambda x: x].index:
+                                        streak_indices = alarm_mask[group == group_id].index
+                                        start_time = streak_indices[0]
+                                        end_time = streak_indices[-1]
+                                        streak_length = len(streak_indices)
+                                        alarm_value = filtered_df.loc[start_time, alrm_var_name]
+
+                                        self._add_an_alarm(start_time, end_time, alrm_var_name,
+                                            f"Heat pump alarm triggered: {alrm_pretty_name} was {alarm_value} for {streak_length} minutes starting at {start_time}.")
+            elif len(pow_codes) > 0 and len(tp_codes) != 1:
+                raise Exception(f"Improper alarm codes for heat pump outage with id {alarm_id}. Requires 1 total power (TP) variable.")
+            elif len(pow_codes) > 0 and len(tp_codes) == 1:
+                if self.ratio_period_days <= 1:
+                    print("HP Outage alarm period, ratio_period_days, must be more than 1")
+                else: 
+                    tp_var_name = tp_codes.iloc[0]['variable_name'] 
+                    daily_df_copy = daily_df.copy()
+                    daily_df_copy = self._append_previous_days_to_df(daily_df_copy, config, self.ratio_period_days, self.day_table_name)
+                    for i in range(self.ratio_period_days - 1, len(daily_df_copy)):
+                        start_idx = i - self.ratio_period_days + 1
+                        end_idx = i + 1
+                        day = daily_df_copy.index[i]
+                        block_data = daily_df_copy.iloc[start_idx:end_idx].sum()
+                        for j in range(len(pow_codes)):
+                            pow_var_name = pow_codes.iloc[j]['variable_name']
+                            pow_var_bound = pow_codes.iloc[j]['bound']
+                            if block_data[pow_var_name] < block_data[tp_var_name] * pow_var_bound:
+                                self._add_an_alarm(day, day + timedelta(1), pow_var_name, f"Possible Heat Pump failure or outage.", False,
+                                                   certainty='med')

ecopipeline/event_tracking/alarms/HPWHOutlet.py

@@ -0,0 +1,85 @@
+import pandas as pd
+import numpy as np
+import datetime as datetime
+from ecopipeline import ConfigManager
+import re
+import mysql.connector.errors as mysqlerrors
+from datetime import timedelta
+from ecopipeline.event_tracking.Alarm import Alarm
+
+class HPWHOutlet(Alarm):
+    """
+    Detects low heat pump outlet temperature by checking if the outlet temperature falls below a threshold
+    while the heat pump is running. The first 10 minutes after each HP turn-on are excluded as a warmup
+    period. An alarm triggers if the temperature stays below the threshold for `fault_time` consecutive
+    minutes after the warmup period.
+
+    VarNames syntax:
+    HPOUTLT_POW_[OPTIONAL ID]:### - Indicates a power variable for the heat pump. ### is the power threshold (default 1.0) above which
+        the heat pump is considered 'on'.
+    HPOUTLT_T_[OPTIONAL ID]:### - Indicates heat pump outlet temperature variable. ### is the temperature threshold (default 140.0)
+        that should always be exceeded while the heat pump is on after the 10-minute warmup period.
+
+    Parameters
+    ----------
+    default_power_threshold : float
+        Default power threshold for POW alarm codes when no custom bound is specified (default 1.0). Heat pump is considered 'on'
+        when power exceeds this value.
+    default_temp_threshold : float
+        Default temperature threshold for T alarm codes when no custom bound is specified (default 140.0). Alarm triggers when
+        temperature falls BELOW this value while heat pump is on (after warmup period).
+    fault_time : int
+        Number of consecutive minutes that temperature must be below threshold (after warmup) before triggering an alarm (default 5).
+
+    """
+    def __init__(self, bounds_df : pd.DataFrame, default_power_threshold : float = 1.0, default_temp_threshold : float = 140.0, fault_time : int = 5):
+        alarm_tag = 'HPOUTLT'
+        type_default_dict = {
+                'POW' : default_power_threshold,
+                'T' : default_temp_threshold
+            }
+        self.fault_time = fault_time
+        super().__init__(bounds_df, alarm_tag,type_default_dict, two_part_tag = True, alarm_db_type='HPWH_OUTLET')
+
+    def specific_alarm_function(self, df: pd.DataFrame, daily_df : pd.DataFrame, config : ConfigManager):
+        for alarm_id in self.bounds_df['alarm_code_id'].unique():
+            for day in daily_df.index:
+                next_day = day + pd.Timedelta(days=1)
+                filtered_df = df.loc[(df.index >= day) & (df.index < next_day)]
+                id_group = self.bounds_df[self.bounds_df['alarm_code_id'] == alarm_id]
+                pow_codes = id_group[id_group['alarm_code_type'] == 'POW']
+                pow_var_name = pow_codes.iloc[0]['variable_name']
+                pow_thresh = pow_codes.iloc[0]['bound']
+                t_codes = id_group[id_group['alarm_code_type'] == 'T']
+                t_var_name = t_codes.iloc[0]['variable_name']
+                t_pretty_name = t_codes.iloc[0]['pretty_name']
+                t_thresh = t_codes.iloc[0]['bound']
+                if len(t_codes) != 1 or len(pow_codes) != 1:
+                    raise Exception(f"Improper alarm codes for balancing valve with id {alarm_id}")
+                if pow_var_name in filtered_df.columns and t_var_name in filtered_df.columns:
+                    # Check for consecutive minutes where both power and temp exceed thresholds
+                    power_mask = filtered_df[pow_var_name] > pow_thresh
+                    temp_mask = filtered_df[t_var_name] < t_thresh
+
+                    # Exclude first 10 minutes after each HP turn-on (warmup period)
+                    warmup_minutes = 10
+                    mask_changes = power_mask != power_mask.shift(1)
+                    run_groups = mask_changes.cumsum()
+                    cumcount_in_run = power_mask.groupby(run_groups).cumcount() + 1
+                    past_warmup_mask = power_mask & (cumcount_in_run > warmup_minutes)
+
+                    combined_mask = past_warmup_mask & temp_mask
+
+                    # Check for fault_time consecutive minutes
+                    consecutive_condition = combined_mask.rolling(window=self.fault_time).min() == 1
+                    if consecutive_condition.any():
+                        # Find all consecutive groups where condition is true
+                        group = (consecutive_condition != consecutive_condition.shift()).cumsum()
+                        for group_id in consecutive_condition.groupby(group).first()[lambda x: x].index:
+                            streak_indices = consecutive_condition[group == group_id].index
+                            start_time = streak_indices[0] - pd.Timedelta(minutes=self.fault_time - 1)
+                            end_time = streak_indices[-1]
+                            streak_length = len(streak_indices) + self.fault_time - 1
+                            actual_temp = filtered_df.loc[streak_indices[0], t_var_name]
+                            self._add_an_alarm(start_time, end_time, t_var_name,
+                                f"Low heat pump outlet temperature: {t_pretty_name} was {actual_temp:.1f} F (below {t_thresh:.1f} F) for {streak_length} minutes while HP was ON starting at {start_time}.")

ecopipeline/event_tracking/alarms/LSInconsist.py

@@ -0,0 +1,114 @@
+import pandas as pd
+import numpy as np
+import datetime as datetime
+from ecopipeline import ConfigManager
+import re
+import mysql.connector.errors as mysqlerrors
+from datetime import timedelta
+from ecopipeline.event_tracking.Alarm import Alarm
+
+class LSInconsist(Alarm):
+    """
+    Detects when reported loadshift mode does not match its expected value during a load shifting event.
+    An alarm is triggered if the variable value does not equal the expected value during the
+    time periods defined in the load shifting schedule for that mode.
+
+    VarNames syntax:
+    SOOSCHD_[mode]:### - Indicates a variable that should equal ### during [mode] load shifting events.
+        [mode] can be: normal, loadUp, shed, criticalPeak, gridEmergency, advLoadUp
+        ### is the expected value (e.g., SOOSCHD_loadUp:1 means the variable should be 1 during loadUp events)
+    """
+    def __init__(self, bounds_df : pd.DataFrame):
+        alarm_tag = 'SOOSCHD'
+        type_default_dict = {}
+        super().__init__(bounds_df, alarm_tag, type_default_dict, two_part_tag=True, alarm_db_type='LS_INCONSIST')
+
+    def specific_alarm_function(self, df: pd.DataFrame, daily_df : pd.DataFrame, config : ConfigManager):
+        ls_df = config.get_ls_df()
+        if ls_df.empty:
+            return # no load shifting events to check
+
+        valid_modes = ['loadUp', 'shed', 'criticalPeak', 'gridEmergency', 'advLoadUp']
+
+        for _, row in self.bounds_df.iterrows():
+            mode = row['alarm_code_type']
+            if mode not in valid_modes and mode != 'normal':
+                continue
+
+            var_name = row['variable_name']
+            pretty_name = row['pretty_name']
+            expected_value = row['bound']
+
+            if var_name not in df.columns:
+                continue
+
+            for day in daily_df.index:
+                next_day = day + pd.Timedelta(days=1)
+                filtered_df = df.loc[(df.index >= day) & (df.index < next_day)]
+
+                if filtered_df.empty:
+                    continue
+
+                if mode == 'normal':
+                    # For 'normal' mode, check periods NOT covered by any load shifting events
+                    normal_df = filtered_df.copy()
+                    if not ls_df.empty:
+                        mask = pd.Series(True, index=normal_df.index)
+                        for _, event_row in ls_df.iterrows():
+                            event_start = event_row['startDateTime']
+                            event_end = event_row['endDateTime']
+                            mask &= ~((normal_df.index >= event_start) & (normal_df.index < event_end))
+                        normal_df = normal_df[mask]
+
+                    if normal_df.empty:
+                        continue
+
+                    # Check if any values don't match the expected value during normal periods
+                    mismatch_mask = normal_df[var_name] != expected_value
+
+                    if mismatch_mask.any():
+                        # Find all consecutive streaks of mismatches
+                        group = (mismatch_mask != mismatch_mask.shift()).cumsum()
+
+                        for group_id in mismatch_mask.groupby(group).first()[lambda x: x].index:
+                            streak_indices = mismatch_mask[group == group_id].index
+                            start_time = streak_indices[0]
+                            end_time = streak_indices[-1]
+                            streak_length = len(streak_indices)
+                            actual_value = normal_df.loc[start_time, var_name]
+
+                            self._add_an_alarm(start_time, end_time, var_name,
+                                f"Load shift mode inconsistency: {pretty_name} was {actual_value} for {streak_length} minutes starting at {start_time} during normal operation (expected {expected_value}).")
+                else:
+                    # For load shifting modes, check periods covered by those specific events
+                    mode_events = ls_df[ls_df['event'] == mode]
+                    if mode_events.empty:
+                        continue
+
+                    # Check each load shifting event for this mode on this day
+                    for _, event_row in mode_events.iterrows():
+                        event_start = event_row['startDateTime']
+                        event_end = event_row['endDateTime']
+
+                        # Filter for data during this event
+                        event_df = filtered_df.loc[(filtered_df.index >= event_start) & (filtered_df.index < event_end)]
+
+                        if event_df.empty:
+                            continue
+
+                        # Check if any values don't match the expected value
+                        mismatch_mask = event_df[var_name] != expected_value
+
+                        if mismatch_mask.any():
+                            # Find all consecutive streaks of mismatches
+                            group = (mismatch_mask != mismatch_mask.shift()).cumsum()
+
+                            for group_id in mismatch_mask.groupby(group).first()[lambda x: x].index:
+                                streak_indices = mismatch_mask[group == group_id].index
+                                start_time = streak_indices[0]
+                                end_time = streak_indices[-1]
+                                streak_length = len(streak_indices)
+                                actual_value = event_df.loc[start_time, var_name]
+
+                                self._add_an_alarm(start_time, end_time, var_name,
+                                    f"Load shift mode inconsistency: {pretty_name} was {actual_value} for {streak_length} minutes starting at {start_time} during {mode} event (expected {expected_value}).")

ecopipeline/event_tracking/alarms/PowerRatio.py

@@ -0,0 +1,111 @@
+import pandas as pd
+import numpy as np
+import datetime as datetime
+from ecopipeline import ConfigManager
+import re
+import mysql.connector.errors as mysqlerrors
+from datetime import timedelta
+from ecopipeline.event_tracking.Alarm import Alarm
+
+class PowerRatio(Alarm):
+    """
+    Detects when power variables fall outside their expected ratio of total power over a rolling period.
+    Variables are grouped by alarm ID, and each variable's ratio is checked against its expected low-high
+    range as a percentage of the group total.
+
+    VarNames syntax:
+    POWRRAT_[ID]:###-### - Power variable to track. [ID] groups variables together for ratio calculation.
+        ###-### is the expected low-high percentage range (e.g., PR_HPWH:60-80 means this variable
+        should account for 60-80% of the HPWH group total).
+
+    Parameters
+    ----------
+    day_table_name : str
+        Name of the site's daily aggregate value table in the database for fetching historical data.
+    ratio_period_days : int
+        Number of days to use for the rolling power ratio calculation (default 7). Each block sums
+        the values over this many days before calculating ratios.
+    """
+    def __init__(self, bounds_df : pd.DataFrame, day_table_name : str, ratio_period_days : int = 7):
+        alarm_tag = 'POWRRAT'
+        type_default_dict = {}
+        self.ratio_period_days = ratio_period_days
+        self.day_table_name = day_table_name # TODO this could be a security issue. Swap it for config manager
+        super().__init__(bounds_df, alarm_tag,type_default_dict, two_part_tag = False, range_bounds=True, alarm_db_type='POWER_RATIO', daily_only=True)
+
+    def specific_alarm_function(self, df: pd.DataFrame, daily_df : pd.DataFrame, config : ConfigManager):
+        daily_df_copy = daily_df.copy()
+        if self.ratio_period_days > 1:
+            daily_df_copy = self._append_previous_days_to_df(daily_df_copy, config, self.ratio_period_days, self.day_table_name)
+        elif self.ratio_period_days < 1:
+            print("power ratio alarm period, ratio_period_days, must be more than 1")
+            return
+
+        # Create blocks of ratio_period_days
+        blocks_df = self._create_period_blocks(daily_df_copy)
+
+        if blocks_df.empty:
+            print("No complete blocks available for analysis")
+            return
+
+        for alarm_id in self.bounds_df['alarm_code_id'].unique():
+            # Calculate total for each block
+            var_list = self.bounds_df[self.bounds_df['alarm_code_id'] == alarm_id]['variable_name'].unique()
+            for var in var_list:
+                if var not in blocks_df.columns:
+                    blocks_df[var] = 0.0
+
+            blocks_df[alarm_id] = blocks_df[var_list].sum(axis=1)
+            for variable in var_list:
+                # Calculate ratio for each block
+                blocks_df[f"{variable}_{alarm_id}"] = (blocks_df[variable]/blocks_df[alarm_id]) * 100
+
+                # Get bounds from bounds_df for this variable and alarm_id
+                var_row = self.bounds_df[(self.bounds_df['variable_name'] == variable) & (self.bounds_df['alarm_code_id'] == alarm_id)]
+                if var_row.empty:
+                    continue
+                low_bound = var_row.iloc[0]['bound']
+                high_bound = var_row.iloc[0]['bound2']
+                pretty_name = var_row.iloc[0]['pretty_name']
+
+                alarm_blocks_df = blocks_df.loc[(blocks_df[f"{variable}_{alarm_id}"] < low_bound) | (blocks_df[f"{variable}_{alarm_id}"] > high_bound)]
+                if not alarm_blocks_df.empty:
+                    for block_end_date, values in alarm_blocks_df.iterrows():
+                        block_start_date = block_end_date - timedelta(days=self.ratio_period_days - 1)
+                        actual_ratio = values[f'{variable}_{alarm_id}']
+                        self._add_an_alarm(block_start_date, block_end_date + timedelta(1), variable,
+                            f"Power ratio alarm ({self.ratio_period_days}-day block ending {block_end_date.strftime('%Y-%m-%d')}): {pretty_name} accounted for {actual_ratio:.1f}% of {alarm_id} energy use. {low_bound:.1f}-{high_bound:.1f}% expected.", add_one_minute_to_end=False) 
+    
+    def _create_period_blocks(self, daily_df: pd.DataFrame, verbose: bool = False) -> pd.DataFrame:
+        """
+        Create blocks of ratio_period_days by summing values within each block.
+        Each block will be represented by its end date.
+        """
+        if len(daily_df) < self.ratio_period_days:
+            if verbose:
+                print(f"Not enough data for {self.ratio_period_days}-day blocks. Need at least {self.ratio_period_days} days but only have {len(daily_df)} days in data")
+            return pd.DataFrame()
+        
+        blocks = []
+        block_dates = []
+        
+        # Create blocks by summing consecutive groups of ratio_period_days
+        for i in range(self.ratio_period_days - 1, len(daily_df)):
+            start_idx = i - self.ratio_period_days + 1
+            end_idx = i + 1
+            
+            block_data = daily_df.iloc[start_idx:end_idx].sum()
+            blocks.append(block_data)
+            # Use the end date of the block as the identifier
+            block_dates.append(daily_df.index[i])
+        
+        if not blocks:
+            return pd.DataFrame()
+        
+        blocks_df = pd.DataFrame(blocks, index=block_dates)
+        
+        if verbose:
+            print(f"Created {len(blocks_df)} blocks of {self.ratio_period_days} days each")
+            print(f"Block date range: {blocks_df.index.min()} to {blocks_df.index.max()}")
+        
+        return blocks_df