synergyMixR

An R package for mixture-based muscle synergy analysis (Mixture Factor Analysis and Mixture Principal Component Analysis).

Installation

# Install from R-universe (recommended, includes pre-built binaries)
install.packages("synergyMixR",
  repos = c("https://x-biosignal.r-universe.dev", "https://cloud.r-project.org"))

# Install from GitHub
devtools::install_github("x-biosignal/synergyMixR")

System Requirements

This package requires C++ compilation. Ensure you have:

• Windows: Rtools
• macOS: Xcode Command Line Tools (xcode-select --install)
• Linux: build-essential and r-base-dev packages

Quick Start

library(synergyMixR)

# Simulate EMG-like data for 30 subjects drawn from 2 clusters, each with
# 3 muscle synergies across 8 muscles.
sim_data <- generate_synergy_data(
  N = 30, K = 2, r = 3, M = 8,
  T_each = 100, seed = 123
)

# Fit a Mixture Factor Analysis (MFA) model
fit_mfa <- mfa_em_fit(
  list_of_data = sim_data$list_of_data,
  K = 2, r = 3,
  n_init = 3,
  use_kmeans_init = TRUE
)

# Cluster assignment of each subject
table(extract_cluster_labels(fit_mfa))

# Cluster-specific synergy loadings (8 muscles x 3 synergies)
round(fit_mfa$Lambda[[1]], 2)

# Model fit: variance accounted for and reconstruction error
compute_global_vaf_mfa(sim_data$list_of_data, fit_mfa)
compute_reconstruction_error(sim_data$list_of_data, fit_mfa, metric = "rmse")

Heatmaps of the cluster synergy loadings use the optional reshape2 package; the guard keeps the block inert when it is absent:

# install.packages("reshape2")
if (requireNamespace("reshape2", quietly = TRUE)) {
  plot_cluster_synergy_loadings_mfa(fit_mfa, plot_type = "heatmap")
}

For a complete tutorial, see:

vignette("quickstart", package = "synergyMixR")

Key Features

• Mixture Models: MFA and MPCA with C++ backend (Rcpp/RcppArmadillo)
• Model Selection: BIC, ICL, cross-validation, bootstrap stability
• EMG Preprocessing: Complete pipeline from raw EMG to analysis-ready data
• Visualization: Unified ggplot2-based plotting functions
• Simulation: Synthetic data generation with configurable noise models
• HPC Support: Parallel computation via future/PBS backends

Vignettes

Vignette	Description
quickstart	Quick start guide
tutorial	Comprehensive tutorial
model_selection_guide	Complete K,r selection workflow
r_selection_framework	r-selection methods
metrics_reference	Understanding metrics
simulation_cluster_separation	Cluster separation analysis
simulation_single_vs_mixture	Single vs mixture model comparison

Citation

If you use this package in your research, please cite:

Matsui, Y. (2026). synergyMixR: Mixture-Based Muscle Synergy Analysis.
R package version 1.0.0. https://github.com/x-biosignal/synergyMixR

License

GPL-3