path_effects: Analyse Multivariate Path Effects

In multiblock: Multiblock Data Fusion in Statistics and Machine Learning

Analyse Multivariate Path Effects

Description

Decomposes effects between blocks in a multiblock system into total effects, unique effects, common contributions, and additional effects. Supports both SO-PLS (Sequential Orthogonalised PLS) and ordinary least squares (OLS) approaches with cross-validation or fitted values.

Usage

path_effects(
  relations,
  blocks,
  validation,
  segments,
  SO = TRUE,
  fits = FALSE,
  boot = 0,
  ncomp = NULL,
  transitive_closure = FALSE,
  ...
)

Arguments

relations	A matrix defining the path structure. Rows specify relationships between blocks, with 2 columns: c(from_block_index, to_block_index).
blocks	A multiblock data frame or list of named matrices containing the block data.
validation	Validation method passed to pls::plsr(). Common options: "CV" for cross-validation, "LOO" for leave-one-out validation, or "none" for fitted values.
segments	Number of segments for cross-validation. Default is 5.
SO	Logical. If TRUE (default), use SO-PLS; if FALSE, use OLS.
fits	Logical. If TRUE, use fitted values instead of cross-validation. Default is FALSE.
boot	Number of bootstrap samples for computing standard errors. Default is 0 (no bootstrapping).
ncomp	Optional component settings per predictor block. Supply either: a vector with length equal to the number of predictor blocks (unique(relations[,1])), in ascending predictor-block order, or a full-length vector with one entry per block (non-predictors may be 0). Positive integers set upper limits; negative integers force exact component counts. All predictor entries must be non-zero and have the same sign.
transitive_closure	Logical. If TRUE, automatically add transitive closure to the relations. Default is FALSE.
...	Additional arguments passed to underlying fitting functions.

Value

An object of class path_effects, which is a matrix with the following components for each path:

• Tot: Total effect

• Un: Unique effect

• Co: Common contribution

• Ad: Additional effect

Attributes include:

• scaled: Scaled contribution matrix

• individual: Individual-level contributions

• boot: Bootstrap replicates (if boot > 0)

See Also

print.path_effects(), plot.path_effects()

Examples

# Analysis of the mobile dataset
data(mobile)

# Define path structure (A->B, A->E, A->G, B->C, B->D, B->E, C->D, D->E, 
#                        D->E, E->F, E->G, F->G)
paths <- matrix(c(1,2, 1,5, 1,7, 2,3, 2,4, 2,5, 3,4, 3,5, # Add 0,2, for A->C
                  4,5, 5,6, 5,7, 6,7),
                ncol=2, byrow=TRUE)

# Compute path effects with cross-validation using SO-PLS
pem <- path_effects(paths, mobile, validation="CV", segments=5, 
                    segment.type="consecutive")

# Print results
print(pem)

# Plot all results
plot(pem)

# Print and plot single path
print(pem, "A","G")
plot(pem, from = "A", to = "G")

# Print and plot results per variable
print(pem, individual = TRUE)
plot(pem, individual = TRUE)

# Analysis of the NIR-Raman-PUFA data (emulsions) 
data(emulsions)

# Standardise response
emulsions$PUFA <- scale(emulsions$PUFA)

# Define path structure (NIR->Raman, NIR->PUFA, Raman->PUFA)
paths_NRP <- matrix(c(1,2,1,3,2,3), ncol = 2, byrow = TRUE)

## Not run:  # Too time consuming
# Compute path effects with cross-validation using SO-PLS
pem_NRP <- path_effects(paths_NRP, emulsions, validation="CV", 
                    segments = 5, segment.type="consecutive", 
                    ncomp=c(16,15))
                    
# Print results
print(pem_NRP)

# Plot all results
plot(pem_NRP)

## End(Not run)
# Reversed order of NIR and Raman (uncomment to run)
# paths_RNP <- matrix(c(2,1,2,3,1,3), ncol = 2, byrow = TRUE)
# pem_RNP <- path_effects(paths_RNP, emulsions, validation="CV",
#                   segments = 5, segment.type="consecutive", ncomp=c(16,15))
# print(pem_RNP)

multiblock documentation built on July 10, 2026, 1:07 a.m.