ecopipeline 1.0.4__py3-none-any.whl → 1.1.0__py3-none-any.whl

ecopipeline/event_tracking/alarms/SOOChange.py

@@ -0,0 +1,127 @@
+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 SOOChange(Alarm):
+    """
+    Detects unexpected state of operation (SOO) changes by checking if the heat pump turns on or off
+    when the temperature is not near the expected aquastat setpoint thresholds. An alarm is triggered
+    if the HP turns on/off and the corresponding temperature is more than 5.0 degrees away from the
+    expected threshold.
+
+    VarNames syntax:
+    SOOCHNG_POW:### - Indicates a power variable for the heat pump system (should be total power across all primary heat pumps). ### is the power threshold (default 1.0) above which
+        the heat pump system is considered 'on'.
+    SOOCHNG_ON_[Mode ID]:### - Indicates the temperature variable at the ON aquastat fraction. ### is the temperature (default 115.0)
+        that should trigger the heat pump to turn ON. Mode ID should be the load up mode from ['loadUp','shed','criticalPeak','gridEmergency','advLoadUp','normal'] or left blank for normal mode
+    SOOCHNG_OFF_[Mode ID]:### - Indicates the temperature variable at the OFF aquastat fraction (can be same as ON aquastat). ### is the temperature (default 140.0)
+        that should trigger the heat pump to turn OFF. Mode ID should be the load up mode from ['loadUp','shed','criticalPeak','gridEmergency','advLoadUp','normal'] or left blank for normal mode
+
+    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_on_temp : float
+        Default ON temperature threshold (default 115.0). When the HP turns on, an alarm triggers if the temperature
+        is more than 5.0 degrees away from this value.
+    default_off_temp : float
+        Default OFF temperature threshold (default 140.0). When the HP turns off, an alarm triggers if the temperature
+        is more than 5.0 degrees away from this value.
+    """
+    def __init__(self, bounds_df : pd.DataFrame, default_power_threshold : float = 1.0, default_on_temp : float = 115.0, default_off_temp : float = 140.0):
+        alarm_tag = 'SOO'
+        self.default_power_threshold = default_power_threshold
+        self.default_on_temp = default_on_temp
+        self.default_off_temp = default_off_temp
+        self.soo_dict = {
+                'loadUp' : 'LOAD UP',
+                'shed' : 'SHED',
+                'criticalPeak': 'CRITICAL PEAK',
+                'gridEmergency' : 'GRID EMERGENCY',
+                'advLoadUp' : 'ADVANCED LOAD UP'
+            }
+        type_default_dict = {
+                'POW' : default_power_threshold,
+                'ON' : default_on_temp,
+                'OFF' : default_off_temp
+            }
+        super().__init__(bounds_df, alarm_tag, type_default_dict, alarm_db_type='SOO_CHANGE')
+
+    def specific_alarm_function(self, df: pd.DataFrame, daily_df : pd.DataFrame, config : ConfigManager):
+        ls_df = config.get_ls_df()
+        pow_codes = self.bounds_df[self.bounds_df['alarm_code_type'] == 'POW']
+        if len(pow_codes) != 1:
+            raise Exception(f"Improper alarm codes for SOO changes; must have 1 POW variable to indicate power to HPWH(s).")
+        pow_var_name = pow_codes.iloc[0]['variable_name']
+        pow_thresh = pow_codes.iloc[0]['bound']
+        non_pow_bounds_df = self.bounds_df[self.bounds_df['alarm_code_type'] != 'POW']
+
+        for alarm_id in non_pow_bounds_df['alarm_code_id'].unique():
+            ls_filtered_df = df.copy()
+            soo_mode_name = 'NORMAL'
+            if alarm_id in self.soo_dict.keys():
+                if not ls_df.empty:
+                    # Filter ls_filtered_df for only date ranges in the right mode of ls_df
+                    mode_rows = ls_df[ls_df['event'] == alarm_id]
+                    mask = pd.Series(False, index=ls_filtered_df.index)
+                    for _, row in mode_rows.iterrows():
+                        mask |= (ls_filtered_df.index >= row['startDateTime']) & (ls_filtered_df.index < row['endDateTime'])
+                    ls_filtered_df = ls_filtered_df[mask]
+                    soo_mode_name = self.soo_dict[alarm_id]
+                else:
+                    print(f"Cannot check for {alarm_id} because there are no {alarm_id} periods in time frame.")
+                    continue
+            elif not ls_df.empty:
+                # Filter out all date range rows from ls_filtered_df's indexes
+                mask = pd.Series(True, index=ls_filtered_df.index)
+                for _, row in ls_df.iterrows():
+                    mask &= ~((ls_filtered_df.index >= row['startDateTime']) & (ls_filtered_df.index < row['endDateTime']))
+                ls_filtered_df = ls_filtered_df[mask]
+
+            for day in daily_df.index:
+                next_day = day + pd.Timedelta(days=1)
+                filtered_df = ls_filtered_df.loc[(ls_filtered_df.index >= day) & (ls_filtered_df.index < next_day)]
+                id_group = non_pow_bounds_df[non_pow_bounds_df['alarm_code_id'] == alarm_id]
+                on_t_codes = id_group[id_group['alarm_code_type'] == 'ON']
+                off_t_codes = id_group[id_group['alarm_code_type'] == 'OFF']
+                if len(on_t_codes) != 1 or len(off_t_codes) != 1:
+                    raise Exception(f"Improper alarm codes for SOO changes with id {alarm_id}. Must have 1 ON and 1 OFF variable")
+                on_t_var_name = on_t_codes.iloc[0]['variable_name']
+                on_t_pretty_name = on_t_codes.iloc[0]['pretty_name']
+                on_t_thresh = on_t_codes.iloc[0]['bound']
+                off_t_var_name = off_t_codes.iloc[0]['variable_name']
+                off_t_pretty_name = off_t_codes.iloc[0]['pretty_name']
+                off_t_thresh = off_t_codes.iloc[0]['bound']
+                if pow_var_name in filtered_df.columns:
+                    power_below = filtered_df[pow_var_name] <= pow_thresh
+                    power_above = filtered_df[pow_var_name] > pow_thresh
+
+                    # Check all turn-on events
+                    if on_t_var_name in filtered_df.columns:
+                        power_turn_on = power_below.shift(1) & power_above
+                        power_on_times = filtered_df.index[power_turn_on.fillna(False)]
+                        # Check if temperature is within 5.0 of on_t_thresh at each turn-on moment
+                        for power_time in power_on_times:
+                            temp_at_turn_on = filtered_df.loc[power_time, on_t_var_name]
+                            if abs(temp_at_turn_on - on_t_thresh) > 5.0:
+                                self._add_an_alarm(power_time, power_time, on_t_var_name,
+                                    f"Unexpected SOO change: during {soo_mode_name}, HP turned on at {power_time} but {on_t_pretty_name} was {temp_at_turn_on:.1f} F (setpoint at {on_t_thresh} F).",
+                                    certainty="med")
+
+                    # Check all turn-off events
+                    if off_t_var_name in filtered_df.columns:
+                        power_turn_off = power_above.shift(1) & power_below
+                        power_off_times = filtered_df.index[power_turn_off.fillna(False)]
+                        # Check if temperature is within 5.0 of off_t_thresh at each turn-off moment
+                        for power_time in power_off_times:
+                            temp_at_turn_off = filtered_df.loc[power_time, off_t_var_name]
+                            if abs(temp_at_turn_off - off_t_thresh) > 5.0:
+                                self._add_an_alarm(power_time, power_time, off_t_var_name,
+                                    f"Unexpected SOO change: during {soo_mode_name}, HP turned off at {power_time} but {off_t_pretty_name} was {temp_at_turn_off:.1f} F (setpoint at {off_t_thresh} F).",
+                                    certainty="med")

ecopipeline/event_tracking/alarms/ShortCycle.py

@@ -0,0 +1,59 @@
+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 ShortCycle(Alarm):
+    """
+    Detects short cycling by identifying when the heat pump turns on for less than `short_cycle_time`
+    consecutive minutes before turning off again. Short cycling can indicate equipment issues or
+    improper system sizing.
+
+    VarNames syntax:
+    SHRTCYC_[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'.
+
+    Parameters
+    ----------
+    default_power_threshold : float
+        Default power threshold when no custom bound is specified in the alarm code (default 1.0). Heat pump is considered 'on'
+        when power exceeds this value.
+    short_cycle_time : int
+        Minimum expected run time in minutes (default 15). An alarm triggers if the heat pump runs for fewer than this many
+        consecutive minutes before turning off.
+    """
+    def __init__(self, bounds_df : pd.DataFrame, default_power_threshold : float = 1.0, short_cycle_time : int = 15):
+        alarm_tag = 'SHRTCYC'
+        type_default_dict = {'default' : default_power_threshold}
+        self.short_cycle_time = short_cycle_time
+        super().__init__(bounds_df, alarm_tag,type_default_dict, two_part_tag = False, alarm_db_type='SHORT_CYCLE')
+
+    def specific_alarm_function(self, df: pd.DataFrame, daily_df : pd.DataFrame, config : ConfigManager):
+        for var_name in self.bounds_df['variable_name'].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)]
+                rows = self.bounds_df[self.bounds_df['variable_name'] == var_name]
+                pwr_thresh = rows.iloc[0]['bound']
+                var_pretty = rows.iloc[0]['pretty_name']
+                if len(rows) != 1:
+                    raise Exception(f"Multiple short cycle alarm codes set for {var_name}")
+                if var_name in filtered_df.columns:
+                    power_on_mask = filtered_df[var_name] > pwr_thresh
+
+                    # Find runs of consecutive True values by detecting changes in the mask
+                    mask_changes = power_on_mask != power_on_mask.shift(1)
+                    run_groups = mask_changes.cumsum()
+
+                    # For each run where power is on, check if it's shorter than short_cycle_time
+                    for group_id in run_groups[power_on_mask].unique():
+                        run_indices = filtered_df.index[(run_groups == group_id) & power_on_mask]
+                        run_length = len(run_indices)
+                        if run_length > 0 and run_length < self.short_cycle_time:
+                            start_time = run_indices[0]
+                            end_time = run_indices[-1]
+                            self._add_an_alarm(start_time, end_time, var_name, f"Short cycle: {var_pretty} was on for only {run_length} minutes starting at {start_time}.")

ecopipeline/event_tracking/alarms/TMSetpoint.py

@@ -0,0 +1,127 @@
+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 TMSetpoint(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:
+    TMNSTPT_T_ID:### - Swing Tank Outlet Temperature. Alarm triggered if over number ### (or 130) for 3 minutes with power on
+    TMNSTPT_SP_ID:### - Swing Tank Power. ### is lowest recorded power for Swing Tank to be considered 'on'. Defaults to 1.0
+    TMNSTPT_TP_ID:### - Total System Power for ratio alarming for alarming if swing tank power is more than ### (40% default) of usage
+    TMNSTPT_ST_ID:### - Swing Tank Setpoint that should not change at all from ### (default 130)
+
+    Parameters
+    ----------
+    default_fault_time : int
+        Number of consecutive minutes for T+SP alarms (default 3). T+SP alarms trigger when tank is powered and temperature exceeds
+        setpoint for this many consecutive minutes.
+    default_setpoint : float
+        Default temperature setpoint in degrees for T and ST alarm codes when no custom bound is specified (default 130.0)
+    default_power_indication : float
+        Default power threshold in kW for SP alarm codes when no custom bound is specified (default 1.0)
+    default_power_ratio : float
+        Default power ratio threshold (as decimal, e.g., 0.4 for 40%) for TP alarm codes when no custom bound is specified (default 0.4)
+    """
+    def __init__(self, bounds_df : pd.DataFrame, default_fault_time : int = 3, default_setpoint : float = 130.0, default_power_indication : float = 1.0,
+                             default_power_ratio : float = 0.4):
+        alarm_tag = 'TMNSTPT'
+        self.default_fault_time = default_fault_time
+        type_default_dict = {'T' : default_setpoint,
+                 'SP': default_power_indication,
+                 'TP': default_power_ratio,
+                 'ST': default_setpoint}
+        super().__init__(bounds_df, alarm_tag,type_default_dict, alarm_db_type='TM_SETPOINT')
+
+    def specific_alarm_function(self, df: pd.DataFrame, daily_df : pd.DataFrame, config : ConfigManager):
+        for day in daily_df.index:
+            next_day = day + pd.Timedelta(days=1)
+            filtered_df = df.loc[(df.index >= day) & (df.index < next_day)]
+            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
+                t_codes = id_group[id_group['alarm_code_type'] == 'T']
+                sp_codes = id_group[id_group['alarm_code_type'] == 'SP']
+                tp_codes = id_group[id_group['alarm_code_type'] == 'TP']
+                st_codes = id_group[id_group['alarm_code_type'] == 'ST']
+
+                # Check for multiple T or SP codes with same ID
+                if len(t_codes) > 1 or len(sp_codes) > 1 or len(tp_codes) > 1 or len(st_codes) > 1:
+                    raise Exception(f"Improper alarm codes for swing tank setpoint with id {alarm_id}")
+                trigger_columns_condition_met = False 
+                if len(st_codes) == 1:
+                    st_var_name = st_codes.iloc[0]['variable_name']
+                    st_setpoint = st_codes.iloc[0]['bound']
+                    st_pretty_name = st_codes.iloc[0]['pretty_name']
+                    # Check if st_var_name exists in filtered_df
+                    if st_var_name in filtered_df.columns:
+                        trigger_columns_condition_met = True
+                        # Check if setpoint was altered for over 10 minutes
+                        altered_mask = filtered_df[st_var_name] != st_setpoint
+                        consecutive_condition = altered_mask.rolling(window=10).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=9)
+                                end_time = streak_indices[-1]
+                                streak_length = len(streak_indices) + 9
+                                actual_value = filtered_df.loc[streak_indices[0], st_var_name]
+                                self._add_an_alarm(start_time, end_time, st_var_name,
+                                    f"Setpoint altered: {st_pretty_name} was {actual_value} for {streak_length} minutes starting at {start_time} (expected {st_setpoint}).")
+                # Check if we have both T and SP
+                if len(t_codes) == 1 and len(sp_codes) == 1:
+                    t_var_name = t_codes.iloc[0]['variable_name']
+                    t_pretty_name = t_codes.iloc[0]['pretty_name']
+                    sp_var_name = sp_codes.iloc[0]['variable_name']
+                    sp_pretty_name = sp_codes.iloc[0]['pretty_name']
+                    sp_power_indication = sp_codes.iloc[0]['bound']
+                    t_setpoint = t_codes.iloc[0]['bound']
+                    # Check if both variables exist in df
+                    if t_var_name in filtered_df.columns and sp_var_name in filtered_df.columns:
+                        trigger_columns_condition_met = True
+                        # Check for consecutive minutes where SP > default_power_indication
+                        # AND T >= default_setpoint
+                        power_mask = filtered_df[sp_var_name] >= sp_power_indication
+                        temp_mask = filtered_df[t_var_name] >= t_setpoint
+                        combined_mask = power_mask & temp_mask
+
+                        # Check for fault_time consecutive minutes
+                        consecutive_condition = combined_mask.rolling(window=self.default_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.default_fault_time - 1)
+                                end_time = streak_indices[-1]
+                                streak_length = len(streak_indices) + self.default_fault_time - 1
+                                actual_temp = filtered_df.loc[streak_indices[0], t_var_name]
+                                self._add_an_alarm(start_time, end_time, sp_var_name,
+                                    f"High TM Setpoint: {sp_pretty_name} showed draw for {streak_length} minutes starting at {start_time} while {t_pretty_name} was {actual_temp:.1f} F (above {t_setpoint} F).",
+                                    certainty="med")
+
+                if len(tp_codes) == 1 and len(sp_codes) == 1:
+                    tp_var_name = tp_codes.iloc[0]['variable_name']
+                    sp_var_name = sp_codes.iloc[0]['variable_name']
+                    sp_pretty_name = sp_codes.iloc[0]['pretty_name']
+                    tp_ratio = tp_codes.iloc[0]['bound']
+                    # Check if both variables exist in df
+                    if tp_var_name in daily_df.columns and sp_var_name in daily_df.columns:
+                        trigger_columns_condition_met = True
+                        # Check if swing tank power ratio exceeds threshold
+                        if day in daily_df.index and daily_df.loc[day, tp_var_name] != 0:
+                            power_ratio = daily_df.loc[day, sp_var_name] / daily_df.loc[day, tp_var_name]
+                            if power_ratio > tp_ratio:
+                                self._add_an_alarm(day, day + timedelta(1), sp_var_name,
+                                    f"High temperature maintenance power ratio: {sp_pretty_name} accounted for {power_ratio * 100:.1f}% of daily power (threshold {tp_ratio * 100}%).",
+                                    certainty="low")

ecopipeline/event_tracking/alarms/TempRange.py

@@ -0,0 +1,84 @@
+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 TempRange(Alarm):
+    """
+    Detects when a temperature value falls outside an acceptable range for
+    too long. An alarm is triggered if the temperature is above the high bound or below the low bound
+    for `fault_time` consecutive minutes.
+
+    VarNames syntax:
+    TMPRANG_[OPTIONAL ID]:###-### - Indicates a temperature variable. ###-### is the acceptable temperature range
+        (e.g., TMPRANG:110-130 means temperature should stay between 110 and 130 degrees).
+
+    Parameters
+    ----------
+    df: pd.DataFrame
+        Post-transformed dataframe for minute data. It should be noted that this function expects consecutive, in order minutes. If minutes
+        are out of order or have gaps, the function may return erroneous alarms.
+    daily_df: pd.DataFrame
+        Post-transformed dataframe for daily data. Used for determining which days to process.
+    config : ecopipeline.ConfigManager
+        The ConfigManager object that holds configuration data for the pipeline. Among other things, this object will point to a file
+        called Variable_Names.csv in the input folder of the pipeline (e.g. "full/path/to/pipeline/input/Variable_Names.csv").
+        The file must have at least two columns which must be titled "variable_name" and "alarm_codes" which should contain the
+        name of each variable in the dataframe that requires alarming and the DHW alarm codes (e.g., DHW:110-130, DHW_1:115-125).
+    system: str
+        String of system name if processing a particular system in a Variable_Names.csv file with multiple systems. Leave as an empty string if not applicable.
+    default_high_temp : float
+        Default high temperature bound when no custom range is specified in the alarm code (default 130). Temperature above this triggers alarm.
+    default_low_temp : float
+        Default low temperature bound when no custom range is specified in the alarm code (default 130). Temperature below this triggers alarm.
+    fault_time : int
+        Number of consecutive minutes that temperature must be outside the acceptable range before triggering an alarm (default 10).
+
+    Returns
+    -------
+    pd.DataFrame:
+        Pandas dataframe with alarm events
+    """
+    def __init__(self, bounds_df : pd.DataFrame, default_high_temp : float = 130, default_low_temp : float = 115, fault_time : int = 10):
+        alarm_tag = 'TMPRANG'
+        type_default_dict = {'default': [default_low_temp, default_high_temp]}
+        self.fault_time = fault_time
+        super().__init__(bounds_df, alarm_tag,type_default_dict, two_part_tag = False, range_bounds=True, alarm_db_type='TEMP_RANGE')
+
+    def specific_alarm_function(self, df: pd.DataFrame, daily_df : pd.DataFrame, config : ConfigManager):
+        # Process each unique alarm_code_id
+        for dhw_var in self.bounds_df['variable_name'].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)]
+                rows = self.bounds_df[self.bounds_df['variable_name'] == dhw_var]
+                low_bound = rows.iloc[0]['bound']
+                high_bound = rows.iloc[0]['bound2']
+                pretty_name = rows.iloc[0]['pretty_name']
+
+                if dhw_var in filtered_df.columns:
+                    # Check if temp is above high bound or below low bound
+                    out_of_range_mask = (filtered_df[dhw_var] > high_bound) | (filtered_df[dhw_var] < low_bound)
+
+                    # Check for fault_time consecutive minutes
+                    consecutive_condition = out_of_range_mask.rolling(window=self.fault_time).min() == 1
+                    if consecutive_condition.any():
+                        # Find all streaks of consecutive True values
+                        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=self.fault_time-1)
+                            end_time = streak_indices[-1]
+                            adjusted_streak_length = streak_length + self.fault_time - 1
+
+                            self._add_an_alarm(start_time, end_time, dhw_var,
+                                f"Temperature out of range: {pretty_name} was outside {low_bound}-{high_bound} F for {adjusted_streak_length} consecutive minutes starting at {start_time}.")