updated docs

Author: osorensen

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: BayesMallowsSMC2
 Type: Package
 Title: Nested Sequential Monte Carlo for the Bayesian Mallows Model
-Version: 0.2.1.9000
+Version: 0.3.0
 Authors@R: c(person("Oystein", "Sorensen",
                     email = "oystein.sorensen.1985@gmail.com",
                     role = c("aut", "cre"),

NEWS.md

@@ -1,3 +1,9 @@
+# BayesMallowsSMC2 version 0.3.0
+
+## New features
+
+* Implemented Conditional Particle Filter with Independent Backward Simulation (CPF-IBS) to mitigate path degeneracy during the rejuvenation step. This can be enabled via `backward_sampling = TRUE` in `set_smc_options()`.
+
 # BayesMallowsSMC2 version 0.2.1
 
 ## Bug fixes

R/compute_sequentially.R

@@ -76,11 +76,16 @@
 #' algorithm automatically performs resampling and rejuvenation steps when the
 #' effective sample size drops below the specified threshold.
 #'
+#' Rejuvenation steps can optionally use Particle Gibbs with Backward Simulation
+#' \\insertCite{Whiteley2010Discussion,Lindsten2013Backward}{BayesMallowsSMC2}, enabled via the `backward_sampling` argument in [set_smc_options()].
+#'
 #' The returned object has S3 methods for printing ([print.BayesMallowsSMC2]),
 #' summarizing ([summary.BayesMallowsSMC2]), and plotting ([plot.BayesMallowsSMC2]).
 #' For visualization of parameter evolution over time, see [trace_plot()].
 #'
 #' @references
+#' \insertAllCited{}
+#'
 #' \insertRef{10.1214/25-BA1564}{BayesMallowsSMC2}
 #'
 #' @export
@@ -100,31 +105,31 @@
 #' plot(mod, parameter = "alpha")
 #'
 compute_sequentially <- function(
-    data,
-    hyperparameters = set_hyperparameters(),
-    smc_options = set_smc_options(),
-    topological_sorts = NULL
-    ){
+  data,
+  hyperparameters = set_hyperparameters(),
+  smc_options = set_smc_options(),
+  topological_sorts = NULL
+) {
   rank_columns <- grepl("item[0-9]+", colnames(data))
   preference_columns <- grepl("top\\_item|bottom\\_item", colnames(data))
 
-  if(any(rank_columns)) {
-    input_timeseries <- split(data, f = ~ timepoint) |>
-      lapply(split, f = ~ user) |>
+  if (any(rank_columns)) {
+    input_timeseries <- split(data, f = ~timepoint) |>
+      lapply(split, f = ~user) |>
       lapply(function(x) lapply(x, function(y) as.numeric(y[rank_columns])))
 
-    if(any(is.na(data[rank_columns]))) {
+    if (any(is.na(data[rank_columns]))) {
       attr(input_timeseries, "type") <- "partial rankings"
     } else {
       attr(input_timeseries, "type") <- "complete rankings"
     }
     sort_matrices <- sort_counts <- list()
-  } else if(sum(preference_columns) == 2) {
-    if(is.null(topological_sorts)) {
+  } else if (sum(preference_columns) == 2) {
+    if (is.null(topological_sorts)) {
       stop("topological_sorts must be provided with preference data.")
     }
-    input_timeseries <- split(data, f = ~ timepoint) |>
-      lapply(split, f = ~ user) |>
+    input_timeseries <- split(data, f = ~timepoint) |>
+      lapply(split, f = ~user) |>
       lapply(function(x) lapply(x, function(y) as.matrix(y[preference_columns])))
     attr(input_timeseries, "type") <- "pairwise preferences"
 
@@ -139,15 +144,16 @@ compute_sequentially <- function(
     stop("Something wrong with data")
   }
 
-  if(max(table(data$user)) > 1 &&
-     attr(input_timeseries, "type") != "pairwise preferences") {
+  if (max(table(data$user)) > 1 &&
+    attr(input_timeseries, "type") != "pairwise preferences") {
     stop("Updated users not supported.")
   }
 
-  ret <- run_smc(input_timeseries, hyperparameters, smc_options,
-                 sort_matrices, sort_counts)
+  ret <- run_smc(
+    input_timeseries, hyperparameters, smc_options,
+    sort_matrices, sort_counts
+  )
 
   class(ret) <- "BayesMallowsSMC2"
   ret
 }
-

R/set_smc_options.R

@@ -48,11 +48,7 @@
 #'   can be used to inspect the evolution of rankings over time but
 #'   substantially increases memory usage. Defaults to `FALSE`.
 #' @param backward_sampling Logical specifying whether to use Particle Gibbs with
-#'   Backward Simulation (PGBS) during the rejuvenation step. PGBS greatly improves
-#'   mixing for static parameters like cluster probabilities and the error rate by
-#'   eliminating path degeneracy in the latent variables. Since user preferences are
-#'   conditionally independent, this utilizes $\\mathcal{O}(S)$ independent 
-#'   Backward Simulation (CPF-IBS). Defaults to `FALSE`.
+#'   Backward Simulation (PGBS) \insertCite{Whiteley2010Discussion,Lindsten2013Backward}{BayesMallowsSMC2} during the rejuvenation step. Defaults to `FALSE`.
 #'
 #' @details
 #' The SMC2 algorithm uses a nested particle filter structure:
@@ -79,6 +75,9 @@
 #'
 #' @seealso [compute_sequentially()], [set_hyperparameters()]
 #'
+#' @references
+#' \insertAllCited{}
+#'
 #' @export
 #'
 #' @examples
@@ -127,11 +126,12 @@
 #' )
 #'
 set_smc_options <- function(
-    n_particles = 1000, n_particle_filters = 50, max_particle_filters = 10000,
-    resampling_threshold = n_particles / 2, doubling_threshold = .2,
-    max_rejuvenation_steps = 20,
-    metric = "footrule", resampler = "multinomial",
-    latent_rank_proposal = "uniform", verbose = FALSE,
-    trace = FALSE, trace_latent = FALSE, backward_sampling = FALSE) {
+  n_particles = 1000, n_particle_filters = 50, max_particle_filters = 10000,
+  resampling_threshold = n_particles / 2, doubling_threshold = .2,
+  max_rejuvenation_steps = 20,
+  metric = "footrule", resampler = "multinomial",
+  latent_rank_proposal = "uniform", verbose = FALSE,
+  trace = FALSE, trace_latent = FALSE, backward_sampling = FALSE
+) {
   as.list(environment())
 }

cran-comments.md

@@ -10,12 +10,9 @@
 
 ## Submission notes
 
-This is a resubmission to fix test failures reported on CRAN checks for the BayesMallowsSMC2 package.
+This release introduces major algorithmic improvements for the SMC2 rejuvenation step.
 
 ### Changes in this version
 
-* Adjusted numerical tolerance in `test-compute_sequentially_partial.R` (line 11) to account for platform-specific differences in Monte Carlo results. The test was failing on r-oldrel-macos and noLD platforms due to slight variations in the computed alpha_hat value (0.046 vs expected > 0.06). The tolerance has been relaxed from 0.06 to 0.04 to accommodate these platform differences while still ensuring the test validates the expected behavior.
-
-## Previous submission
-
-This package was initially released to CRAN as version 0.2.0. The test failures appeared after release on specific platforms (r-oldrel-macos and noLD) due to numerical differences in stochastic computations.
+* Implemented Conditional Particle Filter with Independent Backward Simulation (CPF-IBS) for the rejuvenation step. This resolves path degeneracy in latent variables during Particle Gibbs and improves mixing. It is available via the `backward_sampling` argument in `set_smc_options()`.
+* Retained numerical tolerance fixes from 0.2.1 that accommodated platform-specific variations on r-oldrel-macos and noLD.

inst/REFERENCES.bib

@@ -9,3 +9,23 @@ @article{10.1214/25-BA1564
 doi = {10.1214/25-BA1564},
 URL = {https://doi.org/10.1214/25-BA1564}
 }
+
+@article{Whiteley2010Discussion,
+  author = {Whiteley, N.},
+  title = {{Discussion on 'Particle Markov chain Monte Carlo methods'}},
+  journal = {Journal of the Royal Statistical Society: Series B (Statistical Methodology)},
+  volume = {72},
+  number = {3},
+  pages = {306--307},
+  year = {2010}
+}
+@article{Lindsten2013Backward,
+  title={{Backward simulation methods for Monte Carlo statistical inference}},
+  author={Lindsten, Fredrik and Sch{\"o}n, Thomas B.},
+  journal={Foundations and Trends{\textregistered} in Machine Learning},
+  volume={6},
+  number={1},
+  pages={1--143},
+  year={2013},
+  publisher={Now Publishers, Inc.}
+}