Skip to contents

Fit a Mixture Factor Analysis Model (with optional multi-initialization)

Source: R/mfa_em_fit.R
mfa_em_fit.Rd

This function calls the C++ function mfaTimeseriesCpp() to perform a Mixture Factor Analysis EM algorithm for fixed K and r. By default, it runs a single pass with the internal initialization from C++. However, if you specify multiple initial attempts (via n_init>1) and/or use_kmeans_init=TRUE, this function will try several different initial cluster assignments (in parallel using mclapply), then return the best solution (maximizing the final log-likelihood).

Usage

mfa_em_fit(
  list_of_data,
  K,
  r,
  max_iter = 50,
  iter_fa = 20,
  tol = 0.001,
  n_init = 1,
  use_kmeans_init = TRUE,
  kmeans_rdim = r,
  mc_cores = 1,
  seed = NULL,
  verbose = TRUE,
  n_threads = 0,
  cpp_seed = 0,
  progress_callback = NULL,
  ...
)

Arguments

list_of_data

A list of matrices (each (T_i x M)) to be modeled.

K

Number of clusters.

r

Factor dimension.

max_iter

Maximum EM iterations for mfaTimeseriesCpp.

iter_fa

Number of sub-iterations for the factor analyzer update in C++. (Replaces deprecated nIterFA)

tol

Convergence tolerance for mfaTimeseriesCpp.

n_init

Number of random initial assignments to try (in addition to the default single-run or k-means if requested). Defaults to 1.

use_kmeans_init

If TRUE, we also run one initialization where we extract subject features (via PCA) and apply kmeans to get a cluster assignment. Defaults to FALSE.

kmeans_rdim

PCA dimension for extracting subject-level features, used only if use_kmeans_init=TRUE. Default is r. (Replaces deprecated subject_rdim_for_kmeans)

mc_cores

Number of cores for parallel execution via mclapply. Defaults to 1 (no parallel).

seed

Random seed for reproducibility (default: NULL).

verbose

Logical; if TRUE, print progress messages during EM iterations. Default is TRUE.

n_threads

Integer; number of OpenMP threads to use for parallel computation (0 = auto). Default is 0.

cpp_seed

Integer; random seed for C++ RNG (0 = default/no seed). Default is 0.

progress_callback

Optional function to report progress from C++. Should accept two arguments: current iteration and total iterations.

...

Additional arguments for backwards compatibility. Deprecated arguments like nIterFA and subject_rdim_for_kmeans are accepted with warnings.

Value

A list with the same elements as a single run: z, pi, mu, Lambda, Psi, logLik, resp. It corresponds to the best solution (i.e. highest log-likelihood) among all tried inits.

Details

The single-run approach in C++ already does a built-in initialization if z_init is not provided. Therefore, if n_init=1 and use_kmeans_init=FALSE, we just call mfaTimeseriesCpp once (like the original design). Otherwise:

  1. If use_kmeans_init=TRUE, we do one run where we assign clusters by k-means on some subject-level features (extracted by PCA).

  2. We also sample n_init random assignments (each subject assigned to a random cluster).

  3. For each assignment, we call mfa_em_fit_cpp_singleInit.

  4. We compare all results' logLik and keep the best one.

This provides a more robust initialization scheme to avoid poor local maxima.

See also

mixture_pca_em_fit for MPCA fitting, select_r for selecting optimal r, plot_cluster_synergy_loadings_mfa for visualization

Examples

if (FALSE) { # \dontrun{
# Suppose we have a list_of_data for N=100 subjects, each (T_i x M=8).
# We want to fit K=3, r=2, and try 5 random inits plus one k-means init:
fit <- mfa_em_fit(
  list_of_data, K=3, r=2,
  max_iter=50, iter_fa=20, tol=1e-3,
  n_init=5,
  use_kmeans_init=TRUE,
  kmeans_rdim=2,
  mc_cores=2,
  seed=123
)
print(fit$logLik)
head(fit$z)
} # }