The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Getting Started with msma

Atsushi Kawaguchi

2026-11-08

1 Overview

The msma package implements sparse and supervised matrix decomposition for single-block and multiblock multivariable data. The main function is msma(). The analysis is selected by the supplied inputs:

X only: principal component analysis (PCA);
X and Y: partial least squares (PLS);
Z: optional external supervision variable;
positive regularization parameters: sparse estimation.

X and Y may be matrices or lists of matrices. All blocks must contain the same observations in the same row order.

2 Simulated data

dat <- simdata(n = 40, rho = 0.8, Xps = 5, Yps = 4, seed = 1)
X <- dat$X[[1]]
Y <- dat$Y[[1]]
set.seed(1)
Z <- rbinom(nrow(X), 1, 0.5)

dim(X)
#> [1] 40  5
dim(Y)
#> [1] 40  4

3 PCA

A matrix supplied as X produces a single-block PCA.

fit_pca <- msma(X, comp = 2)
fit_pca
#> Call:
#> .msma_default_legacy(X = X, Y = Y, Z = Z_legacy, comp = comp, 
#>     lambdaX = lambdaX, lambdaY = lambdaY, lambdaXsup = lambdaXsup, 
#>     lambdaYsup = lambdaYsup, eta = eta, type = type, inX = inX, 
#>     inY = inY, inXsup = inXsup, inYsup = inYsup, muX = muX, muY = muY, 
#>     defmethod = defmethod, scaling = scaling, verbose = verbose, 
#>     intseed = intseed, ceps = ceps)
#> 
#> Numbers of non-zeros for X block: 
#>        comp1 comp2
#> block1     5     5
#> 
#> Numbers of non-zeros for X super: 
#>         comp1 comp2
#> comp1-1     1     1
summary(fit_pca)
#> Call:
#> .msma_default_legacy(X = X, Y = Y, Z = Z_legacy, comp = comp, 
#>     lambdaX = lambdaX, lambdaY = lambdaY, lambdaXsup = lambdaXsup, 
#>     lambdaYsup = lambdaYsup, eta = eta, type = type, inX = inX, 
#>     inY = inY, inXsup = inXsup, inYsup = inYsup, muX = muX, muY = muY, 
#>     defmethod = defmethod, scaling = scaling, verbose = verbose, 
#>     intseed = intseed, ceps = ceps)
#> 
#> Error : 0.152

The main X-side results are:

wbX: block-level weights or loadings;
sbX: block-level scores;
cpevX: cumulative percentage of explained variance;
avX: adjusted variance attributable to each component.

fit_pca$wbX
#> $block1
#>           comp1       comp2
#> X.1.1 0.4431214 -0.49397744
#> X.1.2 0.4466817  0.13093264
#> X.1.3 0.4578523 -0.31289594
#> X.1.4 0.4345786  0.79523072
#> X.1.5 0.4534661 -0.09245088
head(fit_pca$sbX[[1]])
#>            [,1]       [,2]
#> [1,]  1.1142257  0.3270756
#> [2,]  0.1564608 -0.1964648
#> [3,]  1.9944396 -0.3583063
#> [4,]  4.5765914  0.4580689
#> [5,] -1.3438766 -0.2214561
#> [6,] -1.1964969  0.2130069
fit_pca$cpevX
#>            comp1     comp2
#> block1 0.8145138 0.8741541

plot(fit_pca, axes = 1, plottype = "bar", las = 2)
plot(fit_pca, v = "score", axes = 1:2, plottype = "scatter")

4 Sparse PCA

A positive lambdaX introduces sparsity into the X-side block weights.

fit_spca <- msma(X, comp = 2, lambdaX = 0.10)
fit_spca$nzwbX
#>        comp1 comp2
#> block1     5     3
fit_spca$selectXnames
#> [[1]]
#> [[1]]$comp1
#> [1] "X.1.1" "X.1.2" "X.1.3" "X.1.4" "X.1.5"
#> 
#> [[1]]$comp2
#> [1] "X.1.1" "X.1.3" "X.1.4"

5 Supervised sparse PCA

Z supplies external supervision. The strength of supervision on X is controlled by muX.

fit_sup_pca <- msma(
  X = X, Z = Z, comp = 2,
  lambdaX = 0.05, muX = 0.20,
  intseed = 1
)
fit_sup_pca$predictiv
#> [1] 0.0004154633 0.1022717687

6 PLS

Supplying both X and Y produces PLS.

fit_pls <- msma(X = X, Y = Y, comp = 2)
fit_pls
#> Call:
#> .msma_default_legacy(X = X, Y = Y, Z = Z_legacy, comp = comp, 
#>     lambdaX = lambdaX, lambdaY = lambdaY, lambdaXsup = lambdaXsup, 
#>     lambdaYsup = lambdaYsup, eta = eta, type = type, inX = inX, 
#>     inY = inY, inXsup = inXsup, inYsup = inYsup, muX = muX, muY = muY, 
#>     defmethod = defmethod, scaling = scaling, verbose = verbose, 
#>     intseed = intseed, ceps = ceps)
#> 
#> Numbers of non-zeros for X block: 
#>        comp1 comp2
#> block1     5     5
#> 
#> Numbers of non-zeros for X super: 
#>         comp1 comp2
#> comp1-1     1     1
#> 
#> Numbers of non-zeros for Y block: 
#>        comp1 comp2
#> block1     4     4
#> 
#> Numbers of non-zeros for Y super: 
#>         comp1 comp2
#> comp1-1     1     1

plot(fit_pls, axes = 1, XY = "XY")
plot(fit_pls, axes = 2, XY = "XY")

Sparse and supervised PLS are requested by adding lambdaX, lambdaY, and optionally Z, muX, and muY.

fit_spls <- msma(
  X = X, Y = Y, Z = Z, comp = 2,
  lambdaX = 0.10, lambdaY = 0.10,
  muX = 0.10, muY = 0.10,
  intseed = 1
)
fit_spls$nzwbX
#>        comp1 comp2
#> block1     5     5
fit_spls$nzwbY
#>        comp1 comp2
#> block1     4     4

7 Prediction and low-rank reconstruction

predict.msma() projects supplied data into fitted component spaces and returns component scores and low-rank reconstructions. It does not predict Y from X. For PLS, newX and newY are reconstructed independently.

The returned elements are reconstructed X, X-side scores sbX, reconstructed Y, and Y-side scores sbY. For PCA, Y and sbY are NULL.

7.1 Historical prediction behavior

Calling predict() without Version 5 controls preserves historical behavior.

legacy_prediction <- predict(fit_pca, newX = X[1:5, , drop = FALSE])
names(legacy_prediction)
#> [1] "X"   "sbX" "Y"   "sbY"

7.2 Fitted preprocessing and reconstruction

Fitted preprocessing reuses training center and scale. Fitted reconstruction uses training-derived reconstruction coefficients.

fitted_prediction <- predict(
  fit_pca,
  newX = X[1:5, , drop = FALSE],
  preprocessing = "fitted",
  reconstruction = "fitted",
  output_scale = "original"
)
lapply(fitted_prediction$X, dim)
#> [[1]]
#> [1] 5 5
lapply(fitted_prediction$sbX, dim)
#> [[1]]
#> [1] 5 2

output_scale = "analysis" returns centered or standardized reconstructions. output_scale = "original" returns reconstructions on original variable scales. Component scores remain on the analysis scale.

7.3 PLS prediction

prediction_pls <- predict(
  fit_pls,
  newX = X[1:5, , drop = FALSE],
  newY = Y[1:5, , drop = FALSE],
  preprocessing = "fitted",
  reconstruction = "fitted",
  output_scale = "original"
)
names(prediction_pls)
#> [1] "X"   "sbX" "Y"   "sbY"

newY is not an outcome predicted from newX. The supplied newY is projected and reconstructed independently.

8 Session information

sessionInfo()
#> R version 4.5.2 (2025-10-31 ucrt)
#> Platform: x86_64-w64-mingw32/x64
#> Running under: Windows 11 x64 (build 26300)
#> 
#> Matrix products: default
#>   LAPACK version 3.12.1
#> 
#> locale:
#> [1] LC_COLLATE=C                    LC_CTYPE=Japanese_Japan.utf8   
#> [3] LC_MONETARY=Japanese_Japan.utf8 LC_NUMERIC=C                   
#> [5] LC_TIME=Japanese_Japan.utf8    
#> 
#> time zone: Asia/Tokyo
#> tzcode source: internal
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] msma_5.1
#> 
#> loaded via a namespace (and not attached):
#>  [1] digest_0.6.39   R6_2.6.1        fastmap_1.2.0   xfun_0.55      
#>  [5] cachem_1.1.0    knitr_1.51      htmltools_0.5.9 rmarkdown_2.31 
#>  [9] lifecycle_1.0.5 cli_3.6.6       sass_0.4.10     jquerylib_0.1.4
#> [13] compiler_4.5.2  tools_4.5.2     evaluate_1.0.5  bslib_0.9.0    
#> [17] yaml_2.3.12     otel_0.2.0      rlang_1.3.0     jsonlite_2.0.0

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.