Skip to contents

Select Optimal r Using Cluster-wise Evaluation for MFA

Source: R/r_selection_clusterwise.R
select_r_clusterwise_mfa.Rd

Selects the optimal number of factors (r) by evaluating each cluster separately, rather than averaging metrics across all clusters. This approach is useful when different clusters may have different optimal r values.

Usage

select_r_clusterwise_mfa(
  list_of_data,
  K,
  rvec = 1:6,
  criteria = c("VAF", "VSS", "smoothness"),
  agg_method = c("max", "mean", "min", "majority"),
  vaf_threshold = NULL,
  vss_threshold = 0.5,
  vss_method = c("threshold", "ratio"),
  vss_rotate = c("none", "varimax"),
  lambda_smooth = 0.001,
  weights = c(VAF = 0.4, VSS = 0.4, smoothness = 0.2),
  vss_normalize = c("logr", "max", "r", "r2", "none"),
  w_elbow = 0,
  w_r = 0,
  vaf_degeneracy_threshold = 0.6,
  max_iter = 50,
  nIterFA = 5,
  tol = 0.001,
  n_init = 1,
  use_kmeans_init = TRUE,
  subject_rdim_for_kmeans = 2,
  mc_cores = 1,
  n_threads = 1,
  verbose = FALSE,
  mode = c("clusterwise", "global-first"),
  global_model = c("PPCA", "FA"),
  global_criterion = c("CV", "ParallelAnalysis"),
  global_folds = 5,
  global_seed = NULL,
  r_init = NULL
)

Arguments

list_of_data

A list of N matrices, each (T_i x M).

K

Number of clusters (fixed).

rvec

Vector of candidate r values to evaluate. Default is 1:6.

criteria

Character vector specifying which criteria to use for selection. Options: "VAF", "VSS", "smoothness". Default is c("VAF", "VSS", "smoothness").

agg_method

Method for aggregating cluster-specific r values. Options: "max" (conservative, takes maximum r across clusters), "mean" (average r, rounded), "min" (minimum r across clusters), "majority" (most common r value). Default is "max".

vaf_threshold

Minimum VAF threshold for each cluster. Set to NULL to disable hard filtering. Default is NULL (disabled).

vss_threshold

Threshold for VSS criterion. Default is 0.5.

vss_method

Method for computing VSS. Options: "threshold" (count variables with exactly one strong loading above threshold), "ratio" (compute concentration ratio max(lambda^2)/sum(lambda^2) for each variable). Default is "threshold". The "ratio" method is more robust when loadings are small in absolute magnitude.

vss_rotate

Rotation method to apply before computing VSS. Options: "none" (no rotation), "varimax" (orthogonal rotation). Default is "none". VSS on unrotated FA loadings is rotation-dependent and often uninformative. Rotation is recommended for meaningful VSS.

lambda_smooth

Smoothness penalty weight (deprecated, use weights instead). Default is 1e-3.

weights

Named vector of weights for combining criteria. Default is c(VAF=0.4, VSS=0.4, smoothness=0.2).

vss_normalize

Method for normalizing VSS to account for r-dependence. Options: "logr" (divide by log(r)), "max" (divide by max VSS), "r" (divide by r), "r2" (divide by r^2), "none". Default is "logr".

w_elbow

Weight for DeltaVAF (elbow detection). Higher values emphasize diminishing returns in VAF. Default is 0 (disabled).

w_r

Weight for direct r penalty (AIC/BIC style). Higher values penalize larger r. Default is 0 (disabled).

vaf_degeneracy_threshold

Threshold for detecting degenerate clusters. If max VAF across all r values is below this threshold, the cluster is considered degenerate and a warning is issued. Default is 0.6.

max_iter

Maximum EM iterations for initial clustering.

nIterFA

Sub-iterations for FA update.

tol

Convergence tolerance.

n_init

Number of random initializations for initial clustering.

use_kmeans_init

Whether to use k-means initialization.

subject_rdim_for_kmeans

Dimension for k-means features.

mc_cores

Number of cores for parallelization.

n_threads

Number of OpenMP threads.

verbose

Logical. If TRUE, print detailed diagnostic information during r selection, including per-r metrics for each cluster and warnings about NA values or degenerate clusters. Default is FALSE.

mode

Selection mode. Options: "clusterwise" (default, evaluate r separately per cluster), "global-first" (first estimate global r using FA/PPCA on pooled data, then use for MFA). The "global-first" mode is recommended as it provides a cluster-independent baseline.

global_model

Model for global r estimation (only used when mode = "global-first"). Options: "PPCA" (default), "FA". PPCA is more stable for mixture models.

global_criterion

Criterion for global r selection (only used when mode = "global-first"). Options: "CV" (default), "ParallelAnalysis". CV is the primary criterion.

global_folds

Number of CV folds for global r selection (only used when mode = "global-first"). Default is 5.

global_seed

Random seed for global r selection (only used when mode = "global-first"). Default is NULL.

r_init

Initial r value for the first-stage clustering (only used when mode = "clusterwise"). If NULL (default), uses median(rvec). When called from hybrid mode in select_r_mixture(), this is set to r_global to use the global estimate as initialization.

Value

A list with:

cluster_r

Named vector of optimal r for each cluster.

agg_r

Aggregated r value across clusters.

cluster_metrics

List of data frames with metrics for each cluster.

initial_fit

The initial MFA fit used to determine cluster assignments.

agg_method

The aggregation method used.

mode

The selection mode used.

global_result

(Only for mode = "global-first") The result from select_r_global_mfa().

Details

This function implements a two-stage approach:

  1. Fit an initial MFA model with K clusters and a reasonable r value (using the median of rvec) to obtain cluster assignments.

  2. For each cluster k, subset the data to subjects assigned to that cluster, and evaluate different r values using cluster-specific metrics.

  3. Select the optimal r_k for each cluster based on normalized scoring that combines VAF (higher is better), VSS (higher is better, normalized by log(r)), and smoothness (lower is better) with specified weights.

  4. Aggregate the cluster-specific r values using the specified method.

The scoring approach addresses the issue where VAF monotonically increases with r by normalizing all metrics per cluster and using weighted combination. VSS is normalized by log(r) to account for the fact that more factors naturally lead to more complex structures. Smoothness acts as a penalty (subtracted from score).

The cluster-wise approach is particularly useful when:

  • Different motor control strategies require different numbers of synergies

  • Averaging metrics across clusters masks cluster-specific structure

  • You want to understand the heterogeneity in synergy complexity

Important Note: The cluster-wise MFA(K=1) approach is experimental and can be unstable. Each cluster is evaluated independently using a single-cluster MFA model, which may not capture the full complexity of the data. Use with caution and carefully inspect the verbose output and degeneracy warnings.

Examples

if (FALSE) { # \dontrun{
# Basic usage with default weights (clusterwise mode)
result <- select_r_clusterwise_mfa(
  list_of_data, K = 3, rvec = 2:6,
  criteria = c("VAF", "VSS", "smoothness")
)
print(result$cluster_r)  # r for each cluster
print(result$agg_r)      # aggregated r

# Global-first mode (recommended)
result <- select_r_clusterwise_mfa(
  list_of_data, K = 3, rvec = 2:6,
  mode = "global-first",
  global_model = "PPCA",
  global_criterion = "CV"
)
print(result$agg_r)  # global r estimate

# Custom weights emphasizing VAF (clusterwise mode)
result <- select_r_clusterwise_mfa(
  list_of_data, K = 3, rvec = 2:6,
  mode = "clusterwise",
  criteria = c("VAF", "VSS", "smoothness"),
  weights = c(VAF = 0.6, VSS = 0.3, smoothness = 0.1)
)
} # }