\name{combss}
\alias{combss}
\title{Best subset selection for generalised linear models via continuous
optimisation (COMBSS).}
\usage{
combss(
  x,
  y,
  family = c("gaussian", "binomial", "multinomial"),
  q = NULL,
  x_val = NULL,
  y_val = NULL,
  lam_ridge = 0,
  Niter = 25,
  alpha = 0.01,
  scale = TRUE,
  mandatory = NULL,
  verbose = FALSE
)
}
\arguments{
\item{x}{Numeric design matrix \verb{(n, p)} without an intercept column.}

\item{y}{Response. Numeric for \code{family = "gaussian"}; \verb{\{0, 1\}} (or two-level
factor) for \code{family = "binomial"}; factor or integer in \verb{\{1, ..., C\}} for
\code{family = "multinomial"}.}

\item{family}{One of \code{"gaussian"} (alias: \code{"linear"}), \code{"binomial"},
\code{"multinomial"}.}

\item{q}{Maximum subset size. Defaults to \code{min(n, p)}.}

\item{x_val, y_val}{Optional validation data. When provided, the best \code{k}
is selected by validation metric and \code{coef_} is returned for the best
subset.}

\item{lam_ridge}{Ridge penalty for the inner solver. Default \code{0}.}

\item{Niter}{Number of homotopy iterations. Default \code{25}.}

\item{alpha}{Frank-Wolfe step size. Default \code{0.01}.}

\item{scale}{Column-normalise \code{x} before the algorithm. Default \code{TRUE}.}

\item{mandatory}{Optional integer vector of 1-indexed columns of \code{x} that
must be included in every model.}

\item{verbose}{Print progress. Default \code{FALSE}.}
}
\value{
An object of class \code{"combss"}, a list with elements:
\itemize{
\item \code{family}: one of \code{"gaussian"}, \code{"binomial"}, \code{"multinomial"}
\item \code{subset_list}: list of length up to \code{q}; element \code{k} is an integer
vector of selected column indices (1-indexed) for subset size \code{k}
\item \code{subset}: best subset (requires validation data; otherwise \code{NULL})
\item \code{mse} / \code{accuracy}: validation metric for the best subset
(requires validation data)
\item \code{lam_ridge}: ridge penalty used
\item \code{q}: maximum subset size evaluated
}
}
\description{
Reformulates the NP-hard discrete subset selection problem as a continuous
optimisation over the hypercube \verb{[0, 1]^p}, solved via a Frank-Wolfe
homotopy algorithm. The inner ridge problem is solved with \code{glmnet}. For
each subset size \verb{k = 1, ..., q}, COMBSS returns the selected feature set;
if validation data is supplied, the best \code{k} is chosen by validation MSE
(Gaussian) or accuracy (binomial / multinomial).
}
\examples{
set.seed(1)
n <- 200; p <- 30
beta <- c(3, 2, 1.5, 1, 0.5, rep(0, p - 5))
x <- matrix(rnorm(n * p), n, p)
y <- as.numeric(x \%*\% beta + rnorm(n) * 0.5)
fit <- combss(x, y, family = "gaussian", q = 10)
fit$subset_list[1:5]

}
\references{
Moka, S., Liquet, B., Zhu, H. and Muller, S. (2024).
COMBSS: best subset selection via continuous optimization.
\emph{Statistics and Computing}. \doi{10.1007/s11222-024-10387-8}

Mathur, A., Liquet, B., Muller, S. and Moka, S. (2026).
Parsimonious Subset Selection for Generalized Linear Models with
Biomedical Applications. \href{https://arxiv.org/abs/2603.21952}{arXiv:2603.21952}.
}
