parafac4microbiome (version 1.1.2)

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

Description

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
)

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.

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)

Examples

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