% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pprf.R
\name{pprf}
\alias{pprf}
\title{Trains a Random Forest of Projection-Pursuit oblique decision trees.}
\usage{
pprf(
  formula = NULL,
  data = NULL,
  x = NULL,
  y = NULL,
  mode = NULL,
  size = 100,
  lambda = 0.5,
  n_vars = NULL,
  p_vars = NULL,
  seed = NULL,
  max_retries = 3L,
  threads = NULL,
  pp = NULL,
  vars = NULL,
  cutpoint = NULL,
  stop = NULL,
  binarize = NULL,
  grouping = NULL,
  leaf = NULL
)
}
\arguments{
\item{formula}{A formula of the form \code{y ~ x1 + x2 + ...}, where \code{y} is a vector of labels and \code{x1}, \code{x2}, ... are the features.}

\item{data}{A data frame containing the variables in the formula.}

\item{x}{A matrix containing the features for each observation.}

\item{y}{A matrix containing the labels for each observation.}

\item{mode}{Training mode: either \code{"classification"} or \code{"regression"}. When \code{NULL} (default), mode is auto-detected from \code{y}'s type — factor or character vectors trigger classification, numeric vectors trigger regression. Setting it explicitly is useful for the binary-integer-labels case (\code{mode = "classification"} with integer 0/1 labels) and for failing fast on a type mismatch (\code{mode = "regression"} with a factor \code{y} errors immediately).}

\item{size}{The number of trees in the forest (default: 100).}

\item{lambda}{A regularization parameter (default: 0.5). If \code{lambda = 0}, the model is trained using Linear Discriminant Analysis (LDA). If \code{lambda > 0}, the model is trained using Penalized Discriminant Analysis (PDA). The default uses PDA because pure LDA (\code{lambda = 0}) is ill-conditioned when there are more variables than effective observations (see the "Known limitations" section of the README). Cannot be used together with \code{pp}.}

\item{n_vars}{The number of variables to consider at each split (integer). These are chosen uniformly in each split. By default, half of the variables are used (\code{p_vars = 0.5}). Cannot be used together with \code{p_vars} or \code{dr}.}

\item{p_vars}{The proportion of variables to consider at each split (number between 0 and 1, exclusive). For example, \code{p_vars = 0.5} uses half the features. Cannot be used together with \code{n_vars} or \code{dr}.}

\item{seed}{An optional integer seed for reproducibility. If \code{NULL} (default), a seed is drawn from R's RNG, so \code{set.seed()} controls reproducibility. If an integer is provided, that value is used directly. The same seed is used for training and for computing permuted variable importance.}

\item{max_retries}{Maximum number of retries for degenerate trees (default: 3). When a bootstrap sample yields a singular covariance matrix, the tree is retrained with a different seed up to this many times.}

\item{threads}{The number of threads to use. The default is the number of cores available.}

\item{pp}{A projection pursuit strategy object created by \code{\link{pp_pda}}. Cannot be used together with \code{lambda}.}

\item{vars}{A variable selection strategy object created by \code{\link{vars_uniform}} or \code{\link{vars_all}}. Cannot be used together with \code{n_vars} or \code{p_vars}.}

\item{cutpoint}{A split cutpoint strategy object created by \code{\link{cutpoint_mean_of_means}} (default).}

\item{stop}{A stopping rule object. Default depends on mode:
\code{\link{stop_pure_node}()} for classification, and
\code{stop_any(stop_min_size(5), stop_min_variance(0.01))} for regression.}

\item{binarize}{A binarization strategy object. Default depends on mode:
\code{\link{binarize_largest_gap}()} for classification, and
\code{\link{binarize_disabled}()} for regression (regression's default
grouping always yields a 2-group partition, so no binarization is needed).}

\item{grouping}{A grouping strategy object. Default depends on mode:
\code{\link{grouping_by_label}()} for classification, and
\code{\link{grouping_by_cutpoint}()} for regression.}

\item{leaf}{A leaf strategy object. Default depends on mode:
\code{\link{leaf_majority_vote}()} for classification, and
\code{\link{leaf_mean_response}()} for regression.}
}
\value{
A \code{pprf} model. Its S3 class vector is
  \code{c("pprf_classification", "pprf", "ppmodel")} or
  \code{c("pprf_regression", "pprf", "ppmodel")} depending on the mode.
}
\description{
This function trains a Random Forest of Projection-Pursuit oblique decision tree using either a formula and data frame interface or a matrix-based interface. When using the formula interface, specify the model formula and the data frame containing the variables. For the matrix-based interface, provide matrices for the features and labels directly.
The number of trees is controlled by the \code{size} parameter. Each tree is trained on a stratified bootstrap sample drawn from the data.
The number of variables to consider at each split is controlled by the \code{n_vars} parameter.
If \code{lambda = 0}, the model is trained using Linear Discriminant Analysis (LDA). If \code{lambda > 0}, the model is trained using Penalized Discriminant Analysis (PDA).
}
\details{
Mode is taken from the \code{mode} argument when explicit, and otherwise auto-detected from `y` (factor/character → classification, numeric → regression). Pass \code{mode = "classification"} to force classification on integer labels (e.g. binary 0/1), or \code{mode = "regression"} to assert intent on numeric responses.

OOB error, OOB predictions, permuted variable importance, and weighted variable importance are computed lazily on first access via the accessor functions (`oob_error()`, `oob_predictions()`, `permuted_importance()`, `weighted_importance()`). Training itself is fast because these OOB-based computations are deferred.
}
\examples{

# Example 1: formula interface with the `iris` dataset
pprf(Species ~ ., data = iris)

# Example 2: formula interface with the `iris` dataset with regularization
pprf(Species ~ ., data = iris, lambda = 0.5)

# Example 3: matrix interface with the `iris` dataset
pprf(x = iris[, 1:4], y = iris[, 5])

# Example 4: matrix interface with the `iris` dataset with regularization
pprf(x = iris[, 1:4], y = iris[, 5], lambda = 0.5)

# Example 5: formula interface with the `crabs` dataset
pprf(Type ~ ., data = crabs)

# Example 6: formula interface with the `crabs` dataset with regularization
pprf(Type ~ ., data = crabs, lambda = 0.5)

}
\seealso{
\code{\link{predict.pprf_classification}}, \code{\link{predict.pprf_regression}}, \code{\link{formula.ppmodel}}, \code{\link{oob_error}}, \code{\link{save_json}}, \code{\link{load_json}}, \code{\link{pp_rand_forest}} for parsnip integration, \code{vignette("introduction")} for a tutorial
}
