Add explain class and shap

.pre-commit-config.yaml

@@ -1,20 +1,20 @@
 repos:
     - repo: https://github.com/pre-commit/pre-commit-hooks
-      rev: v4.5.0
+      rev: v5.0.0
       hooks:
           - id: check-yaml
           - id: end-of-file-fixer
           - id: trailing-whitespace
           - id: check-added-large-files
     - repo: https://github.com/psf/black
-      rev: 23.3.0
+      rev: 24.10.0
       hooks:
           - id: black
-    - repo: https://github.com/PyCQA/docformatter
-      rev: v1.7.5
-      hooks:
-          - id: docformatter
+    # - repo: https://github.com/PyCQA/docformatter
+    #   rev: v1.7.5
+    #   hooks:
+    #       - id: docformatter
     - repo: https://github.com/PyCQA/flake8
-      rev: 7.0.0
+      rev: 7.1.1
       hooks:
           - id: flake8

README.md

@@ -1,10 +1,11 @@
 # pyMAISE: Michigan Artificial Intelligence Standard Environment
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Tests Status](https://github.com/myerspat/pyMAISE/actions/workflows/CI.yml/badge.svg)](https://github.com/myerspat/pyMAISE/actions/workflows)
+[![Tests Status](https://github.com/aims-umich/pyMAISE/actions/workflows/CI.yml/badge.svg)](https://github.com/aims-umich/pyMAISE/actions/workflows)
 [![Documentation Status](https://readthedocs.org/projects/pymaise/badge/?version=latest)](https://pymaise.readthedocs.io/en/latest/?badge=latest)
+[![PyPI](https://img.shields.io/pypi/v/pyMAISE?color=teal)](https://pypi.org/project/pyMAISE/)
 
-pyMAISE is an artificial intelligence (AI) and machine learning (ML) benchmarking library for nuclear reactor applications. It offers to streamline the building, tuning, and comparison of various ML models for user-provided data sets. Also, pyMAISE offers benchmarked data sets, written in Jupyter Notebooks, for AI/ML comparison. Current ML algorithm support includes
+pyMAISE is an artificial intelligence (AI) and machine learning (ML) benchmarking library for nuclear reactor applications. It offers to streamline the building, tuning, comparison, and explainability of various ML models for user-provided data sets. Also, pyMAISE offers benchmarked data sets, written in Jupyter Notebooks, for AI/ML comparison. Current ML algorithm support includes
 
 - linear regression,
 - lasso regression,
@@ -15,7 +16,14 @@ pyMAISE is an artificial intelligence (AI) and machine learning (ML) benchmarkin
 - k-nearest neighbors regression and classification,
 - sequential neural networks.
 
-These models are built using [scikit-learn](https://scikit-learn.org/stable/index.html) and [Keras](https://keras.io). pyMAISE supports the following neural network layers:
+Additionally, pyMAISE supports basic explainability analysis via SHAP for all the ML algorithms listed above. An example is provided in the CHF benchmark. Current SHAP support includes
+
+- DeepLIFT,
+- Integrated Gradients,
+- Kernel SHAP,
+- and Exact SHAP.
+
+These models are built using [scikit-learn](https://scikit-learn.org/stable/index.html) and [Keras](https://keras.io) with explainability using [SHAP](https://shap.readthedocs.io/en/latest/index.html). pyMAISE supports the following neural network layers:
 
 - dense,
 - dropout,
@@ -26,6 +34,26 @@ These models are built using [scikit-learn](https://scikit-learn.org/stable/inde
 - flatten,
 - and reshape.
 
+Please use the following to reference pyMAISE:
+```latex
+@article{MYERS2025105568,
+    title = {pyMAISE: A Python platform for automatic machine learning
+        and accelerated development for nuclear power applications},
+    journal = {Progress in Nuclear Energy},
+    volume = {180},
+    pages = {105568},
+    year = {2025},
+    issn = {0149-1970},
+    doi = {https://doi.org/10.1016/j.pnucene.2024.105568},
+    url = {
+        https://www.sciencedirect.com/science/article/pii/S0149197024005183
+    },
+    author = {Patrick A. Myers and Nataly Panczyk and Shashank Chidige
+        and Connor Craig and Jacob Cooper and Veda Joynt and Majdi
+        I. Radaideh},
+}
+```
+
 ## Installation and Documentation
 
 Refer to the [installation guide](https://pymaise.readthedocs.io/en/latest/installation.html) and [documentation](https://pymaise.readthedocs.io/en/latest/index.html) for help.
@@ -34,12 +62,12 @@ Refer to the [installation guide](https://pymaise.readthedocs.io/en/latest/insta
 
 You can find the pyMAISE benchmarks [here](https://pymaise.readthedocs.io/en/latest/benchmarks.html) or below.
 
-- [MIT Reactor](https://nbviewer.org/github/myerspat/pyMAISE/blob/develop/docs/source/benchmarks/mit_reactor.ipynb)
-- [Reactor Physics](https://nbviewer.org/github/myerspat/pyMAISE/blob/develop/docs/source/benchmarks/reactor_physics.ipynb)
-- [Fuel Performance](https://nbviewer.org/github/myerspat/pyMAISE/blob/develop/docs/source/benchmarks/fuel_performance.ipynb)
-- [Heat Conduction](https://nbviewer.org/github/myerspat/pyMAISE/blob/develop/docs/source/benchmarks/heat_conduction.ipynb)
-- [BWR Micro Core](https://nbviewer.org/github/myerspat/pyMAISE/blob/develop/docs/source/benchmarks/bwr.ipynb)
-- [HTGR Micro-Core Quadrant Power](https://nbviewer.org/github/myerspat/pyMAISE/blob/develop/docs/source/benchmarks/HTGR_microreactor.ipynb)
-- [NEACRP C1 Rod Ejection Accident](https://nbviewer.org/github/myerspat/pyMAISE/blob/develop/docs/source/benchmarks/rod_ejection.ipynb)
-- [Critical Heat Flux (CHF) Prediction](https://nbviewer.org/github/myerspat/pyMAISE/blob/develop/docs/source/benchmarks/chf.ipynb)
-- [Binary Anomaly Detection](https://nbviewer.org/github/myerspat/pyMAISE/blob/develop/docs/source/benchmarks/anomaly.ipynb)
+- [MIT Reactor](https://nbviewer.org/github/aims-umich/pyMAISE/blob/develop/docs/source/benchmarks/mit_reactor.ipynb)
+- [Reactor Physics](https://nbviewer.org/github/aims-umich/pyMAISE/blob/develop/docs/source/benchmarks/reactor_physics.ipynb)
+- [Fuel Performance](https://nbviewer.org/github/aims-umich/pyMAISE/blob/develop/docs/source/benchmarks/fuel_performance.ipynb)
+- [Heat Conduction](https://nbviewer.org/github/aims-umich/pyMAISE/blob/develop/docs/source/benchmarks/heat_conduction.ipynb)
+- [BWR Micro Core](https://nbviewer.org/github/aims-umich/pyMAISE/blob/develop/docs/source/benchmarks/bwr.ipynb)
+- [HTGR Micro-Core Quadrant Power](https://nbviewer.org/github/aims-umich/pyMAISE/blob/develop/docs/source/benchmarks/HTGR_microreactor.ipynb)
+- [NEACRP C1 Rod Ejection Accident](https://nbviewer.org/github/aims-umich/pyMAISE/blob/develop/docs/source/benchmarks/rod_ejection.ipynb)
+- [Critical Heat Flux (CHF) Prediction](https://nbviewer.org/github/aims-umich/pyMAISE/blob/develop/docs/source/benchmarks/chf.ipynb)
+- [Binary Anomaly Detection](https://nbviewer.org/github/aims-umich/pyMAISE/blob/develop/docs/source/benchmarks/anomaly.ipynb)

docs/source/benchmarks.rst

@@ -33,7 +33,7 @@ Creating Your Benchmark
 
 pyMAISE aims to be a medium for AI/ML researchers to benchmark their data sets and models with standard ML methods; subsequently, we encourage you to contribute if you are interested. Here, we outline the procedure for creating a pyMAISE benchmark. Please read the :ref:`dev_guide` before continuing.
 
-1. On the pyMAISE GitHub, open a `Benchmark Request <https://github.com/myerspat/pyMAISE/issues/new?assignees=&labels=&projects=&template=benchmark-request.md&title=>`_ under Issues. Please describe the data set you plan to use in the benchmark and link any relevant resources, such as a link to the published paper (if there is one).
+1. On the pyMAISE GitHub, open a `Benchmark Request <https://github.com/aims-umich/pyMAISE/issues/new?assignees=&labels=&projects=&template=benchmark-request.md&title=>`_ under Issues. Please describe the data set you plan to use in the benchmark and link any relevant resources, such as a link to the published paper (if there is one).
 2. Perform the following:
     1. Add the data to ``pyMAISE/datasets/``.
     2. Add a load function to ``pyMAISE/datasets/_handler.py`` and include a description of the data. This load function should return ``xarray.DataArray``.
@@ -43,6 +43,6 @@ pyMAISE aims to be a medium for AI/ML researchers to benchmark their data sets a
     6. Add the load function to the ``toctree`` in ``docs/source/pymaise_api.rst`` under :ref:`Data Sets <datasets_api>`.
     7. Add the nbviwer link to ``README.md``. Ensure this link is for the develop branch.
     8. If a published paper exists for the data set, add the BibTeX citation to ``docs/source/data_refs.bib``.
-3. Once these steps are completed, you can push the benchmark, ensuring to adhere to the workflow outlined in the :ref:`dev_guide`, and create a `pull request <https://github.com/myerspat/pyMAISE/pulls>`_.
+3. Once these steps are completed, you can push the benchmark, ensuring to adhere to the workflow outlined in the :ref:`dev_guide`, and create a `pull request <https://github.com/aims-umich/pyMAISE/pulls>`_.
 
 A reviewer will ensure the validity of the benchmark and data. They will offer feedback and possible revisions for you. Thank you for contributing!

docs/source/benchmarks/HTGR_microreactor.ipynb

@@ -30,9 +30,9 @@
     "- `fluxQ3` : Neutron flux in quadrant 3 ($\\frac{neutrons}{cm^{2} s}$)\n",
     "- `fluxQ4` : Neutron flux in quadrant 4 ($\\frac{neutrons}{cm^{2} s}$)\n",
     "\n",
-    "The `pyMAISE.datasets.load_HTGR` data features 751 samples with eight inputs and five outputs. It is the raw data from [[PRK22]](https://pymaise.readthedocs.io/en/stable/index.html#id9). Using reactor symmetry, [[PRK22]](https://pymaise.readthedocs.io/en/stable/index.html#id9) boosts the sample size to 3004. \n",
+    "The `pyMAISE.datasets.load_HTGR` data features 751 samples with eight inputs and five outputs. It is the raw data from [[PRK22]](https://pymaise.readthedocs.io/en/stable/data_refs.html). Using reactor symmetry, [[PRK22]](https://pymaise.readthedocs.io/en/stable/data_refs.html) boosts the sample size to 3004. \n",
     "\n",
-    "The data set was built using MCNP simulations of the HOLOS-Quad reactor design, which is depicted below [[PRK22]](https://pymaise.readthedocs.io/en/stable/index.html#id9). This reactor implements modular construction where separate units can be transported independently and assembled at the plant. The HOLOS-Quad core is a 22 MWt high-temperature gas-cooled microreactor (HTGR) controlled by eight cylindrical control drums. It utilizes TRISO fuel particles contained in hexagonal graphite blocks as a moderator. These graphite blocks have channels where helium gas can pass through for cooling.\n",
+    "The data set was built using MCNP simulations of the HOLOS-Quad reactor design, which is depicted below [[PRK22]](https://pymaise.readthedocs.io/en/stable/data_refs.html). This reactor implements modular construction where separate units can be transported independently and assembled at the plant. The HOLOS-Quad core is a 22 MWt high-temperature gas-cooled microreactor (HTGR) controlled by eight cylindrical control drums. It utilizes TRISO fuel particles contained in hexagonal graphite blocks as a moderator. These graphite blocks have channels where helium gas can pass through for cooling.\n",
     "\n",
     "Using machine learning (ML), we aim to predict the neutron distribution given the angles of each of the control drums $\\in[0, 2\\pi]$. The drums control reactivity by rotating to vary the proximity of $B_4C$, indicated as the red strip on the drums shown below, to the fuel. Perturbations in the control drum angle can drastically affect the power distribution in the core. Therefore, predictions of control drum reactivity worth for arbitrary configurations make this problem nontrivial.\n",
     "\n",
@@ -2297,7 +2297,7 @@
     "\n",
     "## Increasing Samples Using Reactor Symmetry (3004 Samples)\n",
     "\n",
-    "We need more data to achieve better results. As shown in [[PRK22]](https://pymaise.readthedocs.io/en/stable/index.html#id9), we can apply symmetry rules to multiply the sample size.  \n",
+    "We need more data to achieve better results. As shown in [[PRK22]](https://pymaise.readthedocs.io/en/stable/data_refs.html), we can apply symmetry rules to multiply the sample size.  \n",
     "\n",
     "### Preprocessing\n",
     "\n",
@@ -3612,7 +3612,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.4"
+   "version": "3.10.12"
   },
   "widgets": {
    "application/vnd.jupyter.widget-state+json": {

docs/source/benchmarks/anomaly.ipynb

@@ -35,9 +35,9 @@
     "\n",
     "- `Class_Run`/`Class_Fault`: Whether a waveform is a part of a system fault\n",
     "\n",
-    "This benchmark analyzes a measured dataset originating from [[RPW+22](https://pymaise.readthedocs.io/en/latest/#data-references), [RPW+23](https://pymaise.readthedocs.io/en/latest/#data-references)] for the high voltage converter modulators (HVCM) of the Spallation Neutron Source facility. While this data does not originate from a nuclear power plant, its nature is similar to that found from measured sensor data in nuclear power plants. \n",
+    "This benchmark analyzes a measured dataset originating from [[RPW+22](https://pymaise.readthedocs.io/en/stable/data_refs.html), [RPW+23](https://pymaise.readthedocs.io/en/stable/data_refs.html)] for the high voltage converter modulators (HVCM) of the Spallation Neutron Source facility. While this data does not originate from a nuclear power plant, its nature is similar to that found from measured sensor data in nuclear power plants. \n",
     "\n",
-    "HVCMs are machines powering the linear accelerator klystrons in the accelerator facility. Klystrons produce high-power radio frequency to accelerate negatively charged hydrogen ions. The waveform signals, as shown in the figure below, were collected from the operation of 15 HVCM systems from 2020 to 2022. These datasets contain the waveform signals and the waveform label recorded by the HVCM controller. These binary labels determine if the waveform was collected before a \"fault\" or \"run\" (non-fault). Each waveform consists of the 14 signals listed above, the components these originate from in the HVCM are shown in the diagram below the waveform plot. The faults may appear in one or more of these signals, and having one faulty signal is sufficient to label the waveform as faulty. In this benchmark, we ask ML models to correctly classify waveforms from the drift-tube linac (DTL) dataset, one of four datasets provided in [Mendeley](https://data.mendeley.com/datasets/kbbrw99vh8/5) from [[RPW+22](https://pymaise.readthedocs.io/en/latest/#data-references)].\n",
+    "HVCMs are machines powering the linear accelerator klystrons in the accelerator facility. Klystrons produce high-power radio frequency to accelerate negatively charged hydrogen ions. The waveform signals, as shown in the figure below, were collected from the operation of 15 HVCM systems from 2020 to 2022. These datasets contain the waveform signals and the waveform label recorded by the HVCM controller. These binary labels determine if the waveform was collected before a \"fault\" or \"run\" (non-fault). Each waveform consists of the 14 signals listed above, the components these originate from in the HVCM are shown in the diagram below the waveform plot. The faults may appear in one or more of these signals, and having one faulty signal is sufficient to label the waveform as faulty. In this benchmark, we ask ML models to correctly classify waveforms from the drift-tube linac (DTL) dataset, one of four datasets provided in [Mendeley](https://data.mendeley.com/datasets/kbbrw99vh8/5) from [[RPW+22](https://pymaise.readthedocs.io/en/stable/data_refs.html)].\n",
     "\n",
     "![hvcm_data.png](attachment:dee07ec8-d027-4ef8-b063-d6bcc29382d0.png)\n",
     "![scheme](supporting/HVCM_schem.png)\n",
@@ -59,7 +59,7 @@
     "\n",
     "## Hyperparameter Tuning\n",
     "\n",
-    "Given the quantity of data and complexity of the neural networks trained here, we hyperparameter-tuned all models separately. The scripts for hyperparameter tuning these models are provided in the `benchmarks/supporting/anomaly/` directory of the [pyMAISE GitHub repository](https://github.com/myerspat/pyMAISE). These scripts include the following:\n",
+    "Given the quantity of data and complexity of the neural networks trained here, we hyperparameter-tuned all models separately. The scripts for hyperparameter tuning these models are provided in the `benchmarks/supporting/anomaly/` directory of the [pyMAISE GitHub repository](https://github.com/aims-umich/pyMAISE). These scripts include the following:\n",
     "\n",
     "- `settings.py`: This script includes many of the global variables used in this benchmark and the supporting scripts, including:\n",
     "  - `input_path`: The path to the raw input data taken from [Mendeley](https://data.mendeley.com/datasets/kbbrw99vh8/5). Note that we do not host this dataset in pyMAISE as its size is rather large.\n",

docs/source/benchmarks/bwr.ipynb

@@ -32,7 +32,7 @@
     "- `F-delta-H`: Ratio of max-to-average enthalpy rises in a channel.\n",
     "- `Max-Fxy`: Maximum radial pin-power peaking factor.\n",
     "\n",
-    "The data set consists of 2000 data points with nine inputs and five outputs. This data set was constructed through uniform and normal sampling of the 9 input parameters for a boiling water reactor (BWR) micro-core. These samples were then used to solve for reactor characteristic changes in heat distribution and neutron flux. This BWR micro-core consists of 4 radially and axially heterogeneous assemblies of the same type constructed in a 2x2 grid with a control blade placed in the center. A single assembly composition can be seen in the figure below. A single assembly was broken into seven zones where each zone's 2D radial cross-sectional information was constructed using CASMO-4. These cross sectional libraries were then processed through CMSLINK for SIMULATE-3 to interpret. The core geometry and physics were implemented and modeled using SIMULATE-3 [[RFS21]](https://pymaise.readthedocs.io/en/stable/index.html#id3).\n",
+    "The data set consists of 2000 data points with nine inputs and five outputs. This data set was constructed through uniform and normal sampling of the 9 input parameters for a boiling water reactor (BWR) micro-core. These samples were then used to solve for reactor characteristic changes in heat distribution and neutron flux. This BWR micro-core consists of 4 radially and axially heterogeneous assemblies of the same type constructed in a 2x2 grid with a control blade placed in the center. A single assembly composition can be seen in the figure below. A single assembly was broken into seven zones where each zone's 2D radial cross-sectional information was constructed using CASMO-4. These cross sectional libraries were then processed through CMSLINK for SIMULATE-3 to interpret. The core geometry and physics were implemented and modeled using SIMULATE-3 [[RFS21]](https://pymaise.readthedocs.io/en/stable/data_refs.html).\n",
     "    \n",
     "Note: The reference uses the same model as this example, but the data generated differs from the paper.\n",
     "\n",
@@ -4506,7 +4506,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.0"
+   "version": "3.10.12"
   },
   "widgets": {
    "application/vnd.jupyter.widget-state+json": {