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

pred <- predict(fit_pls, newX = X, newY = Y)
names(pred)
#> [1] "X"   "sbX" "Y"   "sbY"

8 Session information

sessionInfo()
#> R Under development (unstable) (2026-08-25 r90447 ucrt)
#> Platform: x86_64-w64-mingw32/x64
#> Running under: Windows 11 x64 (build 26200)
#> 
#> 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_3.2
#> 
#> loaded via a namespace (and not attached):
#>  [1] digest_0.6.39   R6_2.6.1        fastmap_1.2.0   xfun_0.60      
#>  [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.7.0  tools_4.7.0     evaluate_1.0.5  bslib_0.12.0   
#> [17] yaml_2.3.12     otel_0.2.0      rlang_1.3.0     jsonlite_2.0.0

Getting Started with msma

Atsushi Kawaguchi

2026-08-26