% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cv_orthoMTL.R
\name{cv_orthoMTL}
\alias{cv_orthoMTL}
\title{Cross-Validation for orthoMTL Hyperparameter Selection}
\usage{
cv_orthoMTL(
  X.train,
  Y.train,
  W.train = NULL,
  K = NULL,
  lambdas = c(0.001, 0.01),
  alphas = 0,
  stepsizes = c(0.1, 0.5),
  diag_vals = c(0.5, 1),
  survival = TRUE,
  logistic = FALSE,
  metric = NULL,
  disjoint = FALSE,
  schedule = c("sqrt", "log", "const", "linear"),
  folds = NULL,
  n_cores = 2,
  seed = NULL,
  verbose = TRUE
)
}
\arguments{
\item{X.train}{A numeric matrix of training features with dimensions
\code{n x p}.}

\item{Y.train}{A numeric matrix of training labels with dimensions
\code{n x numTasks}. May contain \code{NA} for censored observations.}

\item{W.train}{A numeric indicator matrix of dimensions
\code{n x numTasks}, where \code{1} = observed and \code{0} = censored.
Required when \code{survival = TRUE}.}

\item{K}{A square constraint matrix of dimensions
\code{numTasks x numTasks}. The diagonal will be overridden by
values in \code{diag_vals} during the search.}

\item{lambdas}{A numeric vector of regularisation parameters to search.}

\item{alphas}{A numeric vector of elastic-net mixing parameters in
\eqn{[0, 1]} to search. Default: \code{0} (pure orthogonality
penalty, no sparsity).}

\item{stepsizes}{A numeric vector of gradient descent step sizes
to search.}

\item{diag_vals}{A numeric vector of diagonal values for the
constraint matrix \code{K} to search.}

\item{survival}{Logical. Use censored survival loss? Default:
\code{TRUE}.}

\item{logistic}{Logical. Fit logistic (classification) models?
Passed through to \code{\link{orthoMTL}}. Default: \code{FALSE}.}

\item{metric}{Character; the scoring metric maximised/minimised over
the grid, or \code{NULL} (default) to choose automatically by mode:
\code{"cindex"} when \code{survival = TRUE}, \code{"auc"} when
\code{logistic = TRUE}, otherwise \code{"rmse"}. Supported values:
\code{"cindex"}, \code{"auc"}, \code{"accuracy"} (higher is better),
\code{"rmse"} (lower is better), \code{"r2"} (higher is better).}

\item{disjoint}{Logical. Enforce disjoint supports? Default:
\code{FALSE}.}

\item{schedule}{Character; the gradient-step decay schedule passed to
\code{\link{orthoMTL}} for every fit. One of \code{"sqrt"} (default),
\code{"log"}, \code{"const"}, \code{"linear"}. \code{"log"} or
\code{"const"} typically reach the same optimum in far fewer iterations
than the default \code{"sqrt"}, which can noticeably speed up the grid
search; see the \code{schedule} argument of \code{\link{orthoMTL}} for the
trade-offs. Applied uniformly to all configurations (it is not part of the
tuning grid).}

\item{folds}{An integer vector of length \code{n} assigning each
training observation to a fold. If \code{NULL}, a 5-fold
assignment is generated with a warning.}

\item{n_cores}{Integer. Number of cores for parallel execution.
Default: \code{2}.}

\item{seed}{Optional integer random seed for reproducibility. Default:
\code{NULL} (no seed is set; the ambient RNG state is used as-is).
Used both for auto-generated fold assignment and for each
\code{\link{orthoMTL}} fit in the grid.}

\item{verbose}{Logical. Print progress information? Default:
\code{TRUE}.}
}
\value{
An object of class \code{"cv_orthoMTL"} containing:
  \describe{
    \item{best}{A list with the best hyperparameters: \code{lambda},
      \code{alpha}, \code{stepsize}, \code{diag_val}, and the
      corresponding \code{cv_score}.}
    \item{results}{A \code{data.frame} of all configurations with
      their mean CV C-index, sorted descending by \code{cv_score}.}
    \item{folds}{The fold assignment vector used.}
    \item{n_configs}{Total number of configurations tested.}
    \item{n_folds}{Number of unique folds.}
    \item{call}{The matched function call.}
  }
}
\description{
Performs a parallelised grid search over hyperparameters for
\code{\link{orthoMTL}}, evaluating each configuration via
cross-validated concordance index. Returns the best configuration
without retraining a final model (that is the caller's responsibility).
}
\details{
The grid is constructed as the full Cartesian product of
\code{lambdas}, \code{alphas}, \code{stepsizes}, and
\code{diag_vals}. Each configuration is evaluated independently
in parallel across cores. Within each configuration, folds are
evaluated sequentially and the per-fold C-indices are averaged.

The best configuration is selected by joint maximisation of the
mean CV C-index over the entire flattened grid (not greedy
sequential search).

This function does \emph{not} retrain a final model. Use the
returned hyperparameters to train via \code{\link{orthoMTL}}.
}
\examples{
\donttest{
set.seed(42)
n <- 50; p <- 5; n_tasks <- 3
X <- matrix(rnorm(n * p), n, p)
colnames(X) <- paste0("V", seq_len(p))
SurvTime <- rexp(n, rate = 0.1)
Event <- rbinom(n, 1, 0.7)
thresholds <- c(4, 6, 10)

Y <- create_longitudinal_labels(SurvTime, Event, thresholds)
W <- create_indicator_matrix(Y)
K <- create_constraint_matrix(n_tasks)

folds <- rep(1:2, length.out = n)

cv_res <- cv_orthoMTL(
  X.train = X, Y.train = Y, W.train = W, K = K,
  lambdas = c(1e-3, 1e-2), alphas = 0,
  stepsizes = c(0.1), diag_vals = c(0.5, 1),
  survival = TRUE, disjoint = FALSE,
  folds = folds, n_cores = 1, seed = 42, verbose = FALSE
)

print(cv_res)
cv_res$best
}
}
\seealso{
\code{\link{orthoMTL}}, \code{\link{cindex_mtl}}
}
