`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"),
max_iter = 50,
tol = 1e-06,
ridge = 1e-08,
verbose = FALSE,
use_future = FALSE,
...
)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.
- 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.
- 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.
- ...
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`.