simdec 1.5.1__tar.gz → 1.5.2__tar.gz

{simdec-1.5.1 → simdec-1.5.2}/.gitignore

@@ -38,3 +38,8 @@ app.html
 
 # Virtual environment
 venv/
+.venv/
+.wasm-build-venv/
+
+# Local Netlify folder
+.netlify

{simdec-1.5.1 → simdec-1.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: simdec
-Version: 1.5.1
+Version: 1.5.2
 Summary: Sensitivity analysis using simulation decomposition
 Project-URL: homepage, https://www.simdec.fi/
 Project-URL: documentation, https://simdec.readthedocs.io
@@ -30,6 +30,7 @@ Requires-Dist: panel>=1.4.5; extra == 'dashboard'
 Provides-Extra: dev
 Requires-Dist: accessible-pygments; extra == 'dev'
 Requires-Dist: cryptography; extra == 'dev'
+Requires-Dist: ipython>=9.1; extra == 'dev'
 Requires-Dist: myst-nb; extra == 'dev'
 Requires-Dist: numpydoc; extra == 'dev'
 Requires-Dist: panel>=1.4.5; extra == 'dev'
@@ -39,6 +40,8 @@ Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: sphinx; extra == 'dev'
 Requires-Dist: watchfiles; extra == 'dev'
+Provides-Extra: display
+Requires-Dist: ipython>=9.1; extra == 'display'
 Provides-Extra: doc
 Requires-Dist: accessible-pygments; extra == 'doc'
 Requires-Dist: myst-nb; extra == 'doc'
@@ -94,5 +97,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., Ahola, A., Roy, P., & Yeomans, J. S. (2025). Simple Binning Algorithm and SimDec Visualization for Comprehensive Sensitivity Analysis of Complex Computational Models. _Journal of Environmental Informatics Letters_, 13(1), 38-56. [https://arxiv.org/pdf/2310.13446](https://arxiv.org/pdf/2310.13446)
 - 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. (2024). 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. [Available here](https://github.com/Simulation-Decomposition/SimDec-book/blob/74ce72c1d3dda650eba1c59e3b215a4bb35c6be0/chapters/02_SimDec_algorithm_and_instructions/Ch2.pdf).

{simdec-1.5.1 → simdec-1.5.2}/README.md

@@ -42,5 +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., Ahola, A., Roy, P., & Yeomans, J. S. (2025). Simple Binning Algorithm and SimDec Visualization for Comprehensive Sensitivity Analysis of Complex Computational Models. _Journal of Environmental Informatics Letters_, 13(1), 38-56. [https://arxiv.org/pdf/2310.13446](https://arxiv.org/pdf/2310.13446)
 - 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. (2024). 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. [Available here](https://github.com/Simulation-Decomposition/SimDec-book/blob/74ce72c1d3dda650eba1c59e3b215a4bb35c6be0/chapters/02_SimDec_algorithm_and_instructions/Ch2.pdf).

simdec-1.5.2/netlify.toml

@@ -0,0 +1,24 @@
+[build]
+  command = "npm run build"
+  publish = "dist/pyodide"
+
+[dev]
+  ignore = ["dist", ".wasm-build-venv", "panel/data"]
+  port = 8888
+
+[build.environment]
+  PYTHON_VERSION = "3.11"
+  NODE_VERSION = "20"
+  CACHE_VERSION = "2"
+
+[[headers]]
+  for = "/*"
+  [headers.values]
+    Cross-Origin-Embedder-Policy = "require-corp"
+    Cross-Origin-Opener-Policy = "same-origin"
+
+[[headers]]
+  for = "/*.whl"
+  [headers.values]
+    Content-Type = "application/zip"
+    Access-Control-Allow-Origin = "*"

simdec-1.5.2/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "simdec-wasm-site",
+  "private": true,
+  "version": "1.0.0",
+  "description": "Static Panel WASM build wrapper",
+  "scripts": {
+    "build": "bash ./scripts/build_wasm.sh",
+    "serve": "mkdir -p dist/pyodide && python3 -m http.server 8000 --directory dist/pyodide"
+  }
+}

{simdec-1.5.1 → simdec-1.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "simdec"
-version = "1.5.1"
+version = "1.5.2"
 description = "Sensitivity analysis using simulation decomposition"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -41,6 +41,10 @@ dashboard = [
     "cryptography",
 ]
 
+display = [
+    "ipython>=9.1"
+]
+
 test = [
     "pytest",
     "pytest-cov",
@@ -55,7 +59,7 @@ doc = [
 ]
 
 dev = [
-    "simdec[doc,test,dashboard]",
+    "simdec[doc,test,dashboard, display]",
     "watchfiles",
     "pre-commit",
 ]

simdec-1.5.2/scripts/build_wasm.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# Logging
+set -x
+
+# Setup paths and environment
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUT_DIR="${ROOT_DIR}/dist/pyodide"
+
+# Wipe old build before starting
+if [ -d "${OUT_DIR}" ]; then
+    echo "Cleaning old build..."
+    rm -rf "${OUT_DIR}"
+fi
+
+cd "${ROOT_DIR}"
+
+# Determine which Python interpreter to use
+HOST_PYTHON="${PYTHON_BIN:-}"
+if [[ -z "${HOST_PYTHON}" ]]; then
+    if command -v python3 >/dev/null 2>&1; then
+        HOST_PYTHON="python3"
+    elif command -v python >/dev/null 2>&1; then
+        HOST_PYTHON="python"
+    else
+        echo "Error: No python interpreter found. Install python3 and retry."
+        exit 1
+    fi
+fi
+
+# Create build virtual environment
+VENV_DIR="${ROOT_DIR}/.wasm-build-venv"
+if [[ ! -d "${VENV_DIR}" ]]; then
+    echo "Creating build virtual environment at ${VENV_DIR}..."
+    "${HOST_PYTHON}" -m venv "${VENV_DIR}"
+fi
+
+PYTHON_BIN="${VENV_DIR}/bin/python"
+
+# Install build dependencies and build the wheel
+echo "Installing build tools and generating local wheel..."
+"${PYTHON_BIN}" -m pip install --upgrade pip build \
+    "panel==1.8.10" \
+    "bokeh==3.8.0" \
+    "matplotlib==3.10.8" \
+    "seaborn==0.13.2" \
+    "scipy==1.17.1" \
+    "SALib==1.5.2"
+# Clean old builds to avoid picking up the wrong wheel
+rm -rf dist/*.whl
+"${PYTHON_BIN}" -m build --wheel .
+
+# Identify the generated wheel file
+SIMDEC_WHEEL_PATH=$(ls dist/*.whl | head -n 1 || echo "")
+
+if [[ -z "${SIMDEC_WHEEL_PATH}" ]]; then
+    echo "Error: No wheel file found in dist/. Build failed."
+    exit 1
+fi
+
+WHEEL_FILENAME=$(basename "${SIMDEC_WHEEL_PATH}")
+
+# Prepare output directory - USE ABSOLUTE PATH
+OUT_DIR="${ROOT_DIR}/dist/pyodide"
+mkdir -p "${OUT_DIR}/_static"
+mkdir -p "${OUT_DIR}/data"
+
+# Copy the wheel into the output directory so it's accessible via HTTP
+cp "${SIMDEC_WHEEL_PATH}" "${OUT_DIR}/"
+
+# Copy the assets to where the Python scripts expect them
+mkdir -p panel/_static
+if [ -d "docs/_static" ]; then
+  # Use || true to prevent failure if it's empty
+  cp -r docs/_static/* panel/_static/ || true
+fi
+
+echo "Converting Panel apps to Pyodide worker output..."
+export PYTHONPATH="${ROOT_DIR}/src:${PYTHONPATH:-}"
+
+# Change directory into 'panel' so relative paths resolve correctly
+cd "${ROOT_DIR}/panel"
+
+# Bring the wheel into the current folder so we can pass just the filename
+cp "${ROOT_DIR}/${SIMDEC_WHEEL_PATH}" .
+
+# Safe file checking that won't trigger set -e
+echo "Checking necessary files locally before conversion..."
+if [[ ! -f "simdec_app.py" ]]; then echo "Warning: simdec_app.py not found in panel directory!"; fi
+if [[ ! -f "sampling.py" ]]; then echo "Warning: sampling.py not found in panel directory!"; fi
+
+# Ensure data/stress.csv exists relative to the current 'panel' dir
+if [[ ! -f "data/stress.csv" ]]; then
+    echo "Warning: panel/data/stress.csv missing."
+    if [[ -f "../data/stress.csv" ]]; then
+        echo "Found stress.csv in root. Copying to panel/data..."
+        mkdir -p data
+        cp "../data/stress.csv" data/
+    else
+        echo "Error: stress.csv not found anywhere! Conversion may fail."
+    fi
+fi
+
+# Copy stress.csv to output directory
+cp "data/stress.csv" "${OUT_DIR}/data/"
+
+# Run conversion
+"${PYTHON_BIN}" -m panel convert \
+    simdec_app.py \
+    sampling.py \
+    --to pyodide-worker \
+    --out "${OUT_DIR}" \
+    --requirements "${WHEEL_FILENAME}" numpy pandas matplotlib seaborn scipy SALib \
+    --resources data/stress.csv
+
+cp "./${WHEEL_FILENAME}" "${OUT_DIR}/"
+
+# Clean up the copied wheel
+rm "${WHEEL_FILENAME}"
+
+# Step back out to the root directory for the rest of the script
+cd "${ROOT_DIR}"
+
+# Copy custom index page and static assets
+echo "Copying custom index page and static assets..."
+
+# Copy images/thumbnails from docs/_static if they exist
+if [ -d "docs/_static" ]; then
+    cp -r docs/_static/* "${OUT_DIR}/_static/" || true
+fi
+
+# Overwrite default index.html with your custom homepage
+if [ -f "panel/index.html" ]; then
+    cp panel/index.html "${OUT_DIR}/index.html"
+else
+    echo "Warning: panel/index.html not found. Using default Panel index."
+fi
+
+echo "---"
+echo "WASM site successfully generated at ${OUT_DIR}"

{simdec-1.5.1 → simdec-1.5.2}/src/simdec/__init__.py

@@ -1,5 +1,6 @@
 """SimDec main namespace."""
 from simdec.decomposition import *
+from simdec.heterogeneity_indices import *
 from simdec.sensitivity_indices import *
 from simdec.visualization import *
 
@@ -8,6 +9,8 @@ __all__ = [
     "states_expansion",
     "decomposition",
     "visualization",
+    "two_output_visualization",
     "tableau",
     "palette",
+    "heterogeneity_indices",
 ]

{simdec-1.5.1 → simdec-1.5.2}/src/simdec/decomposition.py

@@ -138,7 +138,7 @@ def decomposition(
             n_var_dec = sensitivity_indices.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
+        n_var_dec = min(4, n_var_dec)  # use at most 4 variables
     else:
         n_var_dec = inputs.shape[1]
 

simdec-1.5.2/src/simdec/heterogeneity_indices.py

@@ -0,0 +1,642 @@
+from dataclasses import dataclass
+import math
+import warnings
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+import simdec
+
+__all__ = [
+    "HeterogeneityDetail",
+    "HeterogeneityResult",
+    "heterogeneity_indices",
+]
+
+_DEFAULT_N_REGIONS = 5
+# Computational safeguard, not a guarantee of statistical stability.
+_MIN_REGION_SIZE = 100
+
+
+@dataclass
+class HeterogeneityDetail:
+    """Detailed results for one partitioning variable.
+
+    Attributes
+    ----------
+    raw_profiles : pandas.DataFrame
+        Raw regional combined sensitivity profiles. Rows are regions and
+        columns are model inputs.
+    normalized_profiles : pandas.DataFrame
+        Regional profiles normalized to sum to one within each region. These
+        profiles are used to calculate H.
+    regional_sums : pandas.Series
+        Sum of the raw combined sensitivity indices in each region.
+    region_counts : pandas.Series
+        Number of observations in each region.
+    individual_contributions : pandas.Series
+        Input-level contributions C_{i,Z}. These sum to H_Z. For a categorical
+        input partition, the partitioning input itself is omitted because it is
+        constant within each of its own categories.
+    """
+
+    raw_profiles: pd.DataFrame
+    normalized_profiles: pd.DataFrame
+    regional_sums: pd.Series
+    region_counts: pd.Series
+    individual_contributions: pd.Series
+
+    def __repr__(self) -> str:
+        n_regions, n_inputs = self.raw_profiles.shape
+        return (
+            "HeterogeneityDetail("
+            f"regions={n_regions}, inputs={n_inputs}; "
+            "raw_profiles, normalized_profiles, regional_sums, "
+            "region_counts, individual_contributions)"
+        )
+
+
+@dataclass
+class HeterogeneityResult:
+    """Results returned by :func:`heterogeneity_indices`.
+
+    The main heterogeneity estimates are available through ``indices``.
+    Complete regional diagnostics are stored in ``details``.
+    """
+
+    indices: pd.Series
+    details: dict
+    _input_order: tuple
+
+    def __getitem__(self, partition):
+        """Return H for one partition, e.g. ``H[\"X1\"]``."""
+        return self.indices.loc[partition]
+
+    def __repr__(self) -> str:
+        if self.indices.empty:
+            return "HeterogeneityResult\n\nNo heterogeneity indices were computed."
+        table = self.indices.rename("H").to_frame()
+        return "HeterogeneityResult\n\n" + table.to_string()
+
+    def plot(self, partition=None, ax=None):
+        """Plot raw regional sensitivity profiles.
+
+        Parameters
+        ----------
+        partition : str or sequence of str, optional
+            Partition(s) to plot. If omitted, all available partitions are
+            plotted. Examples: ``H.plot(\"X1\")`` or
+            ``H.plot([\"Y\", \"X1\", \"X2\"])``.
+        ax : matplotlib.axes.Axes, optional
+            Existing axes. Only valid when plotting one partition.
+
+        Returns
+        -------
+        matplotlib.axes.Axes or numpy.ndarray
+            Axes containing the plot(s).
+        """
+        return _plot_heterogeneity(self, partition=partition, ax=ax)
+
+
+def _as_dataframe(inputs) -> pd.DataFrame:
+    X = pd.DataFrame(inputs).reset_index(drop=True).copy()
+    if X.shape[1] == 0:
+        raise ValueError("'inputs' must contain at least one input variable.")
+    if X.columns.has_duplicates:
+        raise ValueError("'inputs' must have unique column names.")
+    return X
+
+
+def _as_series(values, name=None) -> pd.Series:
+    if isinstance(values, pd.Series):
+        s = values.reset_index(drop=True).copy()
+    else:
+        s = pd.Series(values).reset_index(drop=True)
+    if name is not None and s.name is None:
+        s.name = name
+    return s
+
+
+def _is_categorical(series: pd.Series) -> bool:
+    """Identify natural categorical partitions.
+
+    Object, string, boolean, pandas categorical, and binary variables are
+    treated as categorical. Numeric variables with more than two levels are
+    treated as continuous unless explicitly stored with pandas ``category``
+    dtype. This avoids silently interpreting low-cardinality integer-valued
+    continuous variables as categories.
+    """
+    non_missing = series.dropna()
+    n_unique = non_missing.nunique()
+    return (
+        isinstance(series.dtype, pd.CategoricalDtype)
+        or pd.api.types.is_object_dtype(series)
+        or pd.api.types.is_string_dtype(series)
+        or pd.api.types.is_bool_dtype(series)
+        or n_unique <= 2
+    )
+
+
+def _make_regions(
+    z: pd.Series,
+    n_regions: int,
+    name: str,
+) -> tuple[pd.Series, bool]:
+    categorical = _is_categorical(z)
+
+    if categorical:
+        regions = z.astype("category").cat.remove_unused_categories()
+    else:
+        try:
+            regions = pd.qcut(z, q=n_regions, duplicates="drop")
+        except ValueError as exc:
+            raise ValueError(
+                f"Failed to divide '{name}' into {n_regions} equal-frequency "
+                f"regions: {exc}"
+            ) from exc
+
+    if not hasattr(regions, "cat") or len(regions.cat.categories) < 2:
+        raise ValueError(
+            f"At least two regions are required to compute heterogeneity for "
+            f"'{name}'."
+        )
+
+    return regions, categorical
+
+
+def _safe_output_variance(y: pd.Series) -> float | None:
+    try:
+        values = pd.to_numeric(y, errors="raise").to_numpy(dtype=float)
+    except (TypeError, ValueError):
+        return None
+    if len(values) < 2:
+        return 0.0
+    return float(np.var(values, ddof=1))
+
+
+def _mean_pairwise_tv(
+    normalized_profiles: pd.DataFrame,
+) -> tuple[float, pd.Series]:
+    """Mean pairwise total-variation distance and input contributions."""
+    profiles = normalized_profiles.to_numpy(dtype=float)
+    n_regions, n_inputs = profiles.shape
+
+    if n_regions < 2:
+        raise ValueError("At least two normalized regional profiles are required.")
+
+    contribution_sum = np.zeros(n_inputs, dtype=float)
+    n_pairs = 0
+
+    for r in range(n_regions - 1):
+        for s in range(r + 1, n_regions):
+            contribution_sum += 0.5 * np.abs(profiles[r] - profiles[s])
+            n_pairs += 1
+
+    contributions = contribution_sum / n_pairs
+    H = float(contributions.sum())
+
+    # For nonnegative compositional profiles, H is theoretically in [0, 1].
+    if np.nanmin(profiles) >= -1e-12:
+        H = float(np.clip(H, 0.0, 1.0))
+
+    return H, pd.Series(
+        contributions,
+        index=normalized_profiles.columns,
+        dtype=float,
+        name="C_i",
+    )
+
+
+def _compute_partition(
+    *,
+    y: pd.Series,
+    X: pd.DataFrame,
+    z: pd.Series,
+    partition_name,
+    n_regions: int,
+    remove_partition_input: bool,
+) -> tuple[float, HeterogeneityDetail]:
+    regions, partition_is_categorical = _make_regions(
+        z,
+        n_regions=n_regions,
+        name=str(partition_name),
+    )
+
+    X_profile = X
+    if remove_partition_input and partition_is_categorical:
+        X_profile = X.drop(columns=[partition_name])
+        if X_profile.shape[1] == 0:
+            raise ValueError(
+                f"Cannot compute H for categorical input '{partition_name}' "
+                "because no other inputs remain in the regional sensitivity "
+                "profile."
+            )
+
+    profile_rows = []
+    counts = {}
+
+    # Every intended region must be admissible. H is not computed on a silently
+    # reduced subset of the requested partition.
+    for region in regions.cat.categories:
+        mask = regions == region
+        n_in_region = int(mask.sum())
+        counts[region] = n_in_region
+
+        if n_in_region < _MIN_REGION_SIZE:
+            raise ValueError(
+                f"Region {region!r} of '{partition_name}' contains only "
+                f"{n_in_region} observations; at least {_MIN_REGION_SIZE} are "
+                "required for regional sensitivity analysis."
+            )
+
+        X_sub = X_profile.loc[mask]
+        y_sub = y.loc[mask]
+
+        variance = _safe_output_variance(y_sub)
+        if variance is not None and variance < 1e-12:
+            raise ValueError(
+                f"The output is constant, or approximately constant, in region "
+                f"{region!r} of '{partition_name}'. Regional variance-based "
+                "sensitivity indices and H are therefore undefined for this "
+                "partition."
+            )
+
+        try:
+            result = simdec.sensitivity_indices(inputs=X_sub, output=y_sub)
+            si_values = np.asarray(result.si, dtype=float).ravel()
+        except Exception as exc:
+            raise ValueError(
+                f"Regional sensitivity calculation failed in region {region!r} "
+                f"of '{partition_name}': {exc}"
+            ) from exc
+
+        if len(si_values) != X_profile.shape[1]:
+            raise ValueError(
+                f"Sensitivity calculation for region {region!r} of "
+                f"'{partition_name}' returned {len(si_values)} indices for "
+                f"{X_profile.shape[1]} inputs."
+            )
+
+        if not np.all(np.isfinite(si_values)):
+            raise ValueError(
+                f"Non-finite sensitivity indices were returned for region "
+                f"{region!r} of '{partition_name}'."
+            )
+
+        # Remove numerical dust only. Material negative estimates are preserved
+        # and flagged below rather than silently altered.
+        si_values[np.abs(si_values) < 1e-12] = 0.0
+
+        profile_rows.append(
+            pd.Series(si_values, index=X_profile.columns, name=region, dtype=float)
+        )
+
+    raw = pd.DataFrame(profile_rows)
+    raw.index.name = "region"
+
+    regional_sums = raw.sum(axis=1)
+    regional_sums.name = "sum_S_i"
+
+    bad_sums = (~np.isfinite(regional_sums)) | (np.abs(regional_sums) < 1e-12)
+    if bad_sums.any():
+        bad_regions = list(regional_sums.index[bad_sums])
+        raise ValueError(
+            f"Regional sensitivity profiles for '{partition_name}' cannot be "
+            "normalized because their sensitivity-index sum is zero or "
+            f"non-finite in region(s) {bad_regions}."
+        )
+
+    normalized = raw.div(regional_sums, axis=0)
+
+    if (normalized.to_numpy(dtype=float) < -1e-12).any():
+        warnings.warn(
+            f"Negative combined sensitivity indices were found in regional "
+            f"profiles for '{partition_name}'. H is still calculated from the "
+            "normalized profiles, but the strict [0, 1] total-variation "
+            "interpretation assumes nonnegative sensitivity compositions.",
+            RuntimeWarning,
+            stacklevel=3,
+        )
+
+    H, contributions = _mean_pairwise_tv(normalized)
+
+    region_counts = pd.Series(counts, dtype=int, name="n")
+    region_counts.index.name = "region"
+
+    detail = HeterogeneityDetail(
+        raw_profiles=raw,
+        normalized_profiles=normalized,
+        regional_sums=regional_sums,
+        region_counts=region_counts,
+        individual_contributions=contributions,
+    )
+    return H, detail
+
+
+def heterogeneity_indices(
+    output,
+    inputs,
+    n_regions: int = _DEFAULT_N_REGIONS,
+    custom_partition=None,
+) -> HeterogeneityResult:
+    """Calculate heterogeneity in regional sensitivity profiles.
+
+    The heterogeneity index H measures how much the relative sensitivity
+    profile of a model changes across regions. H is calculated as the mean
+    pairwise total-variation distance between normalized regional combined
+    sensitivity profiles.
+
+    With no ``custom_partition``, the function performs a full standard scan:
+    H_Y is calculated across regions of the output and H_Xi across regions of
+    every input. Continuous partitioning variables are divided into
+    ``n_regions`` equal-frequency regions; categorical variables use their
+    observed categories.
+
+    If ``custom_partition`` is supplied, only H_Z for that partition is
+    calculated. A continuous custom partition is divided into ``n_regions``
+    equal-frequency regions. A categorical custom partition uses its natural
+    categories, in which case ``n_regions`` is ignored.
+
+    Parameters
+    ----------
+    output : pandas.Series or array-like
+        Model output vector.
+    inputs : pandas.DataFrame or array-like
+        Model input matrix. DataFrame column names are used as input names.
+    n_regions : int, default 5
+        Number of equal-frequency regions used for continuous partitioning
+        variables.
+    custom_partition : pandas.Series or array-like, optional
+        User-defined partitioning variable Z. When provided, only H_Z is
+        calculated. The partition is used only to assign observations to
+        regions and is not added to the model inputs.
+
+    Returns
+    -------
+    HeterogeneityResult
+        ``H.indices`` contains the calculated heterogeneity indices.
+        ``H.details`` contains raw and normalized regional profiles, regional
+        sensitivity-index sums, observation counts, and input-level
+        contributions for every calculated partition.
+
+    Notes
+    -----
+    For a categorical input X_i, X_i is removed from its own regional
+    sensitivity profiles because it is constant within each category.
+
+    H_Y is not calculated for a categorical output. Partitioning a categorical
+    output by its categories makes the output constant within every region, so
+    regional variance-based sensitivity indices are undefined. H_Xi is still
+    calculated for all inputs for which the regional analysis is admissible.
+
+    Multi-level numeric categorical variables should use pandas ``category``
+    dtype. Binary numeric variables are recognized as categorical
+    automatically.
+    """
+    if not isinstance(n_regions, (int, np.integer)) or n_regions < 2:
+        raise ValueError("'n_regions' must be an integer greater than or equal to 2.")
+
+    y = _as_series(output, name="Y")
+    X = _as_dataframe(inputs)
+
+    if len(y) != len(X):
+        raise ValueError(
+            "'output' and 'inputs' must contain the same number of observations "
+            f"({len(y)} != {len(X)})."
+        )
+
+    input_order = tuple(X.columns)
+    indices = {}
+    details = {}
+
+    # ------------------------------------------------------------
+    # Custom partition: calculate only H_Z.
+    # ------------------------------------------------------------
+    if custom_partition is not None:
+        z = _as_series(custom_partition)
+        if len(z) != len(y):
+            raise ValueError(
+                "'custom_partition' must contain the same number of observations "
+                "as output and inputs."
+            )
+
+        partition_name = z.name if z.name is not None else "Z"
+        custom_is_categorical = _is_categorical(z)
+
+        if custom_is_categorical and n_regions != _DEFAULT_N_REGIONS:
+            warnings.warn(
+                "'n_regions' is ignored because 'custom_partition' is "
+                "categorical. Its observed categories are used as regions.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+        H_value, detail = _compute_partition(
+            y=y,
+            X=X,
+            z=z,
+            partition_name=partition_name,
+            n_regions=n_regions,
+            remove_partition_input=False,
+        )
+        indices[partition_name] = H_value
+        details[partition_name] = detail
+
+        return HeterogeneityResult(
+            indices=pd.Series(indices, dtype=float, name="H").rename_axis("partition"),
+            details=details,
+            _input_order=input_order,
+        )
+
+    # ------------------------------------------------------------
+    # Standard scan: H_Y and H_Xi for all inputs.
+    # ------------------------------------------------------------
+    if _is_categorical(y):
+        warnings.warn(
+            "H_Y was not calculated because the output is categorical. "
+            "Partitioning a categorical output by its own categories makes "
+            "the output constant within each region, so regional variance-based "
+            "sensitivity indices are undefined. H_Xi will still be calculated "
+            "for all inputs where the output varies within the resulting "
+            "regions.",
+            UserWarning,
+            stacklevel=2,
+        )
+    else:
+        try:
+            H_y, detail_y = _compute_partition(
+                y=y,
+                X=X,
+                z=y,
+                partition_name="Y",
+                n_regions=n_regions,
+                remove_partition_input=False,
+            )
+            indices["Y"] = H_y
+            details["Y"] = detail_y
+        except ValueError as exc:
+            warnings.warn(
+                f"H_Y could not be calculated: {exc}",
+                UserWarning,
+                stacklevel=2,
+            )
+            indices["Y"] = np.nan
+
+    for input_name in X.columns:
+        try:
+            H_x, detail_x = _compute_partition(
+                y=y,
+                X=X,
+                z=X[input_name],
+                partition_name=input_name,
+                n_regions=n_regions,
+                remove_partition_input=True,
+            )
+            indices[input_name] = H_x
+            details[input_name] = detail_x
+        except ValueError as exc:
+            warnings.warn(
+                f"H for input '{input_name}' could not be calculated: {exc}",
+                UserWarning,
+                stacklevel=2,
+            )
+            indices[input_name] = np.nan
+
+    return HeterogeneityResult(
+        indices=pd.Series(indices, dtype=float, name="H").rename_axis("partition"),
+        details=details,
+        _input_order=input_order,
+    )
+
+
+def _format_region_label(region) -> str:
+    if isinstance(region, pd.Interval):
+        left = f"{region.left:.3g}"
+        right = f"{region.right:.3g}"
+        return f"{left}-{right}"
+    if isinstance(region, (float, np.floating)):
+        return f"{region:.3g}"
+    return str(region)
+
+
+def _plot_heterogeneity(
+    result: HeterogeneityResult,
+    partition=None,
+    ax=None,
+):
+    available = list(result.details)
+    if not available:
+        raise ValueError("The result contains no regional profiles to plot.")
+
+    if partition is None:
+        names = available
+    elif isinstance(partition, str) or not hasattr(partition, "__iter__"):
+        names = [partition]
+    else:
+        names = list(partition)
+
+    missing = [name for name in names if name not in result.details]
+    if missing:
+        raise KeyError(
+            f"Partition(s) {missing} are not available. Choose from {available}."
+        )
+
+    if ax is not None and len(names) != 1:
+        raise ValueError("'ax' can only be supplied when plotting one partition.")
+
+    input_order = list(result._input_order)
+    cmap = plt.colormaps["terrain"]
+    colors = {
+        name: cmap(pos)
+        for name, pos in zip(
+            input_order,
+            np.linspace(0.05, 0.95, max(len(input_order), 1)),
+        )
+    }
+
+    if len(names) == 1:
+        if ax is None:
+            _, ax = plt.subplots(figsize=(7.0, 4.8))
+        axes = np.array([ax], dtype=object)
+    else:
+        ncols = min(3, len(names))
+        nrows = math.ceil(len(names) / ncols)
+        _, grid = plt.subplots(
+            nrows,
+            ncols,
+            figsize=(5.2 * ncols, 4.2 * nrows),
+            squeeze=False,
+        )
+        axes = grid.ravel()
+
+    used_inputs = []
+
+    for axis, name in zip(axes, names):
+        detail = result.details[name]
+        raw = detail.raw_profiles
+        order = [item for item in input_order if item in raw.columns]
+        order += [item for item in raw.columns if item not in order]
+        data = raw.loc[:, order]
+        used_inputs.extend(item for item in order if item not in used_inputs)
+
+        data.plot(
+            kind="bar",
+            stacked=True,
+            ax=axis,
+            color=[colors.get(item, cmap(0.5)) for item in order],
+            edgecolor="white",
+            linewidth=0.4,
+            width=0.82,
+            legend=False,
+        )
+
+        H_value = result.indices.loc[name]
+        axis.set_title(f"{name}: H = {H_value:.3f}")
+        axis.set_ylabel(r"Combined sensitivity index, $S_i$")
+        axis.set_xlabel("Region")
+        axis.set_xticklabels(
+            [_format_region_label(region) for region in raw.index],
+            rotation=45,
+            ha="right",
+        )
+        axis.grid(axis="y", linestyle=":", alpha=0.30)
+        axis.set_axisbelow(True)
+
+    for axis in axes[len(names) :]:
+        axis.remove()
+
+    handles = [
+        plt.Rectangle(
+            (0, 0),
+            1,
+            1,
+            facecolor=colors.get(name, cmap(0.5)),
+            edgecolor="white",
+            label=str(name),
+        )
+        for name in used_inputs
+    ]
+
+    if len(names) == 1:
+        if handles:
+            axes[0].legend(
+                handles=handles,
+                title="Inputs",
+                bbox_to_anchor=(1.02, 1),
+                loc="upper left",
+            )
+        axes[0].figure.tight_layout()
+        return axes[0]
+
+    if handles:
+        axes[0].figure.legend(
+            handles=handles,
+            title="Inputs",
+            loc="lower center",
+            bbox_to_anchor=(0.5, 0.01),
+            ncol=min(5, len(handles)),
+            frameon=False,
+        )
+    axes[0].figure.subplots_adjust(bottom=0.16, hspace=0.48, wspace=0.28)
+    return axes

{simdec-1.5.1 → simdec-1.5.2}/src/simdec/sensitivity_indices.py

@@ -1,12 +1,53 @@
 from dataclasses import dataclass
+import warnings
 
 import numpy as np
 import pandas as pd
 from scipy import stats
 
-
 __all__ = ["sensitivity_indices"]
 
+try:
+    from IPython.display import display
+
+    HAS_IPYTHON = True
+except ImportError:
+    HAS_IPYTHON = False
+
+
+def _quantile_edges(x: np.ndarray, n_bins: int) -> np.ndarray:
+    """Bin edges holding approximately the same number of points.
+
+    Bins are defined by value, so identical values always fall in the same
+    bin. Duplicated edges are dropped: a factor with many ties gets fewer
+    than ``n_bins`` bins, and a constant factor gets a single one.
+
+    Discrete variables (few unique values relative to n_bins) get one bin
+    per unique value instead of quantile-based edges, to avoid collapsing
+    minority categories into a majority bin.
+    """
+    unique_vals = np.unique(x[~np.isnan(x)])
+    if len(unique_vals) <= n_bins:
+        # midpoints between consecutive unique values, so each value gets
+        # its own bin
+        if unique_vals.size == 1:
+            return np.array([unique_vals[0], np.nextafter(unique_vals[0], np.inf)])
+        midpoints = (unique_vals[:-1] + unique_vals[1:]) / 2
+        return np.concatenate([[unique_vals[0]], midpoints, [unique_vals[-1]]])
+
+    edges = np.unique(np.nanquantile(x, np.linspace(0, 1, n_bins + 1)))
+    if edges.size < 2:
+        edges = np.array([edges[0], np.nextafter(edges[0], np.inf)])
+    return edges
+
+
+def _conditional_var(sample: np.ndarray, y: np.ndarray, edges: list) -> float:
+    """Var(E[Y | bins]), each bin weighted by its number of points."""
+    mean, *_ = stats.binned_statistic_dd(sample, y, statistic="mean", bins=edges)
+    count, *_ = stats.binned_statistic_dd(sample, y, statistic="count", bins=edges)
+    valid = count > 0
+    return _weighted_var(mean[valid], weights=count[valid])
+
 
 def number_of_bins(n_runs: int, n_factors: int) -> tuple[int, int]:
     """Optimal number of bins for first & second-order sensitivity_indices indices.
@@ -37,7 +78,9 @@ class SensitivityAnalysisResult:
 
 
 def sensitivity_indices(
-    inputs: pd.DataFrame | np.ndarray, output: pd.DataFrame | np.ndarray
+    inputs: pd.DataFrame | np.ndarray,
+    output: pd.DataFrame | np.ndarray,
+    print_indices: bool = False,
 ) -> SensitivityAnalysisResult:
     """Sensitivity indices.
 
@@ -50,6 +93,8 @@ def sensitivity_indices(
         Input variables.
     output : ndarray or DataFrame of shape (n_runs, 1)
         Target variable.
+    print_indices : bool, default False
+        If True, displays computed indices.
 
     Returns
     -------
@@ -97,11 +142,18 @@ def sensitivity_indices(
     """
     # Handle inputs conversion
     if isinstance(inputs, pd.DataFrame):
-        cat_columns = inputs.select_dtypes(["category", "O"]).columns
-        inputs[cat_columns] = inputs[cat_columns].apply(
-            lambda x: x.astype("category").cat.codes
-        )
+        var_names = inputs.columns.tolist()
+        cat_cols = inputs.select_dtypes(include=["category", "O", "string"]).columns
+        if not cat_cols.empty:
+            inputs = inputs.copy()  # Avoid SettingWithCopyWarning
+            inputs[cat_cols] = inputs[cat_cols].apply(
+                lambda x: x.astype("category").cat.codes
+            )
         inputs = inputs.to_numpy()
+    else:
+        inputs = np.asarray(inputs)
+        # Fallback names if it's just a numpy array
+        var_names = [f"x{i}" for i in range(inputs.shape[1])]
 
     # Handle output conversion first, then flatten
     if isinstance(output, (pd.DataFrame, pd.Series)):
@@ -120,60 +172,33 @@ def sensitivity_indices(
     foe = np.empty(n_factors)
     soe = np.zeros((n_factors, n_factors))
 
+    edges_foe = [
+        _quantile_edges(inputs[:, k], int(n_bins_foe)) for k in range(n_factors)
+    ]
+    edges_soe = [
+        _quantile_edges(inputs[:, k], int(n_bins_soe)) for k in range(n_factors)
+    ]
+
+    # Marginal Var(E[Y|Xk]) on the SOE binning, identical for every pair
+    var_marginal = np.array(
+        [
+            _conditional_var(inputs[:, [k]], output, [edges_soe[k]])
+            for k in range(n_factors)
+        ]
+    )
+
     for i in range(n_factors):
         # 1. First-order effects (FOE)
-        xi = inputs[:, i]
+        foe[i] = _conditional_var(inputs[:, [i]], output, [edges_foe[i]]) / var_y
 
-        bin_avg, _, binnumber = stats.binned_statistic(
-            x=xi, values=output, bins=n_bins_foe, statistic="mean"
-        )
-
-        # Filter empty bins and get weights (counts)
-        mask_foe = ~np.isnan(bin_avg)
-        mean_i_foe = bin_avg[mask_foe]
-        # binnumber starts at 1; 0 is for values outside range
-        bin_counts_foe = np.unique(binnumber[binnumber > 0], return_counts=True)[1]
-
-        foe[i] = _weighted_var(mean_i_foe, weights=bin_counts_foe) / var_y
-
-        # 2. Second-order effects (SOE)
         for j in range(n_factors):
             if j <= i:
                 continue
 
-            xj = inputs[:, j]
-
-            # 2D Binned Statistic for Var(E[Y|Xi, Xj])
-            bin_avg_ij, x_edges, y_edges, binnumber_ij = stats.binned_statistic_2d(
-                x=xi, y=xj, values=output, bins=n_bins_soe, expand_binnumbers=False
-            )
-
-            mask_ij = ~np.isnan(bin_avg_ij)
-            mean_ij = bin_avg_ij[mask_ij]
-            counts_ij = np.unique(binnumber_ij[binnumber_ij > 0], return_counts=True)[1]
-            var_ij = _weighted_var(mean_ij, weights=counts_ij)
-
-            # Marginal Var(E[Y|Xi]) using n_bins_soe to match MATLAB logic
-            bin_avg_i_soe, _, binnumber_i_soe = stats.binned_statistic(
-                x=xi, values=output, bins=n_bins_soe, statistic="mean"
-            )
-            mask_i = ~np.isnan(bin_avg_i_soe)
-            counts_i = np.unique(
-                binnumber_i_soe[binnumber_i_soe > 0], return_counts=True
-            )[1]
-            var_i_soe = _weighted_var(bin_avg_i_soe[mask_i], weights=counts_i)
-
-            # Marginal Var(E[Y|Xj]) using n_bins_soe to match MATLAB logic
-            bin_avg_j_soe, _, binnumber_j_soe = stats.binned_statistic(
-                x=xj, values=output, bins=n_bins_soe, statistic="mean"
+            var_ij = _conditional_var(
+                inputs[:, [i, j]], output, [edges_soe[i], edges_soe[j]]
             )
-            mask_j = ~np.isnan(bin_avg_j_soe)
-            counts_j = np.unique(
-                binnumber_j_soe[binnumber_j_soe > 0], return_counts=True
-            )[1]
-            var_j_soe = _weighted_var(bin_avg_j_soe[mask_j], weights=counts_j)
-
-            soe[i, j] = (var_ij - var_i_soe - var_j_soe) / var_y
+            soe[i, j] = (var_ij - var_marginal[i] - var_marginal[j]) / var_y
 
     # Mirror SOE and calculate Combined Effect (SI)
     # SI is FOE + half of all interactions associated with that variable
@@ -181,4 +206,19 @@ def sensitivity_indices(
     for k in range(n_factors):
         si[k] = foe[k] + (soe[:, k].sum() / 2)
 
+    if print_indices:
+        if not HAS_IPYTHON:
+            warnings.warn(
+                "print_indices=True requires ipython to be installed. "
+                "Install it with: pip install simdec[display]. Table skipped.",
+                stacklevel=2,
+            )
+        else:
+            df_foe = pd.DataFrame(foe, index=var_names, columns=["First-order effect"])
+            df_soe = pd.DataFrame(soe, index=var_names, columns=var_names)
+            df_si = pd.DataFrame(si, index=var_names, columns=["Combined effect"])
+
+            df_indices = pd.concat([df_foe, df_soe, df_si], axis=1)
+            display(df_indices)
+
     return SensitivityAnalysisResult(si, foe, soe)

{simdec-1.5.1 → simdec-1.5.2}/src/simdec/visualization.py

@@ -10,9 +10,18 @@ import numpy as np
 import seaborn as sns
 import pandas as pd
 from pandas.io.formats.style import Styler
+import warnings
 
-__all__ = ["visualization", "tableau", "palette"]
+from simdec.decomposition import DecompositionResult
 
+__all__ = ["visualization", "two_output_visualization", "tableau", "palette"]
+
+try:
+    from IPython.display import display
+
+    HAS_IPYTHON = True
+except ImportError:
+    HAS_IPYTHON = False
 
 SEQUENTIAL_PALETTES = [
     "#DC267F",
@@ -127,7 +136,8 @@ def palette(
     n_shades = int(np.prod(states[1:]))
     for i in range(n_cmaps):
         cmap = cmaps[i].resampled(n_shades)
-        colors.append(cmap(np.linspace(0, 1, n_shades)))
+        # colors.append(cmap(np.linspace(0, 1, n_shades)))
+        colors.append(cmap(np.linspace(1, 0, n_shades)))
 
     return np.concatenate(colors).tolist()
 
@@ -139,6 +149,8 @@ def visualization(
     n_bins: str | int = "auto",
     kind: Literal["histogram", "boxplot"] = "histogram",
     ax=None,
+    print_legend: bool = False,
+    decomposition: DecompositionResult | None = None,
 ) -> plt.Axes:
     """Histogram plot of scenarios.
 
@@ -154,6 +166,10 @@ def visualization(
         Histogram or Box Plot.
     ax : Axes, optional
         Matplotlib axis.
+    print_legend: Boolean, optional
+        Prints plot legend.
+    decomposition: DecompositionResult, optional
+        Required for print_legend.
 
     Returns
     -------
@@ -186,9 +202,174 @@ def visualization(
         )
     else:
         raise ValueError("'kind' can only be 'histogram' or 'boxplot'")
+
+    if print_legend:
+        if not HAS_IPYTHON or decomposition is None:
+            missing_requirements = []
+            if not HAS_IPYTHON:
+                missing_requirements.append(
+                    "ipython needs to be installed. "
+                    "Install it with: pip install simdec[display]"
+                )
+            if decomposition is None:
+                missing_requirements.append("the decomposition parameter")
+            warnings.warn(
+                f"print_legend=True requires {' and '.join(missing_requirements)}. Table skipped.",
+                stacklevel=2,
+            )
+        else:
+            _, styler = tableau(
+                var_names=decomposition.var_names,
+                statistic=decomposition.statistic,
+                states=decomposition.states,
+                bins=decomposition.bins,
+                palette=palette,
+            )
+            display(styler)
+
     return ax
 
 
+def two_output_visualization(
+    *,
+    bins: pd.DataFrame,
+    bins2: pd.DataFrame,
+    palette: list[list[float]],
+    n_bins: str | int = "auto",
+    output_name: str = "Output 1",
+    output_name2: str = "Output 2",
+    xlim: tuple[float, float] | None = None,
+    ylim: tuple[float, float] | None = None,
+    r_scatter: float = 1.0,
+    print_legend: bool = False,
+    decomposition: DecompositionResult | None = None,
+) -> tuple[plt.Figure, np.ndarray]:
+    """Two-output visualization.
+
+    Produces a 2x2 figure
+    * top-left    : stacked histogram for *output 1* (axes hidden)
+    * bottom-left : scatter of output 1 vs output 2, coloured by scenario
+    * bottom-right: rotated stacked histogram for *output 2* (axes hidden)
+    * top-right   : empty
+
+    Parameters
+    ----------
+    bins : DataFrame
+        Multidimensional bins for the primary output.
+    bins2 : DataFrame
+        Multidimensional bins for the secondary output.
+    palette : list of int of size (n, 4)
+        List of colours corresponding to scenarios.
+    n_bins : str or int
+        Number of bins for the histograms.
+    output_name : str, default "Output 1"
+        Axis label for the primary output.
+    output_name2 : str, default "Output 2"
+        Axis label for the secondary output.
+    xlim : tuple of float, optional
+        Limits for the primary output axis (scatter x / top histogram).
+    ylim : tuple of float, optional
+        Limits for the secondary output axis (scatter y / right histogram).
+    r_scatter : float, default 1.0
+        Fraction of data points shown in the scatter plot.
+    print_legend: Boolean, optional
+        Prints plot legend.
+    decomposition: DecompositionResult, optional
+        Required for print_legend.
+
+    Returns
+    -------
+    fig : Figure
+    axs : ndarray of shape (2, 2)
+
+    """
+    fig, axs = plt.subplots(2, 2, sharex="col", sharey="row", figsize=(8, 8))
+
+    axs[0, 1].axis("off")
+
+    visualization(bins=bins.copy(), palette=palette, n_bins=n_bins, ax=axs[0, 0])
+    if xlim is not None:
+        axs[0, 0].set_xlim(xlim)
+    axs[0, 0].set_box_aspect(1)
+    axs[0, 0].axis("off")
+
+    # Match the ordering visualization() uses
+    bins_plot = bins.copy()
+    bins_plot.columns = pd.RangeIndex(start=len(bins_plot.columns), stop=0, step=-1)
+    bins2_plot = bins2.copy()
+    bins2_plot.columns = pd.RangeIndex(start=len(bins2_plot.columns), stop=0, step=-1)
+
+    data = pd.concat([pd.melt(bins_plot), pd.melt(bins2_plot)["value"]], axis=1)
+    data.columns = ["c", "x", "y"]
+    if r_scatter < 1.0:
+        data = data.sample(frac=r_scatter)
+
+    hue_order = sorted(data["c"].unique())
+    sns.scatterplot(
+        data=data,
+        x="x",
+        y="y",
+        hue="c",
+        hue_order=hue_order,
+        palette=palette,
+        ax=axs[1, 0],
+        legend=False,
+    )
+    axs[1, 0].set(xlabel=output_name, ylabel=output_name2)
+    if xlim is not None:
+        axs[1, 0].set_xlim(xlim)
+    if ylim is not None:
+        axs[1, 0].set_ylim(ylim)
+    axs[1, 0].set_box_aspect(1)
+
+    sns.histplot(
+        data,
+        y="y",
+        hue="c",
+        hue_order=hue_order,
+        multiple="stack",
+        stat="probability",
+        palette=palette,
+        common_bins=True,
+        common_norm=True,
+        bins=40,
+        legend=False,
+        ax=axs[1, 1],
+    )
+    if ylim is not None:
+        axs[1, 1].set_ylim(ylim)
+    axs[1, 1].set_box_aspect(1)
+    axs[1, 1].axis("off")
+
+    fig.subplots_adjust(wspace=-0.015, hspace=0)
+
+    if print_legend:
+        if not HAS_IPYTHON or decomposition is None:
+            missing_requirements = []
+            if not HAS_IPYTHON:
+                missing_requirements.append(
+                    "ipython needs to be installed. "
+                    "Install it with: pip install simdec[display]"
+                )
+            if decomposition is None:
+                missing_requirements.append("the decomposition parameter")
+            warnings.warn(
+                f"print_legend=True requires {' and '.join(missing_requirements)}. Table skipped.",
+                stacklevel=2,
+            )
+        else:
+            _, styler = tableau(
+                var_names=decomposition.var_names,
+                statistic=decomposition.statistic,
+                states=decomposition.states,
+                bins=decomposition.bins,
+                palette=palette[::-1],
+            )
+            display(styler)
+
+    return fig, axs
+
+
 def tableau(
     *,
     var_names: list[str],