mixfaControl: Control settings for the IMIFA family of factor analytic...

In Keefe-Murphy/IMIFA: Infinite Mixtures of Infinite Factor Analysers and Related Models

Control settings for the IMIFA family of factor analytic mixtures

Description

Supplies a list of arguments for use in mcmc_IMIFA pertaining to ALL methods in the IMIFA family: e.g. MCMC settings, cluster initialisation, generic hyperparameters for factor-analytic mixtures, etc.

Usage

mixfaControl(n.iters = 25000L,
             burnin = n.iters/5L,
             thinning = 2L,
             centering = TRUE,
             scaling = c("unit", "pareto", "none"),
             uni.type = c("unconstrained", "isotropic",
                          "constrained", "single"),
             psi.alpha = 2.5,
             psi.beta = NULL,
             mu.zero = NULL,
             sigma.mu = 1L,
             prec.mu = 0.01,
             sigma.l = 1L,
             z.init = c("hc", "kmeans", "list", "mclust", "priors"),
             z.list = NULL,
             equal.pro = FALSE,
             uni.prior = c("unconstrained", "isotropic"),
             mu0g = FALSE,
             psi0g = FALSE,
             drop0sd = TRUE,
             verbose = interactive(),
             ...)

Arguments

n.iters	The number of iterations to run the sampler for. Defaults to 25000.
burnin	The number of burn-in iterations for the sampler. Defaults to n.iters/5. Note that chains can also be burned in later, using get_IMIFA_results.
thinning	The thinning interval used in the simulation. Defaults to 2. No thinning corresponds to 1. Note that chains can also be thinned later, using get_IMIFA_results.
centering	A logical value indicating whether mean centering should be applied to the data, defaulting to TRUE.
scaling	The scaling to be applied - one of "unit", "none" or "pareto". Defaults to "unit".
uni.type	This argument specifies the type of constraint, if any, to be placed on the uniquenesses/idiosyncratic variances, i.e. whether a general diagonal matrix or isotropic diagonal matrix is to be assumed, and in turn whether these matrices are constrained to be equal across clusters. The default "unconstrained" corresponds to factor analysis (and mixtures thereof), whereas "isotropic" corresponds to probabilistic principal components analysers (and mixtures thereof). Constraints may be particularly useful when N <= P, though caution is advised when employing constraints for any of the infinite factor models, especially "isotropic" and "single", which may lead to overestimation of the number of clusters &/or factors if this specification is inappropriate. The four options correspond to the following 4 parsimonious Gaussian mixture models: "unconstrained" (UUU) - variable-specific and cluster-specific: \Psi_g = \Psi_g. "isotropic" (UUC) - cluster-specific, equal across variables: \Psi_g = \psi\mathcal{I}_p. "constrained" (UCU) - variable-specific, equal across clusters: \Psi_g = \Psi. "single" (UCC) - single value equal across clusters and variables: \Psi_g = \psi\mathcal{I}_p. The first letter U here corresponds to constraints on loadings (not yet implemented), the second letter corresponds to uniquenesses constrained/unconstrained across clusters, and the third letter corresponds to the isotropic constraint on the uniquenesses. Of course, only the third letter is of relevance for the single-cluster "FA" and "IFA" models, such that "unconstrained" and "constrained" are equivalent for these models, and so too are "isotropic" and "single".
psi.alpha	The shape of the inverse gamma prior on the uniquenesses. Defaults to 2.5. Must be greater than 1 if psi.beta is not supplied. Otherwise be warned that values less than or equal to 1 may not bound uniquenesses sufficiently far away from 0, and the algorithm may therefore terminate. Also, excessively small values may lead to critical numerical issues and should thus be avoided.
psi.beta	The scale of the inverse gamma prior on the uniquenesses. Can be either a single scalar parameter, a vector of variable specific scales, or (if psi0g is TRUE) a matrix of variable and cluster-specific scales (or a vector coercible to such a matrix) or a list of length length(range.G) of such items of appropriate dimensions. If this is not supplied, psi_hyper is invoked to choose sensible values, depending on the value of uni.prior and the data size and dimension and, for the "MFA" and "MIFA" models only, the value of psi0g (i.e., psi_hyper is applied per cluster if psi0g is TRUE and psi.beta is not supplied). Excessively small values may lead to critical numerical issues and should thus be avoided. Note that optional arguments to psi_hyper can be supplied via the ... construct here.
mu.zero	The mean of the prior distribution for the mean parameter. Either a scalar, a vector of appropriate dimension, or (if mu0g is TRUE) a matrix of variable-specific and cluster-specific hypermeans (or a vector coercible to such a matrix) or a list of length length(range.G) of such items of appropriate dimensions. Defaults to the sample mean of the data.
sigma.mu	The covariance of the prior distribution for the cluster mean parameters. Always assumed to be a diagonal matrix, and set to the identity matrix by default. Can also be a scalar by which the identity is multiplied, a vector of appropriate dimension; if supplied as a matrix, only the diagonal elements will be extracted. Specifying sigma.mu=NULL will use the diagonal entries of the sample covariance matrix: for unit-scaled data this is simply the identity again. See prec.mu for further control over the hypercovariance in the prior for the means.
prec.mu	A scalar controlling the degree of flatness of the prior for the cluster means by scaling sigma.mu (i.e. multiplying every element of sigma.mu by 1/prec.mu). Lower values lead to a more diffuse prior. Defaults to 0.01, such that the prior is relatively non-informative by default. Of course, prec.mu=1 nullifies any effect of this argument. The user can supply a scaled sigma.mu directly, but this argument is especially useful when specifying sigma.mu=NULL, such that the diagonal entries of the sample covariance matrix are used.
sigma.l	A scalar controlling the diagonal covariance of the prior distribution for the loadings. Defaults to 1, i.e. the identity; otherwise a diagonal matrix with non-zero entries all equal to sigma.l Only relevant for the finite factor methods.
z.init	The method used to initialise the cluster labels. Defaults to model-based agglomerative hierarchical clustering via "hc". Other options include "kmeans" (with 10 random starts, by default), Mclust via "mclust", random initialisation via "priors", and a user-supplied "list" (z.list). Not relevant for the "FA" and "IFA" methods. Arguments for the relevant functions can be passed via the ... construct. For "hc", VVV is used by default, unless the data is high-dimensional, in which case the default is EII. The option "priors" may lead to empty components at initialisation, which will return an error. In any case, unless z.list is explicitly supplied, or verbose is FALSE, the initial cluster sizes will be printed to the screen to alert users to potentially bad initialisiations (e.g. heavily imbalanced initial cluster sizes).
z.list	A user supplied list of cluster labels. Only relevant if z.init == "z.list".
equal.pro	Logical variable indicating whether or not the mixing mixing proportions are to be equal across clusters in the model (default = FALSE). Only relevant for the "MFA" and "MIFA" methods.
uni.prior	A switch indicating whether uniquenesses scale hyperparameters are to be "unconstrained" or "isotropic", i.e. variable-specific or not. "uni.prior" must be "isotropic" if the last letter of uni.type is C, but can take either value otherwise. Defaults to correspond to the last letter of uni.type if that is supplied and uni.prior is not, otherwise defaults to "unconstrained" (though "isotropic" is recommended when N <= P). Only relevant when psi.beta is not supplied and psi_hyper is therefore invoked (with optional arguments passable via the ... construct).
mu0g	Logical indicating whether the mu.zero hyperparameter can be cluster-specific. Defaults to FALSE. Only relevant for the "MFA" and "MIFA" methods when z.list is supplied. See Examples below.
psi0g	Logical indicating whether the psi.beta hyperparameter(s) can be cluster-specific. Defaults to FALSE. Only relevant for the "MFA" and "MIFA" methods when z.list is supplied and only allowable when uni.type is one of unconstrained or isotropic. See Examples below.
drop0sd	Logical indicating whether to drop variables with no standard deviation (defaults to TRUE). This is strongly recommended, especially a) when psi.beta is not supplied &/or sigma.mu=NULL, and either/both are therefore estimated using the empirical covariance matrix, &/or b) if some form of posterior predictive checking is subsequently desired when calling get_IMIFA_results.
verbose	Logical indicating whether to print output (e.g. run times) and a progress bar to the screen while the sampler runs. By default is TRUE if the session is interactive, and FALSE otherwise. If FALSE, warnings and error messages will still be printed to the screen, but everything else will be suppressed.
...	Also catches unused arguments. A number of optional arguments can be also supplied here: The additional psi_hyper argument beta0, especially when N <= P. Additional arguments to be passed to hc (modelName & use only), to Mclust (modelNames, and the arguments for hc with which Mclust is itself initialised - modelName & use), or to kmeans (iter.max and nstart only), depending on the value of z.init. Additionally, when z.init="mclust", criterion can be passed here (can be "icl" or "bic", the default) to control how the optimum Mclust model to initialise with is determined.

Value

A named list in which the names are the names of the arguments and the values are the values of the arguments.

Note

Users should be careful to note that data are mean-centered (centering=TRUE) and unit-scaled (scaling="unit") by default when supplying other parameters among the list above, especially those related in any way to psi.hyper, or to the other control functions mgpControl and bnpControl.

Author(s)

Keefe Murphy - <[e-mail]>

References

Murphy, K., Viroli, C., and Gormley, I. C. (2020) Infinite mixtures of infinite factor analysers, Bayesian Analysis, 15(3): 937-963. <\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1214/19-BA1179")}>.

McNicholas, P. D. and Murphy, T. B. (2008) Parsimonious Gaussian mixture models, Statistics and Computing, 18(3): 285-296.

See Also

mcmc_IMIFA, psi_hyper, hc, kmeans, Mclust, mgpControl, bnpControl, storeControl

Examples

mfctrl <- mixfaControl(n.iters=200, prec.mu=1E-03, sigma.mu=NULL,
                       beta0=1, uni.type="constrained")

# data(olive)
# sim  <- mcmc_IMIFA(olive, "IMIFA", mixFA=mfctrl)

# Alternatively specify these arguments directly
# sim  <- mcmc_IMIFA(olive, "IMIFA", n.iters=200, prec.mu=1E-03,
#                    sigma.mu=NULL, beta0=1, uni.type="constrained")

# Use mu0g and psi0g for MIFA models with supplied cluster labels
# oliveScaled <- as.data.frame(scale(olive[,-(1:2)]))
# sim2 <- mcmc_IMIFA(olive, "MIFA", n.iters=200, range.G=c(3, 9),
#                    z.list=list(olive$area, olive$region), mu0g=TRUE, psi0g=TRUE,
#                    mu.zero=list(do.call(cbind, tapply(oliveScaled, olive$area,   colMeans)),
#                                 do.call(cbind, tapply(oliveScaled, olive$region, colMeans))))

Keefe-Murphy/IMIFA documentation built on Jan. 31, 2024, 2:15 p.m.