R/set_smc_options.R

In BayesMallows: Bayesian Preference Learning with the Mallows Rank Model

#' @title Set SMC compute options
#'
#' @description Sets the SMC compute options to be used in
#'   [update_mallows.BayesMallows()].
#'
#' @param n_particles Integer specifying the number of particles.
#' @param mcmc_steps Number of MCMC steps to be applied in the resample-move
#'   step.
#' @param resampler Character string defining the resampling method to use. One
#'   of "stratified", "systematic", "residual", and "multinomial". Defaults to
#'   "stratified". While multinomial resampling was used in
#'   \insertCite{steinSequentialInferenceMallows2023;textual}{BayesMallows},
#'   stratified, systematic, or residual resampling typically give lower Monte
#'   Carlo error \insertCite{Douc2005,Hol2006,Naesseth2019}{BayesMallows}.
#' @param latent_sampling_lag Parameter specifying the number of timesteps to go
#'   back when resampling the latent ranks in the move step. See Section 6.2.3
#'   of \insertCite{Kantas2015}{BayesMallows} for details. The \eqn{L} in their
#'   notation corresponds to `latent_sampling_lag`. See more under Details.
#'   Defaults to `NA`, which means that all latent ranks from previous timesteps
#'   are moved. If set to `0`, no move step is applied to the latent ranks.
#' @param max_topological_sorts User when pairwise preference data are provided,
#'   and specifies the maximum number of topological sorts of the graph
#'   corresponding to the transitive closure for each user will be used as
#'   initial ranks. Defaults to 1, which means that all particles get the same
#'   initial augmented ranking. If larger than 1, the initial augmented ranking
#'   for each particle will be sampled from a set of maximum size
#'   `max_topological_sorts`. If the actual number of topological sorts consists
#'   of fewer rankings, then this determines the upper limit.
#'
#' @return An object of class "SMCOptions".
#'
#'
#' @section Lag parameter in move step:
#'
#'   The parameter `latent_sampling_lag` corresponds to \eqn{L} in
#'   \insertCite{Kantas2015}{BayesMallows}. Its use in this package is can be
#'   explained in terms of Algorithm 12 in
#'   \insertCite{steinSequentialInferenceMallows2023}{BayesMallows}. The
#'   relevant line of the algorithm is:
#'
#'   **for** \eqn{j = 1 : M_{t}} **do** \cr
#'   **M-H step:** update \eqn{\tilde{\mathbf{R}}_{j}^{(i)}} with proposal
#'   \eqn{\tilde{\mathbf{R}}_{j}' \sim q(\tilde{\mathbf{R}}_{j}^{(i)} |
#'   \mathbf{R}_{j}, \boldsymbol{\rho}_{t}^{(i)}, \alpha_{t}^{(i)})}.\cr
#'   **end**
#'
#'   Let \eqn{L} denote the value of `latent_sampling_lag`. With this parameter,
#'   we modify for algorithm so it becomes
#'
#'   **for** \eqn{j = M_{t-L+1} : M_{t}} **do** \cr
#'   **M-H step:** update \eqn{\tilde{\mathbf{R}}_{j}^{(i)}} with proposal
#'   \eqn{\tilde{\mathbf{R}}_{j}' \sim q(\tilde{\mathbf{R}}_{j}^{(i)} |
#'   \mathbf{R}_{j}, \boldsymbol{\rho}_{t}^{(i)}, \alpha_{t}^{(i)})}.\cr
#'   **end**
#'
#'   This means that with \eqn{L=0} no move step is performed on any latent
#'   ranks, whereas \eqn{L=1} means that the move step is only applied to the
#'   parameters entering at the given timestep. The default,
#'   `latent_sampling_lag = NA` means that \eqn{L=t} at each timestep, and hence
#'   all latent ranks are part of the move step at each timestep.
#'
#'
#' @export
#' @references \insertAllCited{}
#'
#' @family preprocessing
set_smc_options <- function(
    n_particles = 1000,
    mcmc_steps = 5,
    resampler = c("stratified", "systematic", "residual", "multinomial"),
    latent_sampling_lag = NA_integer_,
    max_topological_sorts = 1) {
  validate_integer(n_particles)
  validate_integer(mcmc_steps)
  if (!is.na(latent_sampling_lag)) validate_integer(latent_sampling_lag)
  resampler <- match.arg(
    resampler,
    c("stratified", "systematic", "residual", "multinomial")
  )

  ret <- as.list(environment())
  class(ret) <- "SMCOptions"
  ret
}