ecopipeline 1.0.4__tar.gz → 1.1.0__tar.gz

{ecopipeline-1.0.4/src/ecopipeline.egg-info → ecopipeline-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ecopipeline
-Version: 1.0.4
+Version: 1.1.0
 Summary: Contains functions for use in Ecotope Datapipelines
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: GNU General Public License (GPL)

{ecopipeline-1.0.4 → ecopipeline-1.1.0}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = ecopipeline
-version = 1.0.4
+version = 1.1.0
 authors = ["Carlos Bello, <bellocarlos@seattleu.edu>, Emil Fahrig <fahrigemil@seattleu.edu>, Casey Mang <cmang@seattleu.edu>, Julian Harris <harrisjulian@seattleu.edu>, Roger Tram <rtram@seattleu.edu>, Nolan Price <nolan@ecotope.com>"]
 description = Contains functions for use in Ecotope Datapipelines
 long_description = file: README.md

ecopipeline-1.1.0/src/ecopipeline/event_tracking/Alarm.py

@@ -0,0 +1,317 @@
+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
+
+class Alarm:
+    def __init__(self, bounds_df : pd.DataFrame, alarm_tag : str = None, type_default_dict : dict = {},
+                 two_part_tag : bool = True, range_bounds : bool = False, alarm_db_type : str = 'SILENT_ALARM',
+                 daily_only : bool = False):
+        self.daily_only = daily_only
+        self.alarm_tag = alarm_tag
+        self.two_part_tag = two_part_tag
+        self.range_bounds = range_bounds
+        self.type_default_dict = type_default_dict
+        self.alarm_db_type = alarm_db_type
+        self.triggered_alarms = {
+                'start_time_pt' : [],
+                'end_time_pt' : [],
+                'alarm_type' : [],
+                'event_detail' : [],
+                'variable_name' : [],
+                'certainty' : []
+            }
+        self.bounds_df = self._process_bounds_df_alarm_codes(bounds_df)
+
+    def find_alarms(self, df: pd.DataFrame, daily_data : pd.DataFrame, config : ConfigManager) -> pd.DataFrame:
+        """
+        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.
+        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 appropriate alarm codes.
+        Returns
+        -------
+        pd.DataFrame:
+            Pandas dataframe with alarm events
+        """
+        if self.bounds_df.empty:
+            return self._convert_silent_alarm_dict_to_df({}) # no alarms to look into 
+        if self.daily_only:
+            if daily_data.empty:
+                print(f"cannot flag {self.alarm_tag} alarms. Dataframe is empty")
+                return pd.DataFrame()
+        elif df.empty:
+            print(f"cannot flag {self.alarm_tag} alarms. Dataframe is empty")
+            return pd.DataFrame()
+        self.specific_alarm_function(df, daily_data, config)
+        return self._convert_silent_alarm_dict_to_df(self.triggered_alarms)
+    
+    def specific_alarm_function(self, df: pd.DataFrame, daily_df : pd.DataFrame, config : ConfigManager):
+        self.triggered_alarms = {}
+
+    def _add_an_alarm(self, start_time : datetime, end_time : datetime, var_name : str, alarm_string : str, add_one_minute_to_end : bool = True, certainty : str = "high"):
+        certainty_dict = {
+            "high" : 3,
+            "med" : 2,
+            "low" : 1
+        }
+        if certainty not in certainty_dict.keys():
+            raise Exception(f"{certainty} is not a valid certainty key. Valid keys are {certainty_dict.keys()}")
+        else: 
+            certainty = certainty_dict[certainty]
+        if add_one_minute_to_end:
+            end_time = end_time + timedelta(minutes=1)
+        self.triggered_alarms['start_time_pt'].append(start_time)
+        self.triggered_alarms['end_time_pt'].append(end_time)
+        self.triggered_alarms['alarm_type'].append(self.alarm_db_type)
+        self.triggered_alarms['event_detail'].append(alarm_string)
+        self.triggered_alarms['variable_name'].append(var_name)
+        self.triggered_alarms['certainty'].append(certainty)
+    
+    def _convert_silent_alarm_dict_to_df(self, alarm_dict : dict) -> pd.DataFrame:
+
+        alarm_df = pd.DataFrame(alarm_dict)
+        alarm_df = self._compress_alarm_df(alarm_df)
+        return alarm_df
+
+    def _compress_alarm_df(self, alarm_df: pd.DataFrame) -> pd.DataFrame:
+        """
+        Compresses consecutive alarms of the same variable_name and alarm_type into single rows.
+        If one alarm's start_time_pt is within one minute of another alarm's end_time_pt,
+        they are merged into one row with the earliest start_time_pt and latest end_time_pt.
+
+        Parameters
+        ----------
+        alarm_df : pd.DataFrame
+            DataFrame with columns: start_time_pt, end_time_pt, alarm_type, variable_name, event_detail
+
+        Returns
+        -------
+        pd.DataFrame
+            Compressed DataFrame with consecutive alarms merged
+        """
+        if alarm_df.empty:
+            return alarm_df
+
+        # Sort entire DataFrame by start_time_pt before processing
+        alarm_df = alarm_df.sort_values('start_time_pt').reset_index(drop=True)
+
+        compressed_rows = []
+
+        # Group by variable_name and alarm_type
+        for (var_name, alarm_type), group in alarm_df.groupby(['variable_name', 'alarm_type'], sort=False):
+            # Group is already sorted since we sorted the whole DataFrame above
+            group = group.reset_index(drop=True)
+
+            current_start = None
+            current_end = None
+            current_detail = None
+            current_certainty = None
+
+            for _, row in group.iterrows():
+                row_start = row['start_time_pt']
+                row_end = row['end_time_pt']
+
+                if current_start is None:
+                    # First row in group
+                    current_start = row_start
+                    current_end = row_end
+                    current_detail = row['event_detail']
+                    current_certainty = row['certainty']
+                elif row_start <= current_end + timedelta(minutes=1):
+                    # This row is within 1 minute of current end - merge it after checking 
+                    row_certainty = row['certainty']
+                    if row_certainty > current_certainty:
+                        if row_start > current_start:
+                            compressed_rows.append({
+                                'start_time_pt': current_start,
+                                'end_time_pt': row_start,
+                                'alarm_type': alarm_type,
+                                'event_detail': current_detail,
+                                'variable_name': var_name,
+                                'certainty': current_certainty
+                            })
+                        if row_end >= current_end:
+                            current_start = row_start
+                            current_end = row_end
+                            current_detail = row['event_detail']
+                            current_certainty = row_certainty
+                        else:
+                            #encompassed
+                            compressed_rows.append({
+                                    'start_time_pt': row_start,
+                                    'end_time_pt': row_end,
+                                    'alarm_type': alarm_type,
+                                    'event_detail': row['event_detail'],
+                                    'variable_name': var_name,
+                                    'certainty': row_certainty
+                                })
+                            current_start = row_end
+
+                    elif row_certainty < current_certainty:
+                        if row_end > current_end:
+                            compressed_rows.append({
+                                    'start_time_pt': current_start,
+                                    'end_time_pt': current_end,
+                                    'alarm_type': alarm_type,
+                                    'event_detail': current_detail,
+                                    'variable_name': var_name,
+                                    'certainty': current_certainty
+                                })
+                            current_start = current_end
+                            current_end = row_end
+                            current_detail = row['event_detail']
+                            current_certainty = row_certainty
+                        
+                    else:
+                        current_end = max(current_end, row_end)
+                else:
+                    # Gap is more than 1 minute - save current and start new
+                    compressed_rows.append({
+                        'start_time_pt': current_start,
+                        'end_time_pt': current_end,
+                        'alarm_type': alarm_type,
+                        'event_detail': current_detail,
+                        'variable_name': var_name,
+                        'certainty': current_certainty
+                    })
+                    current_start = row_start
+                    current_end = row_end
+                    current_detail = row['event_detail']
+                    current_certainty = row['certainty']
+
+            # Don't forget the last accumulated row
+            if current_start is not None:
+                compressed_rows.append({
+                    'start_time_pt': current_start,
+                    'end_time_pt': current_end,
+                    'alarm_type': alarm_type,
+                    'event_detail': current_detail,
+                    'variable_name': var_name,
+                    'certainty': current_certainty
+                })
+        return pd.DataFrame(compressed_rows)
+    
+    def _process_bounds_df_alarm_codes(self, og_bounds_df : pd.DataFrame) -> pd.DataFrame:
+        # Should only do for alarm codes of format: [TAG]_[TYPE]_[OPTIONAL_ID]:[BOUND]
+        bounds_df = og_bounds_df.copy()
+        required_columns = ["variable_name", "alarm_codes"]
+        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'])
+
+        bounds_df = bounds_df.loc[:, ["variable_name", "alarm_codes", "pretty_name"]]
+        bounds_df.dropna(axis=0, thresh=2, inplace=True)
+
+        # Check if all alarm_codes are null or if dataframe is empty
+        if bounds_df.empty or bounds_df['alarm_codes'].isna().all():
+            return pd.DataFrame()
+        
+        bounds_df = bounds_df[bounds_df['alarm_codes'].str.contains(self.alarm_tag, na=False)]
+
+        # Split alarm_codes by semicolons and create a row for each STS code
+        expanded_rows = []
+        for idx, row in bounds_df.iterrows():
+            alarm_codes = str(row['alarm_codes']).split(';')
+            tag_codes = [code.strip() for code in alarm_codes if code.strip().startswith(self.alarm_tag)]
+
+            if tag_codes:  # Only process if there are STS codes
+                for tag_code in tag_codes:
+                    new_row = row.copy()
+                    if ":" in tag_code:
+                        tag_parts = tag_code.split(':')
+                        if len(tag_parts) > 2:
+                            raise Exception(f"Improperly formated alarm code : {tag_code}")
+                        if self.range_bounds:
+                            bounds = tag_parts[1]
+                            bound_range = bounds.split('-')
+                            if len(bound_range) != 2:
+                                raise Exception(f"Improperly formated alarm code : {tag_code}. Expected bound range in form '[number]-[number]' but recieved '{bounds}'.")
+                            new_row['bound'] = bound_range[0]
+                            new_row['bound2'] = bound_range[1]
+                        else:    
+                            new_row['bound'] = tag_parts[1]
+                        tag_code = tag_parts[0]
+                    else:
+                        new_row['bound'] = None
+                        if self.range_bounds:
+                            new_row['bound2'] = None
+                    new_row['alarm_codes'] = tag_code
+
+                    expanded_rows.append(new_row)
+
+        if expanded_rows:
+            bounds_df = pd.DataFrame(expanded_rows)
+        else:
+            return pd.DataFrame()# no tagged alarms to look into
+        
+        alarm_code_parts = []
+        for idx, row in bounds_df.iterrows():
+            parts = row['alarm_codes'].split('_')
+            if self.two_part_tag:
+                if len(parts) == 2:
+                    alarm_code_parts.append([parts[1], "No ID"])
+                elif len(parts) == 3:
+                    alarm_code_parts.append([parts[1], parts[2]])
+                else:
+                    raise Exception(f"improper {self.alarm_tag} alarm code format for {row['variable_name']}")
+            else:
+                if len(parts) == 1:
+                    alarm_code_parts.append(["default", "No ID"])
+                elif len(parts) == 2:
+                    alarm_code_parts.append(["default", parts[1]])
+                else:
+                    raise Exception(f"improper {self.alarm_tag} alarm code format for {row['variable_name']}")
+        if alarm_code_parts:
+            bounds_df[['alarm_code_type', 'alarm_code_id']] = pd.DataFrame(alarm_code_parts, index=bounds_df.index)
+
+            # Replace None bounds with appropriate defaults based on alarm_code_type
+            for idx, row in bounds_df.iterrows():
+                if pd.isna(row['bound']) or row['bound'] is None:
+                    if row['alarm_code_type'] in self.type_default_dict.keys():
+                        if self.range_bounds:
+                            bounds_df.at[idx, 'bound'] = self.type_default_dict[row['alarm_code_type']][0]
+                            bounds_df.at[idx, 'bound2'] = self.type_default_dict[row['alarm_code_type']][1]
+                        else:
+                            bounds_df.at[idx, 'bound'] = self.type_default_dict[row['alarm_code_type']]
+            # Coerce bound column to float
+            bounds_df['bound'] = pd.to_numeric(bounds_df['bound'], errors='coerce').astype(float)
+            if self.range_bounds:
+                bounds_df['bound2'] = pd.to_numeric(bounds_df['bound2'], errors='coerce').astype(float)
+
+        return bounds_df
+    
+    def _append_previous_days_to_df(self, daily_df: pd.DataFrame, config : ConfigManager, ratio_period_days : int, day_table_name : str, primary_key : str = "time_pt") -> pd.DataFrame:
+        db_connection, cursor = config.connect_db()
+        period_start = daily_df.index.min() - timedelta(ratio_period_days)
+        try:
+            # find existing times in database for upsert statement
+            cursor.execute(
+                f"SELECT * FROM {day_table_name} WHERE {primary_key} < '{daily_df.index.min()}' AND {primary_key} >= '{period_start}'")
+            result = cursor.fetchall()
+            column_names = [desc[0] for desc in cursor.description]
+            old_days_df = pd.DataFrame(result, columns=column_names)
+            old_days_df = old_days_df.set_index(primary_key)
+            daily_df = pd.concat([daily_df, old_days_df])
+            daily_df = daily_df.sort_index(ascending=True)
+        except mysqlerrors.Error:
+            print(f"Table {day_table_name} has no data.")
+
+        db_connection.close()
+        cursor.close()
+        return daily_df

ecopipeline-1.1.0/src/ecopipeline/event_tracking/__init__.py

@@ -0,0 +1,21 @@
+from .event_tracking import *
+from .Alarm import Alarm
+from .alarms.ShortCycle import ShortCycle
+from .alarms.TempRange import TempRange
+from .alarms.LSInconsist import LSInconsist
+from .alarms.SOOChange import SOOChange
+from .alarms.BlownFuse import BlownFuse
+from .alarms.HPWHOutage import HPWHOutage
+from .alarms.BackupUse import BackupUse
+from .alarms.HPWHOutlet import HPWHOutlet
+from .alarms.HPWHInlet import HPWHInlet
+from .alarms.BalancingValve import BalancingValve
+from .alarms.TMSetpoint import TMSetpoint
+from .alarms.AbnormalCOP import AbnormalCOP
+from .alarms.PowerRatio import PowerRatio
+from .alarms.Boundary import Boundary
+
+__all__ = ['central_alarm_df_creator','flag_boundary_alarms','power_ratio_alarm','flag_abnormal_COP','flag_high_tm_setpoint',
+           'flag_recirc_balance_valve','flag_hp_inlet_temp','flag_backup_use','flag_blown_fuse','flag_unexpected_soo_change','flag_shortcycle',
+           'flag_hp_outlet_temp','flag_HP_outage','flag_unexpected_temp','flag_ls_mode_inconsistancy','Alarm','ShortCycle','TempRange','LSInconsist',
+           'SOOChange','BlownFuse','HPWHOutage','BackupUse','HPWHOutlet','HPWHInlet','BalancingValve','TMSetpoint','AbnormalCOP','PowerRatio','Boundary']

ecopipeline-1.1.0/src/ecopipeline/event_tracking/alarms/AbnormalCOP.py

@@ -0,0 +1,76 @@
+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 AbnormalCOP(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_high_bound : float = 4.5, default_low_bound : float = 0):
+        self.default_high_bound = default_high_bound
+        self.default_low_bound = default_low_bound
+        
+        super().__init__(bounds_df, None, {}, alarm_db_type='ABNORMAL_COP', daily_only=True)
+
+    def _process_bounds_df_alarm_codes(self, og_bounds_df : pd.DataFrame) -> pd.DataFrame:
+        bounds_df = og_bounds_df.copy()
+        if not "variable_name" in bounds_df.columns:
+            raise Exception(f"variable_name 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 'high_alarm' in bounds_df.columns:
+            bounds_df['high_alarm'] = self.default_high_bound
+        else:
+            bounds_df['high_alarm'] = bounds_df['high_alarm'].fillna(self.default_high_bound)
+        if not 'low_alarm' in bounds_df.columns:
+            bounds_df['low_alarm'] = self.default_low_bound
+        else:
+            bounds_df['low_alarm'] = bounds_df['low_alarm'].fillna(self.default_low_bound)
+
+        bounds_df = bounds_df.loc[:, ["variable_name", "high_alarm", "low_alarm", "pretty_name"]]
+        bounds_df.dropna(axis=0, thresh=2, inplace=True)
+        bounds_df.set_index(['variable_name'], inplace=True)
+
+        return bounds_df
+
+    def specific_alarm_function(self, df: pd.DataFrame, daily_df : pd.DataFrame, config : ConfigManager):
+        cop_pattern = re.compile(r'^(COP\w*|SystemCOP\w*)$')
+        cop_columns = [col for col in daily_df.columns if re.match(cop_pattern, col)]
+
+        if not daily_df.empty and len(cop_columns) > 0:
+            for bound_var, bounds in self.bounds_df.iterrows():
+                if bound_var in cop_columns:
+                    for day, day_values in daily_df.iterrows():
+                        if not day_values[bound_var] is None and (day_values[bound_var] > bounds['high_alarm'] or day_values[bound_var] < bounds['low_alarm']):
+                            alarm_str = f"Unexpected COP Value detected: {bounds['pretty_name']} = {round(day_values[bound_var],2)}"
+                            self._add_an_alarm(day, day + timedelta(1), bound_var, alarm_str, add_one_minute_to_end=False)

ecopipeline-1.1.0/src/ecopipeline/event_tracking/alarms/BackupUse.py

@@ -0,0 +1,94 @@
+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 BackupUse(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:
+    IMBCKUP_P_ID - Back Up Tank Power Varriable. Must be in same power units as total system power
+    IMBCKUP_TP_ID:### - Total System Power for ratio alarming for alarming if back up power is more than ### (40% default) of usage
+    IMBCKUP_ST_ID:### - Back Up Setpoint that should not change at all from ### (default 130)
+
+    Parameters
+    ----------
+    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_setpoint : float = 130.0, default_power_ratio : float = 0.1):
+        alarm_tag = 'IMBCKUP'
+        type_default_dict = {
+                'POW': None,
+                'TP': default_power_ratio,
+                'ST': default_setpoint
+            }
+        super().__init__(bounds_df, alarm_tag, type_default_dict, alarm_db_type='BACKUP_USE')
+
+    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
+                pow_codes = id_group[id_group['alarm_code_type'] == 'POW']
+                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(tp_codes) > 1:
+                    raise Exception(f"Improper alarm codes for swing tank setpoint with id {alarm_id}")
+
+                if len(st_codes) >= 1:
+                    # Check each ST code against its individual bound
+                    for idx, st_row in st_codes.iterrows():
+                        st_var_name = st_row['variable_name']
+                        st_pretty_name = st_row['pretty_name']
+                        st_setpoint = st_row['bound']
+                        # Check if st_var_name exists in filtered_df
+                        if st_var_name in filtered_df.columns:
+                            # 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"Swing tank setpoint was altered: {st_pretty_name} was {actual_value} for {streak_length} minutes starting at {start_time} (expected {st_setpoint}).")
+
+                if len(tp_codes) == 1 and len(pow_codes) >= 1:
+                    tp_var_name = tp_codes.iloc[0]['variable_name']
+                    tp_bound = tp_codes.iloc[0]['bound']
+                    if tp_var_name in daily_df.columns:
+                        # Get list of ER variable names
+                        bu_pow_names = pow_codes['variable_name'].tolist()
+
+                        # Check if all ER variables exist in daily_df
+                        if all(var in daily_df.columns for var in bu_pow_names):
+                            # Sum all ER variables for this day
+                            bu_pow_sum = daily_df.loc[day, bu_pow_names].sum()
+                            tp_value = daily_df.loc[day, tp_var_name]
+
+                            # Check if sum of ER >= OUT value
+                            if bu_pow_sum >= tp_value*tp_bound:
+                                self._add_an_alarm(day, day + timedelta(1), tp_var_name,
+                                    f"Improper Back Up Use: Sum of back up equipment ({bu_pow_sum:.2f}) exceeds {(tp_bound * 100):.2f}% of total power.", certainty="med")
+    

ecopipeline-1.1.0/src/ecopipeline/event_tracking/alarms/BalancingValve.py

@@ -0,0 +1,78 @@
+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 BalancingValve(Alarm):
+    """
+    Detects recirculation balance issues by comparing sum of ER (equipment recirculation) heater
+    power to either total power or heating output.
+
+    VarNames syntax:
+    BALVALV_ER_[OPTIONAL ID] - Indicates a power variable for an ER heater (equipment recirculation).
+        Multiple ER variables with the same ID will be summed together.
+    BALVALV_TP_[OPTIONAL ID]:### - Indicates the Total Power of the system. Optional ### for the percentage
+        threshold that should not be crossed by the ER elements (default 0.4 for 40%).
+        Alarm triggers when sum of ER >= total_power * threshold.
+    BALVALV_OUT_[OPTIONAL ID] - Indicates the heating output variable the ER heating contributes to.
+        Alarm triggers when sum of ER > sum of OUT * 0.95 (i.e., ER exceeds 95% of heating output).
+        Multiple OUT variables with the same ID will be summed together.
+
+    Note: Each alarm ID requires at least one ER code AND either one TP code OR at least one OUT code.
+    If a TP code exists for an ID, it takes precedence over OUT codes.
+
+    Parameters
+    ----------
+    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_power_ratio : float = 0.4):
+        alarm_tag = 'BALVALV'
+        type_default_dict = {'TP' : default_power_ratio}
+        super().__init__(bounds_df, alarm_tag,type_default_dict, two_part_tag = True, alarm_db_type='BALANCING_VALVE', daily_only=True)
+
+    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]
+            out_codes = id_group[id_group['alarm_code_type'] == 'OUT']
+            tp_codes = id_group[id_group['alarm_code_type'] == 'TP']
+            er_codes = id_group[id_group['alarm_code_type'] == 'ER']
+            if len(er_codes) < 1 or (len(out_codes) < 1 and len(tp_codes) != 1):
+                raise Exception(f"Improper alarm codes for balancing valve with id {alarm_id}")
+            er_var_names = er_codes['variable_name'].tolist()
+            if len(tp_codes) == 1 and tp_codes.iloc[0]['variable_name']in daily_df.columns:
+                tp_var_name = tp_codes.iloc[0]['variable_name']
+                tp_bound = tp_codes.iloc[0]['bound']
+                for day in daily_df.index:
+
+                    # Check if all ER variables exist in daily_df
+                    if all(var in daily_df.columns for var in er_var_names):
+                        # Sum all ER variables for this day
+                        er_sum = daily_df.loc[day, er_var_names].sum()
+                        tp_value = daily_df.loc[day, tp_var_name]
+
+                        # Check if sum of ER >= OUT value
+                        if er_sum >= tp_value*tp_bound:
+                            self._add_an_alarm(day, day + timedelta(1), tp_var_name, 
+                                               f"Recirculation imbalance: Sum of recirculation equipment ({er_sum:.2f}) exceeds or equals {(tp_bound * 100):.2f}% of total power.", 
+                                               add_one_minute_to_end=False, certainty="low")
+            elif len(out_codes) >= 1:
+                out_var_names = out_codes['variable_name'].tolist()
+                for day in daily_df.index:
+
+                    # Check if all ER variables exist in daily_df
+                    if all(var in daily_df.columns for var in er_var_names) and all(var in daily_df.columns for var in out_var_names):
+                        # Sum all ER variables for this day
+                        er_sum = daily_df.loc[day, er_var_names].sum()
+                        out_sum = daily_df.loc[day, out_var_names].sum()
+
+                        # Check if sum of ER >= OUT value
+                        if er_sum > out_sum:
+                            self._add_an_alarm(day, day + timedelta(1), out_codes.iloc[0]['variable_name'], 
+                                               f"Recirculation imbalance: Sum of recirculation equipment power ({er_sum:.2f} kW) exceeds TM heating output ({out_sum:.2f} kW).",
+                                               add_one_minute_to_end=False, certainty="low")