open-fdd 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

open_fdd/air_handling_unit/reports/fault_report.py

@@ -0,0 +1,41 @@
+import matplotlib.pyplot as plt
+import pandas as pd
+import numpy as np
+import sys
+
+
+class BaseFaultReport:
+    def __init__(self, config, fault_col):
+        self.config = config
+        self.fault_col = fault_col
+
+    def create_plot(self, df: pd.DataFrame):
+        raise NotImplementedError
+
+    def summarize_fault_times(self, df: pd.DataFrame) -> dict:
+        raise NotImplementedError
+
+    def create_hist_plot(self, df: pd.DataFrame):
+        df[f"hour_of_the_day_{self.fault_col}"] = df.index.hour.where(
+            df[self.fault_col] == 1
+        )
+        fig, ax = plt.subplots(tight_layout=True, figsize=(25, 8))
+        ax.hist(df[f"hour_of_the_day_{self.fault_col}"].dropna())
+        ax.set_xlabel("Hour of the Day")
+        ax.set_ylabel("Frequency")
+        ax.set_title(f"Hour-Of-Day When Fault Flag {self.fault_col} is TRUE")
+        plt.show()
+        plt.close()
+
+    def display_report_in_ipython(self, df: pd.DataFrame):
+        summary = self.summarize_fault_times(df)
+        for key, value in summary.items():
+            formatted_key = key.replace("_", " ")
+            print(f"{formatted_key}: {value}")
+            sys.stdout.flush()
+
+        if df[self.fault_col].max() != 0:
+            self.create_hist_plot(df)
+        else:
+            print("NO FAULTS FOUND - Skipping time-of-day Histogram plot")
+            sys.stdout.flush()

open_fdd/tests/ahu/test_ahu_fc1.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_one import FaultConditionOne
+from open_fdd.air_handling_unit.faults import FaultConditionOne
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
 from open_fdd.air_handling_unit.faults.fault_condition import MissingColumnError
 

open_fdd/tests/ahu/test_ahu_fc10.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_ten import FaultConditionTen
+from open_fdd.air_handling_unit.faults import FaultConditionTen
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
 
 """

open_fdd/tests/ahu/test_ahu_fc11.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_eleven import (
+from open_fdd.air_handling_unit.faults import (
     FaultConditionEleven,
 )
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils

open_fdd/tests/ahu/test_ahu_fc12.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_twelve import (
+from open_fdd.air_handling_unit.faults import (
     FaultConditionTwelve,
 )
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils

open_fdd/tests/ahu/test_ahu_fc13.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_thirteen import (
+from open_fdd.air_handling_unit.faults import (
     FaultConditionThirteen,
 )
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils

open_fdd/tests/ahu/test_ahu_fc14.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_fourteen import (
+from open_fdd.air_handling_unit.faults import (
     FaultConditionFourteen,
 )
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils

open_fdd/tests/ahu/test_ahu_fc15.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_fifteen import (
+from open_fdd.air_handling_unit.faults import (
     FaultConditionFifteen,
 )
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils

open_fdd/tests/ahu/test_ahu_fc2.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_two import FaultConditionTwo
+from open_fdd.air_handling_unit.faults import FaultConditionTwo
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
 
 """

open_fdd/tests/ahu/test_ahu_fc3.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_three import FaultConditionThree
+from open_fdd.air_handling_unit.faults import FaultConditionThree
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
 
 """

open_fdd/tests/ahu/test_ahu_fc4.py

@@ -1,128 +1,200 @@
 import pandas as pd
-from open_fdd.air_handling_unit.faults.fault_condition import (
-    FaultCondition,
-    MissingColumnError,
-)
-import sys
-
-
-class FaultConditionFour(FaultCondition):
-    """Class provides the definitions for Fault Condition 4.
-
-    This fault flags excessive operating states on the AHU
-    if it's hunting between heating, econ, econ+mech, and
-    a mech clg modes. The code counts how many operating
-    changes in an hour and will throw a fault if there is
-    excessive OS changes to flag control sys hunting.
-    """
-
-    def __init__(self, dict_):
-        super().__init__()
-        self.delta_os_max = float
-        self.ahu_min_oa_dpr = float
-        self.economizer_sig_col = str
-        self.heating_sig_col = str
-        self.cooling_sig_col = str
-        self.supply_vfd_speed_col = str
-        self.troubleshoot_mode = bool  # default to False
-
-        self.set_attributes(dict_)
-
-        # Set required columns, making heating and cooling optional
-        self.required_columns = [
-            self.economizer_sig_col,
-            self.supply_vfd_speed_col,
-        ]
-
-        # If heating or cooling columns are provided, add them to the required columns
-        if self.heating_sig_col:
-            self.required_columns.append(self.heating_sig_col)
-        if self.cooling_sig_col:
-            self.required_columns.append(self.cooling_sig_col)
-
-    def get_required_columns(self) -> str:
-        """Returns a string representation of the required columns."""
-        return f"Required columns for FaultConditionFour: {', '.join(self.required_columns)}"
-
-    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
-        try:
-            # Ensure all required columns are present
-            self.check_required_columns(df)
-
-            # If the optional columns are not present, create them with all values set to 0.0
-            if self.heating_sig_col not in df.columns:
-                df[self.heating_sig_col] = 0.0
-            if self.cooling_sig_col not in df.columns:
-                df[self.cooling_sig_col] = 0.0
-
-            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.heating_sig_col,
-                self.cooling_sig_col,
-                self.supply_vfd_speed_col,
-            ]
-
-            for col in columns_to_check:
-                self.check_analog_pct(df, [col])
-
-            print("=" * 50)
-            print("Warning: The program is in FC4 and resampling the data")
-            print("to compute AHU OS state changes per hour")
-            print("to flag any hunting issue")
-            print("and this usually takes a while to run...")
-            print("=" * 50)
-
-            sys.stdout.flush()
-
-            # AHU htg only mode based on OA damper @ min oa and only htg pid/vlv modulating
-            df["heating_mode"] = (
-                (df[self.heating_sig_col] > 0)
-                & (df[self.cooling_sig_col] == 0)
-                & (df[self.supply_vfd_speed_col] > 0)
-                & (df[self.economizer_sig_col] == self.ahu_min_oa_dpr)
-            )
-
-            # AHU econ only mode based on OA damper modulating and clg htg = zero
-            df["econ_only_cooling_mode"] = (
-                (df[self.heating_sig_col] == 0)
-                & (df[self.cooling_sig_col] == 0)
-                & (df[self.supply_vfd_speed_col] > 0)
-                & (df[self.economizer_sig_col] > self.ahu_min_oa_dpr)
-            )
-
-            # AHU econ+mech clg mode based on OA damper modulating for cooling and clg pid/vlv modulating
-            df["econ_plus_mech_cooling_mode"] = (
-                (df[self.heating_sig_col] == 0)
-                & (df[self.cooling_sig_col] > 0)
-                & (df[self.supply_vfd_speed_col] > 0)
-                & (df[self.economizer_sig_col] > self.ahu_min_oa_dpr)
-            )
-
-            # AHU mech mode based on OA damper @ min OA and clg pid/vlv modulating
-            df["mech_cooling_only_mode"] = (
-                (df[self.heating_sig_col] == 0)
-                & (df[self.cooling_sig_col] > 0)
-                & (df[self.supply_vfd_speed_col] > 0)
-                & (df[self.economizer_sig_col] == self.ahu_min_oa_dpr)
-            )
-
-            # Fill non-finite values with zero or drop them
-            df = df.fillna(0)
-
-            df = df.astype(int)
-            df = df.resample("60min").apply(lambda x: (x.eq(1) & x.shift().ne(1)).sum())
-
-            df["fc4_flag"] = (
-                df[df.columns].gt(self.delta_os_max).any(axis=1).astype(int)
-            )
-
-            return df
-
-        except MissingColumnError as e:
-            print(f"Error: {e.message}")
-            sys.stdout.flush()
-            raise e  # Re-raise the exception so it can be caught by pytest
+import pytest
+from open_fdd.air_handling_unit.faults import FaultConditionFour
+from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+from datetime import datetime, timezone
+
+"""
+To see print statements in pytest run with:
+$ py -3.12 -m pytest tests/ahu/test_ahu_fc4.py -rP -s
+
+Too much hunting in control system
+OS state changes greater than 7 in an hour
+"""
+
+# Constants
+DELTA_OS_MAX = 7
+AHU_MIN_OA = 0.20
+TEST_MIX_AIR_DAMPER_COL = "economizer_sig_col"
+TEST_HEATING_COIL_SIG_COL = "heating_sig_col"
+TEST_COOLING_COIL_SIG_COL = "cooling_sig_col"
+TEST_SUPPLY_VFD_SPEED_COL = "fan_vfd_speed_col"
+TEST_DATASET_ROWS = 60
+
+# Initialize FaultConditionFour with a dictionary
+fault_condition_params = {
+    "DELTA_OS_MAX": DELTA_OS_MAX,
+    "AHU_MIN_OA_DPR": AHU_MIN_OA,
+    "ECONOMIZER_SIG_COL": TEST_MIX_AIR_DAMPER_COL,
+    "HEATING_SIG_COL": TEST_HEATING_COIL_SIG_COL,
+    "COOLING_SIG_COL": TEST_COOLING_COIL_SIG_COL,
+    "SUPPLY_VFD_SPEED_COL": TEST_SUPPLY_VFD_SPEED_COL,
+    "TROUBLESHOOT_MODE": False,  # default value
+}
+
+fc4 = FaultConditionFour(fault_condition_params)
+
+
+def generate_timestamp() -> pd.Series:
+    df = pd.DataFrame()
+    date_range = pd.period_range(
+        # make a time stamp starting at top of
+        # the hour with one min intervals
+        start=datetime(2022, 6, 6, 14, 30, 0, 0, tzinfo=timezone.utc),
+        periods=TEST_DATASET_ROWS,
+        freq="min",
+    )
+    df["Date"] = [x.to_timestamp() for x in date_range]
+    return df["Date"]
+
+
+def econ_plus_mech_clg_row() -> dict:
+    data = {
+        TEST_MIX_AIR_DAMPER_COL: 0.6,
+        TEST_HEATING_COIL_SIG_COL: 0.0,
+        TEST_COOLING_COIL_SIG_COL: 0.6,
+        TEST_SUPPLY_VFD_SPEED_COL: 0.8,
+    }
+    return data
+
+
+def mech_clg_row() -> dict:
+    data = {
+        TEST_MIX_AIR_DAMPER_COL: 0.0,
+        TEST_HEATING_COIL_SIG_COL: 0.0,
+        TEST_COOLING_COIL_SIG_COL: 0.6,
+        TEST_SUPPLY_VFD_SPEED_COL: 0.8,
+    }
+    return data
+
+
+def econ_plus_mech_clg_row_int() -> dict:
+    data = {
+        TEST_MIX_AIR_DAMPER_COL: 0.6,
+        TEST_HEATING_COIL_SIG_COL: 0.0,
+        TEST_COOLING_COIL_SIG_COL: 0.6,
+        TEST_SUPPLY_VFD_SPEED_COL: 88,
+    }
+    return data
+
+
+def econ_plus_mech_clg_row_float_greater_than_one() -> dict:
+    data = {
+        TEST_MIX_AIR_DAMPER_COL: 0.6,
+        TEST_HEATING_COIL_SIG_COL: 0.0,
+        TEST_COOLING_COIL_SIG_COL: 0.6,
+        TEST_SUPPLY_VFD_SPEED_COL: 88.8,
+    }
+    return data
+
+
+class TestFault(object):
+
+    def fault_df(self) -> pd.DataFrame:
+        data = []
+        counter = 0
+        for i in range(TEST_DATASET_ROWS):
+            if i % 2 == 0 and counter < 11:
+                data.append(econ_plus_mech_clg_row())
+                counter += 1  # only simulate 10 OS changes
+            else:
+                data.append(mech_clg_row())
+        return pd.DataFrame(data)
+
+    def test_fault(self):
+        fault_df = self.fault_df().set_index(generate_timestamp())
+        results = fc4.apply(fault_df)
+        actual = results["fc4_flag"].sum()
+        expected = 1
+        message = f"FC4 fault_df actual is {actual} and expected is {expected}"
+        assert actual == expected, message
+
+
+class TestNoFault(object):
+
+    def no_fault_df(self) -> pd.DataFrame:
+        data = []
+        for i in range(TEST_DATASET_ROWS):
+            data.append(mech_clg_row())
+        return pd.DataFrame(data)
+
+    def test_no_fault(self):
+        no_fault_df = self.no_fault_df().set_index(generate_timestamp())
+        results = fc4.apply(no_fault_df)
+        actual = results["fc4_flag"].sum()
+        expected = 0
+        message = f"FC4 no_fault_df actual is {actual} and expected is {expected}"
+        assert actual == expected, message
+
+
+class TestFaultOnInt(object):
+
+    def fault_df_on_output_int(self) -> pd.DataFrame:
+        data = []
+        for i in range(TEST_DATASET_ROWS):
+            if i % 2 == 0:
+                data.append(econ_plus_mech_clg_row_int())
+            else:
+                data.append(mech_clg_row())
+        return pd.DataFrame(data)
+
+    def test_fault_on_int(self):
+        fault_df_on_output_int = self.fault_df_on_output_int().set_index(
+            generate_timestamp()
+        )
+        with pytest.raises(
+            TypeError,
+            match=HelperUtils().float_int_check_err(TEST_SUPPLY_VFD_SPEED_COL),
+        ):
+            fc4.apply(fault_df_on_output_int)
+
+
+class TestFaultOnFloatGreaterThanOne(object):
+
+    def fault_df_on_output_greater_than_one(self) -> pd.DataFrame:
+        data = []
+        for i in range(TEST_DATASET_ROWS):
+            if i % 2 == 0:
+                data.append(econ_plus_mech_clg_row_float_greater_than_one())
+            else:
+                data.append(mech_clg_row())
+        return pd.DataFrame(data)
+
+    def test_fault_on_float_greater_than_one(self):
+        fault_df_on_output_greater_than_one = (
+            self.fault_df_on_output_greater_than_one().set_index(generate_timestamp())
+        )
+        with pytest.raises(
+            TypeError,
+            match=HelperUtils().float_max_check_err(TEST_SUPPLY_VFD_SPEED_COL),
+        ):
+            fc4.apply(fault_df_on_output_greater_than_one)
+
+
+class TestFaultOnMixedTypes(object):
+
+    def fault_df_on_mixed_types(self) -> pd.DataFrame:
+        data = []
+        for i in range(TEST_DATASET_ROWS):
+            if i % 2 == 0:
+                data.append(
+                    {
+                        TEST_MIX_AIR_DAMPER_COL: 0.6,
+                        TEST_HEATING_COIL_SIG_COL: 0.0,
+                        TEST_COOLING_COIL_SIG_COL: 0.6,
+                        TEST_SUPPLY_VFD_SPEED_COL: 1.1,
+                    }
+                )
+            else:
+                data.append(mech_clg_row())
+        return pd.DataFrame(data)
+
+    def test_fault_on_mixed_types(self):
+        fault_df_on_mixed_types = self.fault_df_on_mixed_types().set_index(
+            generate_timestamp()
+        )
+        with pytest.raises(
+            TypeError,
+            match=HelperUtils().float_max_check_err(TEST_SUPPLY_VFD_SPEED_COL),
+        ):
+            fc4.apply(fault_df_on_mixed_types)

open_fdd/tests/ahu/test_ahu_fc5.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_five import FaultConditionFive
+from open_fdd.air_handling_unit.faults import FaultConditionFive
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
 
 """

open_fdd/tests/ahu/test_ahu_fc6.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_six import FaultConditionSix
+from open_fdd.air_handling_unit.faults import FaultConditionSix
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
 
 """
@@ -12,7 +12,7 @@ OA FRACTION TOO LOW OR TOO HIGH; SHOULD BE EQUAL TO %OAmin
 
 # Constants
 TEST_AIRFLOW_ERR_THRES = 0.3
-TEST_AHU_MIN_CFM_DESIGN = 3000
+TEST_AHU_MIN_CFM_DESIGN = 3000.0
 TEST_OAT_DEGF_ERR_THRES = 5.0
 TEST_RAT_DEGF_ERR_THRES = 2.0
 TEST_DELTA_TEMP_MIN = 10.0

open_fdd/tests/ahu/test_ahu_fc7.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_seven import FaultConditionSeven
+from open_fdd.air_handling_unit.faults import FaultConditionSeven
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
 
 """

open_fdd/tests/ahu/test_ahu_fc8.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_eight import FaultConditionEight
+from open_fdd.air_handling_unit.faults import FaultConditionEight
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
 
 """

open_fdd/tests/ahu/test_ahu_fc9.py

@@ -1,6 +1,6 @@
 import pandas as pd
 import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_nine import FaultConditionNine
+from open_fdd.air_handling_unit.faults import FaultConditionNine
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
 
 """

{open_fdd-0.1.3.dist-info → open_fdd-0.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: open_fdd
-Version: 0.1.3
+Version: 0.1.5
 Summary: A package for fault detection and diagnosis in HVAC systems
 Home-page: https://github.com/bbartling/open-fdd
 Author: Ben Bartling
@@ -39,21 +39,28 @@ pip install open-fdd
 For running Jupyter notebooks, I recommend using Visual Studio Code with the Jupyter notebook extension installed, which offers a seamless experience directly within the editor. Be sure to explore the `examples` directory for Jupyter notebook tutorials. If you have your own FDD experiences to share, feel free to contribute by creating a notebook (`.ipynb`). You’re welcome to reach out to me directly, and I can push your example to GitHub on your behalf, which might be a simpler process than submitting a pull request (PR), especially if you're just sharing an example rather than developing `open-fdd`.
 
 ## Project goals
-These are some basic project goals to make this into an interactive FDD application.
- - [x] finish `air_handling_unit` faults and reports based on ASHRAE and NIST
- - [x] publish to PyPI as Python library
- - [ ] make a few IPython notebook tutorials AHU FDD examples with `BRICK` meta data integration.
- - [ ] make a guide for fault `parameters` like error thresholds, etc.
- - [ ] make `central_plant` faults, IPython reports, and examples.
- - [ ] make `energy_efficiency` faults, IPython reports, and examples to `optimize` in reducing energy consumption.
- - [ ] make `metering`, faults, IPython reports, and examples to possibly model utility metering data.
- - [ ] create SQL example to read data from time series db and write back to SQL to then read faults in Grafana.
- - [ ] other?
-
-Certainly! Here's a revised version of your contribution guidelines:
+The following are key objectives to enhance this project into a fully interactive Fault Detection and Diagnostics (FDD) application.
 
-## Contribute
+### Completed
+ - [x] Develop and finalize `air_handling_unit` fault conditions and reports, aligning with ASHRAE and NIST standards.
+ - [x] Publish the project as a Python library on PyPI.
+
+### In Progress
+ - [ ] Create IPython notebook tutorials showcasing AHU FDD examples, incorporating BRICK metadata integration.
+ - [ ] Develop a comprehensive guide on a github.io website (or other?) for defining fault parameters, including error thresholds and other critical settings.
+
+### Upcoming
+ - [ ] Extend the project to include `central_plant` fault conditions, IPython reports, and example applications.
+ - [ ] Design `energy_efficiency` fault detection modules, including IPython reports and examples focused on optimizing energy consumption.
+ - [ ] Develop `metering` fault conditions, along with IPython reports and examples, potentially modeling utility metering data.
+ - [ ] Implement SQL integration examples for reading data from a time series database, writing back to SQL, and visualizing faults in Grafana.
 
+### Future Considerations
+ Explore additional features and enhancements as the project evolves.
+ - [ ] Explore additional features and enhancements as the project evolves.
+
+
+## Contribute
 If you have suggestions for improving developer best practices or solutions, please feel free to reach out to me directly using my contact information or Git issue/discussion. I primarily work on Windows with multiple versions of Python installed, with Python 3.12.x as my default version. You can download the latest version of Python here:
 * https://www.python.org/downloads/