Merge pull request #539 from SALib/docstring-updates

Pre-release documentation updates

.gitignore

@@ -47,3 +47,5 @@ cover/*
 MANIFEST
 
 playground/
+
+docs/html/

CONTRIBUTING.md

@@ -100,6 +100,7 @@ Then, create a new branch with a useful name, such as `new_method_method_name`.
 
 Finally, submit a pull request. Either @willu47 or @jdherman will review the pull request and merge in your changes.
 
+
 ### Other Enhancements
 
 Contributions not related to new methods are also welcome. These might include new test functions (see [SALib.test_functions](https://github.com/SALib/SALib/tree/main/SALib/test_functions) for how these are set up), or other code that is general across some or all of the methods. This general code is currently included in [SALib.util.\_\_init\_\_.py](https://github.com/SALib/SALib/blob/main/SALib/util/__init__.py).
@@ -136,3 +137,15 @@ a release:
 7. Check documentation is built and deployed to readthedocs (http://salib.readthedocs.org)
 8. Check that auto-generated PR is auto-merged on the conda-forge feedstock repo (conda-forge/salib-feedstock)
 9. Update development roadmap on GitHub
+
+## Building a local copy of the documentation
+
+Assuming the current location is the project root (the `SALib` directory):
+
+```bash
+$ conda install pydata-sphinx-theme myst-parser -c conda-forge
+$ sphinx-build -b html docs docs/html
+```
+
+A copy of the documentation will be in the `docs/html` directory.
+Open `index.html` to view it.

docs/api.rst

@@ -10,7 +10,6 @@ FAST - Fourier Amplitude Sensitivity Test
 .. autofunction:: SALib.sample.fast_sampler.sample
    :noindex:
 
-
 .. autofunction:: SALib.analyze.fast.analyze
    :noindex:
 
@@ -20,7 +19,6 @@ RBD-FAST - Random Balance Designs Fourier Amplitude Sensitivity Test
 .. autofunction:: SALib.sample.latin.sample
    :noindex:
 
-
 .. autofunction:: SALib.analyze.rbd_fast.analyze
    :noindex:
 
@@ -30,7 +28,6 @@ Method of Morris
 .. autofunction:: SALib.sample.morris.sample
    :noindex:
 
-
 .. autofunction:: SALib.analyze.morris.analyze
    :noindex:
 
@@ -40,17 +37,15 @@ Sobol' Sensitivity Analysis
 .. autofunction:: SALib.sample.saltelli.sample
    :noindex:
 
+.. autofunction:: SALib.sample.sobol.sample
+   :noindex:
 
 .. autofunction:: SALib.analyze.sobol.analyze
    :noindex:
 
 Delta Moment-Independent Measure
 --------------------------------
 
-.. autofunction:: SALib.sample.latin.sample
-   :noindex:
-
-
 .. autofunction:: SALib.analyze.delta.analyze
    :noindex:
 
@@ -66,7 +61,6 @@ Fractional Factorial
 .. autofunction:: SALib.sample.ff.sample
    :noindex:
 
-
 .. autofunction:: SALib.analyze.ff.analyze
    :noindex:
 

src/SALib/analyze/delta.py

@@ -29,6 +29,13 @@ def analyze(
         all samplers
 
 
+    Examples
+    --------
+        >>> X = latin.sample(problem, 1000)
+        >>> Y = Ishigami.evaluate(X)
+        >>> Si = delta.analyze(problem, X, Y, print_to_console=True)
+
+
     Parameters
     ----------
     problem : dict
@@ -54,13 +61,6 @@ def analyze(
     .. [2] Plischke, E., E. Borgonovo, and C. L. Smith (2013). "Global
            sensitivity measures from given data." European Journal of
            Operational Research, 226(3):536-550, doi:10.1016/j.ejor.2012.11.047.
-
-
-    Examples
-    --------
-        >>> X = latin.sample(problem, 1000)
-        >>> Y = Ishigami.evaluate(X)
-        >>> Si = delta.analyze(problem, X, Y, print_to_console=True)
     """
     if seed:
         np.random.seed(seed)

src/SALib/analyze/dgsm.py

@@ -22,6 +22,13 @@ def analyze(
         `finite_diff` : :func:`SALib.sample.finite_diff.sample`
 
 
+    Examples
+    --------
+        >>> X = finite_diff.sample(problem, 1000)
+        >>> Y = Ishigami.evaluate(X)
+        >>> Si = dgsm.analyze(problem, Y, print_to_console=False)
+
+
     Parameters
     ----------
     problem : dict
@@ -47,12 +54,6 @@ def analyze(
            sensitivity measures and their link with global sensitivity
            indices." Mathematics and Computers in Simulation, 79(10):3009-3017,
            doi:10.1016/j.matcom.2009.01.023.
-
-    Examples
-    --------
-        >>> X = finite_diff.sample(problem, 1000)
-        >>> Y = Ishigami.evaluate(X)
-        >>> Si = dgsm.analyze(problem, Y, print_to_console=False)
     """
     if seed:
         np.random.seed(seed)

src/SALib/analyze/fast.py

@@ -28,6 +28,13 @@ def analyze(
         `fast_sampler` : :func:`SALib.sample.fast_sampler.sample`
 
 
+    Examples
+    --------
+        >>> X = fast_sampler.sample(problem, 1000)
+        >>> Y = Ishigami.evaluate(X)
+        >>> Si = fast.analyze(problem, Y, print_to_console=False)
+
+
     Parameters
     ----------
     problem : dict
@@ -58,13 +65,6 @@ def analyze(
     .. [3] Pujol, G. (2006)
            fast99 - R `sensitivity` package
            https://github.com/cran/sensitivity/blob/master/R/fast99.R
-
-
-    Examples
-    --------
-        >>> X = fast_sampler.sample(problem, 1000)
-        >>> Y = Ishigami.evaluate(X)
-        >>> Si = fast.analyze(problem, Y, print_to_console=False)
     """
     if seed:
         np.random.seed(seed)

src/SALib/analyze/ff.py

@@ -29,6 +29,13 @@ def analyze(problem, X, Y, second_order=False, print_to_console=False, seed=None
         `ff` : :func:`SALib.sample.ff.sample`
 
 
+    Examples
+    --------
+        >>> X = sample(problem)
+        >>> Y = X[:, 0] + (0.1 * X[:, 1]) + ((1.2 * X[:, 2]) * (0.2 + X[:, 0]))
+        >>> analyze(problem, X, Y, second_order=True, print_to_console=True)
+
+
     Parameters
     ----------
     problem: dict
@@ -60,13 +67,6 @@ def analyze(problem, X, Y, second_order=False, print_to_console=False, seed=None
            Global Sensitivity Analysis: The Primer.
            Wiley, West Sussex, U.K.
            http://doi.org/10.1002/9780470725184
-
-
-    Examples
-    --------
-        >>> X = sample(problem)
-        >>> Y = X[:, 0] + (0.1 * X[:, 1]) + ((1.2 * X[:, 2]) * (0.2 + X[:, 0]))
-        >>> analyze(problem, X, Y, second_order=True, print_to_console=True)
     """
     if seed:
         np.random.seed(seed)

src/SALib/analyze/hdmr.py

@@ -36,55 +36,61 @@ def analyze(
     print_to_console: bool = False,
     seed: int = None,
 ) -> Dict:
-    """This method computes global sensitivity indices using meta-modeling
-    technique called High Dimensional Model Representation (HDMR).
+    """Compute global sensitivity indices using the meta-modeling technique
+    known as High-Dimensional Model Representation (HDMR).
 
-    HDMR itself is not a sensitivity analysis method but it is a surrogate model.
-    It constructs a map of relationship between sets of high dimensional input
-    and output system variables [1]. This I/O relation can be constructed using
-    different basis functions (orthonormal polynomials, splines, etc.). The
-    model decomposition can be expressed as
+    HDMR itself is not a sensitivity analysis method but a surrogate modeling
+    approach. It constructs a map of relationship between sets of high
+    dimensional inputs and output system variables [1]. This I/O relation can
+    be constructed using different basis functions (orthonormal polynomials,
+    splines, etc.). The model decomposition can be expressed as
 
     .. math::
         \\widehat{y} = \\sum_{u \\subseteq \\{1, 2, ..., d \\}} f_u
 
-    where u represents any subset including empty set.
+    where u represents any subset including an empty set.
 
-    The HDMR method becomes extremely useful when number of sample points are not
-    enough for Monte Carlo simulation as in Sobol's method. It uses least-square
-    regression to reduce the number of samples and thus number of function (model)
-    evaluations. Another advantage of this method is that it can account for
-    correlation among the model input. Unlike other variance-based methods, the main
-    effects are combination of structural (uncorrelated) part and correlated part.
+    HDMR becomes extremely useful when the computational cost of obtaining
+    sufficient Monte Carlo samples are prohibitive, as may be the case with
+    Sobol's method. It uses least-square regression to reduce the required
+    number of samples and thus the number of function (model) evaluations.
+    Another advantage of this method is that it can account for correlation
+    among the model input. Unlike other variance-based methods, the main
+    effects are the combination of structural (uncorrelated) and
+    correlated contributions.
 
     This method uses as input
 
     - a N x d matrix of N different d-vectors of model inputs (factors/parameters)
     - a N x 1 vector of corresponding model outputs
 
-    Returns:
-
-    - each factor's first, second, and third order sensitivity coefficient
-      (separated in total, structural and correlative contributions),
-    - an estimate of their 95% confidence intervals (from bootstrap method)
-    - the coefficients of the significant B-spline basis functions that
-      govern output,
-    - Y (determined by an F-test of the error residuals of the HDMR model
-      (emulator) with/without a given first, second and/or
-      third order B-spline). These coefficients define an emulator that can
-      be used to predict the output, Y, of the original (CPU-intensive)
-      model for any d-vector of model inputs. For uncorrelated model inputs
-      (columns of X are independent), the HDMR sensitivity indices reduce
-      to a single index (= structural contribution), consistent with their
-      values derived from commonly used variance-based GSA methods.
-
 
     Notes
     -----
     Compatible with:
         all samplers
 
-    Contributed by @sahin-abdullah (sahina@uci.edu)
+    Sets an `emulate` method allowing re-use of the emulator.
+
+
+    Examples
+    --------
+    .. code-block:: python
+        :linenos:
+
+        sp = ProblemSpec({
+            'names': ['X1', 'X2', 'X3'],
+            'bounds': [[-np.pi, np.pi]] * 3,
+            # 'groups': ['A', 'B', 'A'],
+            'outputs': ['Y']
+        })
+
+        (sp.sample_saltelli(2048)
+            .evaluate(Ishigami.evaluate)
+            .analyze_hdmr()
+        )
+
+        sp.emulate()
 
 
     Parameters
@@ -120,26 +126,34 @@ def analyze(
         Regularization term
 
     print_to_console : bool
-        Print results directly to console (default False)
+        Print results directly to console (default: False)
 
     seed : bool
-        Set a seed value
+        Seed to generate a random number
 
 
     Returns
     -------
     Si : ResultDict,
-        Sa: Uncorrelated contribution
-        Sa_conf: Confidence interval of Sa
-        Sb: Correlated contribution
-        Sb_conf: Confidence interval of Sb
-        S: Total contribution of a particular term
-        S_conf: Confidence interval of S
-        ST: Total contribution of a particular dimension/parameter
+        Sa : Uncorrelated contribution of a term
+
+        Sa_conf : Confidence interval of Sa
+
+        Sb : Correlated contribution of a term
+
+        Sb_conf : Confidence interval of Sb
+
+        S : Total contribution of a particular term
+           Sum of Sa and Sb, representing first/second/third order sensitivity indices
+
+        S_conf : Confidence interval of S
+
+        ST : Total contribution of a particular dimension/parameter
+
         ST_conf: Confidence interval of ST
-        Sa: Uncorrelated contribution
         select: Number of selection (F-Test)
-        Em: Result set
+
+        Em : Emulator result set
             C1: First order coefficient
             C2: Second order coefficient
             C3: Third Order coefficient
@@ -149,7 +163,7 @@ def analyze(
     ----------
     .. [1] Rabitz, H. and Aliş, Ö.F.,
            "General foundations of high dimensional model representations",
-           Journal of Mathematical Chemistry 25, 197–233 (1999)
+           Journal of Mathematical Chemistry 25, 197-233 (1999)
            https://doi.org/10.1023/A:1019188517934
 
     .. [2] Genyuan Li, H. Rabitz, P.E. Yelvington, O.O. Oluwole, F. Bacon,
@@ -158,13 +172,6 @@ def analyze(
              Correlated Inputs",
            Journal of Physical Chemistry A, Vol. 114 (19), pp. 6022 - 6032, 2010,
            https://doi.org/10.1021/jp9096919
-
-
-    Examples
-    --------
-        >>> X = saltelli.sample(problem, 512)
-        >>> Y = Ishigami.evaluate(X)
-        >>> Si = hdmr.analyze(problem, X, Y, **options)
     """
     # Random Seed
     if seed:

src/SALib/analyze/morris.py

@@ -54,6 +54,14 @@ def analyze(
         `morris` : :func:`SALib.sample.morris.sample`
 
 
+    Examples
+    --------
+        >>> X = morris.sample(problem, 1000, num_levels=4)
+        >>> Y = Ishigami.evaluate(X)
+        >>> Si = morris.analyze(problem, X, Y, conf_level=0.95,
+        >>>                     print_to_console=True, num_levels=4)
+
+
     Parameters
     ----------
     problem : dict
@@ -100,14 +108,6 @@ def analyze(
              of large models."
            Environmental Modelling & Software, 22(10):1509-1518,
            doi:10.1016/j.envsoft.2006.10.004.
-
-
-    Examples
-    --------
-        >>> X = morris.sample(problem, 1000, num_levels=4)
-        >>> Y = Ishigami.evaluate(X)
-        >>> Si = morris.analyze(problem, X, Y, conf_level=0.95,
-        >>>                     print_to_console=True, num_levels=4)
     """
     if seed:
         np.random.seed(seed)