% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/estimators.R
\name{werm_least_squares}
\alias{werm_least_squares}
\title{Fit a WERM changepoint model with squared loss}
\usage{
werm_least_squares(
  X,
  y,
  num_chgpts,
  delta = 1L,
  search_method = "efficient",
  fit_intercept = TRUE,
  fit_solver = "direct",
  penalty = "none",
  alpha = 0
)
}
\arguments{
\item{X}{Numeric matrix of shape \verb{(n, p)}. Observations must be in order.}

\item{y}{Numeric vector of length \code{n}. Ordered responses.}

\item{num_chgpts}{Integer. Number of changepoints to detect.}

\item{delta}{Integer. Minimum gap between candidate changepoints during
search. Default \code{1}. Rule of thumb: \code{max(1L, as.integer(0.05 * nrow(X)))}.}

\item{search_method}{Character. \code{"efficient"} (default) or \code{"brute_force"}.}

\item{fit_intercept}{Logical. Whether each segment model includes an
intercept. Default \code{TRUE}.}

\item{fit_solver}{Character. \code{"direct"} (default, closed-form) or
\code{"lbfgsb"} (gradient-based).}

\item{penalty}{Character. \code{"none"} (default), \code{"l1"}, or \code{"l2"}.}

\item{alpha}{Numeric. Penalty strength. Default \code{0}.}
}
\value{
An object of class \code{c("werm_least_squares", "werm_fit")} with the
following named elements:
\describe{
\item{\code{changepoints}}{Integer vector of detected changepoints
(\strong{1-indexed}, R convention). Length equals \code{num_chgpts}.}
\item{\code{num_chgpts}}{Integer. Number of detected changepoints.}
\item{\code{num_signals}}{Integer. Number of segments (\code{num_chgpts + 1}).}
\item{\code{objective}}{Numeric. Minimised WERM objective value.}
\item{\code{last_segment_coef}}{Numeric vector. Coefficient of the
unweighted base-loss refit on the last segment (used by \code{predict()}).}
\item{\code{last_segment_intercept}}{Numeric or \code{NULL}.}
\item{\code{signal_coefs}}{Matrix \verb{(num_signals x p)}. Stage-1 WERM
coefficient estimates.}
\item{\code{signal_intercepts}}{Numeric vector or \code{NULL}.}
\item{\code{n_features_in}}{Integer. Number of features.}
}
}
\description{
Detects \code{num_chgpts} changepoints in ordered regression data by minimising
a Weighted Empirical Risk with squared loss.
}
\examples{
# Limit BLAS/OpenMP threads so example CPU time stays proportional to
# elapsed time on multicore CRAN machines.
Sys.setenv(
  OMP_NUM_THREADS = "1",
  OPENBLAS_NUM_THREADS = "1",
  MKL_NUM_THREADS = "1",
  BLAS_NUM_THREADS = "1"
)

if (nzchar(Sys.getenv("RETICULATE_PYTHON")) &&
    weightederm_examples_available("WERMLeastSquares")) {
  set.seed(1)
  n <- 24L; p <- 2L; true_cp <- 12L
  X <- matrix(rnorm(n * p), n, p)
  y <- c(
    X[1:true_cp, ] \%*\% c(3, -1.5),
    X[(true_cp + 1L):n, ] \%*\% c(-3, 1.5)
  ) + rnorm(n, sd = 0.05)
  fit <- werm_least_squares(X, y, num_chgpts = 1L, delta = 3L,
                            fit_intercept = FALSE)
  fit$changepoints
}

}
