simdec 1.2.0.dev0__tar.gz → 1.5.0__tar.gz

{simdec-1.2.0.dev0 → simdec-1.5.0}/.gitignore

@@ -32,5 +32,6 @@ htmlcov/*
 build/*
 dist/*
 sdist/*
-docs/_build
+docs/html
+docs/jupyter_execute
 app.html

{simdec-1.2.0.dev0 → simdec-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: simdec
-Version: 1.2.0.dev0
+Version: 1.5.0
 Summary: Sensitivity analysis using simulation decomposition
 Project-URL: homepage, https://www.simdec.fi/
 Project-URL: documentation, https://simdec.readthedocs.io
@@ -16,30 +16,33 @@ Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
 Requires-Dist: numpy
 Requires-Dist: pandas
 Requires-Dist: salib
 Requires-Dist: seaborn
 Provides-Extra: dashboard
 Requires-Dist: cryptography; extra == 'dashboard'
-Requires-Dist: panel>=1.3.8; extra == 'dashboard'
+Requires-Dist: panel>=1.4.5; extra == 'dashboard'
 Provides-Extra: dev
 Requires-Dist: accessible-pygments; extra == 'dev'
 Requires-Dist: cryptography; extra == 'dev'
 Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: myst-nb; extra == 'dev'
 Requires-Dist: numpydoc; extra == 'dev'
-Requires-Dist: panel>=1.3.8; extra == 'dev'
+Requires-Dist: panel>=1.4.5; extra == 'dev'
 Requires-Dist: pre-commit; extra == 'dev'
 Requires-Dist: pydata-sphinx-theme; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: sphinx; extra == 'dev'
+Requires-Dist: watchfiles; extra == 'dev'
 Provides-Extra: doc
 Requires-Dist: accessible-pygments; extra == 'doc'
+Requires-Dist: myst-nb; extra == 'doc'
 Requires-Dist: numpydoc; extra == 'doc'
 Requires-Dist: pydata-sphinx-theme; extra == 'doc'
 Requires-Dist: sphinx; extra == 'doc'
@@ -92,6 +95,5 @@ Foundation, and Finnish Foundation for Economic Education.
 If you use SimDec in your research we would appreciate a citation to the
 following publications:
 
-- Kozlova, M., & Yeomans, J. S. (2022). Monte Carlo Enhancement via Simulation Decomposition: A “Must-Have” Inclusion for Many Disciplines. _INFORMS Transactions on Education, 22_(3), 147-159. [Available here](https://pubsonline.informs.org/doi/10.1287/ited.2019.0240).
 - Kozlova, M., Moss, R. J., Yeomans, J. S., & Caers, J. (2024). Uncovering Heterogeneous Effects in Computational Models for Sustainable Decision-making. _Environmental Modelling & Software_, 171, 105898. [https://doi.org/10.1016/j.envsoft.2023.105898](https://doi.org/10.1016/j.envsoft.2023.105898)
-- Kozlova, M., Moss, R. J., Roy, P., Alam, A., & Yeomans, J. S. (forthcoming). SimDec algorithm and guidelines for its usage and interpretation. In M. Kozlova & J. S. Yeomans (Eds.), _Sensitivity Analysis for Business, Technology, and Policymaking. Made Easy with Simulation Decomposition_. Routledge.
+- Kozlova, M., Moss, R. J., Roy, P., Alam, A., & Yeomans, J. S. (2024). SimDec algorithm and guidelines for its usage and interpretation. In M. Kozlova & J. S. Yeomans (Eds.), _Sensitivity Analysis for Business, Technology, and Policymaking. Made Easy with Simulation Decomposition_. Routledge. [Available here](https://github.com/Simulation-Decomposition/SimDec-book/blob/74ce72c1d3dda650eba1c59e3b215a4bb35c6be0/chapters/02_SimDec_algorithm_and_instructions/Ch2.pdf).

{simdec-1.2.0.dev0 → simdec-1.5.0}/README.md

@@ -42,6 +42,5 @@ Foundation, and Finnish Foundation for Economic Education.
 If you use SimDec in your research we would appreciate a citation to the
 following publications:
 
-- Kozlova, M., & Yeomans, J. S. (2022). Monte Carlo Enhancement via Simulation Decomposition: A “Must-Have” Inclusion for Many Disciplines. _INFORMS Transactions on Education, 22_(3), 147-159. [Available here](https://pubsonline.informs.org/doi/10.1287/ited.2019.0240).
 - Kozlova, M., Moss, R. J., Yeomans, J. S., & Caers, J. (2024). Uncovering Heterogeneous Effects in Computational Models for Sustainable Decision-making. _Environmental Modelling & Software_, 171, 105898. [https://doi.org/10.1016/j.envsoft.2023.105898](https://doi.org/10.1016/j.envsoft.2023.105898)
-- Kozlova, M., Moss, R. J., Roy, P., Alam, A., & Yeomans, J. S. (forthcoming). SimDec algorithm and guidelines for its usage and interpretation. In M. Kozlova & J. S. Yeomans (Eds.), _Sensitivity Analysis for Business, Technology, and Policymaking. Made Easy with Simulation Decomposition_. Routledge.
+- Kozlova, M., Moss, R. J., Roy, P., Alam, A., & Yeomans, J. S. (2024). SimDec algorithm and guidelines for its usage and interpretation. In M. Kozlova & J. S. Yeomans (Eds.), _Sensitivity Analysis for Business, Technology, and Policymaking. Made Easy with Simulation Decomposition_. Routledge. [Available here](https://github.com/Simulation-Decomposition/SimDec-book/blob/74ce72c1d3dda650eba1c59e3b215a4bb35c6be0/chapters/02_SimDec_algorithm_and_instructions/Ch2.pdf).

simdec-1.5.0/joss/paper.bib

@@ -0,0 +1,115 @@
+@article{Herman2017,
+  doi = {10.21105/joss.00097},
+  year  = {2017},
+  month = {jan},
+  publisher = {The Open Journal},
+  volume = {2},
+  number = {9},
+  author = {Jon Herman and Will Usher},
+  title = {{SALib}: An open-source {Python} library for Sensitivity Analysis},
+  journal = {The Journal of Open Source Software}
+}
+
+@article{Kozlova2024,
+  title = {Uncovering heterogeneous effects in computational models for sustainable decision-making},
+  journal = {Environmental Modelling & Software},
+  volume = {171},
+  pages = {105898},
+  year = {2024},
+  issn = {1364-8152},
+  doi = {10.1016/j.envsoft.2023.105898},
+  author = {Mariia Kozlova and Robert J. Moss and Julian Scott Yeomans and Jef Caers},
+  keywords = {Global sensitivity analysis, Simulation decomposition, Monte Carlo simulation, Decision-making under uncertainty}
+}
+
+@article{Roy2023,
+  doi = {10.21105/joss.05309},
+  year = {2023},
+  publisher = {The Open Journal},
+  volume = {8},
+  number = {84},
+  pages = {5309},
+  author = {Pamphile T. Roy and Art B. Owen and Maximilian Balandat and Matt Haberland},
+  title = {Quasi-Monte Carlo Methods in {Python}},
+  journal = {Journal of Open Source Software}
+}
+
+@article{Virtanen2020,
+  title={SciPy 1.0: fundamental algorithms for scientific computing in {P}ython},
+  author={Virtanen, Pauli and Gommers, Ralf and Oliphant, Travis E and Haberland, Matt and Reddy, Tyler and Cournapeau, David and Burovski, Evgeni and Peterson, Pearu and Weckesser, Warren and Bright, Jonathan et al.},
+  journal={Nature methods},
+  volume={17},
+  number={3},
+  pages={261--272},
+  year={2020},
+  publisher={Nature Publishing Group},
+  doi={10.1038/s41592-019-0686-2}
+}
+
+@book{Saltelli2007,
+author = {Saltelli, Andrea and Ratto, Marco and Andres, Terry and Campolongo, Francesca and Cariboni, Jessica and Gatelli, Debora and Saisana, Michaela and Tarantola, Stefano},
+booktitle = {Global Sensitivity Analysis. The Primer},
+doi = {10.1002/9780470725184},
+isbn = {9780470725184},
+month = {dec},
+pages = {237--275},
+publisher = {John Wiley {\&} Sons, Ltd},
+title = {{Global Sensitivity Analysis. The Primer}},
+year = {2007}
+}
+
+@article{sobol1993,
+  title={Sensitivity analysis for non-linear mathematical models, originally “Sensitivity estimates for non-linear mathematical models”},
+  author={Sobol, Ilya M},
+  journal={Math Model Comput Exp},
+  volume={1},
+  pages={407--414},
+  year={1993}
+}
+
+@report{europeancommission2021,
+  title = {Better {{Regulation Toolbox}}},
+  author = {{European Commission}},
+  date = {2021-11},
+  url = {https://ec.europa.eu/info/law/law-making-process/planning-and-proposing-law/better-regulation-why-and-how/better-regulation-guidelines-and-toolbox_en},
+  city = {Brussels},
+  keywords = {\#nosource}
+}
+
+@software{panel,
+  author       = {Philipp Rudiger and
+                  Marc Skov Madsen and
+                  Simon Høxbro Hansen and
+                  Maxime Liquet and
+                  Andrew and
+                  Xavier Artusi and
+                  James A. Bednar and
+                  Chris B and
+                  Jean-Luc Stevens and
+                  Christoph Deil and
+                  Demetris Roumis and
+                  Julia Signell and
+                  Mateusz Paprocki and
+                  Jerry Wu and
+                  Jon Mease and
+                  Arne and
+                  Coderambling and
+                  Hugues-Yanis Amanieu and
+                  thuydotm and
+                  Simon and
+                  sdc50 and
+                  Luca Fabbri and
+                  kbowen and
+                  Theom and
+                  Joel Ostblom and
+                  Govinda Totla and
+                  Niko Föhr and
+                  TBym},
+  title        = {holoviz/panel: Version 1.4.3},
+  month        = may,
+  year         = 2024,
+  publisher    = {Zenodo},
+  version      = {v1.4.3},
+  doi          = {10.5281/zenodo.11261266},
+  url          = {https://doi.org/10.5281/zenodo.11261266}
+}

simdec-1.5.0/joss/paper.md

@@ -0,0 +1,76 @@
+---
+title: 'Simulation Decomposition in Python'
+tags:
+  - Python
+  - SimDec
+  - statistics
+  - Sensitivity Analysis
+  - Visualization
+authors:
+  - name: Pamphile T. Roy
+    affiliation: 1
+    corresponding: true
+    orcid: 0000-0001-9816-1416
+  - name: Mariia Kozlova
+    affiliation: 2
+    orcid: 0000-0002-6952-7682
+affiliations:
+    - name: Consulting Manao GmbH, Vienna, Austria
+      index: 1
+    - name: LUT Business School, LUT University, Lappeenranta, Finland
+      index: 2
+date: 1 April 2024
+bibliography: paper.bib
+
+---
+
+# Summary
+
+Uncertainties are everywhere. Whether you are developing a new Artificial Intelligence (AI) system,
+running complex simulations or making an experiment in a lab, uncertainties
+influence the system. Therefore, an approach is needed to understand how these uncertainties impact the system's performance.
+
+SimDec offers a novel visual way to understand the intricate role that
+uncertainties play. A clear Python Application Programming Interface (API) and a no-code interactive web
+dashboard make uncertainty analysis with SimDec accessible to everyone.
+
+# Statement of need
+
+From real life experiments to numerical simulations, uncertainties play a
+crucial role in the system under study. With the advent of AI
+and new regulations such as the [AI Act](https://artificialintelligenceact.eu) or the
+*Better Regulation Guideline* [@europeancommission2021], there is a growing need for explainability and
+impact assessments of systems under uncertainties.
+
+Traditional methods to analyse the uncertainties focus on quantitative methods
+to compare the importance of factors, there is a large body of literature and
+the field is known as: Sensitivity Analysis (SA) [@Saltelli2007]. The indices of Sobol' are a
+prominent example of such methods [@sobol1993].
+
+Simulation Decomposition or SimDec moves the field of SA forward by supplementing the computation of sensitivity indices with the visualization of the type of interactions involved, which proves critical for understanding the system's behavior and decision-making [@Kozlova2024].
+In short, SimDec is a hybrid uncertainty-sensitivity analysis approach
+that reveals the critical behavior of a computational model or an empirical
+dataset. It decomposes the distribution of the output
+(target variable) by automatically forming scenarios that reveal the most critical behavior of the system. The scenarios are formed out of the most influential input variables (defined with variance-based sensitivity indices) by breaking down their numeric ranges into states (e.g. _low_ and _high_) and creating an exhaustive list of their combinations (e.g. (i) _low_ _**A**_ & _low_ _**B**_, (ii) _low_ _**A**_ & _high_ _**B**_, (iii) _high_ **_A_** & _low_ **_B_**, and (iv) _high_ **_A_** and _high_ **_B_**). The resulting visualization shows how different
+output ranges can be achieved and what kind of critical interactions affect
+the output—as seen in \autoref{fig:simdec}. The method has shown value for
+various computational models from different fields, including business,
+environment, and engineering, as well as an emerging evidence of use for
+empirical data and AI.
+
+![SimDec: explanation of output by most important inputs. A simulation dataset of a structural reliability model with one key output variable and four input variables is used for this case. Inputs 3 and 1 have the highest sensitivity indices and thus are automatically chosen for decomposition. The most influential input 3 divides the distribution of the output into three main states with distinct colors. Input 1 further subdivides them into shades. From the graph, it becomes obvious that input 1 influences the output when input 3 is low, but has a negligible effect when input 3 is medium or high.\label{fig:simdec}](simdec_presentation.png)
+
+Besides proposing a comprehensive yet simple API through a Python package
+available on PyPi, SimDec is also made available
+to practitioners through an online dashboard at [https://simdec.io](https://simdec.io). The project
+relies on powerful variance-based sensitivity analysis methods from SALib [@Herman2017] and
+SciPy [@Virtanen2020; @Roy2023]—notably the Quasi-Monte Carlo capabilities with
+`sp.stats.qmc` and in the future sensitivity indices with `sp.stats.sensitivity_indices`.
+The dashboard is made possible thanks to Panel [@panel].
+
+# Acknowledgements
+
+The work on this open-source software was supported by grant #220177 from
+Finnish Foundation for Economic Foundation.
+
+# References

{simdec-1.2.0.dev0 → simdec-1.5.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "simdec"
-version = "1.2.0dev0"
+version = "1.5.0"
 description = "Sensitivity analysis using simulation decomposition"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 license = "BSD-3-Clause"
 authors = [
     { name = "Pamphile Roy" },
@@ -23,9 +23,9 @@ classifiers = [
     "Operating System :: OS Independent",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
 ]
 
 dependencies = [
@@ -37,7 +37,7 @@ dependencies = [
 
 [project.optional-dependencies]
 dashboard = [
-    "panel>=1.3.8",
+    "panel>=1.4.5",
     "cryptography",
 ]
 
@@ -51,10 +51,12 @@ doc = [
     "pydata-sphinx-theme",
     "accessible-pygments",
     "numpydoc",
+    "myst-nb",
 ]
 
 dev = [
     "simdec[doc,test,dashboard]",
+    "watchfiles",
     "pre-commit",
     "hatch",
 ]

{simdec-1.2.0.dev0 → simdec-1.5.0}/src/simdec/decomposition.py

@@ -22,6 +22,8 @@ def states_expansion(states: list[int], inputs: pd.DataFrame) -> list[list[str]]
                 expanded_states.append(["low", "high"])
             elif state == 3:
                 expanded_states.append(["low", "medium", "high"])
+            else:
+                expanded_states.append([i for i in range(state)])
         else:
             expanded_states.append(state)
 
@@ -109,11 +111,9 @@ def decomposition(
     var_names = inputs.columns
 
     cat_cols = inputs.select_dtypes(exclude=["number"])
-    cat_cols_idx = []
     for cat_col in cat_cols:
         codes, cat_states_ = pd.factorize(inputs[cat_col])
         inputs[cat_col] = codes
-        cat_cols_idx.append(inputs.columns.get_loc(cat_col))
 
     inputs = inputs.to_numpy()
     output = output.to_numpy()
@@ -136,10 +136,9 @@ def decomposition(
         states = 3 if n_var_dec < 3 else 2
         states = [states] * n_var_dec
 
-        # categorical for a given variable
-        for i in cat_cols_idx:
+        for i in range(n_var_dec):
             n_unique = np.unique(inputs[:, i]).size
-            states[i] = n_unique if n_unique < 5 else states[i]
+            states[i] = n_unique if n_unique <= 5 else states[i]
 
     if auto_ordering:
         var_names = var_names[var_order[:n_var_dec]].tolist()
@@ -163,8 +162,44 @@ def decomposition(
         bins.append(inputs)
         return statistic_method(inputs)
 
+    # make bins with equal number of samples for a given dimension
+    # sort and then split in n-state
+    sorted_inputs = np.sort(inputs, axis=0)
+    bin_edges = []
+
+    for i, states_ in enumerate(states):
+        col = inputs[:, i]
+        uniq = np.unique(col)
+
+        # Categorical-like numeric inputs: if we have few unique numeric values,
+        # build edges around the unique values so we don't create empty states.
+        # We only apply this when the requested number of states matches the
+        # number of categories (uniq.size).
+        if uniq.size <= 5 and states_ == uniq.size:
+            uniq = np.sort(uniq).astype(float)
+
+            if uniq.size == 1:
+                edges = np.array([uniq[0] - 0.5, uniq[0] + 0.5], dtype=float)
+            else:
+                gaps = np.diff(uniq)
+                margin = 0.1 * np.min(gaps)
+                edges = np.concatenate(
+                    ([uniq[0] - margin], uniq[:-1] + margin, [uniq[-1] + margin])
+                ).astype(float)
+
+            bin_edges.append(edges)
+            continue
+
+        # Default: equal-number-of-samples bins
+        splits = np.array_split(sorted_inputs[:, i], states_)
+        edges = [s[0] for s in splits]
+        edges.append(splits[-1][-1])  # last point to close the edges
+        edges = np.array(edges, dtype=float)
+        edges += 1e-10 * np.linspace(0, 1, len(edges))
+        bin_edges.append(edges)
+
     res = stats.binned_statistic_dd(
-        inputs, values=output, statistic=statistic_, bins=states
+        inputs, values=output, statistic=statistic_, bins=bin_edges
     )
 
     bins = pd.DataFrame(bins[1:]).T

{simdec-1.2.0.dev0 → simdec-1.5.0}/src/simdec/sensitivity_indices.py

@@ -164,7 +164,6 @@ def sensitivity_indices(
 
             soe[i, j] = (var_ij - var_i - var_j) / var_y
 
-        soe = np.clip(soe, a_min=0, a_max=None)
         soe = np.where(soe == 0, soe.T, soe)
         si[i] = foe[i] + soe[:, i].sum() / 2
 

{simdec-1.2.0.dev0 → simdec-1.5.0}/src/simdec/visualization.py

@@ -1,3 +1,4 @@
+import copy
 import functools
 import itertools
 from typing import Literal
@@ -202,6 +203,8 @@ def tableau(
     ----------
     var_names : list of str
         Variables name.
+    statistic : ndarray of shape (n_factors, 1)
+        Statistic in each bin.
     states : list of int or list of str
         For each variable, number of states. Can either be a scalar or a list.
 
@@ -225,16 +228,17 @@ def tableau(
     table.rename(columns={"index": "colour"}, inplace=True)
 
     # Default states for 2 or 3
-    for i, state in enumerate(states):
+    states_ = copy.deepcopy(states)
+    for i, state in enumerate(states_):
         if isinstance(state, int):
-            states: list
+            states_: list
             if state == 2:
-                states[i] = ["low", "high"]
+                states_[i] = ["low", "high"]
             elif state == 3:
-                states[i] = ["low", "medium", "high"]
+                states_[i] = ["low", "medium", "high"]
 
     # get the list of states
-    gen_states = [range(x) if isinstance(x, int) else x for x in states]
+    gen_states = [range(x) if isinstance(x, int) else x for x in states_]
     states_ = np.asarray(list(itertools.product(*gen_states)))
     for i, var_name in enumerate(var_names):
         table.insert(loc=i + 1, column=var_name, value=states_[:, i])