Alarm Classes Documentation

class ecopipeline.event_tracking.alarms.AbnormalCOP.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.alarms.BackupUse.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.alarms.BalancingValve.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.alarms.BlownFuse.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.alarms.Boundary.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.alarms.HPWHInlet.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.alarms.HPWHOutage.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.alarms.HPWHOutlet.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.alarms.LSInconsist.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.alarms.PowerRatio.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.alarms.ShortCycle.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.alarms.SOOChange.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.alarms.TempRange.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)

class ecopipeline.event_tracking.alarms.TMSetpoint.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)