Skip to contents

Unified Model Selection for K and r

Source: R/model_selection_wrappers.R
select_K_r.Rd

This function provides a unified interface for selecting optimal K (number of clusters) and r (factor dimension) for mixture models (MFA or MPCA). It supports multiple selection strategies including grid search and two-stage selection.

Usage

select_K_r(
  list_of_data,
  method = c("MFA", "MPCA"),
  strategy = c("grid", "twostage"),
  Kvec = 1:5,
  rvec = 1:5,
  r_fixed = 2,
  criterion = c("ICL", "BIC"),
  icl_max_iter = NULL,
  icl_temperature = 2,
  max_iter = 50,
  nIterFA = 5,
  nIterPCA = 5,
  tol = 0.001,
  mpca_method = "EM",
  n_init = 1,
  use_kmeans_init = TRUE,
  subject_rdim_for_kmeans = 2,
  mc_cores_grid = 1,
  mc_cores = 1,
  n_threads = 1,
  verbose = TRUE
)

Arguments

list_of_data

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

method

Model type: "MFA" or "MPCA".

strategy

Selection strategy: "grid" for full grid search, "twostage" for two-stage sequential selection (K first, then r).

Kvec

Integer vector of candidate K values. Default is 1:5.

rvec

Integer vector of candidate r values. Default is 1:5.

r_fixed

Fixed r value for Stage 1 of twostage selection. Default is 2.

criterion

Model selection criterion: "ICL" (Integrated Completed Likelihood) or "BIC" (Bayesian Information Criterion). Default is "ICL".

icl_max_iter

Maximum iterations for ICL entropy calculation. Default is NULL (uses package default).

icl_temperature

Temperature parameter for ICL entropy scaling. Higher values favor more clusters. Default is 2.0.

max_iter

Maximum EM iterations. Default is 50.

nIterFA

Sub-iterations for FA update (MFA only). Default is 5.

nIterPCA

Sub-iterations for PCA update (MPCA only). Default is 5.

tol

Convergence tolerance. Default is 1e-3.

mpca_method

Method for MPCA: "EM" or "closed_form". Default is "EM".

n_init

Number of random initializations. Default is 1.

use_kmeans_init

Whether to use k-means initialization. Default is TRUE.

subject_rdim_for_kmeans

Dimension for k-means features. Default is 2.

mc_cores_grid

Number of cores for grid-level parallelization. Default is 1.

mc_cores

Number of cores for initialization-level parallelization. Default is 1.

n_threads

Number of OpenMP threads. Default is 1.

verbose

Logical; if TRUE, print progress messages. Default is TRUE.

Value

A list with unified output structure:

best_K

Optimal number of clusters (scalar).

best_r

Optimal factor dimension (scalar).

best_model

Fitted model object with optimal (K, r).

summary_df

Data frame with selection summary. For grid strategy, contains all (K, r) combinations with BIC. For twostage, contains stage1 and stage2 summaries.

meta

List with metadata: method, strategy, Kvec, rvec, etc.

Details

This function wraps the existing model selection functions to provide a unified interface for parameter sweep experiments. It handles:

  • Parallel safety: Prevents nested parallelization by forcing n_threads=1 when mc_cores_grid > 1

  • Windows compatibility: Falls back to sequential execution on Windows

  • Consistent output format: Returns the same structure regardless of method or strategy

Strategy: "grid" Performs full grid search over all (K, r) combinations using BIC for selection. This is thorough but computationally expensive.

Strategy: "twostage" Two-stage sequential selection:

  1. Stage 1: Fix r at r_fixed, search for optimal K using BIC

  2. Stage 2: Fix K at optimal value, search for optimal r using BIC

This is more stable and faster than full grid search.

See also

select_optimal_K_r_mfa, select_optimal_K_r_mpca, select_optimal_K_r_mfa_twostage, select_optimal_K_r_mpca_twostage

Examples

if (FALSE) { # \dontrun{
# Grid search for MFA
result <- select_K_r(
  list_of_data, method = "MFA", strategy = "grid",
  Kvec = 2:4, rvec = 2:4
)
print(result$best_K)
print(result$best_r)

# Two-stage selection for MPCA
result <- select_K_r(
  list_of_data, method = "MPCA", strategy = "twostage",
  Kvec = 2:4, rvec = 2:4, r_fixed = 2
)
} # }