Nothing
#' Poisson lognormal mixture model
#'
#' Fit the mixture variants of the Poisson lognormal with a variational algorithm. Use the (g)lm syntax for model specification (covariates, offsets).
#'
#' @inheritParams PLN formula data subset
#' @param clusters a vector of integer containing the successive number of clusters (or components) to be considered
#' @param control a list-like structure for controlling the optimization, with default generated by [PLNmixture_param()]. See the associated documentation
#' for details.
#'
#' @return an R6 object with class [`PLNmixturefamily`], which contains
#' a collection of models with class [`PLNmixturefit`]
#'
#' @rdname PLNmixture
#' @examples
#' ## Use parallel to dispatch the computations on 2 workers
#' \dontrun{
#' options(mc.cores = 2)
#' }
#'
#' data(trichoptera)
#' trichoptera <- prepare_data(trichoptera$Abundance, trichoptera$Covariate)
#' myMixtures <- PLNmixture(Abundance ~ 1 + offset(log(Offset)), clusters = 1:4, data = trichoptera,
#' control = PLNmixture_param(smoothing = 'none'))
#'
#' \dontrun{
#' options(mc.cores = 1)
#' }
#' @seealso The classes [`PLNmixturefamily`], [`PLNmixturefit`] and [PLNmixture_param()]
#' @importFrom stats model.frame model.matrix model.response model.offset update.formula
#' @export
PLNmixture <- function(formula, data, subset, clusters = 1:5, control = PLNmixture_param()) {
## Temporary test for deprecated use of list()
if (!inherits(control, "PLNmodels_param"))
stop("We now use the function PLNmixture_param() to generate the list of parameters that controls the fit:
replace 'list(my_arg = xx)' by PLN_param(my_arg = xx) and see the documentation of PLNmixture_param().")
# remove the intercept term if any (will be used to deal with group means)
the_call <- match.call(expand.dots = FALSE)
the_call$formula <- update.formula(formula(the_call), ~ . -1)
## extract the data matrices and weights
args <- extract_model(the_call, parent.frame())
## Instantiate the collection of PLN models
if (control$trace > 0) cat("\n Initialization...")
if (control$trace > 0) cat("\n\n Adjusting", length(clusters), "PLN mixture models.\n")
myPLN <- PLNmixturefamily$new(clusters, args$Y, args$X, args$O, args$formula, control)
## Now adjust the PLN models
myPLN$optimize(control$config_optim)
## Smoothing to avoid local minima
if (control$smoothing != "none" & control$trace > 0) cat("\n\n Smoothing PLN mixture models.\n")
myPLN$smooth(control)
## Post-treatments: Compute pseudo-R2, rearrange criteria and the visualization for PCA
if (control$trace > 0) cat("\n Post-treatments")
myPLN$postTreatment(control$config_post, control$config_optim)
if (control$trace > 0) cat("\n DONE!\n")
myPLN
}
#' Control of a PLNmixture fit
#'
#' Helper to define list of parameters to control the PLNmixture fit. All arguments have defaults.
#'
#' @param backend optimization back used, either "builtin", "nlopt" or "torch". Default is "builtin".
#' @param covariance character setting the model for the covariance matrices of the mixture components. Either "full", "diagonal" or "spherical". Default is "spherical".
#' @param smoothing The smoothing to apply. Either, 'none', forward', 'backward' or 'both'. Default is 'both'.
#' @param init_cl The initial clustering to apply. Either, 'kmeans', CAH' or a user defined clustering given as a list of clusterings, the size of which is equal to the number of clusters considered. Default is 'kmeans'.
#' @inheritParams PLN_param trace config_optim config_post inception
#'
#' @return list of parameters configuring the fit.
#' @inherit PLN_param details
#' @section Outer-loop optimization parameters:
#' `PLNmixture_param()` adds parameters controlling the EM and smoothing outer loops:
#' * "ftol_em" outer EM solver stops when the objective changes by less than ftol_em (relative). Default is 1e-3
#' * "maxit_em" outer EM solver stops when the number of iterations exceeds maxit_em. Default is 50
#' * "it_smooth" number of the iterations of the smoothing procedure. Default is 1.
#'
#' @seealso [PLN_param()]
#' @export
PLNmixture_param <- function(
backend = c("builtin", "nlopt", "torch"),
trace = 1 ,
covariance = "spherical",
init_cl = "kmeans" ,
smoothing = "both" ,
config_optim = list() ,
config_post = list() ,
inception = NULL # pretrained PLNfit used as initialization
) {
if (!is.null(inception)) stopifnot(isPLNfit(inception))
## post-treatment config
config_pst <- config_post_default_PLNmixture
config_pst[names(config_post)] <- config_post
config_pst$trace <- trace
## optimization config
backend <- match.arg(backend)
config_opt <- make_config_optim(backend, config_optim, trace,
extra = list(ftol_em = 1e-3, maxit_em = 50, it_smooth = 1))
structure(list(
backend = backend ,
trace = trace ,
covariance = covariance ,
init_cl = init_cl ,
smoothing = smoothing ,
config_optim = config_opt ,
config_post = config_pst ,
inception = inception ), class = "PLNmodels_param")
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.