% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/variable_importance.R
\name{permutation_importance}
\alias{permutation_importance}
\title{Permutation variable importance for suitability model}
\usage{
permutation_importance(
  predicted,
  records,
  presence_col = "presence",
  n_permutations = 50L,
  match_radius_deg = 0.002,
  seed = 42L,
  verbose = TRUE
)
}
\arguments{
\item{predicted}{Dataframe from \code{\link[=predict_oyster]{predict_oyster()}} with \code{lat}, \code{lon},
\code{suitability}, and per-variable score columns (e.g. \code{score_temperature},
\code{score_salinity}). The function uses the per-variable component scores
already computed by \code{\link[=predict_oyster]{predict_oyster()}}.}

\item{records}{Dataframe of presence/absence records (same format as
\code{\link[=validate_against_records]{validate_against_records()}}).}

\item{presence_col}{Character. Name of presence/absence column (default
\code{"presence"}).}

\item{n_permutations}{Integer. Number of permutation replicates per variable
(default 50). More = more stable importance estimates; >= 100 recommended
for publication.}

\item{match_radius_deg}{Numeric. Matching radius (default 0.002degrees).}

\item{seed}{Integer. Random seed (default 42).}

\item{verbose}{Logical. Default TRUE.}
}
\value{
A dataframe (sorted by importance, descending) with columns:
\itemize{
\item \code{variable}: scored variable name
\item \code{baseline_auc}: AUC of unperturbed model
\item \code{mean_permuted_auc}: mean AUC after permuting this variable
\item \code{importance}: baseline_auc - mean_permuted_auc (drop in AUC)
\item \code{importance_sd}: SD of AUC drop across permutation replicates
\item \code{importance_pct}: importance as percentage of baseline AUC
\item \code{rank}: rank by importance (1 = most important)
}
}
\description{
Estimates the importance of each scored environmental variable by randomly
permuting its values and measuring the resulting drop in AUC against known
presence/absence records. A large drop indicates the model strongly depends
on that variable; a small drop indicates it could be removed with minimal
impact.

This approach (Breiman 2001) is model-agnostic, requires no model refit,
and is directly interpretable: "how much does AUC fall if I destroy the
information in variable X?"
}
\section{Interpretation}{

\itemize{
\item importance > 0.10 (> 10\% AUC drop): high importance -- variable is load-
bearing for model discrimination.
\item importance 0.02--0.10: moderate importance.
\item importance < 0.02: low importance -- consider whether this variable adds
value relative to its data collection cost.
}
}

\examples{
\donttest{
records <- read.csv("nbn_ostrea_edulis.csv")
result  <- predict_oyster(survey, "ostrea_edulis")

imp <- permutation_importance(result, records, n_permutations = 100)
print(imp)
# Variable        Importance  Rank
# temperature     0.183       1
# salinity        0.091       2
# depth           0.045       3
# ...
}
}
\references{
Breiman (2001) Machine Learning 45:5-32.
Zurell et al. (2020) Ecography 43:1261-1277.
}
