Event Tracking Documentation

Event tracking and alarm detection utilities for the ecopipeline package.

This module exposes all public alarm-detection functions and alarm classes used to identify fault conditions in heat-pump water-heater (HPWH) and associated building-energy systems. Functions accept post-transformed minute and/or daily pd.DataFrame objects together with a ConfigManager instance and return a pd.DataFrame of detected alarm events.

Alarm classes (e.g. Boundary, ShortCycle, AbnormalCOP) can also be imported directly from this module for lower-level use.

class ecopipeline.event_tracking.AbnormalCOP(bounds_df: DataFrame, default_high_bound: float = 4.5, default_low_bound: float = 0)

Bases: Alarm

Detects abnormal COP (Coefficient of Performance) values by checking if any COP variable falls outside its expected high/low bounds on a given day.

Note: This alarm does not use the alarm_codes column. Variables are matched by their column name pattern in daily_df (must start with ‘COP’ or ‘SystemCOP’), and bounds are read directly from the high_alarm and low_alarm columns in Variable_Names.csv.

Variable_Names.csv columns: variable_name - Name of the COP variable to monitor (must match a column starting with ‘COP’ or ‘SystemCOP’ in daily_df). high_alarm - Upper bound for acceptable COP. Alarm triggers if daily COP exceeds this value. Default: 4.5. low_alarm - Lower bound for acceptable COP. Alarm triggers if daily COP falls below this value. Default: 0. pretty_name - (Optional) Display name for the variable in alarm messages. Defaults to variable_name.

Parameters:

default_high_boundfloat

Default upper COP bound when no high_alarm value is specified (default 4.5).

default_low_boundfloat

Default lower COP bound when no low_alarm value is specified (default 0).

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.Alarm(bounds_df: DataFrame, alarm_tag: str = None, type_default_dict: dict = {}, two_part_tag: bool = True, range_bounds: bool = False, daily_only: bool = False, element_id_matching: bool = False)

Bases: object

Methods

specific_alarm_function

find_alarms(df: DataFrame, daily_data: DataFrame, config: ConfigManager) → 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.

configecopipeline.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

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.BackupUse(bounds_df: DataFrame, default_setpoint: float = 130.0, default_power_ratio: float = 0.1)

Bases: Alarm

Detects improper backup equipment use by monitoring whether backup power exceeds an expected fraction of total system power, and whether setpoint variables have been altered from their expected values.

Variable_Names.csv configuration:

alarm_codes column: IMBCKUP or IMBCKUP:### where ### provides the bound for the variable (see types below). variable_name column: determines the role of the variable by its first underscore-separated part:

PowerIn_[name] - Backup equipment power variable. Multiple allowed; daily values are summed.

No bound needed in alarm_codes (use just IMBCKUP).

PowerIn_Total[…] - Total system power variable. Bound (###) from alarm_codes is the ratio threshold

(default 0.1 for 10%). Alarm triggers when sum of backup power >= total power * threshold.

Setpoint_[name] - Setpoint variable that should remain constant. Bound (###) from alarm_codes is

the expected setpoint value (default 130.0). Alarm triggers if value differs for 10+ consecutive minutes.

Parameters:

default_setpointfloat

Default expected setpoint value for Setpoint variables when no bound is specified (default 130.0).

default_power_ratiofloat

Default ratio threshold for PowerIn_Total variables when no bound is specified (default 0.1). Alarm triggers when sum of backup power >= total power * threshold.

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.BalancingValve(bounds_df: DataFrame, default_power_ratio: float = 0.4)

Bases: Alarm

Detects recirculation balance issues by comparing the sum of electric recirculation (ER) heater power to either total system power or heating output.

Variable_Names.csv configuration:

alarm_codes column: BALVALV or BALVALV:### where ### provides the bound for the variable (see types below). variable_name column: determines the role of the variable by its first underscore-separated part:

PowerIn_[name] - Electric recirculation (ER) heater power variable. Multiple allowed; daily values are summed.

No bound needed in alarm_codes (use just BALVALV).

PowerIn_Total - Total system power variable. Bound (###) from alarm_codes is the fraction threshold

(default 0.4 for 40%). Alarm triggers when sum of ER >= total power * threshold. If present, takes precedence over HeatOut variables.

HeatOut_[name] - Heating output variable. Multiple allowed; values are summed. Alarm triggers when

sum of ER power exceeds sum of heating output. Only used if no PowerIn_Total variable is configured. No bound needed in alarm_codes (use just BALVALV).

Note: Requires at least one PowerIn variable AND either one PowerIn_Total or at least one HeatOut variable.

Parameters:

default_power_ratiofloat

Default ratio threshold for PowerIn_Total variables when no bound is specified (default 0.4). Alarm triggers when sum of ER power >= total power * threshold.

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.BlownFuse(bounds_df: DataFrame, default_power_threshold: float = 1.0, default_power_range: float = 2.0, default_power_draw: float = 30, fault_time: int = 3)

Bases: Alarm

Detects blown fuse conditions for heating elements by identifying when an element is drawing power but significantly less than its expected draw, suggesting a blown fuse.

Variable_Names.csv configuration:

alarm_codes column: BLWNFSE:### where ### is the expected kW draw when the element is fully on. variable_name column: Must start with PowerIn_ (e.g., PowerIn_ERElement1).

PowerIn_[name] - Element power variable. Bound (###) from alarm_codes is the expected kW draw (default 30 kW).

Alarm triggers when element is on (power > default_power_threshold) but drawing less than (expected_draw - default_power_range) for fault_time consecutive minutes.

Parameters:

default_power_thresholdfloat

Minimum power level (kW) to consider the element ‘on’ (default 1.0).

default_power_rangefloat

Allowable variance below expected power draw (default 2.0). Alarm triggers when actual draw < (expected - range).

default_power_drawfloat

Default expected power draw in kW when no bound is specified in the alarm code (default 30).

fault_timeint

Number of consecutive minutes the fault condition must persist before triggering an alarm (default 3).

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.Boundary(bounds_df: DataFrame, default_fault_time: int = 15)

Bases: 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_timeint

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.

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.HPWHInlet(bounds_df: DataFrame, default_power_threshold: float = 1.0, default_temp_threshold: float = 115.0, fault_time: int = 5)

Bases: Alarm

Detects high heat pump inlet temperature by checking if the inlet temperature exceeds a threshold while the heat pump is running. An alarm triggers if the temperature stays above the threshold for fault_time consecutive minutes while the HP is on.

Variable_Names.csv configuration:

alarm_codes column: HPINLET:### where ### provides the bound for the variable (see types below). variable_name column: determines the role and element ID of the variable. The element ID is derived

by removing the leading unit type and any trailing ‘Inlet’/’Outlet’ suffix (e.g., ‘PowerIn_HPWH1’ and ‘Temp_HPWH1_Inlet’ both yield element ID ‘HPWH1’ and are paired together). PowerIn_[ID] - HP power variable. Bound (###) from alarm_codes is the power threshold (default 1.0)

above which the HP is considered ‘on’.

Temp_[ID][Inlet] - HP inlet temperature variable. Bound (###) from alarm_codes is the maximum acceptable

temperature (default 115.0). Alarm triggers when temperature exceeds this while HP is on.

Parameters:

default_power_thresholdfloat

Default power threshold for PowerIn variables when no bound is specified (default 1.0).

default_temp_thresholdfloat

Default temperature threshold for Temp variables when no bound is specified (default 115.0). Alarm triggers when inlet temperature exceeds this value while the HP is on.

fault_timeint

Number of consecutive minutes that both conditions must hold before triggering an alarm (default 5).

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.HPWHOutage(bounds_df: DataFrame, day_table_name: str, default_power_ratio: float = 0.3, ratio_period_days: int = 7)

Bases: 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.

Variable_Names.csv configuration:

alarm_codes column: HPOUTGE or HPOUTGE:### where ### provides the bound for the variable (see types below). variable_name column: determines the role of the variable by its first underscore-separated part:

PowerIn_[name] - HP power variable. Bound (###) from alarm_codes is the minimum expected ratio of HP

power to total system power over the rolling period (default 0.3 for 30%). Alarm triggers when HP power falls below this ratio. Must be in the same units as the PowerIn_Total variable.

PowerIn_Total - Total system power variable. No bound needed in alarm_codes (use just HPOUTGE).

Required when using PowerIn variables.

Alarm_[name] - Direct alarm variable from HP controller. No bound needed in alarm_codes (use just HPOUTGE).

Alarm triggers on any non-zero value. If triggered, the ratio check is skipped.

Parameters:

day_table_namestr

Name of the site’s daily aggregate value table in the database for fetching historical data.

default_power_ratiofloat

Default minimum ratio threshold for PowerIn variables when no bound is specified (default 0.3). Alarm triggers when HP power falls below this ratio of total power over the rolling period.

ratio_period_daysint

Number of days to use for the rolling power ratio calculation (default 7). Must be greater than 1.

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.HPWHOutlet(bounds_df: DataFrame, default_power_threshold: float = 1.0, default_temp_threshold: float = 140.0, fault_time: int = 5)

Bases: 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.

Variable_Names.csv configuration:

alarm_codes column: HPOUTLT:### where ### provides the bound for the variable (see types below). variable_name column: determines the role and element ID of the variable. The element ID is derived

by removing the leading unit type and any trailing ‘Inlet’/’Outlet’ suffix (e.g., ‘PowerIn_HPWH1’ and ‘Temp_HPWH1_Outlet’ both yield element ID ‘HPWH1’ and are paired together). PowerIn_[ID] - HP power variable. Bound (###) from alarm_codes is the power threshold (default 1.0)

above which the HP is considered ‘on’.

Temp_[ID][Outlet] - HP outlet temperature variable. Bound (###) from alarm_codes is the minimum

acceptable temperature (default 140.0). Alarm triggers when temp falls below this after warmup.

Parameters:

default_power_thresholdfloat

Default power threshold for PowerIn variables when no bound is specified (default 1.0).

default_temp_thresholdfloat

Default temperature threshold for Temp variables when no bound is specified (default 140.0). Alarm triggers when outlet temperature falls BELOW this value after the warmup period.

fault_timeint

Number of consecutive minutes that temperature must be below threshold (after warmup) before triggering an alarm (default 5).

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.LSInconsist(bounds_df: DataFrame)

Bases: Alarm

Detects when a variable’s value does not match its expected value during a load shifting event (or during normal operation). An alarm is triggered whenever the variable differs from the expected value for the relevant time period.

Variable_Names.csv configuration:

alarm_codes column: SOOSCHD_[mode]:###

[mode] must be one of: normal, loadUp, shed, criticalPeak, gridEmergency, advLoadUp. Bound (###) from alarm_codes is the expected value of the variable during that mode.

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.PowerRatio(bounds_df: DataFrame, day_table_name: str, ratio_period_days: int = 7)

Bases: Alarm

Detects when power variables fall outside their expected ratio of a group total over a rolling period. Variables are grouped by element ID derived from their variable_name, and each variable’s contribution is checked against its expected low-high percentage range.

Variable_Names.csv configuration:

alarm_codes column: POWRRAT:low-high where low-high is the acceptable percentage range

(e.g., POWRRAT:60-80 means the variable should account for 60-80% of its group total). Bounds (low-high) come from alarm_codes and are not part of the variable_name.

variable_name column: Must start with PowerIn_. Determines the grouping of variables:

PowerIn_Total - Total system power. Used as the denominator for the ‘Total’ group. PowerIn_[name containing ‘_HPWH’] - Grouped under the ‘HPWH’ element ID. The sum of all HPWH

variables is the group denominator; each variable’s ratio is checked against its range.

PowerIn_[other] - All other PowerIn variables are grouped under the ‘Total’ element ID and their

ratios are calculated against the PowerIn_Total variable.

Parameters:

day_table_namestr

Name of the site’s daily aggregate value table in the database for fetching historical data.

ratio_period_daysint

Number of days to use for the rolling power ratio calculation (default 7). Each block sums values over this many days before calculating ratios.

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.SOOChange(bounds_df: DataFrame, default_power_threshold: float = 1.0, default_on_temp: float = 115.0, default_off_temp: float = 140.0)

Bases: Alarm

Detects unexpected state of operation (SOO) changes by checking if the heat pump turns on or off when the corresponding temperature is not near the expected aquastat setpoint threshold. An alarm triggers if the HP turns on/off and the temperature differs by more than 5.0 degrees from expected.

Variable_Names.csv configuration:

The role of each variable is determined by the first underscore-separated part of its variable_name, while the alarm_codes column carries the tag, sub-type, and bound:

variable_name: PowerIn_[name], alarm_codes: SOOCHNG:### — HP system power variable (total power

across all primary HPs). Bound (###) from alarm_codes is the power threshold (default 1.0).

variable_name: Temp_[name], alarm_codes: SOOCHNG_ON_[Mode]:### — Temperature variable checked at

HP turn-on events. Bound (###) from alarm_codes is the expected ON temperature (default 115.0).

variable_name: Temp_[name], alarm_codes: SOOCHNG_OFF[Mode]:### — Temperature variable checked at

HP turn-off events. Bound (###) from alarm_codes is the expected OFF temperature (default 140.0).

[Mode] in alarm_codes is optional and must be one of: loadUp, shed, criticalPeak, gridEmergency, advLoadUp.

If omitted, the variable applies to normal (non-load-shifting) operation.

Each mode requires exactly one ON and one OFF temperature variable.

Parameters:

default_power_thresholdfloat

Default power threshold for PowerIn variables when no bound is specified (default 1.0).

default_on_tempfloat

Default ON temperature threshold (default 115.0). Alarm triggers if temperature differs by more than 5.0 degrees from this value when the HP turns on.

default_off_tempfloat

Default OFF temperature threshold (default 140.0). Alarm triggers if temperature differs by more than 5.0 degrees from this value when the HP turns off.

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.ShortCycle(bounds_df: DataFrame, default_power_threshold: float = 1.0, short_cycle_time: int = 15)

Bases: Alarm

Detects short cycling by identifying when a heat pump runs for fewer than short_cycle_time consecutive minutes before turning off. Short cycling can indicate equipment issues or improper system sizing.

Variable_Names.csv configuration:

alarm_codes column: SHRTCYC:### where ### is the power threshold above which the HP is considered ‘on’. variable_name column: Must start with PowerIn_ (e.g., PowerIn_HPWH1).

PowerIn_[name] - Heat pump power variable. Bound (###) from alarm_codes is the power threshold

(default 1.0). Alarm triggers if the HP runs for fewer than short_cycle_time consecutive minutes.

Parameters:

default_power_thresholdfloat

Default power threshold when no bound is specified in the alarm code (default 1.0).

short_cycle_timeint

Minimum expected run time in minutes (default 15). Alarm triggers if the HP runs for fewer than this many consecutive minutes before turning off.

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.TMSetpoint(bounds_df: DataFrame, default_fault_time: int = 3, default_setpoint: float = 130.0, default_power_indication: float = 1.0, default_power_ratio: float = 0.4)

Bases: Alarm

Detects temperature maintenance (TM) equipment issues including setpoint alterations, overheating while powered on, and excessive power consumption relative to total system power.

Variable_Names.csv configuration:

alarm_codes column: TMNSTPT or TMNSTPT:### where ### provides the bound for the variable (see types below). variable_name column: determines the role of the variable by its first underscore-separated part.

Variables with the same element ID (derived from the rest of the variable name, Inlet/Outlet stripped) are grouped together: Temp_[ID][Outlet] - TM equipment temperature variable. Bound (###) from alarm_codes is the maximum acceptable

temperature (default 130.0). Alarm triggers when equipment is on and temperature stays at or above this for default_fault_time consecutive minutes.

PowerIn_[ID] - TM equipment power variable. Bound (###) from alarm_codes is the minimum power

(default 1.0) to consider the equipment ‘on’. Used with Temp for overheating detection and with PowerIn_Total for ratio comparison.

PowerIn_Total - Total system power variable. Bound (###) from alarm_codes is the ratio threshold

(default 0.4). Alarm triggers if sum of TM power / total power exceeds this on a given day.

Setpoint_[ID] - Setpoint variable that should remain constant. Bound (###) from alarm_codes is the

expected setpoint value (default 130.0). Alarm triggers if value differs for 10+ consecutive minutes.

Parameters:

default_fault_timeint

Number of consecutive minutes for Temp+PowerIn overheating alarms (default 3).

default_setpointfloat

Default expected value for Temp and Setpoint variables when no bound is specified (default 130.0).

default_power_indicationfloat

Default power threshold for PowerIn variables when no bound is specified (default 1.0).

default_power_ratiofloat

Default ratio threshold for PowerIn_Total variables when no bound is specified (default 0.4). Alarm triggers when TM power / total power exceeds this threshold.

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

class ecopipeline.event_tracking.TempRange(bounds_df: DataFrame, default_high_temp: float = 130, default_low_temp: float = 115, fault_time: int = 10)

Bases: Alarm

Detects when a temperature variable falls outside an acceptable range for a sustained period. An alarm triggers when the value stays above the high bound or below the low bound for fault_time consecutive minutes.

Variable_Names.csv configuration:

alarm_codes column: TMPRANG:low-high where low-high is the acceptable temperature range

(e.g., TMPRANG:110-130 means temperature should stay between 110 and 130 degrees F).

variable_name column: Must start with Temp_ (e.g., Temp_SwingTank1).

Temp_[name] - Temperature variable to monitor. Bounds (low-high) come from alarm_codes.

Alarm triggers if the temperature stays outside the [low, high] range for fault_time consecutive minutes.

Parameters:

default_high_tempfloat

Default high temperature bound when no range is specified in the alarm code (default 130). Temperature above this triggers an alarm.

default_low_tempfloat

Default low temperature bound when no range is specified in the alarm code (default 115). Temperature below this triggers an alarm.

fault_timeint

Number of consecutive minutes that temperature must be outside the range before triggering an alarm (default 10).

Methods

find_alarms(df, daily_data, config)

Parameters:

specific_alarm_function

specific_alarm_function(df: DataFrame, daily_df: DataFrame, config: ConfigManager)

ecopipeline.event_tracking.central_alarm_df_creator(df: DataFrame, daily_data: DataFrame, config: ConfigManager, system: str = '', default_cop_high_bound: float = 4.5, default_cop_low_bound: float = 0, default_boundary_fault_time: int = 15, site_name: str = None, day_table_name_header: str = 'day', power_ratio_period_days: int = 7) → DataFrame

Run all available alarm detectors and return a combined alarm event DataFrame.

Iterates over every alarm type (boundary, power ratio, abnormal COP, TM setpoint, balancing valve, HPWH inlet/outlet, backup use, HPWH outage, blown fuse, unexpected SOO change, short cycle, unexpected temperature, and demand-response inconsistency) and concatenates any detected events into a single result.

Parameters:

dfpd.DataFrame

Post-transformed minute-level data DataFrame. Must contain consecutive, in-order minutes; out-of-order rows or gaps may produce erroneous alarms.

daily_datapd.DataFrame

Post-transformed daily-level data DataFrame with a datetime index.

configConfigManager

Pipeline configuration object. Used to locate Variable_Names.csv and to resolve database table names.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

default_cop_high_boundfloat, optional

Upper COP threshold for the abnormal-COP alarm (default 4.5).

default_cop_low_boundfloat, optional

Lower COP threshold for the abnormal-COP alarm (default 0).

default_boundary_fault_timeint, optional

Consecutive minutes a sensor must be out of bounds before a boundary alarm triggers (default 15).

site_namestr, optional

Site identifier used for context in certain alarm checks. Defaults to None.

day_table_name_headerstr, optional

Key passed to config.get_table_name() to resolve the daily database table name (default "day").

power_ratio_period_daysint, optional

Rolling window in days used by the power-ratio alarm (default 7).

Returns:

pd.DataFrame

DataFrame of alarm events with columns end_time_pt, alarm_type, alarm_detail, and variable_name, indexed by start_time_pt. Returns an empty DataFrame if df is empty or Variable_Names.csv cannot be found.

Raises:

Exception

If system is non-empty but the system column is absent from Variable_Names.csv.

ecopipeline.event_tracking.flag_HP_outage(df: DataFrame, daily_df: DataFrame, config: ConfigManager, day_table_name: str, system: str = '', default_power_ratio: float = 0.3, ratio_period_days: int = 7) → DataFrame

Detect possible heat pump failures or outages.

Checks whether heat pump power consumption falls below an expected ratio of total system power over a rolling period, or whether a direct alarm variable from the heat pump controller reports a non-zero value.

VarNames syntax (alarm_codes column in Variable_Names.csv):

• HPOUT_POW_[OPTIONAL ID]:### — Heat pump power variable. ### is the minimum expected ratio of HP power to total power (default default_power_ratio). Must use the same power units as total system power.

• HPOUT_TP_[OPTIONAL ID] — Total system power variable for ratio comparison. Required when using POW codes.

• HPOUT_ALRM_[OPTIONAL ID] — Direct alarm variable from the HP controller. Alarm triggers if any non-zero value is detected.

Parameters:

dfpd.DataFrame

Post-transformed minute-level data DataFrame. Used for checking ALRM codes for non-zero values.

daily_dfpd.DataFrame

Post-transformed daily-level data DataFrame. Used for checking power ratios over the rolling period.

configConfigManager

Pipeline configuration object. Points to a Variable_Names.csv file that must contain at least the columns variable_name and alarm_codes.

day_table_namestr

Name of the daily database table used to fetch previous days’ data for the rolling-period calculation.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

default_power_ratiofloat, optional

Minimum power-ratio threshold (e.g., 0.3 for 30 %) for POW alarm codes when no custom bound is provided (default 0.3). An alarm triggers when HP power falls below this ratio of total power over the rolling period.

ratio_period_daysint, optional

Number of days in the rolling power-ratio window (default 7). Must be greater than 1.

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if df is empty or Variable_Names.csv cannot be found.

ecopipeline.event_tracking.flag_abnormal_COP(daily_data: DataFrame, config: ConfigManager, system: str = '', default_high_bound: float = 4.5, default_low_bound: float = 0) → DataFrame

Detect days with an abnormal coefficient of performance (COP) value.

Reads alarm configuration from Variable_Names.csv via config and delegates detection to AbnormalCOP.

Parameters:

daily_datapd.DataFrame

Post-transformed daily-level data DataFrame with a datetime index.

configConfigManager

Pipeline configuration object used to locate Variable_Names.csv.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

default_high_boundfloat, optional

Upper COP threshold above which an alarm is triggered (default 4.5).

default_low_boundfloat, optional

Lower COP threshold below which an alarm is triggered (default 0).

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if Variable_Names.csv cannot be found.

ecopipeline.event_tracking.flag_backup_use(df: DataFrame, daily_df: DataFrame, config: ConfigManager, system: str = '', default_setpoint: float = 130.0, default_power_ratio: float = 0.1) → DataFrame

Detect improper backup heating use based on power consumption and setpoint checks.

Triggers alarms when the backup tank consumes a disproportionate share of total system power or when the backup setpoint deviates from its expected value.

VarNames syntax (alarm_codes column in Variable_Names.csv):

• BU_P_ID — Backup tank power variable. Must use the same power units as total system power.

• BU_TP_ID:### — Total system power for ratio alarming. Alarm triggers when backup power exceeds ### fraction of total power (default default_power_ratio).

• BU_ST_ID:### — Backup setpoint that must not deviate from ### (default default_setpoint).

Parameters:

dfpd.DataFrame

Post-transformed minute-level data DataFrame. Must contain consecutive, in-order minutes; out-of-order rows or gaps may produce erroneous alarms.

daily_dfpd.DataFrame

Post-transformed daily-level data DataFrame. Used for power-ratio checks and to determine which days to process.

configConfigManager

Pipeline configuration object. Points to a Variable_Names.csv file that must contain at least the columns variable_name and alarm_codes.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

default_setpointfloat, optional

Default temperature setpoint in degrees F for ST alarm codes when no custom bound is provided (default 130.0).

default_power_ratiofloat, optional

Default power-ratio threshold (e.g., 0.1 for 10 %) for TP alarm codes when no custom bound is provided (default 0.1).

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if df is empty or Variable_Names.csv cannot be found.

ecopipeline.event_tracking.flag_blown_fuse(df: DataFrame, daily_df: DataFrame, config: ConfigManager, system: str = '', default_power_threshold: float = 1.0, default_power_range: float = 2.0, default_power_draw: float = 30, fault_time: int = 3) → DataFrame

Detect blown fuse conditions on heating elements.

Identifies when a heating element is drawing power but significantly less than expected, which may indicate a blown fuse.

VarNames syntax (alarm_codes column in Variable_Names.csv):

• BF_[OPTIONAL ID]:### — Blown fuse alarm for an element. ### is the expected kW draw when the element is on.

Parameters:

dfpd.DataFrame

Post-transformed minute-level data DataFrame. Must contain consecutive, in-order minutes; out-of-order rows or gaps may produce erroneous alarms.

daily_dfpd.DataFrame

Post-transformed daily-level data DataFrame.

configConfigManager

Pipeline configuration object. Points to a Variable_Names.csv file that must contain at least the columns variable_name and alarm_codes.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

default_power_thresholdfloat, optional

Power threshold in kW used to determine whether the element is on (default 1.0). Element is considered on when power exceeds this value.

default_power_rangefloat, optional

Allowable variance below the expected power draw in kW (default 2.0). An alarm triggers when actual power is less than expected_power_draw - default_power_range while the element is on.

default_power_drawfloat, optional

Default expected power draw in kW when no custom bound is specified in the alarm code (default 30).

fault_timeint, optional

Consecutive minutes the fault condition must persist before an alarm is triggered (default 3).

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if df is empty or Variable_Names.csv cannot be found.

ecopipeline.event_tracking.flag_boundary_alarms(df: DataFrame, config: ConfigManager, default_fault_time: int = 15, system: str = '', full_days: list = None) → DataFrame

Flag out-of-bounds sensor readings and return alarm events.

Reads acceptable sensor ranges from Variable_Names.csv via config and triggers an alarm whenever a sensor stays outside its bounds for default_fault_time consecutive minutes.

Parameters:

dfpd.DataFrame

Post-transformed minute-level data DataFrame. Must contain consecutive, in-order minutes; out-of-order rows or gaps may produce erroneous alarms.

configConfigManager

Pipeline configuration object. Points to a Variable_Names.csv file that must contain at least the columns variable_name, low_alarm, and high_alarm.

default_fault_timeint, optional

Number of consecutive minutes a sensor must be out of bounds before an alarm is triggered (default 15). Can be overridden per variable using a fault_time column in Variable_Names.csv.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

full_dayslist, optional

List of pd.Timestamp objects representing complete days to consider. If None (default), every day present in df is used.

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if df is empty or Variable_Names.csv cannot be found.

ecopipeline.event_tracking.flag_high_tm_setpoint(df: DataFrame, daily_df: DataFrame, config: ConfigManager, default_fault_time: int = 3, system: str = '', default_setpoint: float = 130.0, default_power_indication: float = 1.0, default_power_ratio: float = 0.4) → DataFrame

Detect temperature-maintenance (TM) setpoint violations on swing-tank equipment.

Triggers alarms when the swing tank outlet temperature exceeds the setpoint while the tank is powered, or when the swing tank consumes a disproportionate share of total system power.

VarNames syntax (alarm_codes column in Variable_Names.csv):

• TMSTPT_T_ID:### — Swing Tank Outlet Temperature. Alarm triggers if temperature exceeds ### (default default_setpoint) for default_fault_time consecutive minutes with power on.

• TMSTPT_SP_ID:### — Swing Tank Power. ### is the minimum power (kW) for the tank to be considered on (default default_power_indication).

• TMSTPT_TP_ID:### — Total System Power for ratio alarming. Alarm triggers when swing-tank power exceeds ### fraction (default default_power_ratio) of total power.

• TMSTPT_ST_ID:### — Swing Tank Setpoint that must remain equal to ### (default default_setpoint).

Parameters:

dfpd.DataFrame

Post-transformed minute-level data DataFrame. Must contain consecutive, in-order minutes; out-of-order rows or gaps may produce erroneous alarms.

daily_dfpd.DataFrame

Post-transformed daily-level data DataFrame. Used for power-ratio checks and to determine which days to process.

configConfigManager

Pipeline configuration object. Points to a Variable_Names.csv file that must contain at least the columns variable_name and alarm_codes.

default_fault_timeint, optional

Consecutive minutes the T+SP fault condition must persist before triggering (default 3).

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

default_setpointfloat, optional

Default temperature setpoint in degrees F for T and ST alarm codes when no custom bound is provided (default 130.0).

default_power_indicationfloat, optional

Default power threshold in kW for SP alarm codes when no custom bound is provided (default 1.0).

default_power_ratiofloat, optional

Default power-ratio threshold (e.g., 0.4 for 40 %) for TP alarm codes when no custom bound is provided (default 0.4).

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if df is empty or Variable_Names.csv cannot be found.

ecopipeline.event_tracking.flag_hp_inlet_temp(df: DataFrame, daily_df: DataFrame, config: ConfigManager, system: str = '', default_power_threshold: float = 1.0, default_temp_threshold: float = 115.0, fault_time: int = 5) → DataFrame

Detect high heat pump inlet temperature while the heat pump is running.

Triggers an alarm when the heat pump is on and its inlet temperature exceeds the threshold for fault_time consecutive minutes.

VarNames syntax (alarm_codes column in Variable_Names.csv):

• HPI_POW_[OPTIONAL ID]:### — Heat pump power variable. ### is the power threshold (default default_power_threshold) above which the heat pump is considered on.

• HPI_T_[OPTIONAL ID]:### — Heat pump inlet temperature variable. ### is the temperature threshold (default default_temp_threshold) that must not be exceeded while the heat pump is on.

Parameters:

dfpd.DataFrame

Post-transformed minute-level data DataFrame. Must contain consecutive, in-order minutes; out-of-order rows or gaps may produce erroneous alarms.

daily_dfpd.DataFrame

Post-transformed daily-level data DataFrame.

configConfigManager

Pipeline configuration object. Points to a Variable_Names.csv file that must contain at least the columns variable_name and alarm_codes.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

default_power_thresholdfloat, optional

Default power threshold in kW for POW alarm codes when no custom bound is provided (default 1.0). Heat pump is considered on when power exceeds this value.

default_temp_thresholdfloat, optional

Default temperature threshold in degrees F for T alarm codes when no custom bound is provided (default 115.0). Alarm triggers when temperature exceeds this value while the heat pump is on.

fault_timeint, optional

Consecutive minutes that both power and temperature must exceed their thresholds before an alarm is triggered (default 5).

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if df is empty or Variable_Names.csv cannot be found.

ecopipeline.event_tracking.flag_hp_outlet_temp(df: DataFrame, daily_df: DataFrame, config: ConfigManager, system: str = '', default_power_threshold: float = 1.0, default_temp_threshold: float = 140.0, fault_time: int = 5) → DataFrame

Detect low heat pump outlet temperature while the heat pump is running.

The first 10 minutes after each HP turn-on are excluded as a warm-up period. An alarm triggers if the outlet temperature stays below the threshold for fault_time consecutive minutes after the warm-up period.

VarNames syntax (alarm_codes column in Variable_Names.csv):

• HPO_POW_[OPTIONAL ID]:### — Heat pump power variable. ### is the power threshold (default default_power_threshold) above which the heat pump is considered on.

• HPO_T_[OPTIONAL ID]:### — Heat pump outlet temperature variable. ### is the temperature threshold (default default_temp_threshold) that must be exceeded while the heat pump is on after the 10-minute warm-up period.

Parameters:

dfpd.DataFrame

Post-transformed minute-level data DataFrame. Must contain consecutive, in-order minutes; out-of-order rows or gaps may produce erroneous alarms.

daily_dfpd.DataFrame

Post-transformed daily-level data DataFrame.

configConfigManager

Pipeline configuration object. Points to a Variable_Names.csv file that must contain at least the columns variable_name and alarm_codes.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

default_power_thresholdfloat, optional

Default power threshold in kW for POW alarm codes when no custom bound is provided (default 1.0). Heat pump is considered on when power exceeds this value.

default_temp_thresholdfloat, optional

Default temperature threshold in degrees F for T alarm codes when no custom bound is provided (default 140.0). Alarm triggers when temperature falls below this value while the heat pump is on (after warm-up period).

fault_timeint, optional

Consecutive minutes that temperature must remain below threshold (after warm-up) before an alarm is triggered (default 5).

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if df is empty or Variable_Names.csv cannot be found.

ecopipeline.event_tracking.flag_ls_mode_inconsistancy(df: DataFrame, daily_df: DataFrame, config: ConfigManager, system: str = '') → DataFrame

Detect load-shift mode inconsistencies.

Triggers an alarm when a reported load-shift mode variable does not match its expected value during a scheduled load-shifting event.

VarNames syntax (alarm_codes column in Variable_Names.csv):

• SOO_[mode]:### — Variable that must equal ### during [mode] load-shifting events. [mode] can be normal, loadUp, shed, criticalPeak, gridEmergency, or advLoadUp. For example, SOO_loadUp:1 means the variable should be 1 during loadUp events.

Parameters:

dfpd.DataFrame

Post-transformed minute-level data DataFrame. Must contain consecutive, in-order minutes; out-of-order rows or gaps may produce erroneous alarms.

daily_dfpd.DataFrame

Post-transformed daily-level data DataFrame with a datetime index.

configConfigManager

Pipeline configuration object used to locate Variable_Names.csv.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if df is empty or Variable_Names.csv cannot be found.

ecopipeline.event_tracking.flag_recirc_balance_valve(daily_df: DataFrame, config: ConfigManager, system: str = '', default_power_ratio: float = 0.4) → DataFrame

Detect recirculation loop balancing valve issues.

Compares the sum of equipment-recirculation (ER) heater power to either total system power or heating output to identify imbalance.

VarNames syntax (alarm_codes column in Variable_Names.csv):

• BV_ER_[OPTIONAL ID] — Power variable for an ER heater. Multiple ER variables sharing the same ID are summed together.

• BV_TP_[OPTIONAL ID]:### — Total system power. Optional ### sets the ratio threshold (default default_power_ratio). Alarm triggers when sum of ER >= total_power * threshold.

• BV_OUT_[OPTIONAL ID] — Heating output variable that ER heating contributes to. Alarm triggers when sum of ER > sum of OUT * 0.95. Multiple OUT variables sharing the same ID are summed together.

Each alarm ID requires at least one ER code and either one TP code or at least one OUT code. When a TP code is present it takes precedence over OUT codes.

Parameters:

daily_dfpd.DataFrame

Post-transformed daily-level data DataFrame. Used to compare ER equipment power against total power or heating output.

configConfigManager

Pipeline configuration object. Points to a Variable_Names.csv file that must contain at least the columns variable_name and alarm_codes.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

default_power_ratiofloat, optional

Default power-ratio threshold (e.g., 0.4 for 40 %) for TP alarm codes when no custom bound is provided (default 0.4).

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if daily_df is empty or Variable_Names.csv cannot be found.

ecopipeline.event_tracking.flag_shortcycle(df: DataFrame, daily_df: DataFrame, config: ConfigManager, system: str = '', default_power_threshold: float = 1.0, short_cycle_time: int = 15) → DataFrame

Detect heat pump short-cycling events.

Identifies when the heat pump turns on for fewer than short_cycle_time consecutive minutes before turning off again. Short cycling can indicate equipment issues or improper system sizing.

VarNames syntax (alarm_codes column in Variable_Names.csv):

• SHRTCYC_[OPTIONAL ID]:### — Heat pump power variable. ### is the power threshold (default default_power_threshold) above which the heat pump is considered on.

Parameters:

dfpd.DataFrame

Post-transformed minute-level data DataFrame. Must contain consecutive, in-order minutes; out-of-order rows or gaps may produce erroneous alarms.

daily_dfpd.DataFrame

Post-transformed daily-level data DataFrame.

configConfigManager

Pipeline configuration object. Points to a Variable_Names.csv file that must contain at least the columns variable_name and alarm_codes.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

default_power_thresholdfloat, optional

Default power threshold in kW when no custom bound is provided in the alarm code (default 1.0). Heat pump is considered on when power exceeds this value.

short_cycle_timeint, optional

Minimum expected run time in minutes (default 15). An alarm triggers when the heat pump runs for fewer than this many consecutive minutes before turning off.

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if df is empty or Variable_Names.csv cannot be found.

ecopipeline.event_tracking.flag_unexpected_soo_change(df: DataFrame, daily_df: DataFrame, config: ConfigManager, system: str = '', default_power_threshold: float = 1.0, default_on_temp: float = 115.0, default_off_temp: float = 140.0) → DataFrame

Detect unexpected state-of-operation (SOO) changes.

Triggers an alarm when the heat pump turns on or off at a temperature that is more than 5.0 degrees away from the expected aquastat setpoint threshold for the current load-shifting mode.

VarNames syntax (alarm_codes column in Variable_Names.csv):

• SOOCHNG_POW:### — Total power variable across all primary heat pumps. ### is the power threshold (default default_power_threshold) above which the HP system is considered on.

• SOOCHNG_ON_[Mode ID]:### — Temperature variable at the ON aquastat setpoint. ### is the temperature (default default_on_temp) that triggers the HP to turn ON. Mode ID should be one of loadUp, shed, criticalPeak, gridEmergency, advLoadUp, or normal (or left blank for normal mode).

• SOOCHNG_OFF_[Mode ID]:### — Temperature variable at the OFF aquastat setpoint (may be the same as the ON variable). ### is the temperature (default default_off_temp) that triggers the HP to turn OFF. Same Mode ID options as above.

Parameters:

dfpd.DataFrame

Post-transformed minute-level data DataFrame. Must contain consecutive, in-order minutes; out-of-order rows or gaps may produce erroneous alarms.

daily_dfpd.DataFrame

Post-transformed daily-level data DataFrame.

configConfigManager

Pipeline configuration object. Points to a Variable_Names.csv file that must contain at least the columns variable_name and alarm_codes.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

default_power_thresholdfloat, optional

Default power threshold in kW for POW alarm codes when no custom bound is provided (default 1.0). Heat pump is considered on when power exceeds this value.

default_on_tempfloat, optional

Default ON temperature threshold in degrees F (default 115.0). An alarm triggers when the HP turns on and the temperature is more than 5.0 degrees from this value.

default_off_tempfloat, optional

Default OFF temperature threshold in degrees F (default 140.0). An alarm triggers when the HP turns off and the temperature is more than 5.0 degrees from this value.

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if df is empty or Variable_Names.csv cannot be found.

ecopipeline.event_tracking.flag_unexpected_temp(df: DataFrame, daily_df: DataFrame, config: ConfigManager, system: str = '', default_high_temp: float = 130, default_low_temp: float = 115, fault_time: int = 10) → DataFrame

Detect temperatures outside an acceptable range.

Triggers an alarm when a temperature variable stays above the high bound or below the low bound for fault_time consecutive minutes.

VarNames syntax (alarm_codes column in Variable_Names.csv):

• TMPRNG_[OPTIONAL ID]:###-### — Temperature variable with acceptable range. The ###-### portion defines the low and high bounds (e.g., TMPRNG:110-130 means temperature must stay between 110 and 130 degrees).

Parameters:

dfpd.DataFrame

Post-transformed minute-level data DataFrame. Must contain consecutive, in-order minutes; out-of-order rows or gaps may produce erroneous alarms.

daily_dfpd.DataFrame

Post-transformed daily-level data DataFrame. Used to determine which days to process.

configConfigManager

Pipeline configuration object. Points to a Variable_Names.csv file that must contain at least the columns variable_name and alarm_codes.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

default_high_tempfloat, optional

Default upper temperature bound in degrees F when no custom range is provided in the alarm code (default 130). Temperature above this value triggers an alarm.

default_low_tempfloat, optional

Default lower temperature bound in degrees F when no custom range is provided in the alarm code (default 115). Temperature below this value triggers an alarm.

fault_timeint, optional

Consecutive minutes temperature must be outside the acceptable range before an alarm is triggered (default 10).

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if df is empty or Variable_Names.csv cannot be found.

ecopipeline.event_tracking.power_ratio_alarm(daily_df: DataFrame, config: ConfigManager, day_table_name: str, system: str = '', verbose: bool = False, ratio_period_days: int = 7) → DataFrame

Detect power-ratio anomalies using daily energy data.

Reads power-ratio alarm configuration from Variable_Names.csv via config and triggers alarms when the ratio of one power variable to another falls outside the defined bounds over a rolling window.

Parameters:

daily_dfpd.DataFrame

Post-transformed daily-level data DataFrame. Must contain consecutive, in-order days; out-of-order rows or gaps may produce erroneous alarms.

configConfigManager

Pipeline configuration object. Points to a Variable_Names.csv file that must contain at least the columns variable_name and alarm_codes. Ratio alarm codes take the form PR_{Power Ratio Name}:{low percentage}-{high percentage}.

day_table_namestr

Name of the daily database table used to fetch historical data for the rolling-period calculation.

systemstr, optional

Name of the system to filter on when Variable_Names.csv contains multiple systems. Pass an empty string (default) if not applicable.

verbosebool, optional

If True, emit additional print statements during processing (default False).

ratio_period_daysint, optional

Number of days in the rolling power-ratio window (default 7).

Returns:

pd.DataFrame

DataFrame of alarm events. Returns an empty DataFrame if no alarms are triggered or Variable_Names.csv cannot be found.