Skip to contents

Fit a Mixture PCA Model (Using mpcaTimeseriesCpp) with optional multi-initialization

Source: R/mpca_em_fit.R
mixture_pca_em_fit.Rd

This function calls the C++ function mpcaTimeseriesCpp() to perform a Mixture PCA (PPCA) EM algorithm for fixed K and r, then converts the W matrices into (P, D), creates Psi, and computes the final log-likelihood/responsibilities in R. By default, it runs a single pass with the built-in initialization in C++. However, if n_init > 1 or use_kmeans_init=TRUE, it performs multiple initializations in parallel and returns the best-fitting result (highest log-likelihood).

Usage

mixture_pca_em_fit(
  list_of_data,
  K,
  r,
  max_iter = 50,
  iter_pca = 20,
  tol = 0.001,
  method = "EM",
  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).

K

Number of clusters.

r

Number of principal components.

max_iter

Maximum EM iterations for the C++ routine.

iter_pca

Sub-iterations for updating each cluster's PPCA parameters. (Replaces deprecated nIterPCA)

tol

Convergence tolerance for mpcaTimeseriesCpp.

method

Either "EM" or "closed_form", passed down to the C++ routine.

n_init

Integer; how many random initial assignments to try (in addition to the default single-run or k-means if requested). Defaults to 1.

use_kmeans_init

Logical; if TRUE, we also run one initialization where we assign clusters by k-means on subject-level PCA features. Defaults to FALSE.

kmeans_rdim

The PCA dimension for the subject-level feature extraction, used only if use_kmeans_init=TRUE. Defaults to 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 nIterPCA and subject_rdim_for_kmeans are accepted with warnings.

Value

A list with elements:

z

Hard cluster assignments (1..K).

pi

Mixing proportions.

mu

List of length K, each a mean vector.

P

List of length K, each (M x r) principal directions.

D

List of length K, each (r x r) diagonal.

Psi

List of length K, each (M x M) diagonal.

logLik

Final log-likelihood over all data.

sigma2

Numeric vector of length K for sigma2.

resp

(N x K) matrix of responsibilities.

Details

If n_init=1 and use_kmeans_init=FALSE, this function runs exactly one pass with the default initialization in C++ (i.e. subject i is assigned to cluster (i % K) + 1). Otherwise:

  1. If use_kmeans_init=TRUE, we do a run where we apply k-means to some subject-level PCA features to get z_init, then run EM once.

  2. We generate n_init random initial assignments, run EM for each in parallel, and collect the results.

  3. We compare all solutions by final log-likelihood and pick the best.

See also

mfa_em_fit for MFA fitting, select_r for selecting optimal r, plot_cluster_synergy_loadings_mpca for visualization

Examples

if (FALSE) { # \dontrun{
# Suppose we have a list_of_data, K=3, r=2, and we want to try 5 random inits + k-means:
fit <- mixture_pca_em_fit(
  list_of_data, K=3, r=2, max_iter=50, iter_pca=20, tol=1e-3, method="EM",
  n_init=5, use_kmeans_init=TRUE, kmeans_rdim=2, mc_cores=2
)
print(fit$logLik)
head(fit$z)
} # }