Bootstrapping procedure to determine PARAFAC model stability for a given number of components.

Usage

assessModelStability(
  dataset,
  minNumComponents = 1,
  maxNumComponents = 5,
  numFolds = dim(dataset$data)[1],
  considerGroups = FALSE,
  groupVariable = "",
  colourCols = NULL,
  legendTitles = NULL,
  xLabels = NULL,
  legendColNums = NULL,
  arrangeModes = NULL,
  method = "als",
  ctol = 1e-06,
  maxit = 2500,
  max_fn = 10000,
  rel_tol = 1e-08,
  abs_tol = 1e-08,
  grad_tol = 1e-08,
  numCores = 1
)

Arguments

dataset: See Fujita2023, Shao2019 or vanderPloeg2024.
minNumComponents: Minimum number of components (default 1).
maxNumComponents: Maximum number of components (default 5).
numFolds: Number of bootstrapped models to create.
considerGroups: Consider subject groups in calculating sparsity (default FALSE)
groupVariable: Column name in dataset$mode1 that should be used to consider groups (default "")
colourCols: Vector of strings stating which column names should be factorized for colours per mode.
legendTitles: Vector of strings stating the legend title per mode.
xLabels: Vector of strings stating the x-axis labels per mode.
legendColNums: Vector of integers stating the desired number of columns for the legends per mode.
arrangeModes: Vector of boolean values per mode, stating if the loadings should be arranged according to colourCols (TRUE) or not (FALSE).
method: Use ALS algorithm ("als", default) or use all-at-once optimization ("opt"). The all-at-once optimization is based on a nonlinear conjugate gradient method with Hestenes-Stiefel updates and the More-Thuente line search algorithm.
ctol: Relative change in loss tolerated to call the algorithm converged in the ALS case (default 1e-4).
maxit: Maximum number of iterations allowed without convergence in the ALS case (default 500).
max_fn: Maximum number of function evaluations allowed without convergence in the OPT case (default 10000).
rel_tol: Relative change in loss tolerated to call the algorithm converged in the OPT case (default 1e-8).
abs_tol: Absolute loss tolerated to call the algorithm converged in the OPT case (default 1e-8).
grad_tol: Tolerance on the two-norm of the gradient divided over the number of elements in the gradient in the OPT case (default 1e-8).
numCores: Number of cores to use. If set larger than 1, it will run the job in parallel (default 1)

Value

A list containing the following:

models: All stabilized sign-flipped bootstrapped PARAFAC models.
modelPlots: A list of plots of the median model with error bars for each number of components.
FMSplot: A bar plot showing the Factor Match Scores per number of components (see Li et al., 2024).
FMS: FMS values that the FMS plot is based on.

Examples

processedFujita = processDataCube(Fujita2023, sparsityThreshold=0.99, centerMode=1, scaleMode=2)
modelStability = assessModelStability(processedFujita,
                                      minNumComponents=1,
                                      maxNumComponents=2,
                                      ctol=1e-4,
                                      maxit=250)