Exporting exact partition function (#412)

* fixing documentation typo

* fixing #409

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: BayesMallows
 Type: Package
 Title: Bayesian Preference Learning with the Mallows Rank Model
-Version: 2.1.1.9005
+Version: 2.1.1.9006
 Authors@R: c(person("Oystein", "Sorensen",
                     email = "oystein.sorensen.1985@gmail.com",
                     role = c("aut", "cre"),

NAMESPACE

@@ -28,6 +28,7 @@ export(assess_convergence)
 export(assign_cluster)
 export(burnin)
 export(compute_consensus)
+export(compute_exact_partition_function)
 export(compute_expected_distance)
 export(compute_mallows)
 export(compute_mallows_mixtures)

NEWS.md

@@ -1,5 +1,8 @@
 # BayesMallows (development versions)
 
+* A function compute_exact_partition_function() is now added, which returns the
+  logarithm of the exact partition function for Cayley, Hamming, and Kendall
+  distance.
 * Fixed a bug in the Ulam distance. Thanks for Marta Crispino for discovering 
   it.
 * Fixed a bug in SMC algorithm for pairwise preference data, where the proposal

R/compute_exact_partition_function.R

@@ -0,0 +1,26 @@
+#' @title Compute exact partition function
+#'
+#' @description For Cayley, Hamming, and Kendall distances, computationally
+#' tractable functions are available for the exact partition function.
+#'
+#' @param alpha Dispersion parameter.
+#' @param n_items Number of items.
+#' @param metric Distance function, one of "cayley", "hamming", or "kendall".
+#'
+#' @return The logarithm of the partition function.
+#' @export
+#'
+#' @references \insertAllCited{}
+#'
+#' @example inst/examples/compute_exact_partition_function_example.R
+#' @family partition function
+compute_exact_partition_function <- function(
+    alpha, n_items,
+    metric = c("cayley", "hamming", "kendall")) {
+  metric <- match.arg(metric, c("cayley", "hamming", "kendall"))
+  validate_integer(n_items)
+  validate_positive(n_items)
+  validate_positive(alpha)
+
+  get_partition_function(alpha, n_items, metric, NULL)
+}

R/estimate_partition_function.R

@@ -10,7 +10,7 @@
 #' any number of items, for footrule distances with up to 50 items, Spearman
 #' distance with up to 20 items, and Ulam distance with up to 60 items. This
 #' function is thus intended for the complement of these cases. See
-#' [get_cardinalities()] for details.
+#' [get_cardinalities()] and [compute_exact_partition_function()] for details.
 #'
 #' @param method Character string specifying the method to use in order to
 #'   estimate the logarithm of the partition function. Available options are

R/get_cardinalities.R

@@ -3,7 +3,7 @@
 #' @description The partition function for the Mallows model can be defined in a
 #'   computationally efficient manner as
 #'   \deqn{Z_{n}(\alpha) = \sum_{d_{n} \in
-#'   \mathcal{D}_{n}} N_{m,n} e^{-(\alpha/n) d_{m}}}.
+#'   \mathcal{D}_{n}} N_{m,n} e^{-(\alpha/n) d_{m}}.}
 #'   In this equation, \eqn{\mathcal{D}_{n}} a set containing all possible
 #'   distances at the given number of items, and \eqn{d_{m}} is on element of
 #'   this set. Finally, \eqn{N_{m,n}} is the number of possible configurations

R/validation_functions.R

@@ -14,7 +14,7 @@ validate_integer <- function(argument) {
 }
 
 validate_positive <- function(argument) {
-  if (argument <= 0 || !is.numeric(argument)) {
+  if (length(argument) > 1 || argument <= 0 || !is.numeric(argument)) {
     stop(paste(
       deparse(substitute(argument)),
       "must be a strictly positive number of length one"

inst/examples/compute_exact_partition_function_example.R

@@ -0,0 +1,11 @@
+compute_exact_partition_function(
+  alpha = 3.4, n_items = 34, metric = "cayley"
+)
+
+compute_exact_partition_function(
+  alpha = 3.4, n_items = 34, metric = "hamming"
+)
+
+compute_exact_partition_function(
+  alpha = 3.4, n_items = 34, metric = "kendall"
+)

tests/testthat/test-compute_exact_partition_function.R

@@ -0,0 +1,35 @@
+test_that("compute_exact_partition_function works", {
+  expect_error(
+    compute_exact_partition_function(3, -1),
+    "n_items must be a positive integer"
+  )
+  expect_error(
+    compute_exact_partition_function(3, 2.3),
+    "n_items must be a positive integer"
+  )
+  expect_error(
+    compute_exact_partition_function(3, 0),
+    "n_items must be a strictly positive number of length one"
+  )
+  expect_error(
+    compute_exact_partition_function(-2, 3),
+    "alpha must be a strictly positive number of length one"
+  )
+  expect_error(
+    compute_exact_partition_function(rnorm(2), 3),
+    "alpha must be a strictly positive number of length one"
+  )
+
+  expect_equal(
+    compute_exact_partition_function(alpha = 3, n_items = 10, metric = "cayley"),
+    13.0481794289176
+  )
+  expect_equal(
+    compute_exact_partition_function(alpha = 3, n_items = 10, metric = "hamming"),
+    12.4542713806513
+  )
+  expect_equal(
+    compute_exact_partition_function(alpha = 3, n_items = 10, metric = "kendall"),
+    9.69641008390133
+  )
+})