`aligned_interbattery()` fits a symmetric two-sided multiblock latent model with subject-specific common scores `T_s`, `X`-side scores `U_s`, and `Y`-side scores `V_s`. The current implementation supports:
* one or more subjects; * one or more blocks per subject on each side; * nested `subject -> domain` input or flat block lists with optional `block_info`; * integer row maps into a subject-level reference row set; * optional subject-wise row-graph penalties on the common score space; and * directional prediction from `X` to `Y`, from `Y` to `X`, or conditional completion from partially observed bundles on both sides.
Loadings are shared across subjects when blocks on the same side share the same domain/schema. This is the minimum coupling required for multi-subject fits to learn a common geometry rather than decomposing into independent subject-specific models. Cross-side decoding uses fitted linear coupling operators from the common score space back to the side-specific score systems.
Usage
aligned_interbattery(
X,
Y,
x_row_map = NULL,
y_row_map = NULL,
x_block_info = NULL,
y_block_info = NULL,
ncomp = 2,
x_preproc = multivarious::center(),
y_preproc = multivarious::center(),
x_weight = NULL,
y_weight = NULL,
row_graph = NULL,
row_graph_lambda = 0,
row_graph_form = c("laplacian", "adjacency", "normalized_laplacian"),
couple_x = 1,
couple_y = 1,
decorrelate = 0,
decorrelate_type = c("penalty", "whiten"),
side_constraint = c("orthonormal", "none"),
max_iter = 50,
tol = 1e-06,
ridge = 1e-08,
verbose = FALSE,
use_future = FALSE,
gram_rank = NULL,
gram_tol = 1e-10,
...
)Arguments
- X
A matrix/data.frame, a flat list of blocks, or a nested `X[[subject]][[domain]]` list for the `X` side.
- Y
A matrix/data.frame, a flat list of blocks, or a nested `Y[[subject]][[domain]]` list for the `Y` side.
- x_row_map
Optional row-map structure for `X`, matching the shape of `X`. Each observed block row must map to `1..N_s` for its subject. Missing row maps imply identity mapping and therefore require full subject rows.
- y_row_map
Optional row-map structure for `Y`, matching the shape of `Y`.
- x_block_info
Optional `data.frame` for flat `X` input with one row per block and columns `block`, `subject`, and optional `domain`.
- y_block_info
Optional `data.frame` for flat `Y` input with one row per block and columns `block`, `subject`, and optional `domain`.
- ncomp
Integer number of latent components.
- x_preproc
Single shared preprocessing pipeline for `X`-side loading types. Defaults to [multivarious::center()].
- y_preproc
Single shared preprocessing pipeline for `Y`-side loading types. Defaults to [multivarious::center()].
- x_weight
Optional non-negative scalar or vector of per-block weights for `X`. If `NULL`, MFA-style inverse-first-singular-value-squared weighting is used after preprocessing.
- y_weight
Optional non-negative scalar or vector of per-block weights for `Y`. If `NULL`, MFA-style inverse-first-singular-value-squared weighting is used after preprocessing.
- row_graph
Optional subject-wise row graph or Laplacian. For one subject, a single square matrix is allowed. For multiple subjects, supply a named or ordered list. When a graph is supplied, `row_graph_form` controls whether it is interpreted as a Laplacian or adjacency matrix.
- row_graph_lambda
Non-negative scalar controlling the row-graph penalty on the common scores.
- row_graph_form
Interpretation of `row_graph`: `"laplacian"`, `"adjacency"`, or `"normalized_laplacian"`. The normalized setting accepts either an adjacency matrix that will be normalized internally or a precomputed normalized Laplacian.
- couple_x
Non-negative scalar controlling the `U_s` to `T_s` coupling.
- couple_y
Non-negative scalar controlling the `V_s` to `T_s` coupling. The two set a direction trade-off. Prediction from one side works best when that side is tightly coupled to `T_s` and the side being predicted is coupled loosely, which stops noise in the target from pulling the common scores. In simulations with noisy data, `couple_y` around `0.03` (keeping `couple_x = 1`) improved `X -> Y` prediction by up to about 0.1 in R-squared, but cut `Y -> X` prediction sharply; the mirror setting does the reverse. The symmetric default `1, 1` stays close to the best in both directions. When the model is used mainly in one direction, lowering the target side's coupling is worth tuning, e.g. by cross-validation.
- decorrelate
For `decorrelate_type = "penalty"`, a non-negative scalar controlling the within-side score decorrelation penalty. For `decorrelate_type = "whiten"`, the partial-whitening exponent `gamma in [0, 1]`, where `0` is covariance-oriented and `1` is fully whitened.
- decorrelate_type
One of `"penalty"` or `"whiten"`. Penalty mode adds a within-side off-diagonal covariance penalty during the side-score updates. Whitening mode replaces that penalty with a fitted partial whitening operator inside the common-to-side coupling.
- side_constraint
How the scale of the side scores `U_s` and `V_s` is fixed. `"orthonormal"` (default) constrains each side's stacked scores to be orthonormal, as the common scores `T_s` are; the loadings carry the scale, the fit converges, and results do not depend on `max_iter`. `"none"` reproduces the earlier unconstrained updates. There the data fit is unchanged by `U -> cU`, loadings `-> loadings / c` while the coupling term shrinks like `c^2`, so the objective has no minimiser: side scores drift toward zero, loadings grow, and the result depends on where `max_iter` stops. Under `"orthonormal"` the pooled side scores are already white, so `decorrelate_type = "whiten"` is ignored with a warning; the decorrelation penalty still acts on each subject's own score covariance. On noisy data the drifting `"none"` fit can predict slightly better in one direction because the drift gradually weakens the coupling; with `"orthonormal"` that trade-off is set explicitly through `couple_x` / `couple_y` (see there).
- max_iter
Maximum ALS iterations.
- tol
Relative convergence tolerance on the objective.
- ridge
Non-negative ridge stabilization for score/loadings updates.
- verbose
Logical; if `TRUE`, print iteration diagnostics.
- use_future
Logical; if `TRUE`, block-wise computations that do not depend on one another may be performed via `furrr::future_map()` when available. The main alternating-least-squares loop is intrinsically sequential and is unaffected. Accepted here primarily for interface parity with the rest of the aligned/anchored family.
- gram_rank, gram_tol
Used when `X` and/or `Y` is a flat [block_source()]: each domain (the blocks that share a loading matrix) is read as one row-stacked block, compressed through its row Gram matrix, and fitted out of core (exact, up to component signs; column-local preprocessing only). Gram truncation (`gram_rank`) is not supported here.
- ...
Unused; reserved for future extensions.
Value
An object inheriting from `multivarious::multiblock_biprojector` with additional class `"aligned_interbattery"`. The common scores are stored in `s` and `common_scores`, subject-wise common scores in `T_list`, subject-wise side scores in `U_list` and `V_list`, and shared side loadings in `x_loadings` and `y_loadings`.