Skip to contents

Select Optimal r Using Cluster-wise Evaluation for MPCA

Source: R/r_selection_clusterwise.R
select_r_clusterwise_mpca.Rd

Selects the optimal number of principal components (r) by evaluating each cluster separately, rather than averaging metrics across all clusters.

Usage

select_r_clusterwise_mpca(
  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,
  nIterPCA = 5,
  tol = 0.001,
  method = "EM",
  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", "mean", "min", "majority". 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.

nIterPCA

Sub-iterations for PCA update.

tol

Convergence tolerance.

method

"EM" or "closed_form".

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 MPCA). 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 MPCA 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 the same two-stage approach as select_r_clusterwise_mfa, but for Mixture PCA models. See select_r_clusterwise_mfa for details on the scoring approach.

Important Note: The cluster-wise MPCA(K=1) approach is experimental and can be unstable. Each cluster is evaluated independently using a single-cluster MPCA 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{
result <- select_r_clusterwise_mpca(
  list_of_data, K = 3, rvec = 2:6,
  criteria = c("VAF", "VSS", "smoothness")
)
print(result$cluster_r)
print(result$agg_r)
} # }