% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cross_validation.R
\name{rfok_cv_beta}
\alias{rfok_cv_beta}
\title{Cross-validate the rfok sensitivity parameter}
\usage{
rfok_cv_beta(
  X,
  y,
  beta = NULL,
  beta_mult = c(0, 1/100, 1/50, 1/30, 1/20, 1/10),
  k = 5,
  num_folds = 5,
  selection_rule = c("crps", "interval_score", "coverage_width"),
  conf = 0.95,
  samples = 1000,
  smoothing = TRUE,
  eps = 0,
  return_fit = FALSE,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{X}{a data frame, matrix, or vector of predictors. A vector is coerced
to a one-column matrix.}

\item{y}{a numeric response vector.}

\item{beta}{optional numeric vector of candidate beta values. If \code{NULL},
candidates are generated as \code{sd(y) * beta_mult}.}

\item{beta_mult}{numeric vector used to generate the beta grid when
\code{beta = NULL}.}

\item{k}{Number of nearest neighbors to use for out-of-bag error estimators.}

\item{num_folds}{Number of cross-validation folds.}

\item{selection_rule}{Criterion used to choose beta. Options are
\code{"crps"}, \code{"interval_score"}, and \code{"coverage_width"}.}

\item{conf}{Confidence level used for interval-based selection rules.}

\item{samples}{Number of conformal samples used when
\code{selection_rule = "crps"}.}

\item{smoothing}{logical; should conformity scores be sampled or smoothed
when generating conformal samples?}

\item{eps}{Tolerance for nearest neighbor search.}

\item{return_fit}{logical; if \code{TRUE}, refit \code{rfok()} on the full
data using the selected beta and include the fitted model in the result.}

\item{verbose}{logical. should progress be printed?}

\item{...}{additional parameters passed to \code{rfok()}.}
}
\value{
A data frame with one row per candidate beta. The selected beta is
  marked in the \code{selected} column. If \code{return_fit = TRUE}, a list is
  returned with elements \code{results}, \code{best_beta}, and \code{fit}.
}
\description{
Cross-validates the sensitivity parameter \code{beta} for an \code{rfok}
model over a user-supplied or automatically generated grid.
}
\details{
The parameter \code{beta} controls the sensitivity of the conformal interval
widths to the local out-of-bag residual scale estimate. Smaller values make
intervals more locally adaptive, while larger values make intervals more
stable and more similar to globally scaled conformal intervals.

This function evaluates candidate \code{beta} values using cross-validation.
For \code{selection_rule = "crps"}, predictive samples are generated for each
held-out observation and the candidate with the smallest average continuous
ranked probability score is selected.

For \code{selection_rule = "interval_score"}, conformal intervals are
constructed at level \code{conf} and the candidate with the smallest average
interval score is selected. The interval score rewards narrow intervals but
penalizes observations that fall outside the interval.

For \code{selection_rule = "coverage_width"}, the selected candidate is the
one with the smallest average interval width among candidates with empirical
coverage at least \code{conf}. If no candidate reaches the desired coverage,
the candidate with the largest empirical coverage is selected, with ties
broken by average interval width.
}
