updated documentation

Author: osorensen

BayesMallowsSMC2.Rproj

@@ -1,4 +1,5 @@
 Version: 1.0
+ProjectId: 05eac0c6-169d-4970-9e0b-098277092c56
 
 RestoreWorkspace: Default
 SaveWorkspace: Default

R/RcppExports.R

@@ -7,19 +7,34 @@
 #' saves them to a specified output directory. It ensures the output directory exists
 #' and creates it if it does not.
 #'
-#' @param prefs An integer matrix (`arma::umat`) representing the preference relations.
+#' @param prefs A matrix representing the preference relations. This matrix
+#'   must have two columns, the first of which represents the preferred item
+#'   and the second of which represents the disfavored item.
 #' @param n_items An integer specifying the number of items to sort.
 #' @param output_directory A string specifying the directory where the output files will be saved.
 #' @param save_frac Number between 0 and 1 specifying which fraction of sorts to save.
 #'
 #' @details
 #' The function generates all possible topological sorts for the provided preference matrix
-#' and saves each sort as a binary file in the specified output directory. The output files
-#' are named sequentially as `sort0.bin`, `sort1.bin`, and so on.
+#' and saves approximately `save_frac` of the sorts as binary file in the specified output directory.
+#' The output files are named sequentially as `sort0.bin`, `sort1.bin`, and so on.
 #'
 #' @return This function returns the number of topological sorts.
 #'
 #' @export
+#' @examples
+#' # Extract preferences from user 1 in the included example data.
+#' prefs <- pairwise_preferences[
+#'  pairwise_preferences$user == 1, c("top_item", "bottom_item"), drop = FALSE]
+#'
+#' # Count the number of sorts without saving them.
+#' precompute_topological_sorts(
+#'   prefs = as.matrix(prefs),
+#'   n_items = 5,
+#'   output_directory = tempdir(),
+#'   save_frac = 0
+#' )
+#'
 precompute_topological_sorts <- function(prefs, n_items, output_directory, save_frac) {
     .Call(`_BayesMallowsSMC2_precompute_topological_sorts`, prefs, n_items, output_directory, save_frac)
 }

man/precompute_topological_sorts.Rd

@@ -87,19 +87,34 @@ void Graph::alltopologicalSort(const std::string& output_directory,
 //' saves them to a specified output directory. It ensures the output directory exists
 //' and creates it if it does not.
 //'
-//' @param prefs An integer matrix (`arma::umat`) representing the preference relations.
+//' @param prefs A matrix representing the preference relations. This matrix
+//'   must have two columns, the first of which represents the preferred item
+//'   and the second of which represents the disfavored item.
 //' @param n_items An integer specifying the number of items to sort.
 //' @param output_directory A string specifying the directory where the output files will be saved.
 //' @param save_frac Number between 0 and 1 specifying which fraction of sorts to save.
 //'
 //' @details
 //' The function generates all possible topological sorts for the provided preference matrix
-//' and saves each sort as a binary file in the specified output directory. The output files
-//' are named sequentially as `sort0.bin`, `sort1.bin`, and so on.
+//' and saves approximately `save_frac` of the sorts as binary file in the specified output directory.
+//' The output files are named sequentially as `sort0.bin`, `sort1.bin`, and so on.
 //'
 //' @return This function returns the number of topological sorts.
 //'
 //' @export
+//' @examples
+//' # Extract preferences from user 1 in the included example data.
+//' prefs <- pairwise_preferences[
+//'  pairwise_preferences$user == 1, c("top_item", "bottom_item"), drop = FALSE]
+//'
+//' # Count the number of sorts without saving them.
+//' precompute_topological_sorts(
+//'   prefs = as.matrix(prefs),
+//'   n_items = 5,
+//'   output_directory = tempdir(),
+//'   save_frac = 0
+//' )
+//'
 // [[Rcpp::export]]
 long long int precompute_topological_sorts(
    arma::umat prefs, int n_items, std::string output_directory, double save_frac) {