new theme, updated citation, edgier

IMMM-SFA · Feb 22, 2022 · 9dbb5ae · 9dbb5ae
1 parent 42b2d98
commit 9dbb5ae
Show file tree

Hide file tree

Showing 28 changed files with 114 additions and 47 deletions.
diff --git a/.github/workflows/02_deploy.yml b/.github/workflows/02_deploy.yml
@@ -13,7 +13,7 @@ jobs:
         with:
           python-version: '3.9'
       - name: Install latex dependencies
-        run: sudo apt-get update -y && sudo apt-get install -y texlive latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
+        run: sudo apt-get update -y && sudo apt-get install -y texlive latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended ghostscript
       - name: Update pip and install python dependencies
         working-directory: 'docs/'
         run: |
@@ -23,9 +23,13 @@ jobs:
         working-directory: 'docs/'
         run: |
           make html latexpdf --keep-going LATEXMKOPTS="-interaction=nonstopmode" || true
-          make html latexpdf --keep-going LATEXMKOPTS="-interaction=nonstopmode" || true
-          make html latexpdf --keep-going LATEXMKOPTS="-interaction=nonstopmode" || true
+          make latexpdf --keep-going LATEXMKOPTS="-interaction=nonstopmode" || true
+          make latexpdf --keep-going LATEXMKOPTS="-interaction=nonstopmode" || true
         continue-on-error: true
+      - name: Concatenate eBook cover with eBook
+        run: |
+          mv docs/build/latex/addressinguncertaintyinmultisectordynamicsresearch.pdf docs/build/latex/ebook_content.pdf
+          gs -dNOPAUSE -sDEVICE=pdfwrite -sOUTPUTFILE=docs/build/latex/addressinguncertaintyinmultisectordynamicsresearch.pdf -dBATCH docs/ebook_cover.pdf docs/build/latex/ebook_content.pdf
       - uses: actions/setup-node@v2
         with:
           node-version: '16'

diff --git a/CITATION.cff b/CITATION.cff
@@ -1,5 +1,8 @@
 cff-version: 1.2.0
 message: "Please cite our work as follows:"
+abstract: "A practical guide to sensitivity analysis and diagnostic model evaluation techniques for confronting the computational and conceptual challenges of multi-model, transdisciplinary workflows."
+license: CC-BY-NC-ND
+type: book
 authors:
 - family-names: "Reed"
   given-names: "Patrick M."
@@ -20,10 +23,10 @@ authors:
   given-names: "Vivek"
   orcid: "https://orcid.org/0000-0003-0049-3805"
 - family-names: "Gupta"
-  given-names: "Rohini"
+  given-names: "Rohini S."
   orcid: "https://orcid.org/0000-0003-3538-0675"
 - family-names: "Gold"
-  given-names: "David"
+  given-names: "David F."
   orcid: "https://orcid.org/0000-0002-0854-1819"
 - family-names: "Lee"
   given-names: "Ben"
@@ -35,7 +38,7 @@ authors:
   given-names: "Jennie S."
   orcid: "https://orcid.org/0000-0002-7833-9456"
 - family-names: "Thurber"
-  given-names: "Travis"
+  given-names: "Travis B."
   orcid: "https://orcid.org/0000-0002-4370-9971"
 title: "Addressing Uncertainty in Multisector Dynamics Research"
 doi: 10.5281/zenodo.6110623

diff --git a/docs/ebook_cover.pdf b/docs/ebook_cover.pdf
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -3,5 +3,5 @@ ipython~=8.0.1
 mathjax~=0.1.2
 nbsphinx~=0.8.6
 sphinx~=4.0.2
-sphinx-rtd-theme~=0.5.2
+sphinx-book-theme~=0.2.0
 sphinxcontrib-bibtex~=2.4.1
diff --git a/docs/source/1_introduction.rst b/docs/source/1_introduction.rst
@@ -24,6 +24,7 @@ We can briefly distinguish the key terms of uncertainty quantification (UQ) and
 .. figure:: _static/figure1_1_state_of_the_science.png
     :alt: Figure 1.1
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     State-of-the-art in different modeling communities, as reported in the survey distributed to IM3 teams. *Deterministic Historical Evaluation*: model evaluation under fully determined conditions defined using historical observations; *Local Sensitivity Analysis*: model evaluation performed by varying uncertain factors around specific reference values; *Global Sensitivity Analysis*: model evaluation performed by varying uncertain factors throughout their entire feasible value space; *Uncertainty Characterization*: model evaluation under alternative factor hypotheses to explore their implications for model output uncertainty; *Uncertainty Quantification*: representation of model output uncertainty using probability distributions; *Traditional statistical inference*: use of analysis results to describe deterministic or probabilistic outcomes resulting from the presence of uncertainty; *Narrative scenarios*: use of a limited decision-relevant number of scenarios to describe (sets of) changing system outcomes; *Exploratory modeling for scenario discovery*: use of large ensembles of uncertain conditions to discover decision-relevant combinations of uncertain factors.

diff --git a/docs/source/2.1_overview_of_model_diagnostics.rst b/docs/source/2.1_overview_of_model_diagnostics.rst
@@ -7,6 +7,7 @@ Model diagnostics provide a rich basis for hypothesis testing, model innovation,
 .. figure:: _static/figure2_1_idealized_uc.png
     :alt: Figure 2.1
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Idealized uncertainty characterization and global sensitivity analysis for two coupled simulation models. Uncertainty coming from various sources (e.g., inputs, model structures, coupling relationships) is propagated through the coupled model(s) to generate empirical distributions of outputs of interest (uncertainty characterization). This model output uncertainty can be decomposed to its origins, by means of sensitivity analysis. Figure adapted from :cite:t:`saltelli2019so`.

diff --git a/docs/source/3.1_global_versus_local_sensitivity.rst b/docs/source/3.1_global_versus_local_sensitivity.rst
@@ -11,6 +11,7 @@ Historically, there have been two broad categories of sensitivity analysis techn
 .. figure:: _static/figure3_1_global_versus_local.png
     :alt: Figure 3.1
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Treatment of a two-dimensional space of variability by local (panels a-b) and global (panel c) sensitivity analyses. Panels depict contour plots with the value of a model response (:math:`y`) changing with changes in the values of input terms :math:`x_1` and :math:`x_2`. Local sensitivity analysis is only an appropriate approach to sensitivity in the case of linear models without interactions between terms, for example in panel (a), where :math:`y=3x_1+5x_2`. In the case of more complex models, for example in panels (b-c), where :math:`y={1 \above 1pt e^{x^2_1+x^2_2}} + {50 \above 1pt e^{(0.1x_1)^2+(0.1x_2)^3}}`, local sensitivity will miscalculate sensitivity indices as the assessed changes in the value :math:`y` depend on the assumed base values chose for :math:`x_1` and :math:`x_2` (panel (b)). In these cases, global sensitivity methods should be used instead (panel (c)). The points in panel (c) are generated using a uniform random sample of :math:`n=50`, but many other methods are available.
diff --git a/docs/source/3.2_why_perform_sensitivity_analysis.rst b/docs/source/3.2_why_perform_sensitivity_analysis.rst
@@ -25,6 +25,7 @@ The nature and context of the model shapes the specific objectives of applying a
 .. figure:: _static/figure3_2_factor_mapping.png
     :alt: Figure 3.2
     :width: 500px
+    :figclass: margin-caption
     :align: center
 
     Factor prioritization, factor fixing and factor mapping settings of sensitivity analysis.

diff --git a/docs/source/3.3.2_full_fractional_factorial_sampling.rst b/docs/source/3.3.2_full_fractional_factorial_sampling.rst
@@ -9,6 +9,7 @@ Fractional factorial sampling is a widely used alternative to full factorial sam
 .. figure:: _static/figure3_3_alternative_designs.png
     :alt: Figure 3.3
     :width: 500px
+    :figclass: margin-caption
     :align: center
 
     Alternative designs of experiments and their computational costs for three uncertain factors :math:`(x_1,` :math:`x_2,` and :math:`x_3)`. (a) Full factorial design sampling of three factors at four levels, at a total of 64 samples; (b) exponential growth of necessary number of samples when applying full factorial design at four levels; (c) fractional factorial design of three factors at four levels, at a total of 32 samples; and (d) Latin Hypercube sample of three factors with uniform distributions, at a total of 32 samples.
diff --git a/docs/source/3.4.2_elementary_effect_methods.rst b/docs/source/3.4.2_elementary_effect_methods.rst
@@ -23,6 +23,7 @@ which is a measure of parametric interactions. Higher values of :math:`\sigma_i`
 .. figure:: _static/figure3_4_morris_method.png
     :alt: Figure 3.4
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Illustrative results of the Morris Method. Factors :math:`x_1`, :math:`x_2`, :math:`x_4`, and :math:`x_5` have an influence on the model outputs, with :math:`x_1`, :math:`x_4`, and :math:`x_5` having interactive or non-linear effects. Whether or not a factor should be considered influential to the output depends on the output selected and is specific to the research context and purpose of the analysis, as discussed in :numref:`why_SA`.
diff --git a/...how_to_choose_a_sensitivity_analysis_method_model_traits_and_dimensionality.rst b/...how_to_choose_a_sensitivity_analysis_method_model_traits_and_dimensionality.rst
@@ -7,6 +7,7 @@ How To Choose A Sensitivity Analysis Method: Model Traits And Dimensionality
 .. figure:: _static/figure3_5classificationofmethods.png
     :alt: Figure 3_5
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Classification of the sensitivity analysis methods overviewed in this section, with regards to their computational cost (horizontal axis), their appropriateness to model complexity (vertical axis), and the purpose they can be used for (colored bars). d: number of uncertain factors considered; ANOVA: Analysis of Variance; FAST: Fourier Amplitude Sensitivity Test; PRIM: Patient Rule Induction Method; CART: Classification and Regression Trees; SRCC: Spearman’s rank correlation coefficient: NSE: Nash–Sutcliffe efficiency; SRC: standardized regression coefficient; PCC: Pearson correlation coefficient. This figure is synthesized from variants found in :cite:p:`iooss2015review, pianosi2016sensitivity`.

diff --git a/docs/source/3.6_software_toolkits.rst b/docs/source/3.6_software_toolkits.rst
@@ -10,6 +10,7 @@ This section presents available open source sensitivity analysis software tools,
 .. figure:: _static/figure3_6_softwaretoolkits.png
     :alt: Figure 3_6
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Sensitivity analysis packages available in different programming language platforms (R, Python, Julia, MATLAB, and C++), with the number of methods they support. Packages supporting more than five methods are indicated in pink. Packages updated since 2018 are indicated with asterisks. 

diff --git a/docs/source/4.1_understanding_errors_what_is_controlling_model_performance.rst b/docs/source/4.1_understanding_errors_what_is_controlling_model_performance.rst
@@ -15,6 +15,7 @@ A comprehensive model diagnostic workflow typically entails the components demon
 .. figure:: _static/figure4_1_diagnostic_workflow.png
     :alt: Figure 4.1
     :width: 500px
+    :figclass: margin-caption
     :align: center
 
     Diagnostic evaluation of model fidelity using sensitivity analysis methods.

diff --git a/.../4.2_consequential_dynamics_what_is_controlling_model_behaviors_of_interest.rst b/.../4.2_consequential_dynamics_what_is_controlling_model_behaviors_of_interest.rst
@@ -5,8 +5,9 @@ Consequential changes in dynamic systems can take many forms, but most dynamic b
 
 .. _Figure_4_2:
 .. figure:: _static/figure4_2_behavior_modes.png
-    :alt: Figure 11.
+    :alt: Figure 4.2
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Common modes of behavior in dynamic systems, occurring based on the presence of positive and negative feedback relationships, and linear and non-linear interactions. Adapted from :cite:t:`sterman2001system`.
@@ -29,6 +30,7 @@ Panels (a-c) in :numref:`Figure_4_3` plot the fluxes of phosphorus into the lake
 .. figure:: _static/figure4_3_lake_problem_fluxes.png
     :alt: Figure 4.3
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Fluxes of phosphorus with regards to mass of phosphorus in the lake and sensitivity analysis results, assuming :math:`b=0.42` and :math:`q=2`. (a) Fluxes of phosphorus assuming no emmisions policy and no natural inflows. (b-c) Fluxes phosphorus when applying two different emissions policies. The "Best economic policy" and the "Most realiable policy" have been identified by :cite:t:`quinn2017direct` and can be found at :cite:t:`quinn_julianneqlake_problem_dps_2017`. (d) Results of a sensitivity analysis on the parameters of the model most consequential to the reliability of the "Most reliable policy". The code to replicate the sensitivity analysis can be found at :cite:t:`hadka_project-platypusrhodium_2017`. Panels (a-c) are used courtesy of Julianne Quinn, University of Virginia.

diff --git a/...urce/4.3_consequential_scenarios_what_is_controlling_consequential_outcomes.rst b/...urce/4.3_consequential_scenarios_what_is_controlling_consequential_outcomes.rst
@@ -9,6 +9,7 @@ As overviewed in :numref:`perspectives`, most models are abstractions of systems
 .. figure:: _static/figure4_4_exploratory_workflow.png
     :alt: Figure 4_4
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     A typical exploratory modeling workflow
@@ -36,6 +37,7 @@ Below we provide an example application of two scenario discovery methods, PRIM
 .. figure:: _static/figure14lake_problem_SD.png
     :alt: Figure 14.
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Scenario discovery for the lake problem, using (a) PRIM and (b) logistic regression.

diff --git a/docs/source/A1.1_UQ_Introduction.rst b/docs/source/A1.1_UQ_Introduction.rst
@@ -11,6 +11,7 @@ The act of quantification requires specific assumptions about distributional for
 .. figure:: _static/figureA1_1_UQ_approaches.png
     :alt: Figure A1.1
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Overview of selected existing approaches for uncertainty quantification and their appropriateness given the number of uncertain model parameters and the number of available model simulations. Green shading denotes regions suitable for uncertainty quantification and red shading indicates regions more appropriate for uncertainty characterization.

diff --git a/docs/source/A1.2_Parametric_Bootstrap.rst b/docs/source/A1.2_Parametric_Bootstrap.rst
@@ -9,6 +9,7 @@ A typical workflow for the parametric bootstrap is shown in :numref:`Figure_A1_2
 .. figure:: _static/figureA1_2_bootstrap_workflow.png
     :alt: Figure A1.2
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Workflow for the parametric bootstrap.

diff --git a/docs/source/A1.3_Precalibration.rst b/docs/source/A1.3_Precalibration.rst
@@ -7,6 +7,7 @@ Pre-calibration :cite:`beven_future_1992, edwards_precalibrating_2011, boukouval
 .. figure:: _static/figureA1_3_precal_workflow.png
     :alt: Figure A1.3
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Workflow for pre-calibration.

diff --git a/docs/source/A1.4_Markov_Chain_Monte_Carlo.rst b/docs/source/A1.4_Markov_Chain_Monte_Carlo.rst
@@ -11,6 +11,7 @@ A general workflow for MCMC is shown in :numref:`Figure_A1_4`. The first decisio
 .. figure:: _static/figureA1_4_mcmc_workflow.png
     :alt: Figure A1.4
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Workflow for Markov chain Monte Carlo.

diff --git a/docs/source/A1.6_Critical_first_step.rst b/docs/source/A1.6_Critical_first_step.rst
@@ -13,6 +13,7 @@ Priors can also be classified in terms of the information encoded by them, demon
 .. figure:: _static/figureA1_5_priors_posteriors.png
     :alt: Figure A1.5
     :width: 700px
+    :figclass: margin-caption
     :align: center
 
     Impact of priors on posterior inferences. These plots show the results of inference for a linear regression model with 15 data points. The true value of the parameter is equal to -3. All priors have mean 0. In panel (a), a non-informative prior allows the tails of the posterior to extend freely, which may result in unreasonably large parameter values. In panel (b), a weakly informative prior constrains the tails more, but allows them to extend without too much restriction. In panel (c), an informative prior strongly constrains the tails of the posterior and biases the inference closer towards the prior mean (the posterior mean is -0.89 in this case, and closer to -3 in the other two cases).

diff --git a/docs/source/acknowledgements.rst b/docs/source/acknowledgements.rst
@@ -1,17 +1,21 @@
-This e-book was developed by the `Integrated Multisector, Multiscale Modeling (IM3) project <https://im3.pnnl.gov>`_, supported by the `U.S. Department of Energy <https://www.energy.gov/>`_, `Office of Science <https://www.energy.gov/science/office-science>`_, as part of research in the `MultiSector Dynamics <https://climatemodeling.science.energy.gov/program/multisector-dynamics>`_, Earth and Environmental System Modeling Program.
 
-Copyright (c) 2022-present; Battelle Memorial Institute
+Acknowledgements
+################
+
+This e-book was developed by the `Integrated Multisector, Multiscale Modeling (IM3) project <https://im3.pnnl.gov>`_, supported by the `U.S. Department of Energy <https://www.energy.gov/>`_, `Office of Science <https://www.energy.gov/science/office-science>`_, as part of research in the `MultiSector Dynamics <https://climatemodeling.science.energy.gov/program/multisector-dynamics>`_, Earth and Environmental System Modeling Program.
 
 Open source under license CC BY-NC-ND 4.0
 
 Open Source Disclaimer:
 
-This material was prepared as an account of work sponsored by an agency of the United States Government.  Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights.
-Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.
+    This material was prepared as an account of work sponsored by an agency of the United States Government.  Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights.
+    Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.
+
+| PACIFIC NORTHWEST NATIONAL LABORATORY
+| operated by
+| BATTELLE
+| for the
+| UNITED STATES DEPARTMENT OF ENERGY
+| under Contract DE-AC05-76RL01830
 
-PACIFIC NORTHWEST NATIONAL LABORATORY
-operated by
-BATTELLE
-for the
-UNITED STATES DEPARTMENT OF ENERGY
-under Contract DE-AC05-76RL01830
+Copyright (c) 2022-present; Battelle Memorial Institute
diff --git a/docs/source/citation.rst b/docs/source/citation.rst
@@ -0,0 +1,4 @@
+Suggested Citation
+###################
+
+    Reed, P.M., Hadjimichael, A., Malek, K., Karimi, T., Vernon, C.R., Srikrishnan, V., Gupta, R.S., Gold, D.F., Lee, B., Keller, K., Rice, J.S., & Thurber, T.B. (2022). Addressing Uncertainty in Multisector Dynamics Research [Book]. Zenodo. https://doi.org/10.5281/zenodo.6110623
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -72,20 +72,17 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_book_theme'
 
-# theme options for alabaster
+# theme options
 html_theme_options = {
-    'note_bg': '#D6EAF8',
-    'seealso_bg': '#D6EAF8',
-    'description': f'''
-Patrick M. Reed, Antonia Hadjimichael, Keyvan Malek,
-Tina Karimi, Chris R. Vernon, Vivek Srikrishnan, Rohini Gupta,
-David Gold, Ben Lee, Klaus Keller, Jennie S. Rice, Travis Thurber
-<br/><br/>
-{today}
-    ''',
-    'show_powered_by': False,
+    'path_to_docs': '/docs',
+    'repository_url': 'https://github.com/IMMM-SFA/msd_uncertainty_ebook',
+    'use_issues_button': True,
+    'use_download_button': True,
+    'use_repository_button': True,
+    'extra_navbar': f'<span style="display:block;text-align:left">{today}</span>',
+    'home_page_in_toc': False,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -116,7 +113,7 @@
      'addressinguncertaintyinmultisectordynamicsresearch.tex',
      '\\textbf{Addressing Uncertainty in MultiSector Dynamics Research}',
      'Patrick M. Reed, Antonia Hadjimichael, Keyvan Malek'
-     '\\and Tina Karimi, Chris R. Vernon, Vivek Srikrishnan, Rohini Gupta'
-     '\\and David Gold, Ben Lee, Klaus Keller, Jennie S. Rice, Travis Thurber',
+     '\\and Tina Karimi, Chris R. Vernon, Vivek Srikrishnan, Rohini S. Gupta'
+     '\\and David F. Gold, Ben Lee, Klaus Keller, Jennie S. Rice, Travis B. Thurber',
      'book')
 ]