open-fdd 0.1.1__py3-none-any.whl → 0.1.4__py3-none-any.whl

open_fdd/air_handling_unit/faults/fault_condition.py

@@ -1,28 +1,52 @@
+import pandas as pd
 import pandas.api.types as pdtypes
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
 import sys
 
+"""see __init__.py for fault classes"""
+
+
+class MissingColumnError(Exception):
+    """Custom exception raised when a required column is missing or None."""
+
+    def __init__(self, message):
+        self.message = message
+        super().__init__(self.message)
+
+
+class InvalidParameterError(Exception):
+    """Custom exception raised when a parameter is not valid (e.g., not a float)."""
+
+    def __init__(self, message):
+        self.message = message
+        super().__init__(self.message)
+
 
 class FaultCondition:
     """Parent class for Fault Conditions. Methods are inherited to all children."""
 
-    def set_attributes(self, dict_):
-        """Passes dictionary into initialization of class instance, then uses the attributes called out below in
-        attributes_dict to set only the attributes that match from dict_.
+    def __init__(self):
+        self.required_columns = []
 
-        :param dict_: dictionary of all possible class attributes (loaded from config file)
-        """
-        for attribute in self.__dict__:
+    def set_attributes(self, dict_):
+        """Passes dictionary into initialization of class instance"""
+        for attribute in self.__dict__.keys():
             upper = attribute.upper()
-            value = dict_[upper]
-            self.__setattr__(attribute, value)
+            if upper in dict_:
+                value = dict_[upper]
+                self.__setattr__(attribute, value)
 
-    def troubleshoot_cols(self, df):
-        """print troubleshoot columns mapping
+    def check_required_columns(self, df: pd.DataFrame):
+        """Checks if required columns are present in the DataFrame."""
+        missing_columns = [
+            col for col in self.required_columns if col is None or col not in df.columns
+        ]
 
-        :param df:
-        :return:
-        """
+        if missing_columns:
+            raise MissingColumnError(f"Missing required columns: {missing_columns}")
+
+    def troubleshoot_cols(self, df):
+        """Print troubleshoot columns mapping."""
         print("Troubleshoot mode enabled - not removing helper columns")
         for col in df.columns:
             print(
@@ -36,11 +60,7 @@ class FaultCondition:
             sys.stdout.flush()
 
     def check_analog_pct(self, df, columns):
-        """check analog outputs [data with units of %] are floats only
-
-        :param columns:
-        :return:
-        """
+        """Check analog outputs [data with units of %] are floats only."""
         helper = HelperUtils()
         for col in columns:
             if not pdtypes.is_float_dtype(df[col]):

open_fdd/air_handling_unit/faults/fault_condition_eight.py

@@ -1,7 +1,9 @@
 import pandas as pd
 import numpy as np
-from open_fdd.air_handling_unit.faults.fault_condition import FaultCondition
-from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+from open_fdd.air_handling_unit.faults.fault_condition import (
+    FaultCondition,
+    MissingColumnError,
+)
 import sys
 
 
@@ -12,6 +14,7 @@ class FaultConditionEight(FaultCondition):
     """
 
     def __init__(self, dict_):
+        super().__init__()
         self.delta_t_supply_fan = float
         self.mix_degf_err_thres = float
         self.supply_degf_err_thres = float
@@ -23,45 +26,102 @@ class FaultConditionEight(FaultCondition):
         self.troubleshoot_mode = bool  # default should be False
         self.rolling_window_size = int
 
-        self.set_attributes(dict_)
+        self.equation_string = (
+            "fc8_flag = 1 if |SAT - MAT - ΔT_fan| > √(εSAT² + εMAT²) "
+            "in economizer mode for N consecutive values else 0 \n"
+        )
+        self.description_string = (
+            "Fault Condition 8: Supply air temperature and mixed air temperature should "
+            "be approximately equal in economizer mode \n"
+        )
+        self.required_column_description = (
+            "Required inputs are the mixed air temperature, supply air temperature, "
+            "economizer signal, and cooling signal \n"
+        )
+        self.error_string = f"One or more required columns are missing or None \n"
 
-    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
-        if self.troubleshoot_mode:
-            self.troubleshoot_cols(df)
+        self.set_attributes(dict_)
 
-        # Check analog outputs [data with units of %] are floats only
-        columns_to_check = [
+        # Set required columns specific to this fault condition
+        self.required_columns = [
+            self.mat_col,
+            self.sat_col,
             self.economizer_sig_col,
             self.cooling_sig_col,
         ]
 
-        self.check_analog_pct(df, columns_to_check)
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
 
-        df["sat_fan_mat"] = abs(
-            df[self.sat_col] - self.delta_t_supply_fan - df[self.mat_col]
-        )
-        df["sat_mat_sqrted"] = np.sqrt(
-            self.supply_degf_err_thres**2 + self.mix_degf_err_thres**2
-        )
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
 
-        df["combined_check"] = (
-            (df["sat_fan_mat"] > df["sat_mat_sqrted"])
-            & (df[self.economizer_sig_col] > self.ahu_min_oa_dpr)
-            & (df[self.cooling_sig_col] < 0.1)
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
         )
 
-        # Rolling sum to count consecutive trues
-        rolling_sum = (
-            df["combined_check"].rolling(window=self.rolling_window_size).sum()
+    def get_required_columns(self) -> str:
+        """Returns a string representation of the required columns."""
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
         )
-        # Set flag to 1 if rolling sum equals the window size
-        df["fc8_flag"] = (rolling_sum >= self.rolling_window_size).astype(int)
 
-        if self.troubleshoot_mode:
-            print("Troubleshoot mode enabled - not removing helper columns")
-            sys.stdout.flush()
-            del df["sat_fan_mat"]
-            del df["sat_mat_sqrted"]
-            del df["combined_check"]
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        try:
+            # Ensure all required columns are present
+            self.check_required_columns(df)
 
-        return df
+            if self.troubleshoot_mode:
+                self.troubleshoot_cols(df)
+
+            # Check analog outputs [data with units of %] are floats only
+            columns_to_check = [
+                self.economizer_sig_col,
+                self.cooling_sig_col,
+            ]
+
+            self.check_analog_pct(df, columns_to_check)
+
+            df["sat_fan_mat"] = abs(
+                df[self.sat_col] - self.delta_t_supply_fan - df[self.mat_col]
+            )
+            df["sat_mat_sqrted"] = np.sqrt(
+                self.supply_degf_err_thres**2 + self.mix_degf_err_thres**2
+            )
+
+            df["combined_check"] = (
+                (df["sat_fan_mat"] > df["sat_mat_sqrted"])
+                & (df[self.economizer_sig_col] > self.ahu_min_oa_dpr)
+                & (df[self.cooling_sig_col] < 0.1)
+            )
+
+            # Rolling sum to count consecutive trues
+            rolling_sum = (
+                df["combined_check"].rolling(window=self.rolling_window_size).sum()
+            )
+            # Set flag to 1 if rolling sum equals the window size
+            df["fc8_flag"] = (rolling_sum >= self.rolling_window_size).astype(int)
+
+            if self.troubleshoot_mode:
+                print("Troubleshoot mode enabled - not removing helper columns")
+                sys.stdout.flush()
+                del df["sat_fan_mat"]
+                del df["sat_mat_sqrted"]
+                del df["combined_check"]
+
+            return df
+
+        except MissingColumnError as e:
+            print(f"Error: {e.message}")
+            sys.stdout.flush()
+            raise e

open_fdd/air_handling_unit/faults/fault_condition_eleven.py

@@ -1,7 +1,8 @@
 import pandas as pd
-import numpy as np
-from open_fdd.air_handling_unit.faults.fault_condition import FaultCondition
-from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+from open_fdd.air_handling_unit.faults.fault_condition import (
+    FaultCondition,
+    MissingColumnError,
+)
 import sys
 
 
@@ -9,11 +10,11 @@ class FaultConditionEleven(FaultCondition):
     """Class provides the definitions for Fault Condition 11.
     Outside air temperature too low for 100% outdoor
     air cooling in economizer cooling mode.
-
     Economizer performance fault
     """
 
     def __init__(self, dict_):
+        super().__init__()
         self.delta_t_supply_fan = float
         self.outdoor_degf_err_thres = float
         self.supply_degf_err_thres = float
@@ -24,45 +25,102 @@ class FaultConditionEleven(FaultCondition):
         self.troubleshoot_mode = bool  # default False
         self.rolling_window_size = int
 
-        self.set_attributes(dict_)
+        self.equation_string = (
+            "fc11_flag = 1 if OAT < (SATSP - ΔT_fan - εSAT) in "
+            "economizer cooling mode for N consecutive values else 0 \n"
+        )
+        self.description_string = (
+            "Fault Condition 11: Outside air temperature too low for 100% outdoor air cooling "
+            "in economizer cooling mode (Economizer performance fault) \n"
+        )
+        self.required_column_description = (
+            "Required inputs are the supply air temperature setpoint, outside air temperature, "
+            "cooling signal, and economizer signal \n"
+        )
+        self.error_string = f"One or more required columns are missing or None \n"
 
-    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
-        if self.troubleshoot_mode:
-            self.troubleshoot_cols(df)
+        self.set_attributes(dict_)
 
-        # Check analog outputs [data with units of %] are floats only
-        columns_to_check = [
-            self.economizer_sig_col,
+        # Set required columns specific to this fault condition
+        self.required_columns = [
+            self.sat_setpoint_col,
+            self.oat_col,
             self.cooling_sig_col,
+            self.economizer_sig_col,
         ]
-        self.check_analog_pct(df, columns_to_check)
 
-        df["oat_plus_oaterror"] = df[self.oat_col] + self.outdoor_degf_err_thres
-        df["satsp_delta_saterr"] = (
-            df[self.sat_setpoint_col]
-            - self.delta_t_supply_fan
-            - self.supply_degf_err_thres
-        )
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
+
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
 
-        df["combined_check"] = (
-            (df["oat_plus_oaterror"] < df["satsp_delta_saterr"])
-            # verify ahu is running in OS 3 clg mode in 100 OA
-            & (df[self.cooling_sig_col] > 0.01)
-            & (df[self.economizer_sig_col] > 0.9)
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
         )
 
-        # Rolling sum to count consecutive trues
-        rolling_sum = (
-            df["combined_check"].rolling(window=self.rolling_window_size).sum()
+    def get_required_columns(self) -> str:
+        """Returns a string representation of the required columns."""
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
         )
-        # Set flag to 1 if rolling sum equals the window size
-        df["fc11_flag"] = (rolling_sum >= self.rolling_window_size).astype(int)
 
-        if self.troubleshoot_mode:
-            print("Troubleshoot mode enabled - not removing helper columns")
-            sys.stdout.flush()
-            del df["oat_plus_oaterror"]
-            del df["satsp_delta_saterr"]
-            del df["combined_check"]
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        try:
+            # Ensure all required columns are present
+            self.check_required_columns(df)
+
+            if self.troubleshoot_mode:
+                self.troubleshoot_cols(df)
+
+            # Check analog outputs [data with units of %] are floats only
+            columns_to_check = [
+                self.economizer_sig_col,
+                self.cooling_sig_col,
+            ]
+            self.check_analog_pct(df, columns_to_check)
+
+            df["oat_plus_oaterror"] = df[self.oat_col] + self.outdoor_degf_err_thres
+            df["satsp_delta_saterr"] = (
+                df[self.sat_setpoint_col]
+                - self.delta_t_supply_fan
+                - self.supply_degf_err_thres
+            )
 
-        return df
+            df["combined_check"] = (
+                (df["oat_plus_oaterror"] < df["satsp_delta_saterr"])
+                # verify ahu is running in OS 3 clg mode in 100 OA
+                & (df[self.cooling_sig_col] > 0.01)
+                & (df[self.economizer_sig_col] > 0.9)
+            )
+
+            # Rolling sum to count consecutive trues
+            rolling_sum = (
+                df["combined_check"].rolling(window=self.rolling_window_size).sum()
+            )
+            # Set flag to 1 if rolling sum equals the window size
+            df["fc11_flag"] = (rolling_sum >= self.rolling_window_size).astype(int)
+
+            if self.troubleshoot_mode:
+                print("Troubleshoot mode enabled - not removing helper columns")
+                sys.stdout.flush()
+                del df["oat_plus_oaterror"]
+                del df["satsp_delta_saterr"]
+                del df["combined_check"]
+
+            return df
+
+        except MissingColumnError as e:
+            print(f"Error: {e.message}")
+            sys.stdout.flush()
+            raise e

open_fdd/air_handling_unit/faults/fault_condition_fifteen.py

@@ -1,17 +1,20 @@
 import pandas as pd
 import numpy as np
-from open_fdd.air_handling_unit.faults.fault_condition import FaultCondition
-from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+from open_fdd.air_handling_unit.faults.fault_condition import (
+    FaultCondition,
+    MissingColumnError,
+)
 import sys
 
 
 class FaultConditionFifteen(FaultCondition):
     """Class provides the definitions for Fault Condition 15.
-    Temperature rise across inactive heating coi.
+    Temperature rise across inactive heating coil.
     Requires coil leaving temp sensor.
     """
 
     def __init__(self, dict_):
+        super().__init__()
         self.delta_supply_fan = float
         self.coil_temp_enter_err_thres = float
         self.coil_temp_leav_err_thres = float
@@ -25,66 +28,125 @@ class FaultConditionFifteen(FaultCondition):
         self.troubleshoot_mode = bool  # default to False
         self.rolling_window_size = int
 
-        self.set_attributes(dict_)
+        self.equation_string = (
+            "fc15_flag = 1 if ΔT_coil >= √(εcoil_enter² + εcoil_leave²) + ΔT_fan "
+            "in inactive heating coil mode for N consecutive values else 0 \n"
+        )
+        self.description_string = (
+            "Fault Condition 15: Temperature rise across inactive heating coil "
+            "detected, requiring coil leaving temperature sensor \n"
+        )
+        self.required_column_description = (
+            "Required inputs are the heating coil entering temperature, heating coil leaving temperature, "
+            "cooling signal, heating signal, economizer signal, and supply fan VFD speed \n"
+        )
+        self.error_string = f"One or more required columns are missing or None \n"
 
-    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
-        if self.troubleshoot_mode:
-            self.troubleshoot_cols(df)
+        self.set_attributes(dict_)
 
-        # Check analog outputs [data with units of %] are floats only
-        columns_to_check = [
-            self.economizer_sig_col,
+        # Set required columns specific to this fault condition
+        self.required_columns = [
+            self.htg_coil_enter_temp_col,
+            self.htg_coil_leave_temp_col,
             self.cooling_sig_col,
             self.heating_sig_col,
+            self.economizer_sig_col,
             self.supply_vfd_speed_col,
         ]
-        self.check_analog_pct(df, columns_to_check)
 
-        # Create helper columns
-        df["htg_delta_temp"] = (
-            df[self.htg_coil_leave_temp_col] - df[self.htg_coil_enter_temp_col]
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
+
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
+
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
         )
 
-        df["htg_delta_sqrted"] = (
-            np.sqrt(
-                self.coil_temp_enter_err_thres**2 + self.coil_temp_leav_err_thres**2
-            )
-            + self.delta_supply_fan
+    def get_required_columns(self) -> str:
+        """Returns a string representation of the required columns."""
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
         )
 
-        df["combined_check"] = (
-            (
-                (df["htg_delta_temp"] >= df["htg_delta_sqrted"])
-                # verify AHU is in OS2 only free cooling mode
-                & (df[self.economizer_sig_col] > self.ahu_min_oa_dpr)
-                & (df[self.cooling_sig_col] < 0.1)
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        try:
+            # Ensure all required columns are present
+            self.check_required_columns(df)
+
+            if self.troubleshoot_mode:
+                self.troubleshoot_cols(df)
+
+            # Check analog outputs [data with units of %] are floats only
+            columns_to_check = [
+                self.economizer_sig_col,
+                self.cooling_sig_col,
+                self.heating_sig_col,
+                self.supply_vfd_speed_col,
+            ]
+            self.check_analog_pct(df, columns_to_check)
+
+            # Create helper columns
+            df["htg_delta_temp"] = (
+                df[self.htg_coil_leave_temp_col] - df[self.htg_coil_enter_temp_col]
+            )
+
+            df["htg_delta_sqrted"] = (
+                np.sqrt(
+                    self.coil_temp_enter_err_thres**2 + self.coil_temp_leav_err_thres**2
+                )
+                + self.delta_supply_fan
             )
-            | (
-                (df["htg_delta_temp"] >= df["htg_delta_sqrted"])
-                # OS4 AHU state clg @ min OA
-                & (df[self.cooling_sig_col] > 0.01)
-                & (df[self.economizer_sig_col] == self.ahu_min_oa_dpr)
+
+            df["combined_check"] = (
+                (
+                    (df["htg_delta_temp"] >= df["htg_delta_sqrted"])
+                    # verify AHU is in OS2 only free cooling mode
+                    & (df[self.economizer_sig_col] > self.ahu_min_oa_dpr)
+                    & (df[self.cooling_sig_col] < 0.1)
+                )
+                | (
+                    (df["htg_delta_temp"] >= df["htg_delta_sqrted"])
+                    # OS4 AHU state clg @ min OA
+                    & (df[self.cooling_sig_col] > 0.01)
+                    & (df[self.economizer_sig_col] == self.ahu_min_oa_dpr)
+                )
+                | (
+                    (df["htg_delta_temp"] >= df["htg_delta_sqrted"])
+                    # verify AHU is running in OS 3 clg mode in 100 OA
+                    & (df[self.cooling_sig_col] > 0.01)
+                    & (df[self.economizer_sig_col] > 0.9)
+                )
             )
-            | (
-                (df["htg_delta_temp"] >= df["htg_delta_sqrted"])
-                # verify AHU is running in OS 3 clg mode in 100 OA
-                & (df[self.cooling_sig_col] > 0.01)
-                & (df[self.economizer_sig_col] > 0.9)
+
+            # Rolling sum to count consecutive trues
+            rolling_sum = (
+                df["combined_check"].rolling(window=self.rolling_window_size).sum()
             )
-        )
+            # Set flag to 1 if rolling sum equals the window size
+            df["fc15_flag"] = (rolling_sum >= self.rolling_window_size).astype(int)
 
-        # Rolling sum to count consecutive trues
-        rolling_sum = (
-            df["combined_check"].rolling(window=self.rolling_window_size).sum()
-        )
-        # Set flag to 1 if rolling sum equals the window size
-        df["fc15_flag"] = (rolling_sum >= self.rolling_window_size).astype(int)
+            if self.troubleshoot_mode:
+                print("Troubleshoot mode enabled - not removing helper columns")
+                sys.stdout.flush()
+                del df["htg_delta_temp"]
+                del df["htg_delta_sqrted"]
+                del df["combined_check"]
 
-        if self.troubleshoot_mode:
-            print("Troubleshoot mode enabled - not removing helper columns")
-            sys.stdout.flush()
-            del df["htg_delta_temp"]
-            del df["htg_delta_sqrted"]
-            del df["combined_check"]
+            return df
 
-        return df
+        except MissingColumnError as e:
+            print(f"Error: {e.message}")
+            sys.stdout.flush()
+            raise e