Package {FSHybridPLS}

FSHybridPLS: Hybrid Penalized Partial Least Squares

Description

Implements Hybrid Penalized Partial Least Squares regression for predictors that combine functional (fd) curves and scalar covariates in a joint Hilbert space, with roughness penalties on functional coefficient directions.

The main workflow is:

1. Build a hybrid predictor with predictor_hybrid() (or simulate_hybrid_data() for synthetic examples).

2. Optionally preprocess with split_and_normalize_all().

3. Fit with fit_hybridPLS() (optionally tune components via cv_fit_hybridPLS()).

4. Predict with predict.hybridPLS().

The method is described in Mun and Jang (2026) https://doi.org/10.48550/arXiv.2601.16364.

Author(s)

Maintainer: Jongmin Mun jongmin.mun@marshall.usc.edu [copyright holder]

See Also

Useful links:

• https://github.com/Jong-Min-Moon/FShybridPLS

• Report bugs at https://github.com/Jong-Min-Moon/FShybridPLS/issues

Broadcast Addition for Matrices

Description

Adds a single observation (vector) to every row of a matrix. Checks that the input is a matrix and the operand is a single observation.

Usage

add_broadcast(input, other, alpha = 1)

Arguments

Value

A matrix with the broadcasted addition applied.

Add two predictor_hybrid objects

Description

Performs element-wise addition of two predictor_hybrid objects. Supports broadcasting if one object is a single sample.

Usage

add_predictor_hybrid(xi_1, xi_2, alpha = 1)

Arguments

Value

A new predictor_hybrid object representing the result of the addition.

Inter-Modality Normalization (Between Functional and Scalar)

Description

Scales the scalar predictors (Z) so that their total variability is comparable to the total variability of the functional predictors. This addresses the scale invariance issue in PLS by weighting the scalar part.

Usage

btwn_normalize_train_test(train, test)

Arguments

Value

A list containing normalized objects and the scaling factor.

Generate K-Fold Cross-Validation Indices

Description

Generate K-Fold Cross-Validation Indices

Usage

create_idx_kfold(n_sample, n_fold)

Arguments

Value

A list of length n_fold; each element has idx_train and idx_valid.

Examples

set.seed(1)
folds <- create_idx_kfold(20, 4)
length(folds)
length(folds[[1]]$idx_valid)

Normalize a functional data object

Description

Subtracts a mean function and divides by a scalar constant. Manual broadcasting is used to ensure robust subtraction across samples.

Usage

curve_normalize(functional, mean_functional, deno)

Arguments

Value

A normalized fd object.

Normalize Functional Predictors (Train/Test Split)

Description

Standardizes functional predictors to have mean zero and unit integrated variance. Statistics (mean and SD) are computed from the training set and applied to the test set.

Usage

curve_normalize_train_test(train, test)

Arguments

Value

A list containing:

predictor_train

The normalized training object.

predictor_test

The normalized testing object.

mean_train

List of mean functions used for centering.

deno_train

Vector of scaling factors used.

Cross-Validated Hybrid Penalized PLS

Description

Fits fit_hybridPLS() on K training folds and records mean validation RMSE for each number of components. Useful for choosing n_iter.

Usage

cv_fit_hybridPLS(W, y, n_iter, lambda, n_fold = 5, seed = NULL)

Arguments

Value

A list with:

rmse_by_component

Mean validation RMSE for components 1:n_iter.

best_n_iter

Component count with smallest mean RMSE.

fold_rmse

Matrix of fold-wise RMSE (n_fold x n_iter).

Examples

set.seed(1)
sim <- simulate_hybrid_data(n = 40, n_basis = 5)
cv <- cv_fit_hybridPLS(sim$W, sim$y, n_iter = 3, lambda = 1e-3, n_fold = 3)
cv$best_n_iter

Fit Hybrid Penalized PLS

Description

Runs the iterative Hybrid Penalized Partial Least Squares algorithm. If validation_data is provided, RMSE on the validation set is stored for each extracted component.

Usage

fit.hybridPLS(W, y, n_iter, lambda, validation_data = NULL)

fit_hybridPLS(W, y, n_iter, lambda, validation_data = NULL)

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

Arguments

Value

An object of class hybridPLS, a list with:

rho

List of score vectors (length n_iter).

xi

List of weight directions as single-sample predictor_hybrid objects.

beta

List of cumulative regression directions; beta[[L]] uses the first L components.

W

List of deflated predictors; W[[1]] is the input, W[[l+1]] is after extracting component l.

delta

List of predictor loadings.

nu

List of response loadings (scalars).

n_iter, lambda

Fitting settings.

validation_rmse

Numeric vector of validation RMSE by component, or NULL.

Examples

set.seed(1)
sim <- simulate_hybrid_data(n = 40, n_functional = 1, n_scalar = 2, n_basis = 5)
fit <- fit_hybridPLS(sim$W, sim$y, n_iter = 2, lambda = 1e-3)
fit
pred <- predict(fit, sim$W, n_components = 2)
cor(pred, sim$y)

Compute hybrid regression coefficient (delta)

Description

Weighted average of predictor observations with weights rho.

Usage

get_delta(W, rho)

Arguments

Value

A single-sample predictor_hybrid object.

Compute scalar regression coefficient (nu)

Description

Compute scalar regression coefficient (nu)

Usage

get_nu(y, rho)

Arguments

Value

Scalar regression coefficient.

Compute Penalized PLS Weight Vector (Linear)

Description

Solves for the PLS weight direction xi that maximizes the covariance with y, subject to roughness penalties on the functional components.

Usage

get_xi_hat_linear_pen(W, y, lambda)

Arguments

Value

A single-sample predictor_hybrid object representing the weight direction xi.

Algebraic Inner Product for Hybrid Objects

Description

Uses pre-computed Gram matrices to calculate hybrid inner products without numerical integration.

Usage

inprod.predictor_hybrid(xi_1, xi_2 = NULL)

inprod_predictor_hybrid(xi_1, xi_2 = NULL)

Arguments

Value

A numeric scalar or vector of inner products. When one argument has a single sample and the other has N samples, returns a length-N vector (broadcasted projection).

Examples

set.seed(1)
sim <- simulate_hybrid_data(n = 20, n_basis = 5)
fit <- fit_hybridPLS(sim$W, sim$y, n_iter = 1, lambda = 1e-3)
scores <- inprod_predictor_hybrid(sim$W, fit$xi[[1]])
length(scores)

Penalized Inner Product for Hybrid Objects

Description

Computes the unpenalized hybrid inner product plus roughness penalties on functional components: \langle \xi_1, \xi_2 \rangle + \sum_k \lambda_k \langle D^m \xi_{1k}, D^m \xi_{2k} \rangle.

Usage

inprod_pen.predictor_hybrid(xi_1, xi_2 = NULL, lambda)

inprod_pen_predictor_hybrid(xi_1, xi_2 = NULL, lambda)

Arguments

Value

A numeric scalar (or vector under broadcasting), the penalized inner product.

Examples

set.seed(1)
sim <- simulate_hybrid_data(n = 20, n_basis = 5)
fit <- fit_hybridPLS(sim$W, sim$y, n_iter = 2, lambda = 1e-3)
inprod_pen_predictor_hybrid(fit$xi[[1]], fit$xi[[1]], lambda = 1e-3)

Load and Preprocess Kidney Data for FSHybridPLS

Description

Processes a raw kidney study data frame into a predictor_hybrid object and a scaled response. The input is expected to contain at least columns ID, Study, and renogram_value, plus clinical covariates used for the response and scalar predictors (accessed by the positional columns described in the paper workflow).

Usage

load_and_preprocess_kidney_data(kidney_df, n_basis = 20)

Arguments

Details

This helper is application-specific and requires user-supplied data; it is not needed for the core Hybrid PLS algorithm.

Value

A list with:

W

A predictor_hybrid object.

y

Min-max scaled numeric response in [0,1].

Examples

try(load_and_preprocess_kidney_data(data.frame(x = 1)), silent = TRUE)

Predict from a Hybrid PLS Model

Description

Computes fitted or predicted responses using the cumulative coefficient direction beta[[n_components]].

Usage

## S3 method for class 'hybridPLS'
predict(object, newdata = NULL, n_components = object$n_iter, ...)

Arguments

Value

Numeric vector of predictions (length newdata$n_sample).

Examples

set.seed(1)
sim <- simulate_hybrid_data(n = 30, n_basis = 5)
fit <- fit_hybridPLS(sim$W, sim$y, n_iter = 2, lambda = 1e-3)
head(predict(fit, sim$W))

Create a predictor_hybrid object

Description

Constructs an S3 object of class predictor_hybrid that stores scalar covariates and functional predictors in a joint representation, along with precomputed Gram and roughness-penalty matrices used by Hybrid PLS.

Usage

predictor_hybrid(Z, functional_list, eval_point, penalty_order = 2)

Arguments

Value

An object of class predictor_hybrid, a named list with:

Z

Scalar predictor matrix (n_sample x n_scalar).

functional_list

List of fd objects for the functional predictors.

gram_list

List of Gram (inner-product) matrices for each functional basis.

gram_deriv_list

List of roughness-penalty matrices for each functional basis.

eval_point

Numeric vector of evaluation points for the functional domain.

n_basis_list

Number of basis functions for each functional predictor.

n_sample

Number of samples.

n_functional

Number of functional predictors.

n_scalar

Number of scalar predictors.

Examples

library(fda)
# Create basis and functional data
fbasis <- create.bspline.basis(c(0, 1), 5)
coefs <- matrix(rnorm(15), 5, 3)
fd_obj <- fd(coefs, fbasis)

# Scalar data
Z_mat <- matrix(rnorm(9), 3, 3)

# Construct hybrid predictor
W <- predictor_hybrid(
  Z = Z_mat,
  functional_list = list(fd_obj),
  eval_point = seq(0, 1, 0.1)
)
class(W)
W$n_sample
W$n_functional
W$n_scalar

Construct a Single-Sample Predictor Hybrid Object from Coefficients

Description

Construct a Single-Sample Predictor Hybrid Object from Coefficients

Usage

predictor_hybrid_from_coef(format, coef)

Arguments

Value

A single-sample predictor_hybrid object.

Replicate a list of single-sample fd objects multiple times

Description

This function broadcasts a list of single-sample functional predictors by replicating their coefficient columns.

Usage

rep_fd(fd_list, n)

Arguments

Value

A list of fd objects, each with n replications.

Residualize the hybrid predictor

Description

Updates each observation in W by subtracting the projection onto rho (rho_i * delta) using vectorized linear algebra.

Usage

residualize_predictor(W, rho, delta)

Arguments

Value

The residualized predictor_hybrid object.

Residualize the response vector

Description

Residualize the response vector

Usage

residualize_y(y, rho, nu)

Arguments

Value

Residualized response.

Multiply a predictor_hybrid object by a scalar

Description

Performs scalar multiplication on both the scalar and functional components of a predictor_hybrid object. Functional predictors are scaled using times.fd() from the fda package.

Usage

scalar_mul_predictor_hybrid(input, scalar)

Arguments

Value

A new predictor_hybrid object scaled by scalar.

Normalize a scalar predictor matrix

Description

Centers columns by 'mean' and scales them by 'deno'.

Usage

scalar_normalize(scalar_predictor, mean, deno)

Arguments

Value

Normalized matrix.

Normalize Scalar Predictors (Train/Test Split)

Description

Standardizes scalar predictors (Z) to have mean zero and unit variance. Statistics are computed from the training set.

Usage

scalar_normalize_train_test(predictor_train, predictor_test)

Arguments

Value

A list containing normalized objects and statistics.

Simulate Hybrid Functional-Scalar Regression Data

Description

Generates synthetic hybrid predictors (functional curves + scalar covariates) and a scalar response useful for examples and testing.

Usage

simulate_hybrid_data(
  n = 50,
  n_functional = 1,
  n_scalar = 3,
  n_basis = 7,
  n_eval = 51,
  signal_to_noise = 3,
  seed = NULL
)

Arguments

Value

A list with:

W

A predictor_hybrid object.

y

Numeric response vector of length n.

beta_true

Single-sample predictor_hybrid used to generate the linear signal.

Examples

set.seed(1)
sim <- simulate_hybrid_data(n = 25, n_functional = 1, n_scalar = 2, n_basis = 5)
class(sim$W)
length(sim$y)

Split Hybrid Predictor and Response Data

Description

Randomly partitions the hybrid predictor object and response vector into training and testing sets based on a given ratio.

Usage

split_all(W_hybrid, response, train_ratio)

Arguments

Value

A named list with:

predictor_train, predictor_test

predictor_hybrid objects.

response_train, response_test

Response vectors for each split.

train_idx, test_idx

Integer indices used for the split.

Examples

set.seed(1)
sim <- simulate_hybrid_data(n = 30, n_basis = 5)
parts <- split_all(sim$W, sim$y, train_ratio = 0.7)
length(parts$response_train) > 0
length(parts$response_test) > 0
inherits(parts$predictor_train, "predictor_hybrid")

Split and Preprocess Hybrid Data

Description

Full preprocessing pipeline: train/test split, within-modality standardization for functional and scalar predictors, between-modality variance balancing, and response standardization (train statistics applied to test).

Usage

split_and_normalize.all(W_hybrid, response, train_ratio)

split_and_normalize_all(W_hybrid, response, train_ratio)

Arguments

Value

A list with:

predictor_train, predictor_test

Normalized predictor_hybrid objects.

response_train, response_test

Standardized responses.

details

Intermediate normalization objects and split indices.

Examples

set.seed(1)
sim <- simulate_hybrid_data(n = 40, n_basis = 5)
prep <- split_and_normalize_all(sim$W, sim$y, train_ratio = 0.7)
fit <- fit_hybridPLS(
  prep$predictor_train,
  prep$response_train,
  n_iter = 2,
  lambda = 1e-3,
  validation_data = list(
    W_test = prep$predictor_test,
    y_test = prep$response_test
  )
)
fit$validation_rmse

Broadcast Subtraction for Matrices

Description

Subtracts a single observation (vector) from every row of a matrix.

Usage

subtr_broadcast(input, other, alpha = 1)

Arguments

Value

A matrix with the broadcasted subtraction applied.

Subtract two predictor_hybrid objects

Description

Performs element-wise subtraction of two predictor_hybrid objects. Internally uses add_predictor_hybrid(input, other, alpha = -1).

Usage

subtr_predictor_hybrid(input, other, alpha = 1)

Arguments

Value

A new predictor_hybrid object representing the result of subtraction.