predict.MoEClust {MoEClust}

Predictions for MoEClust models

Description

Predicts both cluster membership probabilities and fitted response values from a MoEClust model, using covariates and response data, or covariates only. The predicted MAP classification, mixing proportions, and component means are all also reported in both cases, as well as the predictions of the expert network corresponding to the most probable component.

Usage

## S3 method for class 'MoEClust'
predict(object,
        newdata,
        resid = FALSE,
        discard.noise = FALSE,
        MAPresids = FALSE,
        use.y = TRUE,
        ...)

## S3 method for class 'MoEClust'
fitted(object,
       ...)

## S3 method for class 'MoEClust'
residuals(object,
          newdata,
          ...)

Arguments

object

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).

newdata

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.

resid

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.

discard.noise

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.

MAPresids

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.

use.y

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).

Details

Predictions can also be made for models with a noise component, in which case z will include the probability of belonging to "Cluster0" & classification will include labels with the value 0 for observations classified as noise (if any). The argument discard.noise governs how the responses are predicted in the presence of a noise component (see noise_vol for more details).

Note that the argument discard.noise is invoked for any models with a noise component, while the similar MoE_control argument noise.args$discard.noise is only invoked for models with both a noise component and expert network covariates.

Please be aware that a model considered optimal from a clustering point of view may not necessarily be optimal from a prediction point of view. In particular, full MoE models with covariates in both networks (for which both the cluster membership probabilities and component means are observation-specific) are recommended for out-of-sample prediction when only new covariates are observed (see new.x and new.y above, as well as use.y).

Value

A list with the following named components, regardless of whether newdata$new.x and newdata$new.y were used, or newdata$new.x only.

y

Aggregated fitted values of the response variables.

z

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.

classification

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

pro

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.

mean

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.

MAPy

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).

When residuals is called, only the residuals (governed by MAPresids) are returned; when predict is called with resid=TRUE, the list above will also contain the element resids, containing the residuals.

The returned values of pro and mean are always the same, regardless of whether newdata$new.x and newdata$new.y were used, or newdata$new.x only.

Finally, fitted is simply a wrapper to predict.MoEClust(object)$y without any newdata, and with the resid and MAPresids arguments also ignored.

Note

Note that a dedicated predict function is also provided for objects of class "MoE_gating" (typically object$gating, where object is of class "MoEClust"). This function is effectively a shortcut to predict(object, ...)$pro, which (unlike the predict method for multinom on which it is based) accounts for the various ways of treating gating covariates and noise components, although its type argument defaults to "probs" rather than "class". Notably, its keep.noise argument behaves differently from the discard.noise argument here; here, the noise component is only discarded in the computation of the predicted responses. See predict.MoE_gating for further details.

Similarly, a dedicated predict function is also provided for objects of class "MoE_expert" (typically object$expert, where object is of class "MoE_expert"). This function is effectively a wrapper to predict(object, ...)$mean, albeit it returns a list (by default) rather than a 3-dimensional array and also always preserves the dimensions of newdata, even for models without expert network covariates. See predict.MoE_expert for further details.

Author(s)

Keefe Murphy - <[e-mail]>

References

Murphy, K. and Murphy, T. B. (2020). Gaussian parsimonious clustering models with covariates and a noise component. Advances in Data Analysis and Classification, 14(2): 293-325. <doi:10.1007/s11634-019-00373-8>.

See Also

MoE_clust, MoE_control, noise_vol, predict.MoE_gating, predict.MoE_expert

Examples

data(ais)
# Fit a MoEClust model and predict the same data
res     <- MoE_clust(ais[,3:7], G=2, gating= ~ BMI, expert= ~ sex,
                     modelNames="EVE", network.data=ais)
pred1   <- predict(res)

# Get only the fitted responses
fits    <- fitted(res)
all.equal(pred1$y, fits) #TRUE

# Remove some rows of the data for prediction purposes
ind     <- sample(1:nrow(ais), 5)
dat     <- ais[-ind,]

# Fit another MoEClust model to the retained data
res2    <- MoE_clust(dat[,3:7], G=3, gating= ~ BMI + sex,
                     modelNames="EEE", network.data=dat)

# Predict held back data using the covariates & response variables
(pred2  <- predict(res2, newdata=ais[ind,]))
# pred2 <- predict(res2, newdata=list(new.y=ais[ind,3:7],
#                                     new.x=ais[ind,c("BMI", "sex")]))

# Get the residuals
residuals(res2, newdata=ais[ind,])

# Predict held back data using only the covariates
(pred3  <- predict(res2, newdata=ais[ind,], use.y=FALSE))
# pred3 <- predict(res2, newdata=list(new.x=ais[ind,c("BMI", "sex")]))
# pred3 <- predict(res2, newdata=ais[ind,c("BMI", "sex")])