Package {mpem}

Type: Package
Title: Matrix Partial EM for Incomplete Matrix-Normal Data
Version: 0.1.0
Description: Fits single-component and finite-mixture Kronecker-structured matrix-normal models and imputes incomplete matrix-variate data using matrix partial expectation-maximization. General MPEM handles arbitrary missingness, while Rect-MPEM exploits rectangular structural missingness. The methods are described in Lu, Andrews and Browne (2026) "An Efficient EM Algorithm for Both Element-Wise and Structural Missingness in Matrix-Variate Normal Mixture Models" <doi:10.48550/arXiv.2609.00616>.
License: MIT + file LICENSE
URL: https://github.com/LHZMix/MPEM
BugReports: https://github.com/LHZMix/MPEM/issues
Encoding: UTF-8
RoxygenNote: 7.3.3
Depends: R (≥ 4.1.0)
Imports: Rcpp, stats
LinkingTo: Rcpp, RcppArmadillo
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
NeedsCompilation: yes
Packaged: 2026-09-08 18:42:15 UTC; Hanzhang
Author: Hanzhang Lu [aut, cre, cph], Jeffrey L. Andrews [aut, ths], Ryan P. Browne [aut]
Maintainer: Hanzhang Lu <hanzhang.lu@ubc.ca>
Repository: CRAN
Date/Publication: 2026-09-18 11:50:08 UTC

mpem: Matrix Partial EM for Incomplete Matrix-Normal Data

Description

Fits single-component and finite-mixture Kronecker-structured matrix-normal models and imputes incomplete matrix-variate data using matrix partial expectation-maximization. General MPEM handles arbitrary missingness, while Rect-MPEM exploits rectangular structural missingness. The methods are described in Lu, Andrews and Browne (2026) "An Efficient EM Algorithm for Both Element-Wise and Structural Missingness in Matrix-Variate Normal Mixture Models" doi:10.48550/arXiv.2609.00616.

Author(s)

Maintainer: Hanzhang Lu hanzhang.lu@ubc.ca [copyright holder]

Authors:

See Also

Useful links:

Matrix partial EM for incomplete matrix-normal data

Description

mpem() fits either one matrix-normal distribution or a finite mixture of matrix-normal distributions. It estimates separable row and column covariance matrices and imputes missing entries. General MPEM handles arbitrary missingness, while Rect-MPEM exploits a rectangular missing block within each matrix observation. Set G > 1 to estimate component membership and component-specific parameters.

Usage

mpem(
  X,
  row_dim = NULL,
  col_dim = NULL,
  method = c("auto", "arbitrary", "structural"),
  sweeps = 1L,
  tol = 1e-04,
  max_iter = 1000L,
  init = NULL,
  G = 1L,
  mixture_init = c("kmeans", "random"),
  seed = 1L,
  nstart = 10L,
  warm_start = 1,
  ridge = 1e-08,
  verbose = interactive()
)

Arguments

X

A row_dim by col_dim by n numeric array, or an n by row_dim * col_dim numeric matrix. Missing values must be represented by NA.

row_dim

Number of rows in each matrix observation. Inferred from an array and required for a matrix.

col_dim

Number of columns in each matrix observation. Inferred from an array and required for a matrix.

method

Missing-data method. "arbitrary" uses general MPEM; "structural" uses Rect-MPEM and requires at most one rectangular missing block per observation. "auto" selects Rect-MPEM when every nonempty missingness pattern is rectangular and otherwise selects general MPEM.

sweeps

Number of coordinate sweeps used to update conditional covariance matrices.

tol

Relative convergence tolerance.

max_iter

Maximum number of MPEM iterations.

init

Optional list containing mu, row_cov, col_cov, and scale. Identity covariance factors and an observed-data variance are used by default. Available only when G = 1.

G

Number of matrix-normal mixture components. The default G = 1 fits the original single-component MPEM model.

mixture_init

Initialization used when G > 1. "kmeans" clusters mean-filled observations; "random" creates a balanced random partition.

seed

Integer seed used only for mixture initialization.

nstart

Number of random starts used by mixture k-means initialization.

warm_start

Weight in ⁠[0, 1]⁠ assigned to the previous conditional covariance approximation in mixture general MPEM.

ridge

Nonnegative numerical ridge used to stabilize mixture covariance estimates.

verbose

If TRUE, print the observed mixture log-likelihood by iteration.

Value

When G = 1, an object of class mpem_fit containing the imputed data, fitted parameters, and convergence diagnostics. When G > 1, an object of class mpem_mixture_fit that additionally contains mixing proportions, posterior responsibilities, hard clusters, observed log-likelihood, and BIC.

Examples

set.seed(1)
X <- array(rnorm(3 * 2 * 10), dim = c(3, 2, 10))
X[cbind(c(1, 2), c(1, 2), c(1, 2))] <- NA

fit <- mpem(X, method = "auto", max_iter = 3)
anyNA(fit$imputed)
fit$method

X[, , 6:10] <- X[, , 6:10] + 3
mixture_fit <- mpem(X, G = 2, max_iter = 10)
table(mixture_fit$cluster)