Merge 79ff95d into 52de2ab

.readthedocs.yaml

@@ -0,0 +1,28 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+#  fail_on_warning: true
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+formats: all
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - requirements: requirements.txt
+    - requirements: docs/requirements.txt
+    - path: .

README.md

@@ -10,16 +10,35 @@ A Python-based toolkit that harnesses modern techniques to estimate model and pa
 [![Coverage Status](https://coveralls.io/repos/github/SCIInstitute/UncertainSCI/badge.svg?branch=master)](https://coveralls.io/github/SCIInstitute/UncertainSCI?branch=master)
 [![status](https://joss.theoj.org/papers/660d2fe53fbf67dd2714e9546251bd33/status.svg)](https://joss.theoj.org/papers/660d2fe53fbf67dd2714e9546251bd33)
 
+## Overview
+
+UncertainSCI is an open-source tool designed to make modern uncertainty quantification (UQ) techniques more accessible in biomedical simulation applications.   UncertainSCI uses noninvasive UQ techniques, specifically polynomial Chaos estimation (PCE), with a similarly noninvasive interface to external modeling software that can be called in diverse ways.  PCE and UncertainSCI allows users to propagate the effect of input uncertainty on model results, providing essential context for model stability and confidence needed in many modeling fields.  Users can run UncertainSCI by setting input distributions for a model parameters, setting up PCE, sampling the parameter space, running the samples sets within the target model, and compiling output statistics based on PCE.  This process is breifly describe in the [getting started guide](../user_docs/getting_started.html#quick-guide), and more fully explained in the [API documentation](../api_docs/index.html), and supplied [demos and tutorials](../tutorials/index.html).
 
 ## Documentation
 
 <https://uncertainsci.readthedocs.io>
 
+## Getting Started Guide
+
+<https://uncertainsci.readthedocs.io/en/latest/user_docs/getting_started.html>
 
 ## License
 
 Distributed under the MIT license. See ``LICENSE`` for more information.
 
+
+## Publications
+
+- Akil Narayan, Zexin Liu, Jake Bergquist, Chantel Charlebois, Sumientra Rampersad, Lindsay Rupp, Dana Brooks, Dan White, Jess Tate, and Rob S MacLeod. UncertainSCI: Uncertainty quantification for com- putational models in biomedicine and bioengineering. Available at SSRN 4049696, 2022.
+- Kyle M. Burk, Akil Narayan, and Joseph A. Orr. Efficient sampling for polynomial chaos-based uncertainty quantification and sensitivity analysis using weighted approximate fekete points. International Journal for Numerical Methods in Biomedical Engineering, 36(11):e3395, 2020.
+- Jake Bergquist, Brian Zenger, Lindsay Rupp, Akil Narayan, Jess Tate, and Rob MacLeod. Uncertainty quantification in simulations of myocardial ischemia. In Computing in Cardiology, volume 48, September 2021.
+- Lindsay C Rupp, Jake A Bergquist, Brian Zenger, Karli Gillette, Akil Narayan, Jess Tate, Gernot Plank, and Rob S. MacLeod. The role of myocardial fiber direction in epicardial activation patterns via uncertainty quantification. In Computing in Cardiology, volume 48, September 2021.
+- Lindsay C Rupp, Zexin Liu, Jake A Bergquist, Sumientra Rampersad, Dan White, Jess D Tate, Dana H. Brooks, Akil Narayan, and Rob S. MacLeod. Using uncertainSCI to quantify uncertainty in cardiac simu- lations. In Computing in Cardiology, volume 47, September 2020.
+- Jess Tate, Sumientra Rampersad, Chantel Charlebois, Zexin Liu, Jake Bergquist, Dan White, Lindsay Rupp, Dana Brooks, Akil Narayan, and Rob MacLeod. Uncertainty quantification in brain stimulation using uncertainSCI. Brain Stimulation: Basic, Translational, and Clinical Research in Neuromodulation, 14(6):1659–1660, January 2021.
+- Jess D. Tate, Wilson W. Good, Nejib Zemzemi, Machteld Boonstra, Peter van Dam, Dana H. Brooks, Akil Narayan, and Rob S. MacLeod. Uncertainty quantification of the effects of segmentation variability in ECGI. In Functional Imaging and Modeling of the Heart, pages 515–522. Springer-Cham, Palo Alto, USA, 2021.
+- Jess D Tate, Nejib Zemzemi, Shireen Elhabian, Beáta Ondrusǔvá, Machteld Boonstra, Peter van Dam, Akil Narayan, Dana H Brooks, and Rob S MacLeod. Segmentation uncertainty quantification in cardiac propagation models. In 2022 Computing in Cardiology (CinC), volume 498, pages 1–4, 2022.
+
+
 ## Acknowledgements
 
 

demos/build_pce.py

@@ -13,7 +13,7 @@
 # - A parameter distribution
 # - The capacity of the PCE model (here, polynomial space)
 # - The physical model
-
+#
 # # Distribution setup
 
 # Number of parameters
@@ -35,7 +35,7 @@
 # with x in [-1,1] discretized with N points, where a(x,p) is a
 # Fourier-Series-parameterized diffusion model with the variables pj.
 # See the laplace_ode_1d method in UncertainSCI/model_examples.py for
-# deatils.
+# details.
 
 N = 100
 x, model = laplace_ode_1d(Nparams, N=N)

docs/conf.py

@@ -27,7 +27,7 @@
 github_doc_root = 'https://github.com/SCIInstitute/UncertainSCI/tree/master/docs'
 
 # The full version, including alpha/beta/rc tags
-release = '0.01'
+release = '1.0rc2'
 
 
 # -- General configuration ---------------------------------------------------
@@ -40,7 +40,8 @@
         'sphinx.ext.napoleon',
         'recommonmark',
         'sphinxcontrib.bibtex',
-        'sphinx_markdown_tables'
+        'sphinx_markdown_tables',
+        'nbsphinx'
 ]
 
 # Path for bibtex files
@@ -60,6 +61,10 @@
     '.md': 'markdown',
 }
 
+suppress_warnings = [
+    'nbsphinx',
+]
+
 # the master toctree doc
 master_doc = 'index'
 

docs/index.rst

@@ -13,10 +13,10 @@ Welcome to UncertainSCI's documentation!
 About UncertainSCI
 ===================
 
-UncertainSCI is a Python-based toolkit that harnesses modern techniques to estimate model and parametric uncertainty, with a particular emphasis on needs for biomedical simulations and applications. This toolkit enables non-intrusive integration of these techniques with well-established biomedical simulation software.
+UncertainSCI :cite:p:`JDT:Nar2022` is a Python-based toolkit that harnesses modern techniques to estimate model and parametric uncertainty, with a particular emphasis on needs for biomedical simulations and applications. This toolkit enables non-intrusive integration of these techniques with well-established biomedical simulation software.
 
 
-Currently implemented in UncertainSCI is Polynomial Chaos Expansion (PCE) with a number of input distributions.  For more information about these techniques, see: :cite:p:`JDT:Bur2020,narayan_computation_2018,guo_weighted_2018,cohen_optimal_2017`
+Currently implemented in UncertainSCI is Polynomial Chaos Expansion (PCE) with a number of input distributions.  For more information about these techniques, see: :cite:p:`JDT:Bur2020,narayan_computation_2018,guo_weighted_2018,cohen_optimal_2017,gupta1983`.  For studies using UncertainSCI, see: :cite:p:`JDT:Ber2021,JDT:Rup2020,JDT:Rup2021,JDT:Tat2021a,JDT:Tat2021c,JDT:Tat2022`
 
 
 .. toctree::

docs/references.bib

@@ -7,19 +7,128 @@ @techreport{gupta1983
 	year = {1983},
 }
 
-@article{JDT:Bur2020,
-author = {Burk, Kyle M. and Narayan, Akil and Orr, Joseph A.},
-title = {Efficient sampling for polynomial chaos-based uncertainty quantification and sensitivity analysis using weighted approximate Fekete points},
-journal = {International Journal for Numerical Methods in Biomedical Engineering},
-volume = {36},
-number = {11},
-pages = {e3395},
-keywords = {approximate Fekete points, cardiovascular modeling, oxyhemoglobin dissociation, polynomial chaos expansion, sensitivity analysis, uncertainty quantification},
-doi = {https://doi.org/10.1002/cnm.3395},
-url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/cnm.3395},
-year = {2020}
+@Article{JDT:Nar2022,
+  title =        "Uncertain{SCI}: Uncertainty Quantification for
+                 Computational Models in Biomedicine and
+                 Bioengineering",
+  author =       "Akil Narayan and Zexin Liu and Jake Bergquist and
+                 Chantel Charlebois and Sumientra Rampersad and Lindsay
+                 Rupp and Dana Brooks and Dan White and Jess Tate and
+                 Rob S MacLeod",
+  journal =      "Available at SSRN 4049696",
+  year =         "2022",
 }
 
+@Article{JDT:Bur2020,
+  author =       "Kyle M. Burk and Akil Narayan and Joseph A. Orr",
+  title =        "Efficient sampling for polynomial chaos-based
+                 uncertainty quantification and sensitivity analysis
+                 using weighted approximate Fekete points",
+  journal =      "International Journal for Numerical Methods in
+                 Biomedical Engineering",
+  volume =       "36",
+  number =       "11",
+  pages =        "e3395",
+  keywords =     "approximate Fekete points, cardiovascular modeling,
+                 oxyhemoglobin dissociation, polynomial chaos expansion,
+                 sensitivity analysis, uncertainty quantification",
+  doi =          "https://doi.org/10.1002/cnm.3395",
+  year =         "2020",
+}
+
+@InProceedings{JDT:Ber2021,
+  author =       "Jake Bergquist and Brian Zenger and Lindsay Rupp and
+                 Akil Narayan and Jess Tate and Rob MacLeod",
+  title =        "Uncertainty Quantification in Simulations of
+                 Myocardial Ischemia",
+  booktitle =    "Computing in Cardiology",
+  month =        sep,
+  year =         "2021",
+  doi =          "",
+  volume =       "48",
+}
+
+@InProceedings{JDT:Rup2020,
+  author =       "Lindsay C Rupp and Zexin Liu and Jake A Bergquist and
+                 Sumientra Rampersad and Dan White and Jess D Tate and
+                 Dana H. Brooks and Akil Narayan and Rob S. MacLeod",
+  title =        "Using Uncertain{SCI} to Quantify Uncertainty in
+                 Cardiac Simulations",
+  booktitle =    "Computing in Cardiology",
+  month =        sep,
+  year =         "2020",
+  doi =          "",
+  volume =       "47",
+}
+
+@InProceedings{JDT:Rup2021,
+  author =       "Lindsay C Rupp and Jake A Bergquist and Brian Zenger
+                 and Karli Gillette and Akil Narayan and Jess Tate and
+                 Gernot Plank and Rob S. MacLeod",
+  title =        "The Role of Myocardial Fiber Direction in Epicardial
+                 Activation Patterns via Uncertainty Quantification",
+  booktitle =    "Computing in Cardiology",
+  month =        sep,
+  year =         "2021",
+  doi =          "",
+  volume =       "48",
+}
+
+@InCollection{JDT:Tat2021a,
+  author =       "Jess D. Tate and Wilson W. Good and Nejib Zemzemi and
+                 Machteld Boonstra and Peter van Dam and Dana H. Brooks
+                 and Akil Narayan and Rob S. MacLeod",
+  title =        "Uncertainty Quantification of the Effects of
+                 Segmentation Variability in {ECGI}",
+  booktitle =    "Functional Imaging and Modeling of the Heart",
+  publisher =    "Springer-Cham",
+  address =      "Palo Alto, USA",
+  editors =      "D. B. Ennis and L. E. Perotti and V. Y. Wang",
+  pages =        "515--522",
+  doi =          "https://doi.org/10.1007/978-3-030-78710-3_49",
+  year =         "2021",
+}
+
+@Article{JDT:Tat2021c,
+  author =       "Jess Tate and Sumientra Rampersad and Chantel
+                 Charlebois and Zexin Liu and Jake Bergquist and Dan
+                 White and Lindsay Rupp and Dana Brooks and Akil Narayan
+                 and Rob MacLeod",
+  booktitle =    "Brain Stimulation: Basic, Translational, and Clinical
+                 Research in Neuromodulation",
+  date =         "2021/11/01",
+  doi =          "10.1016/j.brs.2021.10.226",
+  ISBN =         "1935-861X",
+  journal =      "Brain Stimulation: Basic, Translational, and Clinical
+                 Research in Neuromodulation",
+  month =        jan,
+  number =       "6",
+  pages =        "1659--1660",
+  publisher =    "Elsevier",
+  title =        "Uncertainty Quantification in Brain Stimulation using
+                 Uncertain{SCI}",
+  ty =           "JOUR",
+  URL =          "https://doi.org/10.1016/j.brs.2021.10.226",
+  volume =       "14",
+  year =         "2021",
+}
+
+@InProceedings{JDT:Tat2022,
+  author =       "Jess D Tate and Nejib Zemzemi and Shireen Elhabian and
+                 Be\'{a}ta Ondru\u{s}ov\'{a} and Machteld Boonstra and
+                 Peter van Dam and Akil Narayan and Dana H Brooks and
+                 Rob S MacLeod",
+  booktitle =    "2022 Computing in Cardiology (CinC)",
+  title =        "Segmentation Uncertainty Quantification in Cardiac
+                 Propagation Models",
+  year =         "2022",
+  volume =       "498",
+  number =       "",
+  pages =        "1--4",
+  doi =          "10.22489/CinC.2022.419",
+}
+
+
 @article{narayan_computation_2018,
 	title = {Computation of induced orthogonal polynomial distributions},
 	volume = {50},

docs/requirements.txt

@@ -8,3 +8,5 @@ sphinx-notfound-page
 sphinx_rtd_theme
 sphinxcontrib-bibtex
 sphinx-markdown-tables
+nbsphinx
+ipykernel

docs/tutorials/demos/index.rst

@@ -6,4 +6,4 @@ Demos
    :caption: Contents:
 
    simple_boxplots
-   pce_statistics
+   pce_statistics

docs/tutorials/index.rst

@@ -5,7 +5,9 @@ Tutorials
    :maxdepth: 2
    :caption: Contents:
 
+   notebooks/build_pce
    demos/index
+   notebooks/adapt_pce
    models
    parameters
    template