| Title: | Projection Pursuit Oblique Decision Trees and Random Forests |
|---|---|
| Description: | Builds decision trees by splitting on linear combinations of randomly chosen variables. Projection pursuit is used to choose a projection of the variables that best separates the groups. Using linear combinations of variables to separate groups takes the correlation between variables into account, which allows the model to outperform a traditional decision tree when the separation between groups occurs in combinations of variables. Single trees can be assembled into random forests for improved accuracy. Implements projection pursuit classification trees (Lee, Cook, Park and Lee (2013) <doi:10.1214/13-EJS810>) and projection pursuit forests (da Silva, Cook and Lee (2021) <doi:10.1080/10618600.2020.1870480>), following the earlier 'PPforest' package. |
| Authors: | Andrés Vidal [aut, cre, cph], Natalia da Silva [aut] |
| Maintainer: | Andrés Vidal <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.1 |
| Built: | 2026-07-19 15:46:00 UTC |
| Source: | https://github.com/cran/ppforest2 |
Returns a list where element 'i' is the integer vector of row indices (1-based, with replacement) drawn into the bootstrap sample of tree 'i'.
bag_samples(model)bag_samples(model)
model |
A |
A list of integer vectors, one per tree.
Placeholder binarizer for specs where binarization never fires —
notably regression, where 'grouping_by_cutpoint()' always produces
a 2-group partition at each node. Selecting binarize_disabled()
documents that intent explicitly; if binarization is ever invoked at
runtime with this strategy configured, training aborts with a clear
error rather than silently passing through. Default for regression
specs.
binarize_disabled()binarize_disabled()
A binarize_strategy object.
binarize_disabled()binarize_disabled()
Creates a binarization strategy that reduces multiclass nodes to binary by projecting group means and splitting at the largest gap. Default for classification specs.
binarize_largest_gap()binarize_largest_gap()
A binarize_strategy object.
binarize_largest_gap()binarize_largest_gap()
Median house values and demographic/geographic predictors for 20,433 California block groups, derived from the 1990 US Census. Classic regression benchmark. Originally released by Pace & Barry (1997); this version drops the categorical 'ocean_proximity' column (to keep the bundled schema all-numeric, matching the rest of the package's datasets) and removes rows with missing 'total_bedrooms'. The regression target, 'median_house_value', is the last column.
data(california_housing)data(california_housing)
A data frame with 20,433 rows and 9 variables.
Longitude of the block group (degrees, negative = west).
Latitude of the block group (degrees).
Median age of houses in the block group (years).
Total number of rooms.
Total number of bedrooms.
Block group population.
Number of households.
Median household income (tens of thousands of USD).
Regression target: median house value (USD).
Pace, R.K. and Barry, R. (1997) Sparse spatial autoregressions. Statistics & Probability Letters, 33, 291-297.
Measurements on rock crabs of the genus Leptograpsus. The dataset contains 200 observations from two species of crab (blue and orange), there are 50 specimens of each sex of each species, collected on site at Fremantle, Western Australia.
is the group variable and has 4 groups with the combinations of species and sex (BlueMale, BlueFemale, OrangeMale and OrangeFemale)
.
the size of the frontal lobe length, in mm
rear width, in mm
length of midline of the carapace, in mm
maximum width of carapace, in mm
depth of the body; for females, measured after displacement of the abdomen, in mm
data(crab)data(crab)
A data frame with 200 rows and 6 variables
Campbell, N. A. & Mahon, R. J. (1974), A Multivariate Study of Variation in Two Species of Rock Crab of genus Leptograpsus, Australian Journal of Zoology 22(3), 417 - 425.
Measurements of 200 crabs from the genus Leptograpsus, with 50 crabs for each of two colour forms and both sexes. Measurements include the frontal lobe size, rear width, carapace length, carapace width, and body depth.
A data frame with 200 rows and 8 variables:
Species code, with 'B' indicating blue and 'O' indicating orange.
Sex of the crab, with 'M' indicating male and 'F' indicating female.
Size of the frontal lobe in mm.
Rear width in mm.
Carapace length in mm.
Carapace width in mm.
Body depth in mm.
Campbell, N.A., and Mahon, R.J. (1974) A multivariate study of variation in two species of rock crab of genus Leptograpsus. Australian Journal of Zoology, 22, 417-425.
Creates a split cutpoint strategy that splits at the midpoint between group means. This is the default (and currently only) split cutpoint.
cutpoint_mean_of_means()cutpoint_mean_of_means()
A cutpoint_strategy object.
pptr, pprf, pp_pda, vars_uniform
cutpoint_mean_of_means()cutpoint_mean_of_means()
There are 159 fishes of 7 species are caught and measured. Altogether there are 7 variables. All the fishes are caught from the same lake(Laengelmavesi) near Tampere in Finland.
has 7 fish groups, with 35 cases of Bream, 11 cases of Parkki, 56 cases of Perch 17 cases of Pike, 20 cases of Roach, 14 cases of Smelt and 6 cases of Whitewish.
Weight of the fish (in grams)
Length from the nose to the beginning of the tail (in cm)
Length from the nose to the notch of the tail (in cm)
Length from the nose to the end of the tail (in cm)
Maximal height as % of Length3
Maximal width as % of Length3
data(fishcatch)data(fishcatch)
A data frame with 159 rows and 7 variables
https://jse.amstat.org/jse_data_archive.htm
Returns predictions on the training data — a factor for classification,
a numeric vector for regression. For forests, training predictions are
optimistic; use oob_predictions() for an honest estimate.
## S3 method for class 'ppmodel' fitted(object, ...)## S3 method for class 'ppmodel' fitted(object, ...)
object |
A |
... |
Unused. |
A factor (classification) or numeric vector (regression), length equal to the number of training observations.
residuals.ppmodel, oob_predictions
Formula extractor for ppforest2 models.
## S3 method for class 'ppmodel' formula(x, ...)## S3 method for class 'ppmodel' formula(x, ...)
x |
A |
... |
Unused. |
The formula the model was trained with, or 'NULL' for matrix-interface fits.
Contains measurements 214 observations of 6 types of glass; defined in terms of their oxide content.
has 6 types of glasses
refractive index
Sodium (unit measurement: weight percent in corresponding oxide).
Magnesium
Aluminum
Silicon
Potassium
Calcium
Barium
Iron
data(glass)data(glass)
A data frame with 214 rows and 10 variables
Creates a grouping strategy for regression trees: observations are split by the cutpoint in projected space, then each child's observations are sorted by the continuous response and median-split into 2 new groups for the next projection-pursuit step. This is the default grouping strategy for regression.
grouping_by_cutpoint()grouping_by_cutpoint()
A grouping_strategy object.
grouping_by_cutpoint()grouping_by_cutpoint()
Creates a grouping strategy that routes all observations of a group to the same child node. This is the default grouping strategy for classification.
grouping_by_label()grouping_by_label()
A grouping_strategy object.
grouping_by_label()grouping_by_label()
Contains 2310 observations of instances from 7 outdoor images
has 7 types of outdoor images, brickface, cement, foliage, grass, path, sky, and window.
the column of the center pixel of the region
the row of the center pixel of the region.
the number of pixels in a region = 9.
the results of a line extraction algorithm that counts how many lines of length 5 (any orientation) with low contrast, less than or equal to 5, go through the region.
measure the contrast of horizontally adjacent pixels in the region. There are 6, the mean and standard deviation are given. This attribute is used as a vertical edge detector.
X5 sd
measures the contrast of vertically adjacent pixels. Used for horizontal line detection.
sd X7
the average over the region of (R + G + B)/3
the average over the region of the R value.
the average over the region of the B value.
the average over the region of the G value.
measure the excess red: (2R - (G + B))
measure the excess blue: (2B - (G + R))
measure the excess green: (2G - (R + B))
3-d nonlinear transformation of RGB. (Algorithm can be found in Foley and VanDam, Fundamentals of Interactive Computer Graphics)
mean of X16
hue mean
data(image)data(image)
A data frame contains 2310 observations and 19 variables
Creates a leaf strategy that assigns the majority group label as the leaf prediction. When groups are tied, the smallest label wins. This is the default leaf strategy for classification.
leaf_majority_vote()leaf_majority_vote()
A leaf_strategy object.
leaf_majority_vote()leaf_majority_vote()
Creates a leaf strategy that predicts the mean of the continuous response values for the observations in the leaf. Used for regression trees; requires a numeric response.
leaf_mean_response()leaf_mean_response()
A leaf_strategy object.
pptr, pprf, leaf_majority_vote
leaf_mean_response()leaf_mean_response()
This dataset comes from a study of gene expression in two types of acute leukemias, acute lymphoblastic leukemia (ALL) and acute myeloid leukemia (AML). Gene expression levels were measured using Affymetrix high density oligonucleotide arrays containing 6817 human genes. A dataset containing 72 observations from 3 leukemia type groups.
has 3 groups with 38 cases of B-cell ALL, 25 cases of AML and 9 cases of T-cell ALL
.
gene expression levels
data(leukemia)data(leukemia)
A data frame with 72 rows and 41 variables
Dudoit, S., Fridlyand, J. and Speed, T. P. (2002). Comparison of Discrimination Methods for the Classification of Tumors Using Gene Expression Data. Journal of the American statistical Association 97 77-87.
Deserializes a pptr or pprf model from a JSON file. The model
can be used for prediction immediately. If variable importance metrics and
OOB fields were saved, they are restored into the model's lazy-computation
cache so later accessor calls (oob_error(), permuted_importance(),
etc.) return the stored values without recomputation.
load_json(path)load_json(path)
path |
File path to read the JSON from. |
Note that formula, x, and y are not stored in the JSON
and will be NULL on the loaded model. Formula-based prediction and
any accessor that requires training data will error unless the user
re-attaches those fields.
A pptr or pprf model (with the appropriate
_classification / _regression subclass).
model <- pptr(Species ~ ., data = iris, seed = 0) path <- tempfile(fileext = ".json") save_json(model, path) loaded <- load_json(path) predict(loaded, as.matrix(iris[, 1:4]))model <- pptr(Species ~ ., data = iris, seed = 0) path <- tempfile(fileext = ".json") save_json(model, path) loaded <- load_json(path) predict(loaded, as.matrix(iris[, 1:4]))
Gene expression in the three most prevalent adult lymphoid malignancies: B-cell chronic lymphocytic leukemia (B-CLL), follicular lymphoma (FL), and diffuse large B-cell lym- phoma (DLBCL). Gene expression levels were measured using a specialized cDNA microarray, the Lymphochip, containing genes that are preferentially expressed in lymphoid cells or that are of known immunologic or oncologic importance. This dataset contain 80 observations from 3 lymphoma types.
Group variable has 3 groups with 29 cases of B-cell ALL (B-CLL), 42 cases of diffuse large B-cell lymphoma (DLBCL) and 9 cases of follicular lymphoma (FL)
.
gene expression
data(lymphoma)data(lymphoma)
A data frame with 80 rows and 51 variables
Dudoit, S., Fridlyand, J. and Speed, T. P. (2002). Comparison of Discrimination Methods for the Classification of Tumors Using Gene Ex- pression Data. Journal of the American statistical Association 97 77-87.
cDNA microarrays were used to examine the variation in gene expression among the 60 cell lines. The cell lines are derived from tumors with different sites of origin. This dataset contain 61 observations and 30 feature variables from 8 different tissue types.
data(NCI60)data(NCI60)
A data frame with 61 rows and 31 variables
has 8 different tissue types, 9 cases of breast, 5 cases of central nervous system (CNS), 7 cases pf colon, 8 cases of leukemia, 8 cases of melanoma, 9 cases of non-small-cell lung carcinoma (NSCLC), 6 cases of ovarian and 9 cases of renal.
gene expression information
Dudoit, S., Fridlyand, J. and Speed, T. P. (2002). Comparison of Discrimination Methods for the Classification of Tumors Using Gene Expression Data. Journal of the American statistical Association 97 77-87.
Implements the standard stats::nobs() contract so downstream tools
(step(), broom's glance(), information criteria) can ask for
the training-sample size.
## S3 method for class 'ppmodel' nobs(object, ...)## S3 method for class 'ppmodel' nobs(object, ...)
object |
A |
... |
Unused. |
Integer scalar. Returns NA_integer_ for models loaded from
JSON without their original training data.
Contains 572 observations and 10 variables
Three super-groups of Italy: North, South and the island of Sardinia
Nine collection areas: three from North, four from South and 2 from Sardinia
fatty acids percent x 100
fatty acids percent x 100
fatty acids percent x 100
fatty acids percent x 100
fatty acids percent x 100
fatty acids percent x 100
fatty acids percent x 100
fatty acids percent x 100
data(olive)data(olive)
A data frame contains 573 observations and 10 variables
Computes (or returns the cached) OOB error using the training data stored on the model. For classification, this is the misclassification rate in '[0, 1]'. For regression, it is the mean squared error against the continuous response.
oob_error(model)oob_error(model)
model |
A |
A numeric scalar in '[0, 1]' for classification or '[0, Inf)' for regression. Returns 'NA_real_' when no observation has any out-of-bag tree (e.g. a degenerate forest where every tree saw every row). Callers should check with 'is.na()' rather than comparing against a sentinel value; in earlier versions this condition was signalled as '-1', which was not distinguishable from a (mathematically impossible but representable) error rate.
Returns predictions for each training row using only trees that did not see that row in their bootstrap sample. Observations with no OOB tree are represented as 'NA' in both modes: 'NA' at the factor level for classification, and 'NA_real_' for regression. Filter with the standard 'is.na()' idiom.
oob_predictions(model)oob_predictions(model)
model |
A |
A factor (classification) or numeric vector (regression), length 'n'.
Returns a list where element 'i' is the integer vector of row indices (1-based) that were **not** in the bootstrap sample of tree 'i'.
oob_samples(model)oob_samples(model)
model |
A |
A list of integer vectors, one per tree.
A dataset containing 195 observations from 2 parkinson types.
Group variable has 2 groups, there are 48 cases of healthy people and 147 cases with Parkinson. The feature variables are biomedical voice measures
.
Average vocal fundamental frequency
Maximum vocal fundamental frequency
Minimum vocal fundamental frequency
MDVP:Jitter(%) measures of variation in fundamental frequency
MDVP:Jitter(Abs) measures of variation in fundamental frequency
MDVP:RAP measures of variation in fundamental frequency
MDVP:PPQ measures of variation in fundamental frequency
Jitter:DDP measures of variation in fundamental frequency
MDVP:Shimmer measures of variation in amplitude
MDVP:Shimmer(dB) measures of variation in amplitude
Shimmer:APQ3 measures of variation in amplitude
Shimmer:APQ5 measures of variation in amplitude
MDVP:APQ measures of variation in amplitude
Shimmer:DDA measures of variation in amplitude
NHR measures of ratio of noise to tonal components in the voice
HNR measures of ratio of noise to tonal components in the voice
RPDE nonlinear dynamical complexity measures
D2 nonlinear dynamical complexity measures
DFA - Signal fractal scaling exponent
spread1 Nonlinear measures of fundamental frequency variation
spread2 Nonlinear measures of fundamental frequency variation
PPE Nonlinear measures of fundamental frequency variation
data(parkinson)data(parkinson)
A data frame with 195 rows and 23 variables
https://archive.ics.uci.edu/ml/datasets/Parkinsons
For each feature, measures the drop in OOB accuracy (classification) or the increase in normalised MSE (regression) after randomly permuting that feature across the OOB observations. Computed lazily from the training data stored on the model; the result is cached.
permuted_importance(model)permuted_importance(model)
model |
A |
**Sign semantics.** Entries may be **negative**. That is not an error and not a sentinel: it means permuting the feature did not degrade OOB fit on average — the feature's signal sits at or below the noise floor of the permutation procedure. Interpret negative or near-zero entries as "no evidence of importance"; rely on the ranking rather than clipping at zero or normalizing. The scale is already comparable within a fitted model.
A numeric vector, one entry per feature. Negative values are meaningful (see Sign semantics above).
Visualizes a pprf model. By default, shows variable importance with
one plot per metric side by side. Use metric to show a single
importance metric.
## S3 method for class 'pprf' plot(x, type = "importance", metric = NULL, tree_index = 1L, node = 1L, ...)## S3 method for class 'pprf' plot(x, type = "importance", metric = NULL, tree_index = 1L, node = 1L, ...)
x |
A pprf model. |
type |
Character string specifying the plot type.
|
metric |
Character string selecting a single importance metric
to plot: |
tree_index |
Integer index of the tree to plot (1-based). Only used when
|
node |
Integer index of the node for projection plots. Defaults to 1 (root).
Only used when |
... |
Additional arguments passed to the internal plotting function. |
A ggplot2-compatible object (invisibly). The importance grid returns
a patchwork object that works with ggplot2::ggsave().
if (requireNamespace("ggplot2", quietly = TRUE) && requireNamespace("patchwork", quietly = TRUE)) { forest <- pprf(Species ~ ., data = iris, size = 10) plot(forest) # all metrics side by side plot(forest, metric = "permuted") # single metric plot(forest, type = "structure", tree_index = 1) plot(forest, type = "projection", tree_index = 1) }if (requireNamespace("ggplot2", quietly = TRUE) && requireNamespace("patchwork", quietly = TRUE)) { forest <- pprf(Species ~ ., data = iris, size = 10) plot(forest) # all metrics side by side plot(forest, metric = "permuted") # single metric plot(forest, type = "structure", tree_index = 1) plot(forest, type = "projection", tree_index = 1) }
Visualizes a pptr model. By default, shows a mosaic overview with tree
structure, decision boundaries, and variable importance. Use type
to show individual plots.
## S3 method for class 'pptr' plot(x, type = NULL, metric = NULL, node = 1L, ...)## S3 method for class 'pptr' plot(x, type = NULL, metric = NULL, node = 1L, ...)
x |
A pptr model. |
type |
Character string specifying the plot type. |
metric |
Character string selecting a single importance metric
to plot: |
node |
Integer index of the node for projection plots (1-based, breadth-first
order). Defaults to 1 (root node). Only used when |
... |
Additional arguments passed to the internal plotting function. |
A ggplot2-compatible object (invisibly). The mosaic layout returns
a patchwork object that works with ggplot2::ggsave().
if (requireNamespace("ggplot2", quietly = TRUE) && requireNamespace("patchwork", quietly = TRUE)) { model <- pptr(Species ~ ., data = iris) plot(model) # mosaic overview plot(model, type = "structure") # tree structure only plot(model, type = "importance") # variable importance plot(model, type = "projection") # projection histogram plot(model, type = "boundaries") # decision boundaries }if (requireNamespace("ggplot2", quietly = TRUE) && requireNamespace("patchwork", quietly = TRUE)) { model <- pptr(Species ~ ., data = iris) plot(model) # mosaic overview plot(model, type = "structure") # tree structure only plot(model, type = "importance") # variable importance plot(model, type = "projection") # projection histogram plot(model, type = "boundaries") # decision boundaries }
Creates a Penalized Discriminant Analysis (PDA) projection pursuit strategy
for use with pptr or pprf.
pp_pda(lambda = 0)pp_pda(lambda = 0)
lambda |
A regularization parameter between 0 and 1.
If |
A pp_strategy object.
pptr, pprf, vars_uniform, vars_all, cutpoint_mean_of_means
# PDA with lambda = 0.5 pp_pda(0.5) # Use with pptr pptr(Species ~ ., data = iris, pp = pp_pda(0.5)) # Use with pprf pprf(Species ~ ., data = iris, pp = pp_pda(0.5), vars = vars_uniform(n_vars = 2))# PDA with lambda = 0.5 pp_pda(0.5) # Use with pptr pptr(Species ~ ., data = iris, pp = pp_pda(0.5)) # Use with pprf pprf(Species ~ ., data = iris, pp = pp_pda(0.5), vars = vars_uniform(n_vars = 2))
Creates a model specification for a Projection Pursuit random forest.
Use set_engine("ppforest2") to select the ppforest2 engine.
pp_rand_forest( mode = "classification", trees = NULL, mtry = NULL, mtry_prop = NULL, penalty = NULL )pp_rand_forest( mode = "classification", trees = NULL, mtry = NULL, mtry_prop = NULL, penalty = NULL )
mode |
A character string for the model type. Either |
trees |
The number of trees in the forest (maps to |
mtry |
The number of variables to consider at each split (maps to |
mtry_prop |
The proportion of variables to consider at each split (maps to |
penalty |
The regularization parameter (maps to |
A parsnip model specification.
pprf for the underlying training function, pp_tree for single trees
if (requireNamespace("parsnip", quietly = TRUE)) { library(parsnip) spec <- pp_rand_forest(trees = 50, mtry = 2) %>% set_engine("ppforest2") fit <- spec %>% fit(Species ~ ., data = iris) predict(fit, iris) predict(fit, iris, type = "prob") }if (requireNamespace("parsnip", quietly = TRUE)) { library(parsnip) spec <- pp_rand_forest(trees = 50, mtry = 2) %>% set_engine("ppforest2") fit <- spec %>% fit(Species ~ ., data = iris) predict(fit, iris) predict(fit, iris, type = "prob") }
Creates a model specification for a single Projection Pursuit decision tree.
Use set_engine("ppforest2") to select the ppforest2 engine.
pp_tree(mode = "classification", penalty = NULL)pp_tree(mode = "classification", penalty = NULL)
mode |
A character string for the model type. Either |
penalty |
The regularization parameter (maps to |
A parsnip model specification.
pptr for the underlying training function, pp_rand_forest for forests
if (requireNamespace("parsnip", quietly = TRUE)) { library(parsnip) spec <- pp_tree(penalty = 0) %>% set_engine("ppforest2") fit <- spec %>% fit(Species ~ ., data = iris) predict(fit, iris) }if (requireNamespace("parsnip", quietly = TRUE)) { library(parsnip) spec <- pp_tree(penalty = 0) %>% set_engine("ppforest2") fit <- spec %>% fit(Species ~ ., data = iris) predict(fit, iris) }
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 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 n_vars parameter.
If lambda = 0, the model is trained using Linear Discriminant Analysis (LDA). If lambda > 0, the model is trained using Penalized Discriminant Analysis (PDA).
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 )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 )
formula |
A formula of the form |
data |
A data frame containing the variables in the formula. |
x |
A matrix containing the features for each observation. |
y |
A matrix containing the labels for each observation. |
mode |
Training mode: either |
size |
The number of trees in the forest (default: 100). |
lambda |
A regularization parameter (default: 0.5). If |
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 ( |
p_vars |
The proportion of variables to consider at each split (number between 0 and 1, exclusive). For example, |
seed |
An optional integer seed for reproducibility. If |
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. |
threads |
The number of threads to use. The default is the number of cores available. |
pp |
A projection pursuit strategy object created by |
vars |
A variable selection strategy object created by |
cutpoint |
A split cutpoint strategy object created by |
stop |
A stopping rule object. Default depends on mode:
|
binarize |
A binarization strategy object. Default depends on mode:
|
grouping |
A grouping strategy object. Default depends on mode:
|
leaf |
A leaf strategy object. Default depends on mode:
|
Mode is taken from the mode argument when explicit, and otherwise auto-detected from 'y' (factor/character → classification, numeric → regression). Pass mode = "classification" to force classification on integer labels (e.g. binary 0/1), or 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.
A pprf model. Its S3 class vector is
c("pprf_classification", "pprf", "ppmodel") or
c("pprf_regression", "pprf", "ppmodel") depending on the mode.
predict.pprf_classification, predict.pprf_regression, formula.ppmodel, oob_error, save_json, load_json, pp_rand_forest for parsnip integration, vignette("introduction") for a tutorial
# 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)# 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)
This function trains a 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.
If lambda = 0, the model is trained using Linear Discriminant Analysis (LDA). If lambda > 0, the model is trained using Penalized Discriminant Analysis (PDA).
pptr( formula = NULL, data = NULL, x = NULL, y = NULL, mode = NULL, lambda = 0.5, seed = NULL, pp = NULL, cutpoint = NULL, stop = NULL, binarize = NULL, grouping = NULL, leaf = NULL )pptr( formula = NULL, data = NULL, x = NULL, y = NULL, mode = NULL, lambda = 0.5, seed = NULL, pp = NULL, cutpoint = NULL, stop = NULL, binarize = NULL, grouping = NULL, leaf = NULL )
formula |
A formula of the form |
data |
A data frame containing the variables in the formula. |
x |
A matrix containing the features for each observation. |
y |
A matrix containing the labels for each observation. |
mode |
Training mode: either |
lambda |
A regularization parameter (default: 0.5). If |
seed |
An optional integer seed for reproducibility. If |
pp |
A projection pursuit strategy object created by |
cutpoint |
A split cutpoint strategy object created by |
stop |
A stopping rule object. Default depends on mode:
|
binarize |
A binarization strategy object. Default depends on mode:
|
grouping |
A grouping strategy object. Default depends on mode:
|
leaf |
A leaf strategy object. Default depends on mode:
|
Mode is taken from the mode argument when explicit, and otherwise auto-detected from 'y' (factor/character → classification, numeric → regression). Pass mode = "classification" to force classification on integer labels (e.g. binary 0/1), or mode = "regression" to assert intent on numeric responses.
A pptr model. Its S3 class vector is
c("pptr_classification", "pptr", "ppmodel") or
c("pptr_regression", "pptr", "ppmodel") depending on the mode.
predict.pptr_classification, predict.pptr_regression, formula.ppmodel, print.pptr, save_json, load_json, pp_tree for parsnip integration
# Example 1: formula interface with the `iris` dataset pptr(Species ~ ., data = iris) # Example 2: formula interface with the `iris` dataset with regularization pptr(Species ~ ., data = iris, lambda = 0.5) # Example 3: matrix interface with the `iris` dataset pptr(x = iris[, 1:4], y = iris[, 5])# Example 1: formula interface with the `iris` dataset pptr(Species ~ ., data = iris) # Example 2: formula interface with the `iris` dataset with regularization pptr(Species ~ ., data = iris, lambda = 0.5) # Example 3: matrix interface with the `iris` dataset pptr(x = iris[, 1:4], y = iris[, 5])
Predicts labels or vote proportions from a pprf model (classification mode).
## S3 method for class 'pprf_classification' predict(object, new_data = NULL, type = NULL, ...)## S3 method for class 'pprf_classification' predict(object, new_data = NULL, type = NULL, ...)
object |
A |
new_data |
A data frame or matrix of new observations. If |
type |
The type of prediction: |
... |
For backward compatibility, the first positional argument is treated as |
If type = "class", a factor of predicted labels. If type = "prob", a data frame with one column per group, each row summing to 1.
model <- pprf(Species ~ ., data = iris) predict(model, iris) predict(model, iris, type = "prob")model <- pprf(Species ~ ., data = iris) predict(model, iris) predict(model, iris, type = "prob")
Predicts numeric responses from a pprf model (regression mode).
## S3 method for class 'pprf_regression' predict(object, new_data = NULL, type = NULL, ...)## S3 method for class 'pprf_regression' predict(object, new_data = NULL, type = NULL, ...)
object |
A |
new_data |
A data frame or matrix of new observations. |
type |
Must be |
... |
For backward compatibility, the first positional argument is treated as |
A numeric vector of mean predictions across the forest's trees.
pprf, predict.pprf_classification
Predicts labels or per-group one-hot proportions from a pptr model (classification mode).
## S3 method for class 'pptr_classification' predict(object, new_data = NULL, type = NULL, ...)## S3 method for class 'pptr_classification' predict(object, new_data = NULL, type = NULL, ...)
object |
A |
new_data |
A data frame or matrix of new observations. If |
type |
|
... |
Backward-compat positional 'new_data'. |
A factor or data frame.
Predicts numeric responses from a pptr model (regression mode).
## S3 method for class 'pptr_regression' predict(object, new_data = NULL, type = NULL, ...)## S3 method for class 'pptr_regression' predict(object, new_data = NULL, type = NULL, ...)
object |
A |
new_data |
A data frame or matrix of new observations. |
type |
Must be |
... |
Backward-compat positional 'new_data'. |
A numeric vector.
pptr, predict.pptr_classification
Prints a compact summary of a pprf forest.
## S3 method for class 'pprf' print(x, ...)## S3 method for class 'pprf' print(x, ...)
x |
A |
... |
Unused. |
Invisibly returns the input pprf model x (unchanged).
Called for its side effect of printing a compact description of the forest
(call, number of trees, mode, group names, formula) to the console.
Prints the structure of a pptr tree.
## S3 method for class 'pptr' print(x, ...)## S3 method for class 'pptr' print(x, ...)
x |
A |
... |
Unused. |
Invisibly returns the input pptr model x (unchanged).
Called for its side effect of printing the tree structure – the oblique
split rules and leaf predictions – to the console.
The projection-based importance (VI2): each split's scaled absolute
projection coefficients ('|a_j| * sigma_j') aggregated into a per-feature
score, averaged over the non-degenerate trees of a forest. Unlike
permuted_importance and weighted_importance,
this measure is not OOB-based — it depends only on the fitted projector
geometry, is computed eagerly at fit time (cheap), and is available for
both single trees (pptr) and forests (pprf).
projection_importance(model)projection_importance(model)
model |
A |
**Sign semantics.** Entries are non-negative by construction (absolute coefficients scaled by each feature's standard deviation). Rely on the ranking rather than re-normalizing.
A non-negative numeric vector, one entry per feature.
permuted_importance, weighted_importance
Returns y - fitted(model). Only defined for regression models —
classification residuals have no canonical scalar form, so this method
errors on classification models rather than inventing a convention.
## S3 method for class 'ppmodel' residuals(object, ...)## S3 method for class 'ppmodel' residuals(object, ...)
object |
A |
... |
Unused. |
A numeric vector of length nobs(object).
Serializes a pptr or pprf model to JSON format compatible
with the C++ CLI. The JSON includes the model structure, group labels,
training parameters, and optionally variable importance metrics.
save_json(model, path, ...) ## S3 method for class 'ppmodel' save_json(model, path, include_metrics = TRUE, ...)save_json(model, path, ...) ## S3 method for class 'ppmodel' save_json(model, path, include_metrics = TRUE, ...)
model |
A |
path |
File path to write the JSON to. |
... |
Additional arguments (currently unused). |
include_metrics |
If |
Invisibly returns the file path that was written (a length-one
character string). Called for its side effect of serializing model
to a JSON file at path.
model <- pptr(Species ~ ., data = iris, seed = 0) path <- tempfile(fileext = ".json") save_json(model, path)model <- pptr(Species ~ ., data = iris, seed = 0) path <- tempfile(fileext = ".json") save_json(model, path)
Creates a composite stopping rule that fires when any of the child rules
fires. Useful for combining multiple criteria, e.g. stop_any(stop_min_size(5),
stop_min_variance(0.01)) for regression.
stop_any(...)stop_any(...)
... |
Two or more |
A stop_strategy object.
stop_min_size, stop_min_variance, stop_pure_node
stop_any(stop_min_size(5), stop_min_variance(0.01))stop_any(stop_min_size(5), stop_min_variance(0.01))
Creates a stopping rule that stops splitting when a node's depth reaches
max_depth. Depth is zero-based at the root, so max_depth(k)
allows at most k + 1 levels. Mode-agnostic: useful for bounding
tree complexity in both classification and regression trees.
stop_max_depth(max_depth)stop_max_depth(max_depth)
max_depth |
Maximum depth (non-negative integer; 0 produces a root-only stump). |
A stop_strategy object.
stop_max_depth(5)stop_max_depth(5)
Creates a stopping rule that stops splitting when a node has fewer than
min_size observations. Used primarily for regression trees.
stop_min_size(min_size = 5L)stop_min_size(min_size = 5L)
min_size |
Minimum node size to allow a split (default: 5). |
A stop_strategy object.
stop_min_size(5)stop_min_size(5)
Creates a stopping rule that stops splitting when the within-node response
variance falls below threshold. Used primarily for regression trees;
requires a continuous response.
stop_min_variance(threshold = 0.01)stop_min_variance(threshold = 0.01)
threshold |
Variance threshold below which to stop splitting (default: 0.01). |
A stop_strategy object.
stop_min_variance(0.01)stop_min_variance(0.01)
Creates a stopping rule that stops splitting when a node contains only one group. This is the default stopping rule for classification.
stop_pure_node()stop_pure_node()
A stop_strategy object.
stop_pure_node()stop_pure_node()
Summary of a pprf forest (shared header + VI).
## S3 method for class 'pprf' summary(object, ...)## S3 method for class 'pprf' summary(object, ...)
object |
A |
... |
Unused. |
Invisibly returns the input pprf model object
(unchanged). Called for its side effect of printing a detailed summary –
the training specification, data summary, and variable-importance table
(plus, for classification, the training/OOB confusion matrices) – to the
console.
pp_rand_forest model specification.Implements parsnip's update protocol so that tune::tune_grid()
(and any other caller that finalises a spec via update()) can fill
in the tuned values for trees, mtry, and penalty.
Without this method, update() falls back to stats::update.default
and fails with "need an object with call component".
## S3 method for class 'pp_rand_forest' update( object, parameters = NULL, trees = NULL, mtry = NULL, mtry_prop = NULL, penalty = NULL, fresh = FALSE, ... )## S3 method for class 'pp_rand_forest' update( object, parameters = NULL, trees = NULL, mtry = NULL, mtry_prop = NULL, penalty = NULL, fresh = FALSE, ... )
object |
A |
parameters |
A named list of parameters to update (alternative to passing them as args). |
trees, mtry, mtry_prop, penalty
|
New values for the corresponding parameters. |
fresh |
If |
... |
Engine-specific arguments to update. |
An updated pp_rand_forest model specification.
pp_tree model specification.Companion to update.pp_rand_forest — exists for the same
reason (tune::tune_grid() relies on update() to finalise the
spec at each grid point).
## S3 method for class 'pp_tree' update(object, parameters = NULL, penalty = NULL, fresh = FALSE, ...)## S3 method for class 'pp_tree' update(object, parameters = NULL, penalty = NULL, fresh = FALSE, ...)
object |
A |
parameters |
A named list of parameters to update (alternative to passing them as args). |
penalty |
A new value for the regularisation parameter. |
fresh |
If |
... |
Engine-specific arguments to update. |
An updated pp_tree model specification.
Creates a variable selection strategy that uses all variables at each
split. This is the default for single trees (pptr).
vars_all()vars_all()
A vars_strategy object.
pptr, vars_uniform, pp_pda, cutpoint_mean_of_means
vars_all()vars_all()
Creates a variable selection strategy that randomly selects a subset
of variables at each split. Used with pprf for random forests.
vars_uniform(n_vars = NULL, p_vars = NULL)vars_uniform(n_vars = NULL, p_vars = NULL)
n_vars |
The number of variables to consider at each split (integer).
Cannot be used together with |
p_vars |
The proportion of variables to consider at each split
(number between 0 and 1, exclusive). Resolved to an integer count when
the number of features is known. Cannot be used together with |
Exactly one of n_vars or p_vars may be specified. When
p_vars is used, it is stored as-is and resolved to an integer count
later by pprf once the number of features is known.
A vars_strategy object.
pprf, vars_all, pp_pda, cutpoint_mean_of_means
# Select 2 variables at each split vars_uniform(n_vars = 2) # Select half the variables at each split vars_uniform(p_vars = 0.5) # Use with pprf pprf(Species ~ ., data = iris, vars = vars_uniform(n_vars = 2))# Select 2 variables at each split vars_uniform(n_vars = 2) # Select half the variables at each split vars_uniform(p_vars = 0.5) # Use with pprf pprf(Species ~ ., data = iris, vars = vars_uniform(n_vars = 2))
Weights each tree's projection-based importance by a per-tree OOB quality score — '1 - error_rate' in '[0, 1]' for classification, and 'max(0, 1 - NMSE)' in '[0, 1]' for regression — then aggregates 'I_s × |a_j|' over splits. Computed lazily from the training data stored on the model; the result is cached.
weighted_importance(model)weighted_importance(model)
model |
A |
**Sign semantics.** Entries are non-negative by construction (weights
and per-split contributions are both non-negative). A zero entry means
"this feature never appeared in a weighted OOB-contributing split,"
not "within noise." Contrast with permuted_importance,
where negative values are meaningful. Do not re-normalize — rely on
the ranking.
A non-negative numeric vector, one entry per feature.
A dataset containing 178 observations from 3 wine grown cultivares in Italy.
data(wine)data(wine)
A data frame with 178 rows and 14 variables
Group variable has 3 groups that are 3 different wine grown cultivars in Italy.
Check vbles