A n * G matrix representing a hard partition (all entries 0 or 1) or soft cluster-membership probabilities.

An object of class "MoEClust" generated by MoE_clust, or an object of class "MoECompare" generated by MoE_compare. Models with gating and/or expert covariates and/or a noise component are facilitated here too.

A logical indicating whether the average posterior probabilities should be computed per component. Defaults to TRUE.

An object of class "MoEClust" generated by MoE_clust, or an object of class "MoECompare" generated by MoE_compare. Models with a noise component are facilitated here too.

A vector of colours as per image. Will be checked for validity.

A logical (defaults to TRUE) indicating whether observations should be reordered for visual clarity.

A logical (defaults to TRUE) indicating whether to append a colour key legend.

Catches unused arguments, or arguments to be passed to hclust when reorder=TRUE.

An object of class "MoEClust" generated by MoE_clust, or an object of class "MoECompare" generated by MoE_compare. Models with a noise component are facilitated here too.

The type of plot to be produced (defaults to "barplot"). The "profile" option instead displays uncertainties in increasing/decreasing order of magnitude (see decreasing).

An optional argument giving the true classification of the data. When truth is supplied and type="barplot", misclassified observations are highlighted in a different colour, otherwise observations with uncertainty greater than 1/res$G are given in a different colour. When truth is supplied and type="profile", the uncertainty of misclassified observations is marked by vertical lines on the plot.

A logical indicating whether uncertainties should be ordered in decreasing order (defaults to FALSE). Only relevant when type="profile".

Only relevant when truth=NULL. A character string indicating whether points should be coloured according to their "cluster"-memberships (the default) in res$classification, according to whether they exceed the threshold to be deemed "uncertain", or not at all ("none"). "cluster" is inadvisable when the number of clusters res$G is large.

A logical which is relevant only when type="barplot" and res$d == 1, i.e. the model was fitted to univariate data. When rug1d=TRUE, the x-axis is given by the actual observations (indicated with a rug), otherwise the x-axis is given by the indices of the observations as per similar plots when res$d > 1.

Catches unused arguments.

A numeric vector, matrix, or data frame of observations. Categorical variables are not allowed. If a matrix or data frame, rows correspond to observations and columns correspond to variables.

An integer vector specifying the number(s) of mixture components (clusters) to fit. Defaults to G=1:9. Must be a strictly positive integer, unless a noise component is included in the estimation, in which case G=0 is allowed and also included by default. (see MoE_control).

A vector of character strings indicating the models to be fitted in the EM/CEM phase of clustering. With n observations and d variables, the defaults are:

For single-component models these options reduce to:

For zero-component models with a noise component only the "E" and "EII" models will be fitted for univariate and multivariate data, respectively, although this is clearly for naming consistency only. The help file for mclustModelNames further describes the available models (though the "X" in the single-component models will be coerced to "E" if supplied that way). For single-component models, other model names equivalent to those above can be supplied, but will be coerced to those above.

A formula for determining the model matrix for the multinomial logistic regression in the gating network when fixed covariates enter the mixing proportions. Defaults to ~1, i.e. no covariates. This will be ignored where G=1. Continuous, categorical, and/or ordinal covariates are allowed. Logical covariates will be coerced to factors. Interactions, transformations, and higher order terms are permitted: the latter must be specified explicitly using the AsIs operator (I). The specification of the LHS of the formula is ignored. Intercept terms are included by default.

A formula for determining the model matrix for the (multivariate) WLS in the expert network when fixed covariates are included in the component densities. Defaults to ~1, i.e. no covariates. Continuous, categorical, and/or ordinal covariates are allowed. Logical covariates will be coerced to factors. Interactions, transformations, and higher order terms are permitted: the latter must be specified explicitly using the AsIs operator (I). The specification of the LHS of the formula is ignored. Intercept terms are included by default.

A list of control parameters for the EM/CEM and other aspects of the algorithm. The defaults are set by a call to MoE_control. In particular, arguments pertaining to the inclusion of an additional noise component are documented here.

An optional data frame (or a matrix with named columns) in which to look for the covariates in the gating &/or expert network formulas, if any. If not found in network.data, any supplied gating &/or expert covariates are taken from the environment from which MoE_clust is called. Try to ensure the names of variables in network.data do not match any of those in data.

An alternative means of passing control parameters directly via the named arguments of MoE_control. Do not pass the output from a call to MoE_control here! This argument is only relevant for the MoE_clust function and will be ignored for the associated print and summary functions.

Arguments required for the print and summary functions: x and object are objects of class "MoEClust" resulting from a call to MoE_clust, while digits gives the number of decimal places to round to for printing purposes (defaults to 3). classification, parameters, and networks are logicals which govern whether a table of the MAP classification of observations, the mixture component parameters, and the gating/expert network coefficients are printed, respectively.

The matched call.

The input data, as a data.frame.

A character string denoting the GPCM/mclust model type at which the optimal criterion occurs.

The number of observations in the data.

The dimension of the data.

The optimal number of mixture components according to criterion.

A matrix of all BIC values with length{G} rows and length(modelNames) columns. May include missing entries: NA represents models which were not visited, -Inf represents models which were terminated due to error, for which a log-likelihood could not be estimated. Inherits the classes "MoECriterion" and "mclustBIC", for which dedicated print, summary, and plot methods exist.

A matrix of all ICL values with length{G} rows and length(modelNames) columns. May include missing entries: NA represents models which were not visited, -Inf represents models which were terminated due to error, for which a log-likelihood could not be estimated. Inherits the classes "MoECriterion" and "mclustICL", for which dedicated print, summary, and plot methods exist.

A matrix of all AIC values with length{G} rows and length(modelNames) columns. May include missing entries: NA represents models which were not visited, -Inf represents models which were terminated due to error, for which a log-likelihood could not be estimated. Inherits the classes "MoECriterion" and "mclustAIC", for which dedicated print, summary, and plot methods exist.

The BIC value corresponding to the optimal model. May not necessarily be the optimal BIC.

The ICL value corresponding to the optimal model. May not necessarily be the optimal ICL.

The AIC value corresponding to the optimal model. May not necessarily be the optimal AIC.

An object of class "MoE_gating" (for which dedicated print, summary, and predict methods exist) and either "multinom" or "glm" (only for single-component models or noise-only models) giving the multinom regression coefficients of the gating network. If gating covariates were NOT supplied (or the best model has just one component), this corresponds to a RHS of ~1, otherwise the supplied gating formula. As such, a fitted gating network is always returned even in the absence of supplied covariates or clusters. The number of parameters to penalise by for MoE_crit is given by length(coef(gating)), and the gating formula used is stored here as an attribute. If there is a noise component (and the option noise.gate=TRUE is invoked), its coefficients are those for the last component. Users are cautioned against making inferences about statistical significance from summaries of the coefficients in the gating network.

An object of class "MoE_expert" (for which dedicated print, summary, and predict methods exist) and "lm" giving the (multivariate) WLS regression coefficients of the expert network. If expert covariates were NOT supplied, this corresponds to a RHS of ~1, otherwise the supplied expert formula. As such, a fitted expert network is always returned even in the absence of supplied covariates. The number of parameters to penalise by for MoE_crit is given by G * length(coef(expert[[1]])), and the expert formula used is stored here is an attribute. Users are cautioned against making inferences about statistical significance from summaries of the coefficients in the expert network.

A matrix of all maximal log-likelihood values with length{G} rows and length(modelNames) columns. May include missing entries: NA represents models which were not visited, -Inf represents models which were terminated due to error, for which a log-likelihood could not be estimated. Inherits the classes "MoECriterion" and "mclustLOGLIK", for which dedicated print, summary, and plot methods exist.

The vector of increasing log-likelihood values for every EM/CEM iteration under the optimal model. The last element of this vector is the maximum log-likelihood achieved by the parameters returned at convergence.

An asymptotic estimate of the final converged maximised log-likelihood. Returned when stopping="aitken" and G > 1 (see MoE_control and aitken), otherwise the last element of loglik is returned instead.

The number of estimated parameters in the optimal model (i.e. the number of ‘used’ degrees of freedom). Subtract this number from n to get the degrees of freedom. The number of parameters due to the gating network, expert network, and covariance matrices are also stored here as attributes of df.

The total number of EM/CEM iterations for the optimal model.

The hypervolume parameter for the noise component if required, otherwise set to NA (see MoE_control).

A list with the following named components:

pro

The mixing proportions: either a vector of length G or, if gating covariates were supplied, a matrix with an entry for each observation (rows) and component (columns).

mean

The means of each component. If there is more than one component, this is a matrix whose k-th column is the mean of the k-th component of the mixture model.

For models with expert network covariates, this is given by the posterior mean of the fitted values, otherwise the posterior mean of the response is reported. For models with expert network covariates, the observation-specific component means can be accessed by calling predict on the expert object above.

variance

A list of variance parameters of each component of the model. The components of this list depend on the model type specification. See the help file for mclustVariance for details. Also see expert_covar for an alternative approach to summarising the variance parameters in the presence of expert network covariates.

Vinv

The inverse of the hypervolume parameter for the noise component if required, otherwise set to NULL (see MoE_control).

The final responsibility matrix whose [i,k]-th entry is the probability that observation i belonds to the k-th component. If there is a noise component, its values are found in the last column.

The vector of cluster labels for the chosen model corresponding to z, i.e. max.col(z). Observations belonging to the noise component, if any, will belong to component 0.

The uncertainty associated with the classification.

A data frame gathering the unique set of covariates used in the gating and expert networks, if any. Will contain zero columns in the absence of gating or expert network covariates. Supplied gating covariates will be excluded if the optimal model has only one component. May have fewer columns than covariates supplied via the network.data argument also, as only the included covariates are gathered here.

In the presence of expert network covariates, this is the augmented data actually used in the clustering at convergence, as a list of G matrices of WLS residuals of dimension n * d. Will contain zero columns in the absence of expert network covariates.

A matrix giving the numbers of estimated parameters (i.e. the number of ‘used’ degrees of freedom) for all visited models, with length{G} rows and length(modelNames) columns. Subtract these numbers from n to get the degrees of freedom. May include missing entries: NA represents models which were not visited, -Inf represents models which were terminated due to error, for which parameters could not be estimated. Inherits the classes "MoECriterion" and "mclustDF", for which dedicated print, summary, and plot methods exist.

A matrix giving the total number of EM/CEM iterations for all visited models, with length{G} rows and length(modelNames) columns. May include missing entries: NA represents models which were not visited, Inf represents models which were terminated due to singularity/error and thus would never have converged. Inherits the classes "MoECriterion" and "mclustITERS", for which dedicated print, summary, and plot methods exist.

One or more objects of class "MoEClust" outputted by MoE_clust. All models must have been fit to the same data set. A single named list of such objects can also be supplied. Additionally, objects of class "MoECompare" outputted by this very function can also be supplied here.

This argument is only relevant for the MoE_compare function and will be ignored for the associated print function.

The criterion used to determine the ranking. Defaults to "bic".

The (integer) number of models to be ranked and compared. Defaults to 10L. Will be constrained by the number of models within the "MoEClust" objects supplied via ... if optimal.only is FALSE, otherwise constrained simply by the number of "MoEClust" objects supplied. Setting pick=Inf is a valid way to select all models.

Logical indicating whether to only rank models already deemed optimal within each "MoEClust" object (TRUE), or to allow models which were deemed suboptimal enter the final ranking (FALSE, the default). See details.

Arguments required for the associated print function:

x

An object of class "MoECompare" resulting from a call to MoE_compare.

index

A logical or numeric vector giving the indices of the rows of the table of ranked models to print. This defaults to the full set of ranked models. It can be useful when the table of ranked models is large to examine a subset via this index argument, for display purposes. See rerank.

posidens

A logical indicating whether models which have been flagged for having positive log-densities should be included in the comparison (defaults to TRUE). Such models may correspond to spurious solutions and can be discarded by specifying posidens=FALSE. Only relevant if any of the "MoEClust" objects being compared were themselves run with posidens=TRUE.

rerank

A logical indicating whether the ranks should be recomputed when subsetting using index. Defaults to FALSE. Only relevant when details=TRUE.

digits

The number of decimal places to round model selection criteria to (defaults to 3).

details

Logical indicating whether some additional details should be printed, defaults to TRUE. Exists to facilitate MoE_stepwise printing.

maxi

A number specifying the maximum number of rows/models to print. Defaults to length(index).

The name of the data set to which the models were fitted.

The single optimal model (an object of class "MoEClust") among those supplied, according to the chosen criterion.

The final number of ranked models. May be different (i.e. less than) the supplied pick value.

The names of the supplied "MoEClust" objects.

The mclustModelNames.

The optimal numbers of components.

The numbers of estimated parameters.

The numbers of EM/CEM iterations.

BIC values, ranked according to criterion (not necessarily "bic").

ICL values, ranked according to criterion (not necessarily "icl").

AIC values, ranked according to criterion (not necessarily "aic").

Maximal log-likelihood values.

The gating formulas.

The expert formulas.

The algorithm used for fitting the model - either "EM", "CEM", "cemEM".

Logical indicating whether mixing proportions were constrained to be equal across components.

Hypervolume parameters for the noise component if relevant, otherwise set to NA (see MoE_control).

The type of noise component fitted (if any). Only displayed if at least one of the compared models has a noise component.

Logical indicating whether gating covariates were allowed to influence the noise component's mixing proportion. Only printed for models with a noise component, when at least one of the compared models has gating covariates.

Logical indicating whether the mixing proportion of the noise component for equalPro models is also equal (TRUE) or estimated (FALSE).

The method used to initialise the cluster labels for the non-noise components. Defaults to "hc", i.e. model-based agglomerative hierarchical clustering tree as per hc, for multivariate data (see hc.args), or "quantile"-based clustering as per quant_clust for univariate data (unless there are expert network covariates incorporated via exp.init$joint &/or exp.init$clustMD, in which case the default is again "hc"). The "quantile" option is thus only available for univariate data when expert network covariates are not incorporated via exp.init$joint &/or exp.init$clustMD, or when expert network covariates are not supplied.

Other options include "kmeans" (see km.args), "random.hard" or "soft.random" initialisation (see nstarts below), where init.z="soft.random" is only available when algo != "EM", a user-supplied "list" (see z.list below), and a full run of Mclust (itself initialised via a model-based agglomerative hierarchical clustering tree, again see hc.args), although this last option "mclust" will be coerced to "hc" if there are no gating &/or expert covariates within MoE_clust (in order to better reproduce Mclust output).

When init.z="list", exp.init$clustMD is forced to FALSE; otherwise, when exp.init$clustMD=TRUE and the clustMD package is loaded, the init.z argument instead governs the method by which a call to clustMD is initialised. In this instance, "quantile" will instead default to "hc", and the arguments to hc.args and km.args will be ignored (unless all clustMD model types fail for a given number of components).

When init.z="mclust" or clustMD is successfully invoked (via exp.init$clustMD), the argument init.crit (see below) specifies the model-selection criterion ("bic" or "icl") by which the optimal Mclust or clustMD model type to initialise with is determined, and criterion remains unaffected.

Finally, when the model includes expert network covariates and exp.init$mahalanobis=TRUE, the argument exp.init$estart (see below) can be used to modify the behaviour of init.z="random.hard" or init.z="soft.random" when nstarts > 1, toggling between a full run of the EM algorithm for each random initialisation (i.e. exp.init$estart=FALSE, the default), or a single run of the EM algorithm starting from the best initial partition obtained among the random starts according to the iterative reallocation initialisation routine (i.e. exp.init$estart=TRUE).

A list supplying select named parameters to control inclusion of a noise component in the estimation of the mixture. If either or both of the arguments tau0 &/or noise.init are supplied, a noise component is added to the the model in the estimation.

tau0

Prior mixing proportion for the noise component. If supplied, a noise component will be added to the model in the estimation, with tau0 giving the prior probability of belonging to the noise component. Typically supplied as a scalar in the interval (0, 1), e.g. 0.1, such that the same prior probability of belonging to the noise component applies to all observations. However, tau0 can also be supplied as a vector (with length equal to the number of observations), which may be particularly useful when gating covariates are present and noise.args$noise.gate is TRUE. Finally, note that this argument can be supplied instead of or in conjunction with the argument noise.init below.

noise.init

A logical or numeric vector indicating an initial guess as to which observations are noise in the data. If numeric, the entries should correspond to row indices of the data. If supplied, a noise component will be added to the model in the estimation. This argument can be used in conjunction with tau0 above, or can be replaced by that argument also.

noise.gate

A logical indicating whether gating network covariates influence the mixing proportion for the noise component, if any. Defaults to TRUE, but leads to greater parsimony if FALSE. Only relevant in the presence of a noise component; only effects estimation in the presence of gating covariates.

noise.meth

The method used to estimate the volume when a noise component is invoked. Defaults to hypvol. For univariate data, this argument is ignored and the range of the data is used instead (unless noise.vol below is specified). The options "convexhull" and "ellipsoidhull" require loading the geometry and cluster packages, respectively. This argument is only relevant if noise.vol below is not supplied.

noise.vol

This argument can be used to override the argument noise.meth by specifying the (hyper)volume directly, i.e. specifying an improper uniform density. This will override the use of the range of the response data for univariate data if supplied. Note that the (hyper)volume, rather than its inverse, is supplied here. This can affect prediction and the location of the MVN ellipses for MoE_gpairs plots (see noise_vol).

equalNoise

Logical which is only invoked when equalPro=TRUE and gating covariates are not supplied. Under the default setting (FALSE), the mixing proportion for the noise component is estimated, and remaining mixing proportions are equal; when TRUE all components, including the noise component, have equal mixing proportions.

discard.noise

A logical governing how the means are summarised in parameters$mean and by extension the location of the MVN ellipses in MoE_gpairs plots for models with both expert network covariates and a noise component (otherwise this argument is irrelevant).

The means for models with expert network covariates are summarised by the posterior mean of the fitted values. By default (FALSE), the mean of the noise component is accounted for in the posterior mean. Otherwise, or when the mean of the noise component is unavailable (due to having been manually supplied via noise.args$noise.vol), the z matrix is renormalised after discarding the column corresponding to the noise component prior to computation of the posterior mean. The renormalisation approach can be forced by specifying noise.args$discard.noise=TRUE, even when the mean of the noise component is available. For models with a noise component fitted with algo="CEM", a small extra E-step is conducted for observations assigned to the non-noise components in this case.

In particular, the argument noise.meth will be ignored for high-dimensional n <= d data, in which case the argument noise.vol must be specified. Note that this forces noise.args$discard.noise to TRUE. See noise_vol for more details.

The arguments tau0 and noise.init can be used separately, to provide alternative means to invoke a noise component. However, they can also be supplied together, in which case observations corresponding to noise.init have probability tau0 (rather than 1) of belonging to the noise component. This strategy also works when tau0 is supplied as a vector.

The default values of stopping and hc.args$hcUse (see below) are such that results for models with no covariates in either network are liable to differ from results for equivalent models obtained via Mclust. MoEClust uses stopping="aitken" and hcUse="VARS" by default, while mclust always implicitly uses stopping="relative" and defaults to hcUse="SVD".

asMclust is a logical variable (FALSE, by default) which functions as a simple convenience tool for overriding only these two arguments (even if explicitly supplied!) such that they behave like the function Mclust. Other user-specified arguments which differ from mclust are not affected by asMclust, as their defaults already correspond to mclust. Results may still differ slightly as MoEClust calculates log-likelihood values with greater precision and may also differ slightly in other numerical aspects which affect parameter estimation or convergence in some cases. Finally, note that asMclust=TRUE can be invoked even for models with covariates which are not accommodated by mclust.

Logical variable indicating whether or not the mixing proportions are to be constrained to be equal in the model. Default: equalPro = FALSE. Only relevant when gating covariates are not supplied within MoE_clust, otherwise ignored. In the presence of a noise component (see noise.args), only the mixing proportions for the non-noise components are constrained to be equal (by default, see equalNoise), after accounting for the noise component.

A list supplying select named parameters to control the initialisation routine in the presence of expert network covariates (otherwise ignored):

joint

A logical indicating whether the initial partition is obtained on the joint distribution of the responses & expert network covariates (defaults to TRUE) or just the responses (FALSE). By default, only continuous expert covariates are considered (see exp.init$clustMD below). Only relevant when init.z is neither "random.hard" nor "soft.random" (unless exp.init$clustMD=TRUE, in which case init.z specifies the initialisation routine for a call to clustMD, where init.z="random.hard" & init.z="soft.random" both map to the clustMD argument startCL="random"). This will render the "quantile" option of init.z for univariate data unusable if continuous expert covariates are supplied &/or categorical/ordinal expert covariates are supplied when exp.init$clustMD=TRUE and the clustMD package is loaded.

mahalanobis

A logical indicating whether to iteratively reallocate observations during the initialisation phase to the component corresponding to the expert network regression to which it's closest to the fitted values of in terms of Mahalanobis distance (defaults to TRUE). This will ensure that each component can be well modelled by a single expert prior to running the EM/CEM algorithm.

estart

A logical governing the behaviour of init.z="random.hard" or init.z="soft.random" when nstarts > 1 in the presence of expert network covariates. Only relevant when exp.init$mahalanobis=TRUE. Defaults to FALSE; i.e. all random starts are put through full runs of the EM algorithm. When TRUE, all random starts are put through the initial iterative reallocation routine prior to a full run of EM for only the single best random initial partition obtained. See the last set of Examples below.

clustMD

A logical indicating whether categorical/ordinal covariates should be incorporated when using the joint distribution of the response and expert network covariates for initialisation (defaults to FALSE). Only relevant when exp.init$joint=TRUE. Requires the use of the clustMD package. Note that initialising in this manner involves fitting all clustMD model types in parallel for all numbers of components considered, and may fail (especially) in the presence of nominal expert network covariates.

Unless init.z="list", supplying this argument as TRUE when the clustMD package is loaded has the effect of superseding the init.z argument: this argument now governs instead how the call to clustMD is initialised (unless all clustMD model types fail for a given number of components, in which case init.z is invoked instead to initialise for G values for which all clustMD model types failed). Similarly, the arguments hc.args and km.args will be ignored (again, unless all clustMD model types fail for a given number of components).

max.init

The maximum number of iterations for the Mahalanobis distance-based reallocation procedure when exp.init$mahalanobis is TRUE. Defaults to .Machine$integer.max.

identity

A logical indicating whether the identity matrix (corresponding to the use of the Euclidean distance) is used in place of the covariance matrix of the residuals (corresponding to the use of the Mahalanobis distance). Defaults to FALSE for multivariate response data but defaults to TRUE for univariate response data. Setting identity=TRUE with multivariate data may be advisable when the dimensions of the data are such that the covariance matrix cannot be inverted (otherwise, the pseudo-inverse is used under the FALSE default).

drop.break

When exp.init$mahalanobis=TRUE observations will be completely in or out of a component during the initialisation phase. As such, it may occur that constant columns will be present when building a given component's expert regression (particularly for categorical covariates). It may also occur, due to this partitioning, that "unseen" data, when calculating the residuals, will have new factor levels. When exp.init$drop.break=TRUE, the Mahalanobis distance based initialisation phase will explicitly fail in either of these scenarios.

Otherwise, drop_constants and drop_levels will be invoked when exp.init$drop.break is FALSE (the default) to try to remedy the situation. In any case, only a warning that the initialisation step failed will be printed, regardless of the value of exp.init$drop.break.

Switch controlling whether models are fit using the "EM" (the default) or "CEM" algorithm. The option "cemEM" allows running the EM algorithm starting from convergence of the CEM algorithm.

When either G or modelNames is a vector, criterion determines whether the "bic" (Bayesian Information Criterion), "icl" (Integrated Complete Likelihood), "aic" (Akaike Information Criterion) is used to determine the ‘best’ model when gathering output. Note that all criteria will be returned in any case.

The criterion used to assess convergence of the EM/CEM algorithm. The default ("aitken") uses Aitken's acceleration method via aitken, otherwise the "relative" change in log-likelihood is monitored (which may be less strict). The "relative" option corresponds to the stopping criterion used by Mclust: see asMclust above.

Both stopping rules are ultimately governed by tol[1]. When the "aitken" method is employed, the asymptotic estimate of the final converged maximised log-likelihood is also returned as linf for models with 2 or more components, though the largest element of the returned vector loglik still gives the log-likelihood value achieved by the parameters returned at convergence, under both stopping methods (see MoE_clust).

A user supplied list of initial cluster allocation matrices, with number of rows given by the number of observations, and numbers of columns given by the range of component numbers being considered. In particular, z.list must only include columns corresponding to non-noise components when using this method to initialise in the presence of a noise component. Only relevant if init.z="z.list". These matrices are allowed correspond to both soft or hard clusterings, and will be internally normalised so that the rows sum to 1 (or coerced always to a 'hard' matrix if algo != "EM"). See noise.init and tau0 above for details on initialisation in the presence of a noise component.

The number of random initialisations to use when init.z="random.hard" or init.z="soft.random". Defaults to 1. When there are no expert covariates (or when exp.init$mahalanobis=FALSE or exp.init$estart=FALSE), the results will be based on the random start yielding the highest estimated log-likelihood after each initial partition is subjected to a full run of the EM algorithm. Note, in this case, that all nstarts random initialisations are affected by exp.init$mahalanobis, if invoked in the presence of expert network covariates, which may remove some of the randomness.

Conversely, if exp.init$mahalanobis=TRUE and exp.init$estart=TRUE, all nstarts random starts are put through the initial iterative reallocation routine and only the single best initial partition uncovered is put through the full run of the EM algorithm. See init.z and exp.init$estart above for more details, though note that exp.init$mahalanobis=TRUE and exp.init$estart=FALSE, by default.

A scalar tolerance associated with deciding when to terminate computations due to computational singularity in covariances. Smaller values of eps allow computations to proceed nearer to singularity. The default is the relative machine precision .Machine$double.eps, which is approximately 2e-16 on IEEE-compliant machines.

A vector of length three giving relative convergence tolerances for 1) the log-likelihood of the EM/CEM algorithm, 2) parameter convergence in the inner loop for models with iterative M-step ("VEI", "VEE", "EVE", "VVE", "VEV"), and 3) optimisation in the multinomial logistic regression in the gating network, respectively. The default is c(1e-05, sqrt(.Machine$double.eps), 1e-08). If only one number is supplied, it is used as the tolerance for all three cases given.

A vector of length three giving integer limits on the number of iterations for 1) the EM/CEM algorithm, 2) the inner loop for models with iterative M-step ("VEI", "VEE", "EVE", "VVE", "VEV"), and 3) the multinomial logistic regression in the gating network, respectively.

The default is c(.Machine$integer.max, .Machine$integer.max, 1000L), allowing termination to be completely governed by tol[1] & tol[2] for the inner and outer loops of the EM/CEM algorithm. If only one number is supplied, it is used as the iteration limit for the outer loop only and the other elements of itmax retain their usual defaults.

If, for any model with gating covariates, the multinomial logistic regression in the gating network fails to converge in itmax[3] iterations at any stage of the EM/CEM algorithm, an appropriate warning will be printed, prompting the user to modify this argument.

A list supplying select named parameters to control the initialisation of the cluster allocations when init.z="hc" (or when init.z="mclust", which itself relies on hc), unless exp.init$clustMD=TRUE, the clustMD package is loaded, and none of the clustMD model types fail (otherwise irrelevant):

hcUse

A string specifying the type of input variables to be used. This defaults to "VARS" here, unlike mclust which defaults to "SVD". Other allowable values are documented in mclust.options. See asMclust above.

hc.meth

A character string indicating the model to be used when hierarchical clustering (see hc) is employed for initialisation (either when init.z="hc" or init.z="mclust"). Defaults to "EII" for high-dimensional data, or "VVV" otherwise.

A list supplying select named parameters to control the initialisation of the cluster allocations when init.z="kmeans", unless exp.init$clustMD=TRUE, the clustMD package is loaded, and none of the clustMD model types fail (otherwise irrelevant):

kstarts

The number of random initialisations to use. Defaults to 10.

kiters

The maximum number of K-Means iterations allowed. Defaults to 10.

A logical governing whether to continue running the algorithm even in the presence of positive log-densities. Defaults to TRUE, but setting posidens=FALSE can help to safeguard against spurious solutions, which will be instantly terminated if positive log-densities are encountered. Note that versions of MoEClust prior to and including version 1.3.1 always implicitly assumed posidens=FALSE.

The criterion to be used to determine the optimal model type to initialise with, when init.z="mclust" or when exp.init$clustMD=TRUE and the clustMD package is loaded (one of "bic" or "icl"). Defaults to "icl" when criterion="icl", otherwise defaults to "bic". The criterion argument remains unaffected.

A single number giving the iteration count at which a warning will be printed if the EM/CEM algorithm has failed to converge. Defaults to 0, i.e. no warning (which is true for any warn.it value less than 3), otherwise the message is printed regardless of the value of verbose. If non-zero, warn.it should be moderately large, but obviously less than itmax[1]. A warning will always be printed if one of more models fail to converge in itmax[1] iterations.

The maximum allowable number of weights in the call to multinom for the multinomial logistic regression in the gating network. There is no intrinsic limit in the code, but increasing MaxNWts will probably allow fits that are very slow and time-consuming. It may be necessary to increase MaxNWts when categorical concomitant variables with many levels are included or the number of components is high.

Logical indicating whether to print messages pertaining to progress to the screen during fitting. 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.

Catches unused arguments.

A character string indicating the model. The help file for mclustModelNames describes the available models. Not necessary if df is supplied.

The log-likelihood for a data set with respect to the Gaussian mixture model specified in the modelName argument.

The number of observations in the data, dimension of the data, and number of components in the Gaussian mixture model, respectively, used to compute loglik. d & G are not necessary if df is supplied.

The number of parameters of the gating network of the MoEClust model. Defaults to G - 1, which corresponds to no gating covariates. If covariates are included, this should be the number of regression coefficients in the fitted gating object. If there are no covariates and mixing proportions are further assumed to be present in equal proportion, gating.pen should be 0. The number of parameters used in the estimation of the noise component, if any, should also be included. Not necessary if df is supplied.

The number of parameters of the expert network of the MoEClust model. Defaults to G * d, which corresponds to no expert covariates. If covariates are included, this should be the number of regression coefficients in the fitted expert object. Not necessary if df is supplied.

The n times G responsibility matrix whose [i,k]-th entry is the probability that observation i belongs to the k-th component.. If supplied the ICL is also computed and returned, otherwise only the BIC and AIC.

An alternative way to specify the number of estimated parameters (or ‘used’ degrees of freedom) exactly. If supplied, the arguments modelName, d, G, gating.pen, and expert.pen, which are used to calculate the number of parameters, will be ignored. The number of parameters used in the estimation of the noise component, if any, should also be included.

If there are no expert network covariates, data should be a numeric matrix or data frame, wherein rows correspond to observations (n) and columns correspond to variables (d). If there are expert network covariates, this should be a list of length G containing matrices/data.frames of (multivariate) WLS residuals for each component.

The mean for each of G components. If there is more than one component, this is a matrix whose k-th column is the mean of the k-th component of the mixture model. For the univariate models, this is a G-vector of means. In the presence of expert network covariates, all values should be equal to 0.

The variance component in the parameters list from the output to e.g. MoE_clust. The components of this list depend on the specification of modelName (see mclustVariance for details). The number of components G, the number of variables d, and the modelName are inferred from sigs.

If covariates enter the gating network, an n times G matrix of mixing proportions, otherwise a G-vector of mixing proportions for the components of the mixture. Must be on the log-scale in both cases. The default of 0 effectively means densities (or log-densities) aren't scaled by the mixing proportions.

An estimate of the reciprocal hypervolume of the data region. See the function noise_vol. Used only if an initial guess as to which observations are noise is supplied. Mixing proportion(s) must be included for the noise component also.

(Optional) A numeric matrix whose [i,k]-th entry is the log-density of observation i in component k, scaled by the mixing proportions, to which the function is to be applied, typically obtained by MoE_dens but this is not necessary. If this is supplied, all other arguments are ignored, otherwise MoE_dens is called according to the other supplied arguments. If a vector is supplied, it will be coerced to a matrix with one row.

A matrix with n rows and G columns containing 1 where the observation belongs to the cluster indicated by the column number, and 0 otherwise.

The estimated conditional log-likelihood.

If there are no expert network covariates, data should be a numeric matrix or data frame, wherein rows correspond to observations (n) and columns correspond to variables (d). If there are expert network covariates, this should be a list of length G containing matrices/data.frames of (multivariate) WLS residuals for each component.

The mean for each of G components. If there is more than one component, this is a matrix whose k-th column is the mean of the k-th component of the mixture model. For the univariate models, this is a G-vector of means. In the presence of expert network covariates, all values should be equal to 0.

The variance component in the parameters list from the output to e.g. MoE_clust. The components of this list depend on the specification of modelName (see mclustVariance for details). The number of components G, the number of variables d, and the modelName are inferred from sigs.

If covariates enter the gating network, an n times G matrix of mixing proportions, otherwise a G-vector of mixing proportions for the components of the mixture. Must be on the log-scale in both cases. The default of 0 effectively means densities (or log-densities) aren't scaled by the mixing proportions.

An estimate of the reciprocal hypervolume of the data region. See the function noise_vol. Used only if an initial guess as to which observations are noise is supplied. Mixing proportion(s) must be included for the noise component also.

A logical value indicating whether or not the logarithm of the component densities should be returned. This defaults to TRUE, otherwise component densities are returned, obtained from the component log-densities by exponentiation. The log-densities can be passed to MoE_estep or MoE_cstep.

An object of class "MoEClust" generated by MoE_clust, or an object of class "MoECompare" generated by MoE_compare. Models with gating and/or expert covariates and/or a noise component are facilitated here too.

A logical (defaults to FALSE) indicating whether component-specific average entropies should be returned instead.

If there are no expert network covariates, data should be a numeric matrix or data frame, wherein rows correspond to observations (n) and columns correspond to variables (d). If there are expert network covariates, this should be a list of length G containing matrices/data.frames of (multivariate) WLS residuals for each component.

The mean for each of G components. If there is more than one component, this is a matrix whose k-th column is the mean of the k-th component of the mixture model. For the univariate models, this is a G-vector of means. In the presence of expert network covariates, all values should be equal to 0.

The variance component in the parameters list from the output to e.g. MoE_clust. The components of this list depend on the specification of modelName (see mclustVariance for details). The number of components G, the number of variables d, and the modelName are inferred from sigs.

If covariates enter the gating network, an n times G matrix of mixing proportions, otherwise a G-vector of mixing proportions for the components of the mixture. Must be on the log-scale in both cases. The default of 0 effectively means densities (or log-densities) aren't scaled by the mixing proportions.

An estimate of the reciprocal hypervolume of the data region. See the function noise_vol. Used only if an initial guess as to which observations are noise is supplied. Mixing proportion(s) must be included for the noise component also.

(Optional) A numeric matrix whose [i,k]-th entry is the log-density of observation i in component k, scaled by the mixing proportions, to which the softmax function is to be applied, typically obtained by MoE_dens but this is not necessary. If this is supplied, all other arguments are ignored, otherwise MoE_dens is called according to the other supplied arguments. If a vector is supplied, it will be coerced to a matrix with one row.

A matrix with n rows and G columns containing the probability of cluster membership for each of n observations and G clusters.

The estimated log-likelihood, computed efficiently via logsumexp.

An object of class "MoEClust" generated by MoE_clust, or an object of class "MoECompare" generated by MoE_compare. Models with a noise component are facilitated here too.

The type of plot desired for the scatterplots comparing continuous response variables. Defaults to "points". See scatter.pars below.

Points can also be sized according to their associated clustering uncertainty with the option "uncertainty". In doing so, the transparency of the points will also be proportional to their clustering uncertainty, provided the device supports transparency. See also MoE_Uncertainty for an alternative means of visualising observation-specific cluster uncertainties (especially for univariate data). See scatter.pars below, and note that models fitted via the "CEM" algorithm will have no associated clustering uncertainty.

Alternatively, the bivariate parametric "density" contours can be displayed (see density.pars), provided there is at least one Gaussian component in the model. Caution is advised when producing density plots for models with covariates in the expert network; the required number of evaluations of the (multivariate) Gaussian density for each panel (res$G * prod(density.pars$grid.size)) increases by a factor of res$n, thus plotting may be slow (particularly for large data sets). However, this is offset somewhat by using pre-calculated densities from the corresponding upper-triangular panels when producing the lower-triangular panels. See density.pars below.

A list giving named arguments for producing only a subset of panels:

show.map

Logical indicating whether to show panels involving the MAP classification (defaults to TRUE, unless there is only one component, in which case the MAP classification is never plotted.).

data.ind

For subsetting response variables: a vector of column indices corresponding to the variables in the columns of res$data which should be shown. Defaults to all. Can be 0, in order to suppress plotting the response variables. Alternatively, character strings matching the column names of res$data can be supplied here.

cov.ind

For subsetting covariates: a vector of column indices corresponding to the covariates in the columns res$net.covs which should be shown. Defaults to all. Can be 0, in order to suppress plotting the covariates. Alternatively, character strings matching the column names of res$net.covs can be supplied here.

submat

Can take the values "all" (default), "upper", "lower", or "diagonal", for displaying all panels or only the upper/lower triangular panels or diagonal (marginal) panels of the plot matrix.

The results of the subsetting must ensure that at least one panel of some sort can be plotted. The arguments data.ind and cov.ind can also be used to simply reorder the panels, without actually subsetting. Diagonal panels are always drawn, regardless of the value of submat (but can be somewhat suppressed using diag.pars$show.hist=FALSE and diag.pars$show.dens=FALSE; see diag.pars below). When diag.pars$diagonal=TRUE (the default), the triangular portions are the "upper"-right and "lower"-left, whereas they are the "upper"-left and "lower"-right when diag.pars$diagonal=FALSE. Generally, submat="upper" should be preferable to submat="lower", as it ensures that response variables and covariates are displayed as appropriate on the y-axes and x-axes, respectively.

A vector of length 2 (or 1) giving the plot type for the upper and lower triangular portions of the plot, respectively, pertaining to the associated covariates. Defaults to "lm" for covariate vs. response panels and "points" otherwise. Only relevant for models with continuous covariates in the gating &/or expert network. "ci" and "lm" type plots are only produced for plots pairing covariates with response, and never response vs. response or covariate vs. covariate. Note that lines &/or confidence intervals will only be drawn for continuous covariates included in the expert network; to include covariates included only in the gating network also, the options "lm2" or "ci2" can be used but this is not generally advisable. See scatter.pars below.

A vector of length 2 (or 1) giving the plot type for the upper and lower triangular portions of the plot, respectively, for plots involving a mix of categorical and continuous variables. Defaults to "stripplot" in the upper triangle and "boxplot" in the lower triangle (see panel.stripplot and panel.bwplot). "violin" and "barcode" plots can also be produced. Only relevant for models with categorical covariates in the gating &/or expert network, unless show.MAP is TRUE. Comparisons of two categorical variables (which can only ever be covariates or the MAP classification) are always displayed via mosaic plots (see strucplot).

All conditional panel types can be customised further; see stripplot.pars, boxplot.pars (for both "boxplot" and "violin" plots), barcode.pars, and mosaic.pars below. Note that when conditional is of length 1, that plot type will be used in both the upper and lower triangular portions of the plot, where relevant.

Controls whether to add MVN ellipses with axes corresponding to the within-cluster covariances for the response data. The options "inner" and "outer" (the default) will colour the axes or the perimeter of those ellipses, respectively, according to the cluster they represent (according to scatter.pars$eci.col). The option "both" will obviously colour both the axes and the perimeter. The "yes" or "no" options merely govern whether the ellipses are drawn, i.e. "yes" draws ellipses without any colouring. Ellipses are only ever drawn for multivariate data, and only when response.type is "points" or "uncertainty".

Ellipses are centered on the posterior mean of the fitted values when there are expert network covariates, otherwise on the posterior mean of the response variables. In the presence of expert network covariates, the component-specific covariance matrices are also (by default, via the argument expert.covar below) modified for plotting purposes via the function expert_covar, in order to account for the extra variability of the means, usually resulting in bigger shapes & sizes for the MVN ellipses.

Logical (defaults to TRUE) governing whether the extra variability in the component means is added to the MVN ellipses corresponding to the component covariance matrices in the presence of expert network covariates. See the function expert_covar. Only relevant when response.type is "points" or "uncertainty" when addEllipses is invoked accordingly, and only relevant for models with expert network covariates and multivariate responses.

A vector of length 5 (or 1) containing border colours for plots against the MAP classification, response vs. response, covariate vs. response, response vs. covariate, and covariate vs. covariate panels, respectively.

Defaults to c("purple", "black", "brown", "brown", "navy").

A vector of length 5 (or 1) containing background colours for plots against the MAP classification, response vs. response, covariate vs. response, response vs. covariate, and covariate vs. covariate panels, respectively.

Defaults to c("cornsilk", "white", "palegoldenrod", "palegoldenrod", "cornsilk").

A list of length 4 with units as components named bottom, left, top, and right, giving the outer margins; the defaults uses two lines of text. A vector of length 4 with units (ordered properly) will work, as will a vector of length 4 with numeric variables (interpreted as lines). May need to be increased to accommodate outer labels in some cases.

The default is typically NULL, for alternating labels around the perimeter. If "all", all labels are printed, and if "none", no labels are printed. If subset$submat="upper" or subset$submat="lower", outer.labels instead defaults to "all".

Note that axis labels always correspond to the range of the depicted variable, and thus should not be interpreted as indicating counts or densities for the diagonal panels when diag.pars$show.hist=TRUE &/or diag.pars$show.dens=TRUE.

A 2-vector (x, y) rotating the top/bottom outer labels x degrees and the left/right outer labels y degrees. Only works for categorical labels of boxplot, mosaic, strip plot, and violin plot panels. Defaults to c(0, 90). Reordering via data.ind or cov.ind may improve appearance of outer labels in some cases.

The gap between the tiles; defaulting to 0.05 of the width of a tile.

The fraction by which to expand the range of quantitative variables to provide plots that will not truncate plotting symbols. Defaults to 0.025, i.e. 2.5 percent of the range. Particularly useful when ellipses are drawn (see addEllipses) to ensure ellipses are visible in full.

A logical indicating whether the expansion factor for points on plots involving covariates should also be modified when response.type="uncertainty". Defaults to FALSE, and only relevant for scatterplot and strip plot panels. When TRUE, scatter.pars$uncert.pch is invoked as the plotting symbols for covariate-related scatterplot and strip plot panels, otherwise scatter.pars$scat.pch and stripplot.pars$strip.pch are invoked for such panels.

A list supplying select parameters for the continuous vs. continuous scatterplots.

NULL is equivalent to:

list(scat.pch=res$classification, uncert.pch=19,
     scat.col=res$classification, scat.size=unit(0.25, "char"), 
     eci.col=1:res$G, noise.size=unit(0.2, "char")),

where scat.pch, scat.col, and scat.size give the plotting symbols, colours, and sizes of the points in scatterplot panels, respectively. Note that eci.col gives both a) the colour of the fitted lines &/or confidence intervals for expert-related panels when scatter.type is one of "ci" or "lm" and b) the colour of the ellipses (if any) when addEllipses is one of "outer", "inner", or "both" and the response data is multivariate. Note that eci.col will inherit a suitable default from scat.col instead if the latter is supplied but the former is not.

Note also that scat.size will be modified on an observation-by-observation level when response.type is "uncertainty". Furthermore, note that the behaviour for plotting symbols when response.type="uncertainty" changes compared to response.type="points" depending on the value of the uncert.cov argument above. uncert.pch gives the plotting symbol used for all scatterplot (and strip plot) panels when response.type="uncertainty" and uncert.cov is TRUE. However, when uncert.cov is FALSE, scat.pch is invoked for scatterplots involving covariates and uncert.pch is used for panels involving only response variables. Finally, noise.size can be used to modify scat.size for observations assigned to the noise component (if any), but only when response.type="points".

A list supplying select parameters for visualising the bivariate parametric density contours, only when response.type is "density".

NULL is equivalent to:

list(grid.size=c(100, 100), dcol="grey50", dens.points=FALSE,
     nlevels=11, show.labels=!dens.points, label.style="mixed"),

where grid.size is a vector of length two giving the number of points in the x & y directions of the grid over which the density is evaluated, respectively (though density.pars$grid.size can also be supplied as a scalar, which will be automatically recycled to a vector of length 2), and dcol is either a single colour or a vector of length nlevels colours. dens.points governs whether points should be overlaid when response.type="density" (in other words, dens.points=TRUE is akin to specifying response.type="points" and response.type="density" simultaneously) and show.labels governs whether the density contours should be labelled. Note that contours are not labelled when dens.points=TRUE by default. Finally, label.style can take the values "mixed", "flat", or "align".

A list supplying select parameters for panels along the diagonal.

NULL is equivalent to:

list(diag.fontsize=9, diagonal=TRUE, hist.color=hist.color, 
     show.hist=TRUE, show.counts=TRUE, show.dens=FALSE, dens.grid=100),

where hist.color is a vector of length 4, giving the colours for the response variables, gating covariates, expert covariates, and covariates entering both networks, respectively. By default, diagonal panels for response variables are ifelse(diag.pars$show.dens, "white", "black") and covariates of any kind are "dimgrey". hist.color also governs the outer colour for mosaic panels and the fill colour for boxplot, and violin panels (except for those involving the MAP classification; see boxplot.pars below). However, in the case of response vs. (categorical) covariates boxplots and violin plots, the fill colour is always "white". The MAP classification is always coloured by cluster membership, by default. The argument show.counts is only relevant for categorical variables.

The argument show.dens toggles whether parametric density estimates are drawn over the diagonal panels for each response variable. When show.dens=TRUE, the component densities are shown via thin lines, with colours given by scatter.pars$scat.col, while a thick "black" line is used for the overall mixture density. This argument can be used with or without show.hist also being TRUE. Finally, the grid size when show.dens=TRUE is given by diag.grid=100 by default. As per response.type="density", plotting is liable to be a little slower when show.dens=TRUE for models with expert network covariates. This is why show.dens=FALSE by default; otherwise it is recommended to be set to TRUE.

When diagonal=TRUE (the default), the diagonal from the top left to the bottom right is used for displaying the marginal distributions of variables (via histograms, with or without overlaid density estimates, or barplots, as appropriate). Specifying diagonal=FALSE will place the diagonal running from the top right down to the bottom left (with subset$submat accounted for accordingly).

A list supplying select parameters for continuous vs. categorical panels when one or both of the entries of conditional is "stripplot".

NULL is equivalent to:

list(strip.pch=res$classification, strip.size=unit(0.5, "char"),
     strip.col=res$classification, jitter=TRUE, size.noise=unit(0.4, "char")),

where strip.size and size.noise retain the definitions for the similar arguments under scatter.pars above. However, stripplot.pars$size.noise is invoked regardless of the response.type (in contrast to scatter.pars$noise.size). Notably, strip.col will inherit a suitable default from scatter.pars$scat.col if the latter is supplied but the former is not. Note also that the strip.pch default is modified to scatter.pars$uncert.pch if uncert.cov is TRUE.

A list supplying select parameters for continuous vs. categorical panels when one or both of the entries of conditional is "boxplot" or "violin".

NULL is equivalent to:

list(box.pch="|", box.col="black", varwidth=FALSE,
     notch=FALSE, notch.frac=0.5, box.fill=1:res$G).

All of the above are relevant for "boxplot" panels, are passed to panel.bwplot when producing boxplots, and retain the same definitions as the similarly named arguments therein. However, only box.col, varwidth, and box.fill are relevant for "violin" panels, and in both cases box.fill is only invoked for panels where the categorical variable is the MAP classification (i.e. when subset$show.map=TRUE). See diag.pars$hist.color for controlling the colours of non-MAP-related boxplot/violin panels. Notably, box.fill will inherit a suitable default from scatter.pars$scat.col if the latter is supplied but the former is not.

A list supplying select parameters for continuous vs. categorical panels when one or both of the entries of conditional is "barcode".

NULL is equivalent to:

list(bar.col=res$G:1, nint=0, ptsize=scatter.pars$scat.size, 
     ptpch=scatter.pars$scat.pch, bcspace=NULL, use.points=FALSE),

where bar.col will inherit a suitable default from scatter.pars$scat.col if the latter is supplied but the former is not. See the help file for barcode::barcode for details on the remaining arguments. Note that the arguments ptsize and ptpch, which are only relevant when use.points=TRUE are given by the corresponding scatter.pars$scat.size/scatter.pars$noise.size and scatter.pars$scat.pch arguments, by default.

A list supplying select parameters for categorical vs. categorical panels (if any).

NULL is equivalent to:

list(shade=NULL, gp_labels=grid::gpar(fontsize=9), 
     gp_args=list(), gp=list(), mfill=TRUE, mcol=1:res$G).

The current default arguments and values thereof are passed through to strucplot for producing mosaic tiles. When shade is not FALSE, mfill is a logical which governs the colouring scheme for panels (if any) involving the MAP classification. When mfill is TRUE (the default), gp is invoked here in such a way that tiles will inherit appropriate interior colours via gp$fill from mcol and a "black" outer colour via gp$col. When mfill is FALSE, or the panel involves two categorical covariates, the outer colours are inherited from mcol and the interior fill colour is inherited from bg.col. See diag.pars$hist.color for controlling the interior fill colour of non-MAP-related mosaic panels. Notably, mcol will inherit a suitable default from scatter.pars$scat.col if the latter is supplied but the former is not.

A list supplying select parameters for controlling the axes.

NULL is equivalent to:

list(n.ticks=5, axis.fontsize=9).

The argument n.ticks will be overwritten for categorical variables with fewer than 5 levels.

Catches unused arguments. Alternatively, named arguments can be passed directly here to any/all of scatter.pars, density.pars, diag.pars, stripplot.pars, boxplot.pars, barcode.pars, mosaic.pars, and axis.pars.

A fitted lm model, inheriting either the "mlm" or "lm" class.

The residuals. Can be residuals for observations included in the model, or residuals arising from predictions on unseen data. Must be coercible to a matrix with the number of columns being the number of response variables. Missing values are not allowed.

A logical. By default (FALSE), the generalized interpoint distance is computed. Set this flag to TRUE for the squared value.

A logical indicating whether the identity matrix is used in place of the precision matrix in the Mahalanobis distance calculation. Defaults to FALSE for multivariate response data but defaults to TRUE for univariate response data, where TRUE corresponds to the use of the Euclidean distance. Setting identity=TRUE with multivariate data may be advisable when the dimensions of the data are such that the covariance matrix cannot be inverted (otherwise, the pseudo-inverse is used under the FALSE default).

An object of class "MoEClust" generated by MoE_clust, or an object of class "MoECompare" generated by MoE_compare. Models with a noise component are facilitated here too.

The criterion to be plotted. Defaults to "bic". Recall that MoE_control only allows "bic", "icl", and "aic" to be used as model selection criteria within MoE_clust. The same applies to MoE_control. Uppercase crit will be coerced to lowercase.

Catches other arguments, or additional arguments to be passed to plot.mclustBIC (or equivalent functions for the other criterion arguments). In particular, the argument legendArgs to plot.mclustBIC can be passed.

An object of class "MoEClust" generated by MoE_clust, or an object of class "MoECompare" generated by MoE_compare. Models with a noise component are facilitated here too.

Optional argument for the x-axis against which the mixing proportions are plotted. Defaults to 1:res$n if missing. Supplying x.axis changes the defaults for the type and xlab arguments. Users are advised to only use quantities related to the gating network of the fitted model here. Furthermore, use of the x.axis argument is not recommended for models with more than one gating network covariate.

These graphical parameters retain their definitions from matplot. col defaults to the settings in mclust.options. Note that the default value of type changes depending on whether x.axis is supplied and whether the gating network contains multiple covariates &/or categorical covariates.

Catches unused arguments, or additional arguments to be passed to matplot.

An object of class "MoEClust" generated by MoE_clust, or an object of class "MoECompare" generated by MoE_compare. Models with a noise component are facilitated here too.

These graphical parameters retain their usual definitions from plot.

Catches unused arguments, or additional arguments to be passed to plot.

A numeric vector, matrix, or data frame of observations. Categorical variables are not allowed. If a matrix or data frame, rows correspond to observations and columns correspond to variables.

An optional matrix or data frame in which to look for the covariates specified in the gating &/or expert networks, if any. Must include column names. Columns in network.data corresponding to columns in data will be automatically removed. While a single covariate can be supplied as a vector (provided the '$' operator or '[]' subset operator are not used), it is safer to supply a named 1-column matrix or data frame in this instance.

A vector giving the names of columns in network.data used to define the scope of the gating network. By default, the initial model will contain no covariates (unless initialModel is supplied with gating covariates), thereafter all variables in gating (save for those in initialModel, if any) will be considered for inclusion where appropriate.

If gating is not supplied (or set to NULL), all variables in network.data will be considered for the gating network. gating can also be supplied as NA, in which case no gating network covariates will ever be considered (save for those in initialModel, if any). Supplying gating and expert can be used to ensure different subsets of covariates enter different parts of the model.

A vector giving the names of columns in network.data used to define the scope of the expert network. By default, the initial model will contain no covariates (unless initialModel is supplied with expert covariates), thereafter all variables in expert (save for those in initialModel, if any) will be considered for inclusion where appropriate.

If expert is not supplied (or set to NULL), all variables in network.data will be considered for the expert network. expert can also be supplied as NA, in which case no expert network covariates will ever be considered (save for those in initialModel, if any). Supplying expert and gating can be used to ensure different subsets of covariates enter different parts of the model.

A character string of valid model names, to be used to restrict the size of the search space, if desired. By default, all valid model types are explored. Rather than considering the changing of the model type as an additional step, every step is evaluated over all entries in modelNames. See MoE_clust for more details.

Note that if initialModel is supplied (see below), modelNames will be augmented with initialModel$modelName if needs be.

A logical which, when TRUE, ensures that only models where the same covariates enter both parts of the model (the gating and expert networks) are considered. This restricts the search space to exclude models where covariates differ across networks. Thus, the search is likely to be faster, at the expense of potentially missing out on optimal models. Defaults to FALSE.

Furthermore, when TRUE, the set of candidate covariates is automatically taken to be the union of the named covariates in gating and expert, for convenience. In other words, gating=NA will only work if expert=NA also, and both should be set to NULL in order to consider all potential covariates.

In addition, caution is advised using this argument in conjunction with initialModel, which must satisfy the constraint that the same set of covariates be used in both parts of the model, for initial models where gating covariates are allowable. Finally, note that this argument does not preclude a model with only expert covariates included if the number of components is such that the inclusion of gating covariates is infeasible.

A logical indicating whether to assume all models contain an additional noise component (TRUE) or not (FALSE, the default). If initialModel or initialG is not specified, the search starts from a G=0 noise-only model when noise is TRUE, otherwise the search starts from a G=1 model with no covariates when noise is FALSE. See MoE_control for more details. Note, however, that if the model specified in initialModel contains a noise component, the value of the noise argument will be overridden to TRUE; similarly, if the initialModel model does not contain a noise component, noise will be overridden to FALSE.

An object of class "MoEClust" generated by MoE_clust or an object of class "MoECompare" generated by MoE_compare. This gives the initial model to use at the first step of the selection algorithm, to which components and/or covariates etc. can be added. Especially useful if the model is expected to have more than one component a priori (see initialG below as an alternative). The initialModel model must have been fitted to the same data in data.

If initialModel is not specified, the search starts from a G=0 noise-only model when noise is TRUE, otherwise the search starts from a G=1 model with no covariates when noise is FALSE. If initialModel is supplied and it contains a noise component, only models with a noise component will be considered thereafter (i.e. the noise argument can be overridden by the initialModel argument). If initialModel contains gating &/or expert covariates, these covariates will be included in all subsequent searches, with covariates in expert and gating still considered as candidates for additional inclusion, as normal.

However, while initialModel can include covariates not specified in gating &/or expert, the initialModel$modelName should be included in the specified modelNames; if it is not, modelNames will be forcibly augmented with initialModel$modelName (as stated above). Furthermore, it is assumed that initialModel is already optimal with respect to the model type. If it is not, the algorithm may be liable to converge to a sub-optimal model, and so a warning will be printed if the function suspects that this might be the case.

A single (positive) integer giving the number of mixture components (clusters) to initialise the stepwise search algorithm with. This is a simpler alternative to the initialModel argument, to be used when the only prior knowledge relates to the number of components, and not other features of the model (e.g. the covariates which should be included). Consequently, initialG is only relevant when initialModel is not supplied. When neither initialG nor initialModel is specified, the search starts from a G=0 noise-only model when noise is TRUE, otherwise the search starts from a G=1 model with no covariates when noise is FALSE. See stepG below for fixing the number of components at this initialG value.

A logical indicating whether the algorithm should consider incrementing the number of components at each step. Defaults to TRUE; use FALSE when searching only over configurations with the same number of components is of interest. Setting stepG to FALSE is possible with or without specifying initialModel or initialG, but is primarily intended for use when one of these arguments is supplied, otherwise the algorithm will be stuck forever with only one component.

The model selection criterion used to determine the optimal action at each step. Defaults to "bic".

A character string indicating whether models with equal mixing proportions should be considered. "both" means models with both equal and unequal mixing proportions will be considered, "yes" means only models with equal mixing proportions will be considered, and "no" means only models with unequal mixing proportions will be considered. Notably, no setting for equalPro is enough to rule out models with gating covariates from consideration.

The default ("all") is equivalent to "both" with the addition that all possible mixing proportion constraints will be tried for the initialModel (if any, provided it doesn't contain gating covariate(s)) or initialG before adding a component or additional covariates; otherwise, this equalPro argument only governs whether mixing proportion constraints are considered as components are added.

Considering "all" (or "both") equal and unequal mixing proportion models increases the search space and the computational burden, but this argument becomes irrelevant after a model, if any, with gating network covariate(s) is considered optimal for a given step. The "all" default is strongly recommended so that viable candidate models are not missed out on, particularly when initialModel or initialG are given. However, this does not guarantee that an optimal model will not be skipped; if equalPro is restricted via "yes" or "no", a suboptimal model at one step may ultimately lead to a better final model, in some edge cases. See MoE_control for more details.

A character string indicating whether models where the gating network for the noise component depends on covariates are considered. "yes" means only models where this is the case will be considered, "no" means only models for which the noise component's mixing proportion is constant will be considered and "both" means both of these scenarios will be considered.

The default ("all") is equivalent to "both" with the addition that all possible gating network noise settings will be tried for the initialModel (if any, provided it contains gating covariates and a noise component) before adding a component or additional covariates; otherwise, this noise.gate argument only governs the inclusion/exclusion of this constraint as components or covariates are added.

Considering "all" (or "both") settings increases the search space and the computational burden, but this argument is only relevant when noise=TRUE and gating covariates are being considered. The "all" default is strongly recommended so that viable candidate models are not missed out on, particularly when initialModel or initialG are given. However, this does not guarantee that an optimal model will not be skipped; if noise.gate is restricted via "yes" or "no", a suboptimal model at one step may ultimately lead to a better final model, in some edge cases. See MoE_control for more details.

Logical indicating whether to print messages pertaining to progress to the screen during fitting. 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.

Additional arguments to MoE_control, except for those arguments of the same name which are already listed here, e.g. equalPro and noise.gate. Note that these arguments will be supplied to all candidate models for every step. For arguments specific to MoE_control (e.g. stopping, algo, etc.), it is recommended to run MoE_stepwise multiple times while toggling these arguments, if desired.

A vector of three consecutive log-likelihood values. These three values should be in ascending order, though this is not checked.

The most current estimate of the log-likelihood, i.e. loglik[3].

The most current estimate of the final converged maximised log-likelihood.

The Aitken acceleration value where typically 0 <= a <= 1. When a < 0, a numerical issue or bug has occurred; when a > 1, the algorithm is accelerating and should not be stopped.

The difference between linf and the previous estimate of the log-likelihood, i.e. loglik[2], in accordance with McNicholas et al. (2010).

An object of class "MoEClust" generated by MoE_clust or an object of class "MoECompare" generated by MoE_compare. Models with a noise component are facilitated here too.

Logical (defaults to TRUE) governing whether the extra variability in the component means is added to the MVN ellipses corresponding to the component covariance matrices in the presence of expert network covariates. See the function expert_covar.

Significance level for outlier removal. Must be a single number in the interval [0, 1). Corresponds to the percentage of data to be considered extreme and therefore removed (half of signif at each endpoint, on a column-wise basis). The default, 0, corresponds to no outlier removal. Only invoke this argument as an aid to visualisation via plot.Mclust.

Further arguments to be passed to other methods.

A data.frame where rows correspond to observations and columns correspond to variables. Ideally column names should be present.

An object of class "formula": a symbolic description of the model to be fitted. Variables in the formula not present in the columns of dat will automatically be discarded. The formula may include interactions, transformations, or higher order terms: the latter must be specified explicitly using the AsIs operator (I).

An optional vector specifying a subset of observations to be used in the fitting process.

A fitted lm or multinom model.

A data.frame containing variables with which to predict.

An object of class "MoEClust" generated by MoE_clust, or an object of class "MoECompare" generated by MoE_compare. Models with a noise component are facilitated here too.

A logical indicating whether the estimated cluster membership probabilities should be used to provide a weighted estimate of the variability due to the component means. Defaults to TRUE. The option weighted=FALSE is provided only so that previous behaviour under earlier versions of MoEClust can be recovered but is otherwise not recommended.

Catches unused arguments.

A matrix, which must be either upper-triangular or lower-triangular.

A numeric vector, matrix, or data frame of observations. Categorical variables are not allowed, and covariates should not be included. If a matrix or data frame, rows correspond to observations and columns correspond to variables. There must be more observations than variables.

The method used to estimate the hypervolume. The default method uses the function hypvol. The "convexhull" and "ellipsoidhull" options require loading the geometry and cluster packages, respectively. This argument is only relevant for multivariate data; for univariate data, the range of the data is used. Note that the "convexhull" method is liable to be slow when data has many columns.

A logical variable indicating whether or not the reciprocal hypervolume is desired rather than the hypervolume itself. The default is to return the hypervolume.

An object of class "MoEClust" generated by MoE_clust, or an object of class "MoECompare" generated by MoE_compare. Models with a noise component are facilitated here too.

The type of graph requested:

gpairs

A generalised pairs plot. To further customise this plot, arguments to MoE_gpairs can be supplied.

gating

The gating network. To further customise this plot, arguments to MoE_plotGate and matplot can be supplied.

criterion

The model selection criteria. To further customise this plot, arguments to MoE_plotCrit and plot.mclustBIC can be supplied.

loglik

The log-likelihood vs. the iterations of the EM algorithm. To further customise this plot, arguments to MoE_plotLogLik and plot can be supplied.

similarity

The similarity matrix constructed from x$z at convergence, in the form of a heatmap. To further customise this plot, arguments to MoE_Similarity can be supplied.

uncertainty

The clustering uncertainty for every observation. To further customise this plot, arguments to MoE_Uncertainty can be supplied.

By default, all of the above graphs are produced.

Optional arguments to be passed to MoE_gpairs, MoE_plotGate, MoE_plotCrit, MoE_plotLogLik, MoE_Similarity, MoE_Uncertainty, matplot, plot.mclustBIC and plot. In particular, the argument legendArgs to plot.mclustBIC can be passed to MoE_plotCrit.

An object of class "MoEClust" generated by MoE_clust, or an object of class "MoECompare" generated by MoE_compare. Predictions for models with a noise component are facilitated here too (see discard.noise).

A list with two named components, each of which must be a data.frame or matrix with named columns, giving the data for which predictions are desired.

new.x

The new covariates for the gating &/or expert networks. Must be supplied when newdata$new.y is supplied.

new.y

(Optional) response data (see use.y below). When supplied, cluster and response prediction is based on both newdata$new.x and newdata$new.y, otherwise only on the covariates in newdata$new.x.

If supplied as a list with elements new.x and new.y, both must have the same number of rows.

Alternatively, a single data.frame or matrix can be supplied and an attempt will be made to extract & separate covariate and response columns (if any) into newdata$new.x and newdata$new.y based on the variable names in object$data and object$net.covs.

When newdata is not supplied in any way, the covariates and response variables used in the fitting of the model are used here. It is possible to not supply new.y and to supply an empty data.frame or matrix for new.x (or to equivalently supply an empty data.frame or matrix for newdata itself) for models with no covariates of any kind, which effectively predicts the weighted mean of the component means.

A logical indicating whether to return the residuals also. Defaults to FALSE. Only allowed when response variables are supplied in some form. The function residuals is a wrapper to predict with the argument resid set to TRUE, with only the residuals returned.

A logical governing how predictions of the responses are made for models with a noise component (otherwise this argument is irrelevant). By default (FALSE), the mean of the noise component is accounted for. Otherwise, or when the mean of the noise component is unavailable (due to having been manually supplied through MoE_control via noise.args$noise.vol), prediction of the responses is performed using a z matrix which is renormalised after discarding the column corresponding to the noise component. The renormalisation approach can be forced by specifying TRUE, even when the mean of the noise component is available. For models with a noise component fitted with algo="CEM", a small extra E-step is conducted for observations assigned to the non-noise components in this case.

A logical indicating whether residuals are computed against y (TRUE, the default) or MAPy when FALSE. Not relevant for models with equal mixing proportions when only new.x is available. See Value below for more details.

A logical indicating whether the response variables (if any are supplied either via new.y or via newdata itself) are actually used in the prediction. Defaults to TRUE, but useful when FALSE for computing residuals as though only the covariates in new.x were supplied. For out-of-sample prediction, typically new.y would not be supplied anyway and so the use.y=TRUE default becomes irrelevant.

Catches unused arguments (and allows the predict arguments discard.noise &/or use.y to be passed through fitted or the discard.noise, MAPresids, and/or use.y arguments to be passed through residuals).

Aggregated fitted values of the response variables.

A matrix whose [i,k]-th entry is the probability that observation i of the newdata belongs to the k-th component. For models with a noise component, the final column gives the probability of belonging to the so-called Cluster0.

The vector of predicted cluster labels for the newdata. 0 is returned for observations assigned to the noise component.

The predicted mixing proportions for the newdata, i.e. predicted values of the gating network. object$parameters$pro is returned for models without gating network covariates. See predict.MoE_gating.

The predicted component means for the newdata, i.e. predicted values of the expert network. Given as a 3-dimensional array with dimensions given by the number of new observations, the number of variables, and the number of clusters. The first dimension is of length 1 when there are no expert network covariates, in which case the entries correspond to object$parameters$mean. See predict.MoE_expert.

Fitted values of the single expert network to which each observation is most probably assigned. Not returned for models with equal mixing proportions when only new.x is available. Likely to only be of use for models with gating and expert covariates when only new.x is supplied. Note that MAPy and y will coincide for models fitted via the CEM algorithm (see MoE_control and its argument algo).

An object of class "MoE_expert" (typically x$expert, where x is of class "MoEClust").

A matrix or data frame of test examples. If omitted, the fitted values are used.

Logical indicating whether to simplify the output (in the form of a list) to a 3-dimensional array with dimensions given by the number of new observations, the number of variables, and the number of clusters. The first dimension of such an array is of length 1 when there are no expert network covariates, in which case the entries correspond to object$parameters$mean. Defaults to FALSE.

A logical indicating whether unseen factor levels in categorical variables within newdata should be dropped (with NA predicted in their place). Defaults to FALSE. See drop_levels.

Catches unused arguments or allows the simplify argument to be passed through fitted and residuals.

An object of class "MoE_gating" (typically x$gating, where x is of class "MoEClust").

A matrix or data frame of test examples. If omitted, the fitted values are used.

The type of output desired. The default ("probs") returns prior probabilities, while "class" returns labels indicating the most likely group a priori. Note that observations classified assigned the noise component (if any) are given a label of 0.

A logical indicating whether the output should acknowledge the noise component (if any). Defaults to TRUE; when FALSE, this column is discarded and the matrix of probabilities is renormalised accordingly.

A logical indicating whether unseen factor levels in categorical variables within newdata should be dropped (with NA predicted in their place). Defaults to FALSE. See drop_levels.

Catches unused arguments or allows the type and keep.noise arguments to be passed through fitted and the keep.noise argument to be passed through residuals.

A vector of numeric data.

The desired number of clusters.