Package {PLSsemEngine}

Non-Parametric Bootstrap for Structural Paths

Description

Executes a case-level percentile bootstrap to assess the statistical significance of structural path coefficients. Crucially, to capture the total sampling uncertainty, this function performs a full-model re-estimation for every bootstrap replica, recalculating both outer weights and inner paths.

Usage

bootstrap_paths(
  data,
  measurement_model,
  structural_model,
  nboot = 500,
  seed = 123,
  sign_correction = FALSE,
  inner_scheme = "factorial"
)

Arguments

Value

A data frame containing the estimated path coefficients for all bootstrap iterations.

Examples

set.seed(1)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100)
)
mm <- list(Quality = c("SQ1", "SQ2", "SQ3"), Satisfaction = c("CS1", "CS2", "CS3"))
sm <- list(Satisfaction ~ Quality)
boot <- bootstrap_paths(dat, mm, sm, nboot = 20)
head(boot)

Compute Full Collinearity VIF for Common Method Bias

Description

Assesses potential common method bias using the full collinearity VIF approach proposed by Kock (2015). Values above 3.3 may indicate pathological collinearity. In line with the engine's design philosophy, no automatic classification or model modification is applied.

Usage

compute_cmb_vif(scores, digits = 2)

Arguments

Value

A data frame containing the VIF values for each construct.

Examples

set.seed(1)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100)
)
mm <- list(Quality = c("SQ1", "SQ2", "SQ3"), Satisfaction = c("CS1", "CS2", "CS3"))
sm <- list(Satisfaction ~ Quality)
engine <- pls_engine(dat, mm, sm)
compute_cmb_vif(engine$scores)

Compute HTMT and HTMT2 Ratios for Discriminant Validity

Description

Computes the Heterotrait-Monotrait ratio of correlations (HTMT) following Henseler et al. (2015), and the revised HTMT2 following Roemer et al. (2021). HTMT2 uses the geometric mean to relax the tau-equivalence assumption, making it suitable for congeneric models.

Usage

compute_htmt_metrics(data, measurement_model, digits = 2)

Arguments

Value

A list containing the HTMT and HTMT2 symmetric matrices.

Examples

set.seed(1)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100)
)
mm <- list(Quality = c("SQ1", "SQ2", "SQ3"), Satisfaction = c("CS1", "CS2", "CS3"))
compute_htmt_metrics(dat, mm)

Compute Global Model Fit Indices

Description

Calculates global fit indices including the Standardised Root Mean Square Residual (SRMR), exact squared Euclidean distance (d_ULS), and exact geodesic distance (d_G). Calculations are based on the saturated model-implied correlation matrix following Henseler et al. (2014).

Usage

compute_model_fit(engine, data, measurement_model, digits = 3)

Arguments

Value

A data frame containing the computed fit metrics.

Examples

set.seed(1)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100)
)
mm <- list(Quality = c("SQ1", "SQ2", "SQ3"), Satisfaction = c("CS1", "CS2", "CS3"))
sm <- list(Satisfaction ~ Quality)
engine <- pls_engine(dat, mm, sm)
compute_model_fit(engine, dat, mm)

Cross-Validated Predictive Ability Test (CVPAT)

Description

Implements the Cross-Validated Predictive Ability Test (CVPAT) proposed by Liengaard et al. (2021) and extended by Sharma et al. (2023). Unlike PLSpredict, which provides descriptive predictive metrics (RMSE, Q2_predict), CVPAT provides an inferential test of whether the PLS model predicts significantly better than the naive linear model (LM) benchmark.

The test computes, for each fold and each endogenous indicator, the mean squared loss difference (MSE_LM - MSE_PLS). A one-sample t-test evaluates whether the average loss difference across folds is significantly greater than zero (H0: mean loss difference = 0). A positive and significant result indicates that the PLS model predicts significantly better than the benchmark.

Usage

cvpat(plspredict_result)

Arguments

Value

A data frame with one row per endogenous indicator, reporting: mean loss difference, standard deviation, t-statistic, degrees of freedom, p-value, and a significance flag. An attribute "interpretation" is attached with a brief methodological note.

References

Liengaard, B. D., Sharma, P. N., Hult, G. T. M., Jensen, M. B., Sarstedt, M., Hair, J. F., & Ringle, C. M. (2021). Prediction: coveted, yet forsaken? Introducing a cross-validated predictive ability test in partial least squares path modeling. Decision Sciences, 52(2), 362-392.

Sharma, P. N., Liengaard, B. D., Hair, J. F., Sarstedt, M., & Ringle, C. M. (2023). Predictive model assessment and selection in composite-based modeling using PLS-SEM: extensions and guidelines for using CVPAT. European Journal of Marketing, 57(6), 1662-1677.

Examples

set.seed(1)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100)
)
mm <- list(Quality = c("SQ1", "SQ2", "SQ3"), Satisfaction = c("CS1", "CS2", "CS3"))
sm <- list(Satisfaction ~ Quality)
pred <- plspredict(dat, mm, sm, k = 5)
cvpat(pred)

Export to Lavaan Syntax (CB-SEM / CFA Integration)

Description

Actively encourages cross-methodological validation by natively translating the PLSsemEngine model specification into lavaan-compatible syntax. This allows researchers to seamlessly evaluate their composite models against common factor models (CFA).

Usage

export_lavaan_syntax(measurement_model, structural_model = NULL)

Arguments

Value

Invisibly returns the generated lavaan syntax string while printing it to the console.

Examples

mm <- list(
  Quality = c("SQ1", "SQ2", "SQ3"),
  Satisfaction = c("CS1", "CS2", "CS3"),
  Loyalty = c("CL1", "CL2", "CL3")
)
sm <- list(
  Satisfaction ~ Quality,
  Loyalty ~ Satisfaction + Quality
)
export_lavaan_syntax(mm, sm)

Export Latent Variable Scores

Description

Extracts and exports the estimated latent variable scores to a CSV file. A sequential 'Case' identifier is appended to improve data traceability and facilitate subsequent external analyses.

Usage

export_scores(model, file = NULL)

Arguments

Value

Invisibly returns the data frame of scores while writing the CSV file to disk.

Examples

set.seed(123)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100),
  CL1 = rnorm(100), CL2 = rnorm(100), CL3 = rnorm(100)
)
mm <- list(
  Quality = c("SQ1", "SQ2", "SQ3"),
  Satisfaction = c("CS1", "CS2", "CS3"),
  Loyalty = c("CL1", "CL2", "CL3")
)
sm <- list(
  Satisfaction ~ Quality,
  Loyalty ~ Satisfaction + Quality
)
model <- pls_sem(dat, mm, sm, nboot = 20)
out_file <- file.path(tempdir(), "latent_scores.csv")
export_scores(model, file = out_file)
unlink(out_file)

Calculate Exact Boundary Intersections for Rectangles

Description

A geometric helper function that calculates the precise offset required for arrow positioning, ensuring that structural paths touch the boundaries of the construct rectangles rather than overlapping them.

Usage

get_boundary_offset(angle, bw, bh)

Arguments

Value

Numeric. The geometric offset distance.

Examples

get_boundary_offset(angle = pi / 4, bw = 1.1, bh = 0.3)

Calculate Indirect Effects

Description

Computes indirect effects as the mathematical product of the respective structural path coefficients. Consistent with the engine's design philosophy, no automated mediation classifications (e.g., "full" or "partial") are provided, ensuring the theoretical interpretation remains entirely in the hands of the researcher.

Usage

get_indirect_effects(model, digits = 3)

Arguments

Value

A data frame containing the calculated indirect effects, or NULL if no structural mediators exist.

Examples

set.seed(123)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100),
  CL1 = rnorm(100), CL2 = rnorm(100), CL3 = rnorm(100)
)
mm <- list(
  Quality = c("SQ1", "SQ2", "SQ3"),
  Satisfaction = c("CS1", "CS2", "CS3"),
  Loyalty = c("CL1", "CL2", "CL3")
)
sm <- list(
  Satisfaction ~ Quality,
  Loyalty ~ Satisfaction + Quality
)
model <- pls_sem(dat, mm, sm, nboot = 20)
get_indirect_effects(model)

Retrieve Standard Methodological References

Description

Provides a quick-reference table outlining standard evaluation heuristics and literature citations for PLS-SEM. This tool is intended to support researcher-led interpretation rather than enforce mechanical rule application.

Usage

get_references()

Value

A data frame mapping analytical components to standard thresholds and academic references.

Examples

get_references()

HTMT-Guided Item Diagnostics

Description

When discriminant validity is compromised at the construct level (HTMT > threshold), this function provides a granular, item-level diagnostic. It calculates cross-construct correlations to help researchers isolate specific problematic indicators that may be inflating the trait ratios.

Usage

htmt_item_diagnostics(model, threshold = 0.85, digits = 2)

Arguments

Value

A data frame detailing problematic construct pairs and their item-level cross-correlations, or NULL if no issues are detected.

Examples

set.seed(123)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100),
  CL1 = rnorm(100), CL2 = rnorm(100), CL3 = rnorm(100)
)
mm <- list(
  Quality = c("SQ1", "SQ2", "SQ3"),
  Satisfaction = c("CS1", "CS2", "CS3"),
  Loyalty = c("CL1", "CL2", "CL3")
)
sm <- list(
  Satisfaction ~ Quality,
  Loyalty ~ Satisfaction + Quality
)
model <- pls_sem(dat, mm, sm, nboot = 20)
htmt_item_diagnostics(model)

Optional Methodological Assessment

Description

Provides a narrative diagnostic layer based on established PLS-SEM literature (e.g., Hair et al., 2017; Henseler et al., 2015). Crucially, this function contextualises the raw metrics without imposing mechanical or automated decision-making, keeping the final analytical judgement with the researcher.

Usage

interpret_model(model)

Arguments

Value

Invisibly prints a structured console report flagging potential issues.

Examples

set.seed(123)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100),
  CL1 = rnorm(100), CL2 = rnorm(100), CL3 = rnorm(100)
)
mm <- list(
  Quality = c("SQ1", "SQ2", "SQ3"),
  Satisfaction = c("CS1", "CS2", "CS3"),
  Loyalty = c("CL1", "CL2", "CL3")
)
sm <- list(
  Satisfaction ~ Quality,
  Loyalty ~ Satisfaction + Quality
)
model <- pls_sem(dat, mm, sm, nboot = 20)
interpret_model(model)

Plot Model Results (Beta & R-squared)

Description

Overlays the estimated path coefficients and R-squared values onto the structural model plot. In response to usability requests, R-squared values can be toggled on or off to provide maximum formatting flexibility.

Usage

plot_model_results(
  model,
  layout = NULL,
  show_r2 = TRUE,
  box_width = 1.1,
  box_height = 0.3,
  cex_node = 0.9,
  cex_beta = 0.8,
  cex_r2 = 0.75,
  arr_lwd = 1.2,
  box_col = "white",
  save_plot = FALSE,
  file_name = NULL,
  width = 2500,
  height = 1500,
  res = 300
)

Arguments

Value

Invisibly generates a plot on the active graphic device.

Examples

set.seed(123)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100),
  CL1 = rnorm(100), CL2 = rnorm(100), CL3 = rnorm(100)
)
mm <- list(
  Quality = c("SQ1", "SQ2", "SQ3"),
  Satisfaction = c("CS1", "CS2", "CS3"),
  Loyalty = c("CL1", "CL2", "CL3")
)
sm <- list(
  Satisfaction ~ Quality,
  Loyalty ~ Satisfaction + Quality
)
model <- pls_sem(dat, mm, sm, nboot = 20)
plot_model_results(model)

Plot Structural Model Base Geometry

Description

Generates a pure base R plot of the structural model layout. It relies exclusively on native graphical parameters to avoid third-party dependencies, ensuring long-term reproducibility and stability.

Usage

plot_structural_model(
  structural_model,
  layout = NULL,
  box_width = 1.1,
  box_height = 0.3,
  cex_node = 0.9,
  arr_lwd = 1.2,
  box_col = "white",
  save_plot = FALSE,
  file_name = NULL,
  width = 2500,
  height = 1500,
  res = 300
)

Arguments

Value

Invisibly generates a plot on the active graphic device.

Examples

sm <- list(
  Satisfaction ~ Quality,
  Loyalty ~ Satisfaction + Quality
)
plot_structural_model(sm)

Core PLS-SEM Estimation Engine (Mode A)

Description

Implements the standard Partial Least Squares (PLS) iterative algorithm restricted to reflective measurement models (Mode A). The engine estimates latent variable scores, indicator loadings, and structural path coefficients using pure matrix operations. By design, it avoids automatic model re-specification or hidden interpretative heuristics.

Usage

pls_engine(
  data,
  measurement_model,
  structural_model,
  max_iter = 300,
  tol = 1e-06,
  sign_correction = FALSE,
  inner_scheme = "factorial"
)

Arguments

Value

A list containing latent scores, outer weights, indicator loadings, structural paths, R-squared values, and metadata.

Examples

set.seed(1)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100)
)
mm <- list(Quality = c("SQ1", "SQ2", "SQ3"), Satisfaction = c("CS1", "CS2", "CS3"))
sm <- list(Satisfaction ~ Quality)
engine <- pls_engine(dat, mm, sm)
engine$paths

Estimate a PLS-SEM Model (Mode A)

Description

This is the main high-level wrapper of the PLSsemEngine. It coordinates the estimation, assessment, and predictive evaluation stages, returning all results in a structured, publication-ready S3 object. It deliberately restricts estimation to reflective blocks (Mode A) and avoids hidden model modifications.

Usage

pls_sem(
  data,
  measurement_model,
  structural_model,
  k = 5,
  nboot = 500,
  digits = 2,
  sign_correction = FALSE,
  inner_scheme = "factorial"
)

Arguments

Value

A list of class 'pls_model' containing structured tables for measurement, structural, and predictive assessments.

Examples

set.seed(123)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100),
  CL1 = rnorm(100), CL2 = rnorm(100), CL3 = rnorm(100)
)
mm <- list(
  Quality = c("SQ1", "SQ2", "SQ3"),
  Satisfaction = c("CS1", "CS2", "CS3"),
  Loyalty = c("CL1", "CL2", "CL3")
)
sm <- list(
  Satisfaction ~ Quality,
  Loyalty ~ Satisfaction + Quality
)
model <- pls_sem(dat, mm, sm, nboot = 20)
model$structural_model

PLSpredict: Out-of-Sample Predictive Evaluation

Description

Implements the PLSpredict algorithm using k-fold cross-validation. The function estimates the model exclusively on the training set and explicitly projects the outer weights onto the test set. Predictive performance (RMSE) is then compared against a naive linear model (LM) benchmark. Fold-level losses are retained to enable inferential testing via cvpat().

Usage

plspredict(
  data,
  measurement_model,
  structural_model,
  k = 5,
  seed = 123,
  sign_correction = FALSE,
  inner_scheme = "factorial"
)

Arguments

Value

A list containing a predictive evaluation table (RMSE and Q2_predict), fold-level squared losses per indicator (fold_losses), and conditional warnings.

Examples

set.seed(1)
dat <- data.frame(
  SQ1 = rnorm(100), SQ2 = rnorm(100), SQ3 = rnorm(100),
  CS1 = rnorm(100), CS2 = rnorm(100), CS3 = rnorm(100)
)
mm <- list(Quality = c("SQ1", "SQ2", "SQ3"), Satisfaction = c("CS1", "CS2", "CS3"))
sm <- list(Satisfaction ~ Quality)
pred <- plspredict(dat, mm, sm, k = 5)
pred$table