% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/orthoMTL.R
\name{orthoMTL}
\alias{orthoMTL}
\title{Multi-task learning with orthogonal constraints}
\usage{
orthoMTL(
  X,
  Y,
  lambda = 1,
  step_size = 0.1,
  tol = 1e-05,
  stop_no_improve = 100,
  max_iter = 1e+06,
  W_0 = NULL,
  seed = NULL,
  K = NULL,
  disjoint = FALSE,
  logistic = FALSE,
  alpha = 0,
  schedule = c("sqrt", "log", "const", "linear"),
  survival = FALSE,
  censored.mat = NULL,
  verbose = 0
)
}
\arguments{
\item{X}{a matrix of predictor variables with dimensions n x p}

\item{Y}{a matrix of response variables with dimensions n x numTasks, where numTasks is the number of response variables. NAs can be used for censored data.}

\item{lambda}{the regularization parameter for the OrthoPen penalty, default is 1}

\item{step_size}{the step size for updating the regression coefficients in gradient descent, default is 0.1}

\item{tol}{Convergence tolerance. The algorithm stops when the
improvement in the objective function is less than \code{tol}.
Default: \code{1e-5}.}

\item{stop_no_improve}{the number of iterations without improvement in the objective function to trigger convergence, default is 100}

\item{max_iter}{the maximum number of iterations, default is 1e+06}

\item{W_0}{a matrix of initial values for the regression coefficients, default is NULL, as not provided and will be randomly attributed}

\item{seed}{an optional random seed for reproducibility, default is
\code{NULL} (no seed is set; the ambient RNG state is used as-is).
Only relevant when \code{W_0} is not provided and \code{disjoint = TRUE},
since that is the only case where \code{orthoMTL} draws random numbers.
Pass an integer to make that random initialisation reproducible.}

\item{K}{a constraint matrix of weights to adjust the OrthoPen penalty, default is an identity matrix with dimensions numTasks x numTasks}

\item{disjoint}{a logical value indicating whether the response variables should have disjoint supports, default is FALSE}

\item{logistic}{a logical value indicating whether logistic regression should be used instead of linear regression, default is FALSE}

\item{alpha}{the elastic-net mixing parameter in \eqn{[0, 1]}, default is 0.
The penalty is \eqn{\lambda [(1 - \alpha)/2\, \Omega_K(W)^2 + \alpha \|W\|_1]};
\code{alpha = 0} gives the pure orthogonality penalty and \code{alpha = 1}
gives a pure Lasso.}

\item{schedule}{Character; the gradient-step decay schedule -- how the
per-iteration scale grows with the iteration index \eqn{i}. The coefficient
update is \eqn{W \leftarrow W - \texttt{step\_size}\, \nabla /
(\texttt{scale} \cdot \|\nabla\|)}, so a faster-growing \code{scale} means a
faster-decaying effective step. One of:
\describe{
  \item{\code{"sqrt"}}{(default) \eqn{\texttt{scale} = \sqrt{i}}, effective
    step \eqn{\propto 1/\sqrt{i}} -- the classic subgradient schedule and
    the historical hardcoded behaviour.}
  \item{\code{"log"}}{\eqn{\texttt{scale} = \log(i) + 1} (slow decay).}
  \item{\code{"const"}}{\eqn{\texttt{scale} = 1} (no decay).}
  \item{\code{"linear"}}{\eqn{\texttt{scale} = i}, effective step
    \eqn{\propto 1/i} (Robbins-Monro).}
}
The default \code{"sqrt"} is retained for backward compatibility: it
reproduces previously published results exactly. An A/B study shipped with
the package (\code{validation/ab_s02_gradient_schedule.R}) found that
\code{"sqrt"} reaches the \emph{correct} optimum but converges to it roughly
12--17x slower than \code{"log"} and \code{"const"} (which reach the same
objective in a small fraction of the iterations), while \code{"linear"}
decays too aggressively and can stall short of the optimum. Prefer
\code{"log"} or \code{"const"} when convergence speed matters; note that
changing the schedule changes the optimisation path and therefore the exact
coefficients, so it should not be altered when reproducing published runs.}

\item{survival}{a logical value indicating whether survival analysis should be performed, default is FALSE}

\item{censored.mat}{a matrix indicating whether observations are censored, used only if survival=TRUE}

\item{verbose}{the level of verbosity, default is 0 (no messages)}
}
\value{
a list containing the following elements:
\item{B}{a matrix of regression coefficients with dimensions p x numTasks}
\item{obj}{the final objective function when algorithms stops}
\item{imax}{the number of iterations}
}
\description{
This function solves a multi-task problem where relationships between tasks can be complex
}
\examples{
# Regression with orthogonal columns
set.seed(42)
n <- 100; p <- 10; n_tasks <- 3
X <- matrix(rnorm(n * p), n, p)
W_true <- qr.Q(qr(matrix(rnorm(p * n_tasks), p, n_tasks)))
Y <- X \%*\% W_true + matrix(rnorm(n * n_tasks), n) * 0.1
K <- matrix(1, n_tasks, n_tasks)
diag(K) <- 0.5
fit <- orthoMTL(X, Y, lambda = 1e-3, K = K, disjoint = FALSE)
fit$B           # coefficient matrix
fit$converged   # did optimisation converge?

}
\references{
Kevin Vervier, Pierre Mahé, Alexandre d’Aspremont, Jean-Baptiste Veyrieras, Jean-Philippe Vert (2014). On learning matrices with orthogonal columns or disjoint supports. https://hal.science/hal-00985654/file/learningDisjointSupports.pdf
}
