Package {PRTree}

Type:	Package
Date:	2026-07-13
Title:	Probabilistic Regression Trees
Version:	1.1.0
Depends:	R (≥ 4.3.0)
Suggests:	ggplot2
Imports:	tidyr (≥ 1.3.0), gridExtra (≥ 2.3), stats, grDevices, utils, tidyselect, graphics, rlang
Description:	Implementation of Probabilistic Regression Trees (PRTree), providing functions for model fitting and prediction, with specific adaptations to handle missing values. The main computations are implemented in 'Fortran' for high efficiency. The package is based on the PRTree methodology described in Alkhoury et al. (2020), "Smooth and Consistent Probabilistic Regression Trees" https://proceedings.neurips.cc/paper_files/paper/2020/file/8289889263db4a40463e3f358bb7c7a1-Paper.pdf. Details on the treatment of missing data and implementation aspects are presented in Prass, T.S.; Neimaier, A.S.; Pumi, G. (2025), "Handling Missing Data in Probabilistic Regression Trees: Methods and Implementation in R" <doi:10.48550/arXiv.2510.03634>.
License:	GPL (≥ 3)
Encoding:	UTF-8
NeedsCompilation:	yes
Collate:	'prtree.R' 'prtree_control.R' 'prtree_control_utils.R' 'prtree_cv.R' 'prtree_cv_methods.R' 'prtree_rules.R' 'prtree_defaults.R' 'prtree_grid_expansion.R' 'prtree_main.R' 'prtree_main_methods.R' 'prtree_messages.R' 'prtree_predict.R' 'prtree_split.R' 'prtree_validation.R'
Config/roxygen2/version:	8.0.0
RoxygenNote:	7.3.3
Packaged:	2026-07-13 20:09:13 UTC; Taiane
Author:	Taiane Schaedler Prass [aut, ths, cre], Alisson Silva Neimaier [aut]
Maintainer:	Taiane Schaedler Prass <taianeprass@gmail.com>
Repository:	CRAN
Date/Publication:	2026-07-13 20:30:10 UTC

PRTree: Probabilistic Regression Tress

Description

Implementation of Probabilistic Regression Trees (PRTree), providing functions for model fitting and prediction, with specific adaptations to handle missing values. The main computations are implemented in 'Fortran' for high efficiency. The package is based on the PRTree methodology described in Alkhoury et al. (2020), "Smooth and Consistent Probabilistic Regression Trees" <https://proceedings.neurips.cc/paper_files/paper/2020/file/8289889263db4a40463e3f358bb7c7a1-Paper.pdf>. Details on the treatment of missing data and implementation aspects are presented in Prass, T.S.; Neimaier, A.S.; Pumi, G. (2025), "Handling Missing Data in Probabilistic Regression Trees: Methods and Implementation in R" <doi:10.48550/arXiv.2510.03634>.

Author(s)

Taiane Schaedler Prass taianeprass@gmail.com and Alisson Silva Neimaier alissonneimaier@hotmail.com

Create a grid of sigma vectors for Probabilistic Regression Trees

Description

Creates a grid of candidate \boldsymbol\sigma vectors for use in pr_tree. The grid is generated from the feature standard deviations of X, or using unit scales when X = NULL

Usage

expand_sigma_grid(X = NULL, n_feat = NULL, idx_train = NULL,
  grid_size = 8, min_mult = 0, max_mult = 2, tiny_sigma = NULL,
  verbose = TRUE)

Arguments

Details

When X is provided, the grid is based on the empirical standard deviations of the features. If a standard deviation for a feature cannot be computed (e.g., due to all missing values or a constant feature), it defaults to 1.0 to ensure the grid generation proceeds without errors.

Automatic grid generation

The automatic grid is generated as follows:

• For each feature j, the base values are the empirical standard deviations \hat\sigma_j from the training data.

• If grid_size = 1, the grid consists solely of these base values \hat{\boldsymbol\sigma}.

• If grid_size > 1, the grid is constructed using grid_size multipliers equally spaced in the interval:

  • ⁠(min_mult, max_mult]⁠ when min_mult = 0 (excludes 0, includes max_mult).

  • ⁠[min_mult, max_mult]⁠ when min_mult > 0 (both inclusive).

  Each multiplier m generates a candidate vector m \times \hat{\boldsymbol\sigma}.

• If tiny_sigma is provided, it is added as an extra candidate (first row) with \boldsymbol\sigma = \text{tiny\_sigma} \cdot \boldsymbol{1}_p, where \boldsymbol{1}_p is a vector of ones of length p (the number of features). This results in a final grid of size grid_size + 1.

See Also

pr_tree_control for setting control parameters.

pr_tree_control_cv for cross-validation settings.

pr_tree for fitting a single tree.

pr_tree_cv for cross-validation.

Examples

# With actual data, default range (0, 2]
X <- matrix(runif(100 * 3, 0, 10), ncol = 3)
grid1 <- expand_sigma_grid(X, grid_size = 8)

# Custom range with min_mult > 0 (includes min_mult)
grid2 <- expand_sigma_grid(X, grid_size = 8, min_mult = 0.5, max_mult = 3)

# Without data (unit scales)
grid3 <- expand_sigma_grid(n_feat = 3, grid_size = 8)

# Only tiny sigma
grid4 <- expand_sigma_grid(n_feat = 3, grid_size = 0, tiny_sigma = 1e-20)

Plot method for PRTree objects

Description

Provides visualization of a fitted Probabilistic Regression Tree model. Note that the original response vector y is only required for plots 1-4. Plot 5 (terminal node probabilities) can be generated without y.

Usage

## S3 method for class 'prtree'
plot(x, y = NULL, which = NULL, ncol = NULL, ...)

Arguments

Value

Invisibly returns the original object.

Plot method for PRTree Cross-Validation objects

Description

Provides visualizations for cross-validation results of Probabilistic Regression Trees.

Usage

## S3 method for class 'prtree.cv'
plot(x, which = NULL, ncol = NULL, ...)

Arguments

Value

Invisibly returns the original object.

Plot a PRTree as a dendrogram with gamma and P distributions

Description

Draws a tree representation of a fitted PRTree model with root at top. Terminal nodes show gamma coefficients and a mini heatmap of the distribution of the corresponding column of the probability matrix P.

Usage

plot_tree(x, heatmap_width = 0.8, heatmap_height = 0.08, max_bins = 6,
  ...)

Arguments

Value

Invisibly returns the original object.

Probabilistic Regression Trees (PRTrees)

Description

Fits a Probabilistic Regression Tree (PRTree) model. This is the main user-facing function of the package.

Usage

pr_tree(y, X, control = list(), ...)

Arguments

Details

The tree is built using the training data specified by idx_train (or determined by prop_test). If validation data is available (the complement of idx_train), it is used to select the optimal \boldsymbol\sigma values from the grid.

Grid generation:

• If sigma_grid is not provided, it is automatically generated using only the training set (the observations identified by idx_train, which can be passed via control or calculated internally from prop_test). The validation/test data is used only for evaluation.

• Alternatively, users can create a custom grid using the helper function expand_sigma_grid(X, ...) and pass it via the control parameter. This allows using the full dataset (or any desired subset) to define the grid of \boldsymbol\sigma values to be tested.

Important: The returned model is trained only on the training set, not on the combined training + validation data. This matches standard practice where validation data is used only for hyperparameter selection, not for final parameter estimation.

If you want to retrain the model using the selected \boldsymbol\sigma values on a larger dataset (e.g., combining training and validation), you can:

1. Extract the optimal \boldsymbol\sigma from the fitted model (model$sigma)

2. Create a new control object with sigma_grid = matrix(model$sigma, nrow = 1) and set prop_test = 0 to use all data for training

3. Run pr_tree again

Value

An object of class prtree containing the fitted model. This is a list with the following components

See Also

pr_tree_cv for cross-validation options.

pr_tree_control for setting control parameters.

expand_sigma_grid for creating custom sigma grids.

Examples

set.seed(1234)
X <- matrix(runif(200, 0, 10), ncol = 1)
eps <- matrix(rnorm(200, 0, 0.05), ncol = 1)
y <- cos(X) + eps

# Fit model
reg <- pr_tree(y, X, max_terminal_nodes = 9, prop_hold = 0)

# Visualize fit (X is 1D, so we can plot the relationship)
ord <- order(X)
plot(X[ord], reg$yhat[ord],
  type = "l", col = "blue", lwd = 2,
  xlab = "x", ylab = "y",
  main = "PRTree Fit to cos(x)"
)
points(X[ord], y[ord], col = "red", cex = 0.5)
legend("topright",
  legend = c("Fitted", "Observed"),
  col = c("blue", "red"), lty = c(1, NA), pch = c(NA, 1)
)

# Diagnostic plots
par(mar = c(3, 4, 1.5, 1))
plot(reg, y, which = c(1, 4, 2, 5), ncol = 2)

# Plotting the final tree
plot_tree(reg, max_bins = 10)

Control parameters for PRTree

Description

This function creates a list of control parameters for the pr_tree function, with validation for each parameter.

Usage

pr_tree_control(sigma_grid = NULL, grid_size = 8, min_mult = 0,
  max_mult = 2, tiny_sigma = NULL, max_terminal_nodes = 15L,
  max_depth = max_terminal_nodes - 1, cp = 0.01, n_min = 5L,
  prop_x = 0.1, p_min = 0.05, prop_hold = 0.2, idx_train = NULL,
  fill_type = 2L, proxy_crit = "both", n_candidates = 3L,
  by_node = FALSE, dist = "norm", iprint = -1, verbose = TRUE, ...)

Arguments

Details

Custom grid specification

When a custom grid is provided via sigma_grid, it must follow these rules:

• A single number is expanded to a constant vector (same value for all features).

• A numeric vector of length p (the number of features) is used directly as one candidate vector.

• A k \times p numeric matrix provides k candidates, one per row.

In all custom grid cases, the automatic grid parameters (grid_size, min_mult, max_mult, tiny_sigma) are ignored.

Automatic grid generation

The automatic grid is generated as follows:

• For each feature j, the base values are the empirical standard deviations \hat\sigma_j from the training data.

• If grid_size = 1, the grid consists solely of these base values \hat{\boldsymbol\sigma}.

• If grid_size > 1, the grid is constructed using grid_size multipliers equally spaced in the interval:

  • ⁠(min_mult, max_mult]⁠ when min_mult = 0 (excludes 0, includes max_mult).

  • ⁠[min_mult, max_mult]⁠ when min_mult > 0 (both inclusive).

  Each multiplier m generates a candidate vector m \times \hat{\boldsymbol\sigma}.

• If tiny_sigma is provided, it is added as an extra candidate (first row) with \boldsymbol\sigma = \text{tiny\_sigma} \cdot \boldsymbol{1}_p, where \boldsymbol{1}_p is a vector of ones of length p (the number of features). This results in a final grid of size grid_size + 1.

Splitting Constraints and Numerical Stability

The parameters prop_x and p_min work together to control the splitting process. A splitting attempt is made in a given region only when at least a proportion prop_x of the training rows have a probability greater than p_min in that region's column of the probability matrix P. The split will be ignored if any of the resulting child regions do not meet this same criterion.

Warning: Setting either parameter to zero may lead to near-zero columns in P, making the matrix computationally singular or ill-conditioned for inversion.

Data Splitting Strategy The package uses a flexible data splitting strategy controlled by the prop_hold and idx_train arguments:

• Automatic Split (idx_train = NULL): The training indices are computed automatically based on prop_hold. The split uses stratified sampling to ensure that the proportion of observations with missing values is preserved across the training and validation/test sets.

• Manual Split (idx_train provided): The supplied indices are used directly, and prop_hold is ignored. The vector must be a valid subset of 1:nrow(X). This approach is useful for reusing specific splits from previous analyses, performing custom cross-validation, or ensuring identical training sets across different models.

Role of the Hold-out Set When prop_hold > 0 and idx_train is NULL, the exact role of the held-out data depends on the grid search parameters (sigma_grid or grid_size):

• Multiple candidates (grid_size > 1): The hold-out data acts as a validation set to select the best \boldsymbol\sigma. If prop_hold = 0, the selection is based on the in-sample MSE of the training data.

• Single candidate (grid_size = 1): The hold-out data acts as a test set to evaluate the final model. If prop_hold = 0, the entire dataset is used for training without an independent test evaluation.

Value

A list of class prtree.control containing the validated control parameters.

Examples

# Get default control parameters
controls <- pr_tree_control()

# Customize some parameters
ctrl1 <- pr_tree_control(max_depth = 5, n_candidates = 5)

# equivalent calls
ctrl2.v1 <- pr_tree_control(dist = "t", df = 4)
ctrl2.v2 <- pr_tree_control(dist = "t", dist_pars = list(df = 4))

Control parameters for PRTree with optional cross-validation

Description

Creates a list of control parameters for Probabilistic Regression Trees. The base function pr_tree_control returns parameters for tree construction. The extended function pr_tree_control_cv returns both tree parameters and cross-validation settings.

Usage

pr_tree_control_cv(method = "montecarlo", n_rep = 10, only_sigma = FALSE,
  prop_test = 0.2, prop_valid = 0.2, stratify = FALSE,
  update_final = TRUE, fold_idx = NULL, ...)

Arguments

Details

Choosing the right configuration:

Value

A list of class prtree.control_cv containing merged with cross-validation settings

See Also

pr_tree for fitting a single tree,

pr_tree_cv for cross-validation.

Examples

# Default k-fold CV
cv1 <- pr_tree_control_cv()

# Monte Carlo CV with custom parameters
cv2 <- pr_tree_control_cv(
  method = "montecarlo",
  n_iter = 20,
  prop_test = 0.3,
  prop_valid = 0.2,
  stratify = TRUE
)

Cross-Validation for Probabilistic Regression Trees

Description

Performs cross-validation for Probabilistic Regression Trees. Supports both k-fold and Monte Carlo (repeated random subsampling) methods.

Usage

pr_tree_cv(y, X, control_cv = list(), verbose = TRUE, ...)

Arguments

Details

The pr_tree_cv function provides flexible cross-validation for Probabilistic Regression Trees, supporting three common scenarios:

1. Sigma + test error estimation (default)

When both prop_valid > 0 and a grid of \boldsymbol\sigma values is provided (either via control$sigma_grid or automatically generated), the function performs a two-step procedure in each iteration/fold:

• The training data is further split into training and validation sets according to prop_valid.

• The validation set is used to select the optimal \boldsymbol\sigma from the grid.

• The model is then refitted using the full training set (training + validation) with the selected \boldsymbol\sigma.

• Finally, the refitted model is evaluated on the test set.

This yields both the selected \boldsymbol\sigma values for each iteration/fold and estimates of the test error.

2. Test error estimation only (sigma vector fixed)

When prop_valid = 0 or NULL, no internal validation is performed. This is appropriate when \boldsymbol\sigma is already known (e.g., from a previous analysis) and you only need to estimate the test error. In this case:

• The model is trained directly on the full training set using the provided \boldsymbol\sigma values (a vector or 1 by n_feat matrix).

• The test error is computed on the test set.

This mode is computationally lighter and focuses solely on error estimation.

3. Sigma selection only (no test error)

When prop_test = 0 (for Monte Carlo) or when you're interested only in the selected \boldsymbol\sigma values and not in test error estimation, the function can be used without a test set. In this case:

• All data is used for training and validation.

• The optimal \boldsymbol\sigma is selected via internal validation (if prop_valid > 0) or using the full training set (if prop_valid = 0).

• No test error is computed (rmse_by_rep will contain NULL).

This mode is useful when you want to estimate \boldsymbol\sigma from the entire dataset before refitting a final model, or when you're only interested in the stability of \boldsymbol\sigma estimates across different splits.

Cross-validation methods

Two resampling methods are available:

• Monte Carlo CV (method = "montecarlo"): In each of n_iter iterations, the data is randomly split into training (1 - prop_test) and testing (prop_test) sets. Observations may appear in multiple test sets across iterations.

• k-fold CV (method = "kfold"): The data is partitioned into n_folds disjoint subsets. Each fold serves as the test set once, while the remaining n_folds - 1 folds are used for training and validation. This ensures every observation is tested exactly once.

Value

A list of class prtree.cv with components:

Examples

# Generate example data
set.seed(123)
X <- matrix(runif(1000, 0, 10), ncol = 2)
y <- 2 * sin(X[, 1]) + 0.5 * X[, 2] + rnorm(500, 0, 0.2)

# Default k-fold CV
cv1 <- pr_tree_cv(y, X)
plot(cv1)

# Monte Carlo CV with custom parameters
control_cv <- pr_tree_control_cv(
  method = "montecarlo",
  n_iter = 20,
  prop_test = 0.3,
  prop_valid = 0.2
)
cv2 <- pr_tree_cv(y, X, control_cv = control_cv)
plot(cv2)

Predict from a Probabilistic Regression Tree Model

Description

Obtains predictions from a fitted prtree object.

Usage

## S3 method for class 'prtree'
predict(object, newdata, complete = FALSE, ...)

Arguments

Value

If complete = FALSE, a numeric vector of predicted values (yhat). If complete = TRUE, a list containing:

Print method for idx.split objects

Description

Prints a brief summary of a train/test split result.

Usage

## S3 method for class 'idx.split'
print(x, ...)

Arguments

Value

Invisibly returns the original object.

Print method for PRTree objects

Description

Prints a brief summary of a fitted Probabilistic Regression Tree model.

Usage

## S3 method for class 'prtree'
print(x, ...)

Arguments

Value

Invisibly returns the original object.

Print method for PRTree control objects

Description

Prints a summary of the control parameters for PRTree model fitting.

Usage

## S3 method for class 'prtree.control'
print(x, ...)

Arguments

Value

Invisibly returns the original object.

Print method for PRTree control objects

Description

Prints a summary of the control parameters for PRTree model fitting.

Usage

## S3 method for class 'prtree.control_cv'
print(x, ...)

Arguments

Value

Invisibly returns the original object.

Print method for PRTree Cross-Validation objects

Description

Prints a brief summary of cross-validation results for Probabilistic Regression Trees.

Usage

## S3 method for class 'prtree.cv'
print(x, ...)

Arguments

Value

Invisibly returns the original object.

Print method for sigma grid objects

Description

Prints a summary of a sigma grid generated by expand_sigma_grid.

Usage

## S3 method for class 'sigma_grid'
print(x, digits = 4, ...)

Arguments

Value

Invisibly returns the original object.

Print method for summary of idx.split objects

Description

Prints a detailed summary of a train/test split result.

Usage

## S3 method for class 'summary.idx.split'
print(x, ...)

Arguments

Value

Invisibly returns the original object.

Print method for summary of PRTree objects

Description

Prints a summary of a fitted Probabilistic Regression Tree model.

Usage

## S3 method for class 'summary.prtree'
print(x, ...)

Arguments

Value

Invisibly returns the original object.

Print method for summary of PRTree Cross-Validation objects

Description

Prints a detailed summary of cross-validation results.

Usage

## S3 method for class 'summary.prtree.cv'
print(x, ...)

Arguments

Value

Invisibly returns the original object.

Summary method for idx.split objects

Description

Provides a detailed summary of a train/test split result, including statistics about missing values if available.

Usage

## S3 method for class 'idx.split'
summary(object, ...)

Arguments

Value

A list of class summary.idx.split containing detailed statistics.

Summary method for PRTree objects

Description

Provides a detailed summary of a fitted Probabilistic Regression Tree model.

Usage

## S3 method for class 'prtree'
summary(object, ...)

Arguments

Value

A list of class summary.prtree containing summary statistics.

Summary method for PRTree Cross-Validation objects

Description

Provides a detailed summary of cross-validation results for Probabilistic Regression Trees, including statistics for RMSE and selected sigma values.

Usage

## S3 method for class 'prtree.cv'
summary(object, ...)

Arguments

Value

A list of class summary.prtree.cv containing:

Split data into training and testing sets

Description

Creates indices for training and testing sets. Can use simple random sampling or stratified sampling based on missing values.

Usage

train_test_split(n_obs = NULL, prop_test = 0.2, stratify = FALSE,
  is_NA = NULL, n_rep = NULL)

Arguments

Details

The function creates indices for training and testing sets using either simple random sampling or stratified sampling based on missing values.

Stratified sampling: When stratify = TRUE, the sampling preserves the proportion of rows with missing values in both training and testing sets. In this case:

• is_NA must be provided

• n_obs is ignored (determined from is_NA)

Missing values statistics: If is_NA is provided but stratify = FALSE, the function will still compute missing values statistics for the resulting splits. The length of is_NA is against n_obs to ensure consistency. These statistics will be available in the summary output, with a note indicating that they were not used for stratification.

Reproducibility: To ensure reproducible splits, call set.seed before using this function.

Value

An object of class idx.split.

If n_rep = NULL (default), the returned object contains:

• idx_train: Integer vector of training indices.

• idx_test: Integer vector of testing indices (or NULL if prop_test = 0).

• n_train: Integer. Number of training observations.

• n_test: Integer. Number of testing observations.

• stratified: Logical indicating whether stratified sampling was used.

• missing_stats: List with missing-value counts (if is_NA is provided), containing:

  • train_na: Number of rows with missing values in the training set.

  • test_na: Number of rows with missing values in the testing set.

  • total_na: Total number of rows with missing values.

If n_rep is specified, the returned object contains:

• fold_idx: Integer vector indicating the fold assignment of each observation.

• n_rep: Integer. Number of folds.

• stratified: Logical indicating whether stratified sampling was used.

• fold_stats: Data frame summarizing each fold, including the number of observations, the number of rows with missing values, and the corresponding proportion of missing values.

Examples

# Simple random split
set.seed(123)
split <- train_test_split(n_obs = 100, prop_test = 0.3)
str(split)

# Stratified split by missing values
missing <- sample(c(TRUE, FALSE), 100, replace = TRUE, prob = c(0.2, 0.8))
split <- train_test_split(
  prop_test = 0.3,
  stratify = TRUE,
  is_NA = missing
)
summary(split)

# Compute missing stats without stratification
missing2 <- sample(c(TRUE, FALSE), 100, replace = TRUE, prob = c(0.2, 0.8))
split <- train_test_split(
  n_obs = 100,
  prop_test = 0.3,
  stratify = FALSE,
  is_NA = missing2
)
summary(split) # Note about missing stats will appear


# Stratified 10-fold partition
folds <- train_test_split(
  n_obs = 1000,
  is_NA = sample(c(TRUE, FALSE), prob = c(0.1, 0.9), replace = TRUE, size = 1000),
  stratify = TRUE,
  n_rep = 5
)
summary(folds)