msma

msma is an R package for sparse multivariable analysis, including PCA, PLS, supervised analysis, and multiblock methods.

This repository provides msma 5.1.

Version 4.0 introduced supervised sparse soft-structured PCA while preserving the default computational paths of msma 3.2. Version 5.0 extended the prediction workflow and strengthened the supervision contract. Version 5.1 is a corrective release that improves the portability of prediction regression tests across BLAS/LAPACK platforms, including macOS on Apple Silicon.

The package implementation, default behavior, fitted-object structure, and public API are unchanged between versions 5.0 and 5.1.

Current release

Version 5.1 corrects platform-dependent prediction regression tests identified by CRAN on macOS arm64. Numerically equivalent results are compared using an explicit tolerance of 1e-12. The revised package passed 1,028 regression expectations and completed R CMD check successfully on aarch64-apple-darwin23.

The package implementation, default behavior, fitted-object structure, and public API are unchanged from version 5.0.

See NEWS for release details.

Main additions in Version 4.0

The ordinary msma() interface remains unchanged unless structured PCA is explicitly requested.

Version 5 prediction workflow

Version 5 extends predict.msma() while preserving the historical prediction behavior as the default.

predict.msma() projects and reconstructs supplied X-side and Y-side data. It does not predict Y from X.

set.seed(1)
X <- matrix(stats::rnorm(180), nrow = 30, ncol = 6)
colnames(X) <- paste0("x", seq_len(ncol(X)))

fit <- msma(X = X, comp = 2, scaling = TRUE, intseed = 3)

prediction <- predict(
  fit,
  newX = X[1:5, , drop = FALSE],
  preprocessing = "fitted",
  reconstruction = "fitted",
  output_scale = "original"
)

names(prediction)

Prediction controls are preprocessing, reconstruction, and output_scale. Component scores sbX and sbY remain on the analysis scale. output_scale controls reconstructed X and Y values.

Installation

Tagged GitHub release candidate

install.packages("remotes")
remotes::install_github("kawa-a/msma", ref = "v5.1")

Separate test library

test_library <- path.expand("~/R/msma-5.1")
dir.create(test_library, recursive = TRUE, showWarnings = FALSE)

remotes::install_github(
  "kawa-a/msma",
  ref = "v5.1",
  lib = test_library
)

library(msma, lib.loc = test_library)
packageVersion("msma")
find.package("msma", lib.loc = test_library)

Backward compatibility

Existing analyses stay on the Version 3.2 computational path when structured PCA is not requested.

fit <- msma(
  X = X,
  Z = Z,
  comp = 2,
  lambdaX = 0.10,
  muX = 0.50
)

This is equivalent to explicitly specifying:

fit <- msma(
  X = X,
  Z = Z,
  comp = 2,
  lambdaX = 0.10,
  muX = 0.50,
  structure.method = "none",
  gammaX = 0
)

Soft-structured PCA

set.seed(4)
n <- 80
p <- 30
X <- scale(matrix(rnorm(n * p), nrow = n, ncol = p))
Z <- as.numeric(scale(0.8 * X[, 1] - 0.5 * X[, 5] + rnorm(n)))
colnames(X) <- paste0("x", seq_len(p))

fit <- msma(
  X = X,
  Z = Z,
  comp = 3,
  lambdaX = 0.10,
  muX = 0.80,
  structure.method = "soft",
  gammaX = 0.10,
  history.method = "sumabs",
  niterS4 = 30,
  scaling = FALSE,
  intseed = 4
)

fit$W
fit$S
fit$overlap_all
fit$overlap_selected
fit$diagnostics

Conceptually, for component $k$ the variable-specific threshold is

$$ \lambda_{jk} = \lambda_X + \gamma_X h_{j,k-1}, $$

with the reference-compatible default

$$ h_{j,k-1} = \sum_{\ell < k} |w_{j\ell}|. $$

Hard-exclusive PCA

fit_exclusive <- msma(
  X = X,
  Z = Z,
  comp = 3,
  lambdaX = 0.05,
  muX = 0.80,
  structure.method = "exclusive",
  niterS4 = 30,
  scaling = FALSE,
  intseed = 4
)

Reconstruction

X_reconstructed <- s4pca_reconstruct(fit)
X_new_reconstructed <- s4pca_reconstruct(
  fit,
  newdata = X[1:10, , drop = FALSE]
)

When a model is fitted with scaling = TRUE, the default reconstruction is returned on the original scale. Use scaled = TRUE for the standardized scale.

Repeated split model selection

selection <- s4pca_conformal_select(
  X = X,
  Z = Z,
  lambdaX = c(0.05, 0.10),
  gammaX = c(0, 0.10),
  comp = 2:3,
  alpha = 0.10,
  repeats = 3,
  calibration_fraction = 0.25,
  max_overlap = 0.50,
  muX = 0.80,
  history.method = "sumabs",
  niterS4 = 20,
  scaling = FALSE,
  intseed = 4
)

selection$selected
selection$summary
selection$details
selection$fit

The current criterion is reconstruction-based and conformal-style. It is not a complete predictive interval procedure for the supervision outcome.

Current scope

Version 4.0 structured estimation supports:

Not yet supported

The following are intentionally deferred to a future version:

Existing multiblock functionality remains available through the ordinary msma() interface, but it cannot currently be combined with structure.method = "soft" or "exclusive".

Validation completed before RC1

What collaborators should test

  1. Rerun an existing msma 3.2 analysis without adding structured arguments.
  2. Test structure.method = "soft" on a real dataset.
  3. Compare soft structure with structure.method = "exclusive".
  4. Check training and new-data reconstruction.
  5. Run a small model-selection grid and record execution time and stability.
  6. Comment on argument names, error messages, output structure, and vignette clarity.

Reproducible issue reports

Please include:

sessionInfo()
packageVersion("msma")
find.package("msma")

Also include the complete call, full warning or error, random seed, data dimensions, operating system, release tag or commit, and a minimal example when possible.

https://github.com/kawa-a/msma/issues/new?template=bug_report.yml

Known limitations of RC1

Development status

v5.0
    -> CRAN release
    -> macOS arm64 portability correction
    -> v5.1 corrective release
    -> Version 6.0 development for missing-data imputation

Citation

Please cite the CRAN version of msma used in the analysis. For reproducibility, also record the package version and, when installing from GitHub, the release tag or commit.

citation("msma")

License

GPL version 2 or later.

Maintainer

Atsushi Kawaguchi