2.1 Mathematical definition

For a prediction \(\hat{f}(\mathbf{x})\) and background dataset \(\mathcal{D}\), the SHAP value for feature \(j\) and observation \(\mathbf{x}\) is defined as the weighted average of marginal contributions across all feature coalitions (Lundberg and Lee 2017):

\[ \phi_j(\hat{f}, \mathbf{x}) = \sum_{S \subseteq \mathcal{F} \setminus \{j\}} \frac{|S|!\,(|\mathcal{F}| - |S| - 1)!}{|\mathcal{F}|!} \left[\hat{f}_{S \cup \{j\}}(\mathbf{x}_{S \cup \{j\}}) - \hat{f}_{S}(\mathbf{x}_{S})\right] \]

where \(\mathcal{F}\) is the full set of features and \(S\) ranges over all subsets excluding feature \(j\).

2.2 Key properties

2.3 Computational implementation

xaiHydro uses a built-in permutation-based Monte Carlo SHAP estimator (Strumbelj and Kononenko, 2014) requiring no additional packages:

\[ \hat{\phi}_j = \frac{1}{B} \sum_{b=1}^{B} \left[\hat{f}(\mathbf{x}^{(b)}_{+j}) - \hat{f}(\mathbf{x}^{(b)}_{-j})\right] \]

where \(\mathbf{x}^{(b)}_{+j}\) and \(\mathbf{x}^{(b)}_{-j}\) are randomly constructed versions of \(\mathbf{x}\) with and without feature \(j\) replaced by background values.

# B = nsim Monte Carlo replicates
shap_vals <- hydro_shap(exp, nsim = 50, seed = 42)

Practical guidance for hydrology:

• Use nsim ≥ 50 for stable importance rankings in final figures.
• Background dataset should span the full observed range of predictors (all seasons, wet and dry years).
• For daily streamflow models with 8–15 predictors, nsim = 100 runs in approximately 2–3 minutes on a standard laptop.

3.1 Mathematical definition

LIME fits a locally weighted linear surrogate \(g \in G\) that approximates the complex model \(\hat{f}\) in the neighbourhood of observation \(\mathbf{x}'\) (Ribeiro et al. 2016):

\[ \xi(\mathbf{x}') = \arg\min_{g \in G} \mathcal{L}(\hat{f},\, g,\, \pi_{\mathbf{x}'}) + \Omega(g) \]

where \(\pi_{\mathbf{x}'}(\mathbf{z}) = \exp(-d(\mathbf{x}', \mathbf{z})^2 / \sigma^2)\) is an exponential kernel weighting neighbourhood samples by proximity, and \(\Omega(g)\) is a complexity penalty (LASSO for linear \(g\)).

3.2 Implementation

lime_result <- hydro_lime(
  explainer    = exp,
  new_obs      = X[storm_day, , drop = FALSE],
  n_features   = 6,       # number of features in local model
  kernel_width = 0.75     # σ — controls neighbourhood size
)

3.3 Selecting kernel_width

Note: Check local R² in the plot subtitle. An R² < 0.5 indicates the surrogate does not capture local model behaviour adequately; try increasing kernel_width or reducing n_features.

4.1 Mathematical definition

The partial dependence function for feature set \(S\) is (Friedman 2001):

\[ \hat{f}_S(\mathbf{x}_S) = \mathbb{E}_{\mathbf{x}_C}\left[\hat{f}(\mathbf{x}_S,\, \mathbf{x}_C)\right] = \int \hat{f}(\mathbf{x}_S,\, \mathbf{x}_C)\, d\mathbb{P}(\mathbf{x}_C) \]

estimated by averaging over the observed marginal distribution:

\[ \hat{f}_S(\mathbf{x}_S) \approx \frac{1}{n} \sum_{i=1}^{n} \hat{f}(\mathbf{x}_S,\, \mathbf{x}^{(i)}_C) \]

4.2 Limitation: correlated predictors

When features in \(S\) and \(C\) are correlated, the marginal average integrates over covariate combinations that never occur in practice (e.g., very high precipitation with very low soil moisture in monsoon hydrology). ALE avoids this.

5.1 Mathematical definition

ALE resolves the PDP extrapolation problem by integrating local conditional effects over observed data slices (Apley and Zhu 2020):

\[ \hat{f}^{\text{ALE}}(x_j) = \int_{x_{j,\min}}^{x_j} \mathbb{E}\left[ \frac{\partial \hat{f}(X)}{\partial X_j} \Big| X_j = z_j \right] dz_j - c \]

where \(c\) is a centering constant ensuring \(\mathbb{E}[\hat{f}^{\text{ALE}}] = 0\).

5.2 When to use ALE vs PDP

# ALE — recommended when predictors are correlated
ale <- hydro_pdp(exp, variable = c("precipitation", "soil_moisture"),
                 type = "accumulated")

# PDP — acceptable when predictors are approximately independent
pdp <- hydro_pdp(exp, variable = "ndvi",
                 type = "partial")

Decision rule: Compute the Pearson correlation matrix of your predictors. If any |r| > 0.5 between the target predictor and others, prefer ALE.

6.1 Definition

Permutation importance for feature \(j\) is (Breiman 2001):

\[ \text{VI}_j = \frac{1}{B} \sum_{b=1}^{B} \left[L\!\left(\hat{f}, \tilde{\mathbf{X}}^{(b)}_j\right) - L(\hat{f}, \mathbf{X})\right] \]

where \(\tilde{\mathbf{X}}^{(b)}_j\) is the dataset with feature \(j\) randomly permuted in the \(b\)-th repetition, and \(L\) is the loss function (RMSE by default).

imp <- hydro_importance(exp, loss_function = "rmse", B = 20)