25  Decomposition

decomp() fits a dimensionality-reduction model. Its algorithm configuration selects the method, component count, and optional feature subset.

25.1 Fit, apply, and reconstruct PCA

x <- iris[, 1:4]
execution <- setup_SerialExecution(n_workers_algorithm = 1L, seed = 2026L)
pca <- decomp(x, config = setup_PCA(k = 2L), execution_config = execution)

2026-10-08 02:54:08 ▶ [decomp]
2026-10-08 02:54:08 Input: 150 cases x 4 features. [summarize_unsupervised]
2026-10-08 02:54:08 // CPU | serial | 1 worker: algorithm 1 thread [msg_resources]
2026-10-08 02:54:08 Decomposing with PCA... [decomp]
2026-10-08 02:54:08 Done in 0.09 seconds. [decomp]

head(pca@transformed)

           PC1        PC2
[1,] -2.257141 -0.4784238
[2,] -2.074013  0.6718827
[3,] -2.356335  0.3407664
[4,] -2.291707  0.5953999
[5,] -2.381863 -0.6446757
[6,] -2.068701 -1.4842053

new_scores <- apply_decomp(pca, x[1:5, ], execution_config = execution)
new_scores

        PC1        PC2
1 -2.257141 -0.4784238
2 -2.074013  0.6718827
3 -2.356335  0.3407664
4 -2.291707  0.5953999
5 -2.381863 -0.6446757

head(reconstruct(pca, x, execution_config = execution))

  Sepal.Length Sepal.Width Petal.Length Petal.Width
1     5.018949    3.514854     1.466013   0.2519220
2     4.738463    3.030433     1.603913   0.2720735
3     4.720130    3.196830     1.328961   0.1674138
4     4.668436    3.086770     1.384170   0.1822470
5     5.017093    3.596402     1.345411   0.2067056
6     5.414590    3.897492     1.702574   0.3843767

@transformed contains the fitted component scores. apply_decomp() projects new cases using the fitted transformation. reconstruct() maps a fitted representation back to input space where the method supports it. Reconstruction from fewer components is generally approximate.

25.2 Method capabilities

decomposition_traits()

                     name                                   description linear
1             Autoencoder                           Autoencoder (torch)  FALSE
2                     ICA                Independent Component Analysis   TRUE
3                  Isomap                                        Isomap  FALSE
4                     MDS                      Multidimensional Scaling  FALSE
5                     NMF             Non-negative Matrix Factorization   TRUE
6                     PCA                  Principal Component Analysis   TRUE
7                    PCoA                Principal Coordinates Analysis  FALSE
8                    tSNE   t-Distributed Stochastic Neighbor Embedding  FALSE
9                    UMAP Uniform Manifold Approximation and Projection  FALSE
10 VariationalAutoencoder               Variational autoencoder (torch)  FALSE
   can_apply invertible orthogonal ordered deterministic      preserves nonneg
1       TRUE       TRUE      FALSE   FALSE         FALSE reconstruction  FALSE
2       TRUE       TRUE      FALSE   FALSE         FALSE       variance  FALSE
3      FALSE      FALSE      FALSE   FALSE          TRUE         global  FALSE
4      FALSE      FALSE       TRUE   FALSE         FALSE         global  FALSE
5       TRUE       TRUE      FALSE   FALSE         FALSE reconstruction   TRUE
6       TRUE       TRUE       TRUE    TRUE          TRUE       variance  FALSE
7       TRUE      FALSE       TRUE    TRUE          TRUE         global  FALSE
8      FALSE      FALSE      FALSE   FALSE         FALSE          local  FALSE
9       TRUE      FALSE      FALSE   FALSE         FALSE          local  FALSE
10      TRUE       TRUE      FALSE   FALSE         FALSE reconstruction  FALSE
   threaded package
1      TRUE   torch
2     FALSE fastICA
3     FALSE   vegan
4     FALSE   vegan
5     FALSE     NMF
6     FALSE   stats
7     FALSE   vegan
8      TRUE   Rtsne
9      TRUE    uwot
10     TRUE   torch

Method	Apply to new cases	Reconstruct input
PCA, ICA, NMF	Yes	Yes
PCoA	Yes	No
UMAP	Yes	No
tSNE, Isomap, MDS	No	No
Autoencoder, variational autoencoder	Yes	Yes

PCA describes orthogonal directions of variance. ICA estimates independent components. NMF requires nonnegative inputs. PCoA uses a selected dissimilarity and Gower’s out-of-sample mapping. MDS supports metric or nonmetric fitting through vegan with multiple starts. UMAP and tSNE provide nonlinear embeddings with different neighborhood objectives.

pcoa_config <- setup_PCoA(k = 2L, dist_method = "euclidean")
mds_config <- setup_MDS(k = 2L, nstart = 5L)
umap_config <- setup_UMAP(k = 2L)

Decomposition and clustering select numeric columns when features is unset. An explicit feature subset makes that choice part of the configuration. decomp_metrics() computes measures appropriate to the decomposition’s capabilities; inspect unavailable measures and their applicability.

25.3 Neural decompositions

autoencoder <- setup_Autoencoder(k = 2L, hidden_units = c(8L, 4L), max_epochs = 20L)
variational <- setup_VariationalAutoencoder(k = 2L, beta = 1, max_epochs = 20L)

These configurations require a working torch runtime to fit. Input noise or input dropout configures denoising. The variational autoencoder reports latent means as components; beta weights the KL-divergence contribution to the objective. Device and algorithm threads come from execution_config.

25.4 A decomposition inside supervised learning

mod <- train(
  iris,
  decomposition_config = setup_PCA(k = 2L),
  hyperparameters = setup_CART(),
  outer_resampling_config = setup_KFold(n_resamples = 3L, seed = 2026L),
  execution_config = execution
)

2026-10-08 02:54:09 Checking data is ready for training... ✔ [check_supervised]
2026-10-08 02:54:09 ▶ [train]
2026-10-08 02:54:09 Training set: 150 cases x 4 features. [summarize_supervised]
2026-10-08 02:54:09 // CPU | serial | 1 worker: algorithm 1 thread, tuning 1, outer resampling 1 (as set) [msg_resources]
2026-10-08 02:54:09 Shared memory (auto): not sharing training data (7.3 kB) -- this run transfers nothing to workers. [report_shared_memory]
2026-10-08 02:54:09 <> Training CART Classification using 3 independent folds... [train]

⠋ Outer resamples 1/3
⠙ Outer resamples 2/3 ETA 0:01
⠹ Outer resamples 3/3 ETA 0:00
⠸ Outer resamples 3/3         
                     
2026-10-08 02:54:10 ✔ Outer resamples 3/3 done in 0:01
2026-10-08 02:54:10 </> Outer resampling done. [train]

<Resampled Classification Model>
CART (CART decision tree (rpart))
◈ Decomposed 4 features to 2 components using PCA.
⟳ Tested using 3 independent folds.

  <Resampled Classification Training Metrics>
  Aggregate Confusion Matrix across resamples.
                     Predicted
          Reference  setosa  versicolor  virginica  
             setosa     100           0          0
         versicolor       0          98          2
          virginica       0           2         98

  Showing mean (sd) across resamples.
  Balanced Accuracy: 0.987 (0.011)
                 F1: 0.987 (0.011)
           Accuracy: 0.987 (0.011)

  <Resampled Classification Test Metrics>
  Aggregate Confusion Matrix across resamples.
                     Predicted
          Reference  setosa  versicolor  virginica  
             setosa      50           0          0
         versicolor       0          41          9
          virginica       0           5         45

  Showing mean (sd) across resamples.
  Balanced Accuracy: 0.907 (0.073)
                 F1: 0.907 (0.073)
           Accuracy: 0.907 (0.073)

2026-10-08 02:54:10 Done in 1.38 seconds. [train]

review(mod)

<SupervisedReview>
  CART decision tree (rpart) was used for classification. Decomposition was performed using PCA, reducing 4 numeric features to 2 components. Mean balanced accuracy was 0.99 in the training set and 0.91 in the test set across 3 independent folds.
  3 resamples: 150 out-of-sample predictions of 150 cases, at least 99 training cases per resample; 4 predictors, 2 learner columns including 2 components from PCA (16.5 minority-class training cases per learner column).

  Performance, mean (SD) over 3 resamples
                            Training           Test  Training - test
    Balanced Accuracy  0.987 (0.011)  0.907 (0.073)            0.079
    F1                 0.987 (0.011)  0.907 (0.073)            0.080
    Accuracy           0.987 (0.011)  0.907 (0.073)            0.079

  Baseline comparisons, mean over resamples
    Accuracy 0.907 vs 0.333 (most common training class); better in 3 of 3 resamples compared
    Balanced Accuracy 0.907 vs 0.333 (chance level); better in 3 of 3 resamples compared

  Findings
    * FOLD_VARIATION (note): Test balanced accuracy ranged from 0.824 to 0.961 across 3 resamples (mean 0.907, SD 0.073); 3 of 3 resamples in which the metric is defined outperformed their baseline. Resamples share training cases, so their results are not independent, and no confidence interval or test is computed from them.

  Limitations
    - Whether the model is useful depends on the question it addresses, the costs of different errors, and how its predictions will be used; performance metrics cannot establish this.
    - Preprocessing, decomposition and tuning done by rtemis are fitted on the training cases of each split and only applied to its test cases. Steps taken before the data was passed to rtemis -- selecting or filtering predictors, transforming or removing cases using all the data, or choosing among models by their test performance -- can bias evaluation; this review cannot determine whether that happened.
    - Performance estimates apply to cases from the population the data was drawn from; performance on a different population or setting may differ.

The transformation is learned within the training splits. Supervised configurations require a method that can transform new cases, because the same fitted transformation applies to assessment data and later predictions.