% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/svem_select_score_from_table.R
\name{svem_select_from_score_table}
\alias{svem_select_from_score_table}
\title{Select best row and diverse candidates from an SVEM score table}
\usage{
svem_select_from_score_table(
  score_table,
  target = "score",
  direction = c("max", "min"),
  k = 5,
  top_type = c("frac", "n"),
  top = 0.1,
  predictor_cols = NULL,
  label = NULL
)
}
\arguments{
\item{score_table}{Data frame with predictors, responses, scores, and
\code{uncertainty_measure}, typically \code{scored$score_table} from
\code{\link{svem_score_random}}. When medoids are requested
(\code{k > 0}), the predictor columns used for clustering are taken
from the \code{"svem_predictor_cols"} attribute by default. If that
attribute is missing, a heuristic is used. If you accidentally pass the
full \code{scored} list, a helpful error is thrown reminding you to use
\code{scored$score_table}.}

\item{target}{Character scalar naming the column in \code{score_table}
to optimize (e.g. \code{"score"}, \code{"wmt_score"},
\code{"uncertainty_measure"}, or a response-specific column such as
\code{"Y_pred"}). The robust bounded columns created by
\code{\link{svem_score_random}} may contain ties at 0 or 1 because of
percentile clipping. For a single largest predicted response, use
\code{<response>_pred}; for a single widest interval, create a raw width
column such as \code{<response>_ciw = <response>_upr - <response>_lwr} and
use that as \code{target}.}

\item{direction}{Either \code{"max"} or \code{"min"} indicating whether
larger or smaller values of \code{target} are preferred.}

\item{k}{Integer; desired number of medoid candidates to return. If
\code{k <= 0}, only the \code{best} row is returned and no clustering
is performed.}

\item{top_type}{Either \code{"frac"} or \code{"n"} specifying whether
\code{top} is a fraction of rows or an integer count.}

\item{top}{Value for the top set: a fraction in (0,1] if
\code{top_type = "frac"}, or an integer \code{>= 1} if
\code{top_type = "n"}.}

\item{predictor_cols}{Optional character vector of predictor column names
used to measure diversity in the PAM step when \code{k > 0}. When
\code{NULL} (default), the function first tries
\code{attr(score_table, "svem_predictor_cols")}. If that is unavailable,
it falls back to a heuristic that prefers non-derived predictor columns
(excluding e.g. \code{*_pred}, \code{*_des}, \code{*_lwr}, \code{*_upr},
\code{*_ciw_w}, \code{*_p_in_spec_mean}, \code{*_in_spec_point},
\code{score}, \code{wmt_score}, \code{uncertainty_measure},
\code{p_joint_mean}, \code{joint_in_spec_point},
\code{candidate_type}, \code{selection_label}, \code{Notes_from_SVEMnet}).
If no usable predictor columns can be inferred, a warning is issued and only
\code{best} is returned.}

\item{label}{Optional character scalar. When non-\code{NULL}, this label
is appended into a \code{"Notes_from_SVEMnet"} column for the returned \code{best}
row and \code{candidates}. If \code{"Notes_from_SVEMnet"} is missing, it is created;
if present and nonempty, the label is appended using \code{"; "} as
separator.}
}
\value{
A list with components:
\describe{
\item{best}{One-row data frame at the optimum of \code{target}
under the specified \code{direction}, including any columns present
in \code{score_table} (e.g. \code{*_lwr} / \code{*_upr}).}
\item{candidates}{Data frame of medoid candidates (possibly
empty or \code{NULL}) drawn from the top \code{top} of the ranking
on \code{target}, with all columns carried through from
\code{score_table}.}
\item{label}{The \code{label} value supplied to this call (or
\code{NULL}); used by \code{\link{svem_export_candidates_csv}} for the
\code{selection_label} column.}
\item{call}{The matched call, including all arguments used to
create this selection object.}
}
}
\description{
Given a scored random-search table (e.g. from \code{svem_score_random()}),
pick a single "best" row under a chosen objective column and sample a
small, diverse set of medoid candidates from the top of that ranking.
Any per-response CI columns (e.g. \code{*_lwr} / \code{*_upr}) present in
\code{score_table} are carried through unchanged.

Optionally, a string \code{label} can be supplied to annotate the returned
\code{best} row and \code{candidates} by appending that label to a
\code{"Notes_from_SVEMnet"} column. If \code{"Notes_from_SVEMnet"} is missing, it is created. If it
exists and is nonempty, the label is appended with \code{"; "} as a
separator.
}
\details{
\code{svem_score_random()} returns both response prediction columns
(for example, \code{Y_pred}) and robust bounded summaries such as
\code{score}, per-response desirabilities, per-response weighted CI-width
summaries, and \code{uncertainty_measure}. The bounded summaries are useful
for defining high-desirability or high-uncertainty regions for medoid
selection, but they may not identify a unique single best row when several
rows are clipped to 1. In that case, select on a raw column such as
\code{Y_pred}, or add a raw CI-width column such as
\code{Y_ciw = Y_upr - Y_lwr}, before calling this function.
}
\seealso{
\code{\link{svem_score_random}},
\code{svem_select_candidates()}
}
