Refactor significance to sensitivity_indices

Author: tupui

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.
 

app.py

@@ -56,12 +56,12 @@ def filtered_output(data, output_name):
 
 
 @pn.cache
-def significance(inputs, output):
-    si = sd.significance(inputs=inputs, output=output).si
+def sensitivity_indices(inputs, output):
+    si = sd.sensitivity_indices(inputs=inputs, output=output).si
     return si
 
 
-def significance_table(si, inputs):
+def sensitivity_indices_table(si, inputs):
     var_names = inputs.columns
     var_order = np.argsort(si)[::-1]
     var_names = var_names[var_order].tolist()
@@ -98,30 +98,30 @@ def explained_variance(si):
     return sum(si) + np.finfo(np.float64).eps
 
 
-def filtered_si(significance_table, input_names):
-    df = significance_table.value
+def filtered_si(sensitivity_indices_table, input_names):
+    df = sensitivity_indices_table.value
     si = []
     for input_name in input_names:
         si.append(df.loc[df["Inputs"] == input_name, "Indices"])
     return np.asarray(si).flatten()
 
 
-def explained_variance_80(significance_table):
-    si = significance_table.value["Indices"]
+def explained_variance_80(sensitivity_indices_table):
+    si = sensitivity_indices_table.value["Indices"]
     pos_80 = bisect.bisect_right(np.cumsum(si), 0.8)
 
     # pos_80 = max(2, pos_80)
     # pos_80 = min(len(si), pos_80)
 
-    input_names = significance_table.value["Inputs"]
+    input_names = sensitivity_indices_table.value["Inputs"]
     return input_names.to_list()[: pos_80 + 1]
 
 
 def decomposition(dec_limit, si, inputs, output):
     return sd.decomposition(
         inputs=inputs,
         output=output,
-        significance=si,
+        sensitivity_indices=si,
         dec_limit=dec_limit,
         auto_ordering=False,
     )
@@ -203,15 +203,19 @@ def tableau_states(res, states):
     filtered_output, interactive_file, selector_inputs_sensitivity
 )
 
-interactive_significance = pn.bind(significance, interactive_inputs, interactive_output)
-interactive_explained_variance = pn.bind(explained_variance, interactive_significance)
+interactive_sensitivity_indices = pn.bind(
+    sensitivity_indices, interactive_inputs, interactive_output
+)
+interactive_explained_variance = pn.bind(
+    explained_variance, interactive_sensitivity_indices
+)
 
-interactive_significance_table = pn.bind(
-    significance_table, interactive_significance, interactive_inputs
+interactive_sensitivity_indices_table = pn.bind(
+    sensitivity_indices_table, interactive_sensitivity_indices, interactive_inputs
 )
 
 interactive_explained_variance_80 = pn.bind(
-    explained_variance_80, interactive_significance_table
+    explained_variance_80, interactive_sensitivity_indices_table
 )
 selector_inputs_decomposition = pn.widgets.MultiChoice(
     name="Select inputs for decomposition",
@@ -224,7 +228,7 @@ def tableau_states(res, states):
 )
 
 interactive_filtered_si = pn.bind(
-    filtered_si, interactive_significance_table, selector_inputs_decomposition
+    filtered_si, interactive_sensitivity_indices_table, selector_inputs_decomposition
 )
 interactive_filtered_explained_variance = pn.bind(
     explained_variance, interactive_filtered_si
@@ -339,7 +343,7 @@ def tableau_states(res, states):
             ),
             pn.Spacer(height=50),
             pn.pane.Markdown(si_description, styles={"color": "#0072b5"}),
-            pn.Column(interactive_significance_table, width=400),
+            pn.Column(interactive_sensitivity_indices_table, width=400),
         ),
         pn.Column(
             pn.pane.Markdown(table_description, styles={"color": "#0072b5"}),

docs/index.rst

@@ -5,7 +5,7 @@ Welcome to SimDec's documentation!
 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.
 

src/simdec/__init__.py

@@ -1,10 +1,10 @@
 """SimDec main namespace."""
 from simdec.decomposition import *
-from simdec.significance import *
+from simdec.sensitivity_indices import *
 from simdec.visualization import *
 
 __all__ = [
-    "significance",
+    "sensitivity_indices",
     "states_expansion",
     "decomposition",
     "visualization",

src/simdec/decomposition.py

@@ -51,7 +51,7 @@ def decomposition(
     inputs: pd.DataFrame,
     output: pd.DataFrame,
     *,
-    significance: np.ndarray,
+    sensitivity_indices: np.ndarray,
     dec_limit: float = 1,
     auto_ordering: bool = True,
     states: list[int] | None = None,
@@ -65,12 +65,12 @@ def decomposition(
         Input variables.
     output : DataFrame of shape (n_runs, 1)
         Target variable.
-    significance : ndarray of shape (n_factors, 1)
-        Significance index, combined effect of each input.
+    sensitivity_indices : ndarray of shape (n_factors, 1)
+        Sensitivity indices, combined effect of each input.
     dec_limit : float
         Explained variance ratio to filter the number input variables.
     auto_ordering : bool
-        Automatically order input columns based on the relative significance
+        Automatically order input columns based on the relative sensitivity_indices
         or use the provided order.
     states : list of int, optional
         List of possible states for the considered parameter.
@@ -105,11 +105,11 @@ def decomposition(
     output = output.to_numpy()
 
     # 1. variables for decomposition
-    var_order = np.argsort(significance)[::-1]
+    var_order = np.argsort(sensitivity_indices)[::-1]
 
     # only keep the explained variance corresponding to `dec_limit`
-    significance = significance[var_order]
-    n_var_dec = np.where(np.cumsum(significance) < dec_limit)[0].size
+    sensitivity_indices = sensitivity_indices[var_order]
+    n_var_dec = np.where(np.cumsum(sensitivity_indices) < dec_limit)[0].size
     n_var_dec = max(1, n_var_dec)  # keep at least one variable
     n_var_dec = min(5, n_var_dec)  # use at most 5 variables
 

src/simdec/significance.py src/simdec/sensitivity_indices.pysrc/simdec/significance.py renamed to src/simdec/sensitivity_indices.py

@@ -6,11 +6,11 @@
 from scipy import stats
 
 
-__all__ = ["significance"]
+__all__ = ["sensitivity_indices"]
 
 
 def number_of_bins(n_runs: int, n_factors: int) -> tuple[int, int]:
-    """Optimal number of bins for first & second-order significance indices.
+    """Optimal number of bins for first & second-order sensitivity_indices indices.
 
     Linear approximation of experimental results from (Marzban & Lahmer, 2016).
     """
@@ -31,18 +31,18 @@ def _weighted_var(x: np.ndarray, weights: np.ndarray) -> np.ndarray:
 
 
 @dataclass
-class SignificanceResult:
+class SensitivityAnalysisResult:
     si: np.ndarray
     first_order: np.ndarray
     second_order: np.ndarray
 
 
-def significance(
+def sensitivity_indices(
     inputs: pd.DataFrame | np.ndarray, output: pd.DataFrame | np.ndarray
-) -> SignificanceResult:
-    """Significance indices.
+) -> SensitivityAnalysisResult:
+    """Sensitivity indices.
 
-    The significance express how much variability of the output is
+    The sensitivity_indices express how much variability of the output is
     explained by the inputs.
 
     Parameters
@@ -54,11 +54,11 @@ def significance(
 
     Returns
     -------
-    res : SignificanceResult
+    res : SensitivityAnalysisResult
         An object with attributes:
 
         si : ndarray of shape (n_factors, 1)
-            Significance index, combined effect of each input.
+            Sensitivity indices, combined effect of each input.
         foe : ndarray of shape (n_factors, 1)
             First-order effects (also called 'main' or 'individual').
         soe : ndarray of shape (n_factors, 1)
@@ -89,9 +89,9 @@ def significance(
     ... )
     >>> output = f_ishigami(inputs.T)
 
-    We can now pass our inputs and outputs to the `significance` function:
+    We can now pass our inputs and outputs to the `sensitivity_indices` function:
 
-    >>> res = sd.significance(inputs=inputs, output=output)
+    >>> res = sd.sensitivity_indices(inputs=inputs, output=output)
     >>> res.si
     array([0.43157591, 0.44241433, 0.11767249])
 
@@ -168,4 +168,4 @@ def significance(
         soe = np.where(soe == 0, soe.T, soe)
         si[i] = foe[i] + soe[:, i].sum() / 2
 
-    return SignificanceResult(si, foe, soe)
+    return SensitivityAnalysisResult(si, foe, soe)

src/simdec/workflow.py

@@ -16,7 +16,7 @@ def test_decomposition():
     output_name, *v_names = list(data.columns)
     inputs, output = data[v_names], data[output_name]
     si = np.array([0.04, 0.50, 0.11, 0.28])
-    res = sd.decomposition(inputs=inputs, output=output, significance=si)
+    res = sd.decomposition(inputs=inputs, output=output, sensitivity_indices=si)
 
     assert res.var_names == ["sigma_res", "R", "Rp0.2", "Kf"]
     assert res.states == [2, 2, 2, 2]

tests/test_decomposition.py

@@ -47,7 +47,7 @@ def ishigami_ref_indices():
     return s_first, s_second, s_total
 
 
-def test_significance(ishigami_ref_indices):
+def test_sensitivity_indices(ishigami_ref_indices):
     rng = np.random.default_rng(1655943881803900660874135192647741156)
     n_dim = 3
 
@@ -57,7 +57,7 @@ def test_significance(ishigami_ref_indices):
     )
     output = f_ishigami(inputs.T)
 
-    res = sd.significance(inputs=inputs, output=output)
+    res = sd.sensitivity_indices(inputs=inputs, output=output)
 
     assert res.si.shape == (3,)
     assert res.first_order.shape == (3,)
@@ -83,12 +83,12 @@ def test_significance(ishigami_ref_indices):
         ),
     ],
 )
-def test_significance_dataset(fname, foe_ref, si_ref):
+def test_sensitivity_indices_dataset(fname, foe_ref, si_ref):
     data = pd.read_csv(fname)
     output_name, *v_names = list(data.columns)
     inputs, output = data[v_names], data[output_name]
 
-    res = sd.significance(inputs=inputs, output=output)
+    res = sd.sensitivity_indices(inputs=inputs, output=output)
 
     npt.assert_allclose(res.first_order, foe_ref, atol=5e-3)
     npt.assert_allclose(res.si, si_ref, atol=5e-2)