simdec 1.0.0__tar.gz → 1.2.0__tar.gz

{simdec-1.0.0 → simdec-1.2.0}/.gitignore

@@ -7,6 +7,9 @@ __pycache__
 .cache/*
 **/.ipynb_checkpoints
 
+# Env variables with direnv
+.envrc
+
 # OS generated files
 .DS_Store*
 
@@ -29,4 +32,6 @@ htmlcov/*
 build/*
 dist/*
 sdist/*
-docs/_build
+docs/html
+docs/jupyter_execute
+app.html

{simdec-1.0.0 → simdec-1.2.0}/CONTRIBUTING.md

@@ -161,3 +161,39 @@ a release:
 5. Check that release has been deployed to PyPI
 6. Check documentation is built and deployed to readthedocs
 7. Check that auto-generated PR is auto-merged on the conda-forge feedstock repo
+
+## Dashboard
+A live dashboard is available at:
+
+https://simdec.io
+
+The DNS records are available on CPanel and the rest is hosted on Google Cloud
+Platform.
+
+Developing locally requires the installation of GCP CLI and Docker engine.
+
+A few helper commands are provided in the Makefile.
+
+### Local use
+
+The dashboard can be run locally using:
+
+    make serve-dev
+
+If you want to test OAuth, you need to export the following env variables:
+
+    export PANEL_OAUTH_REDIRECT_URI=http://localhost:5006/app
+    export PANEL_OAUTH_KEY=[VALUE IN GCP Secret Manager]
+    export PANEL_OAUTH_SECRET=[VALUE IN GCP Secret Manager]
+    export PANEL_OAUTH_ENCRYPTION=[VALUE IN GCP Secret Manager]
+
+Use the CLI tool `direnv` for convenience. Then you can serve with
+OAuth support:
+
+    make serve-oauth
+
+### Deployment
+
+New version can either be deployed from the CI with `cloudbuild` or locally:
+
+    make production

{simdec-1.0.0 → simdec-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: simdec
-Version: 1.0.0
+Version: 1.2.0
 Summary: Sensitivity analysis using simulation decomposition
 Project-URL: homepage, https://www.simdec.fi/
 Project-URL: documentation, https://simdec.readthedocs.io
@@ -16,22 +16,32 @@ 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.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
-Requires-Python: >=3.9
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
 Requires-Dist: numpy
 Requires-Dist: pandas
-Requires-Dist: panel
 Requires-Dist: salib
 Requires-Dist: seaborn
-Requires-Dist: typer[all]
+Provides-Extra: dashboard
+Requires-Dist: cryptography; extra == 'dashboard'
+Requires-Dist: panel>=1.3.8; 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: pre-commit; extra == 'dev'
-Requires-Dist: simdec[doc,test]; 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'
 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'
@@ -56,7 +66,7 @@ When public
 analysis method, which is based on Monte Carlo simulation. SimDec consists of
 three major parts:
 
-1. computing significance indices,
+1. computing sensitivity indices,
 2. creating multi-variable scenarios and mapping the output values to them, and
 3. visualizing the scenarios on the output distribution by color-coding its segments.
 
@@ -64,7 +74,15 @@ SimDec reveals the nature of causalities and interaction effects in the model.
 See our [publications](https://www.simdec.fi/publications) and join our
 [discord community](https://discord.gg/54SFcNsZS4).
 
-...
+## Python API
+The library is distributed on PyPi and can be installed with:
+
+    pip install simdec
+
+## Dashboard
+A live dashboard is available at:
+
+https://simdec.io
 
 ## Citations
 
@@ -76,13 +94,6 @@ 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. DOI:10.1287/ited.2019.0240.
-- Kozlova, M., Moss, R. J., Yeomans, J. S., & Caers, J. (forthcoming).
-  Uncovering Heterogeneous Effects in Computational Models for Sustainable
-  Decision-making. _Environmental Modelling & Software_.
-- Kozlova, M., Moss, R. J., Roy, P., Alam, A., & Yeomans, J. S. (forthcoming).
-  SimDec algorithm. In M. Kozlova & J. S. Yeomans (Eds.), _Sensitivity Analysis
-  for Business, Technology, and Policymaking Made Easy with Simulation
-  Decomposition_. Routledge.
+- 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.

{simdec-1.0.0 → simdec-1.2.0}/README.md

@@ -14,7 +14,7 @@ When public
 analysis method, which is based on Monte Carlo simulation. SimDec consists of
 three major parts:
 
-1. computing significance indices,
+1. computing sensitivity indices,
 2. creating multi-variable scenarios and mapping the output values to them, and
 3. visualizing the scenarios on the output distribution by color-coding its segments.
 
@@ -22,7 +22,15 @@ SimDec reveals the nature of causalities and interaction effects in the model.
 See our [publications](https://www.simdec.fi/publications) and join our
 [discord community](https://discord.gg/54SFcNsZS4).
 
-...
+## Python API
+The library is distributed on PyPi and can be installed with:
+
+    pip install simdec
+
+## Dashboard
+A live dashboard is available at:
+
+https://simdec.io
 
 ## Citations
 
@@ -34,13 +42,6 @@ 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. DOI:10.1287/ited.2019.0240.
-- Kozlova, M., Moss, R. J., Yeomans, J. S., & Caers, J. (forthcoming).
-  Uncovering Heterogeneous Effects in Computational Models for Sustainable
-  Decision-making. _Environmental Modelling & Software_.
-- Kozlova, M., Moss, R. J., Roy, P., Alam, A., & Yeomans, J. S. (forthcoming).
-  SimDec algorithm. In M. Kozlova & J. S. Yeomans (Eds.), _Sensitivity Analysis
-  for Business, Technology, and Policymaking Made Easy with Simulation
-  Decomposition_. Routledge.
+- 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.

simdec-1.2.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.2.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.0.0 → simdec-1.2.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "simdec"
-version = "1.0.0"
+version = "1.2.0"
 description = "Sensitivity analysis using simulation decomposition"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 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.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
 ]
 
 dependencies = [
@@ -33,11 +33,14 @@ dependencies = [
     "pandas",
     "SALib",
     "seaborn",
-    "typer[all]",
-    "panel",
 ]
 
 [project.optional-dependencies]
+dashboard = [
+    "panel>=1.3.8",
+    "cryptography",
+]
+
 test = [
     "pytest",
     "pytest-cov",
@@ -48,32 +51,37 @@ doc = [
     "pydata-sphinx-theme",
     "accessible-pygments",
     "numpydoc",
+    "myst-nb",
 ]
 
 dev = [
-    "simdec[doc,test]",
+    "simdec[doc,test,dashboard]",
     "pre-commit",
     "hatch",
 ]
 
-[project.scripts]
-simdec = "simdec.workflow:app"
-
 [project.urls]
 homepage = "https://www.simdec.fi/"
 documentation = "https://simdec.readthedocs.io"
 source = "https://github.com/Simulation-Decomposition/simdec-python"
 
 [tool.hatch]
+build.targets.wheel.packages = ["src/simdec"]
 build.targets.sdist.exclude = [
   ".github",
   "docs",
+  "panel",
   "tests",
   "*.rst",
   "*.yml",
   ".*",
+  "Makefile",
+  "Dockerfile",
 ]
 
+[project.entry-points."panel.auth"]
+custom_google = "simdec.auth:CustomGoogleLoginHandler"
+
 [tool.pytest.ini_options]
 addopts = "--durations 10"
 testpaths = [

simdec-1.2.0/src/simdec/__init__.py

@@ -0,0 +1,13 @@
+"""SimDec main namespace."""
+from simdec.decomposition import *
+from simdec.sensitivity_indices import *
+from simdec.visualization import *
+
+__all__ = [
+    "sensitivity_indices",
+    "states_expansion",
+    "decomposition",
+    "visualization",
+    "tableau",
+    "palette",
+]

simdec-1.2.0/src/simdec/auth.py

@@ -0,0 +1,17 @@
+from panel.auth import GoogleLoginHandler
+from panel.io.resources import CDN_DIST
+
+
+class CustomGoogleLoginHandler(GoogleLoginHandler):
+    def _simple_get(self):
+        html = self._login_template.render(errormessage="", PANEL_CDN=CDN_DIST)
+        self.write(html)
+
+    async def get(self):
+        if "login" in self.request.uri and "state" not in self.request.uri:
+            self._simple_get()
+        else:
+            await super().get()
+
+    async def post(self):
+        await super().get()