docs: add CRAN-compliant documentation with examples for exported functions

Co-authored-by: aider (anthropic/claude-sonnet-4-20250514) <aider@aider.chat>

Author: osorensen

R/set_hyperparameters.R

@@ -1,12 +1,41 @@
-#' Set hyperparameters
+#' Set hyperparameters for Bayesian Mallows model
 #'
-#' @param n_items Integer defining the number of items.
-#' @param alpha_shape Shape of gamma prior for alpha.
-#' @param alpha_rate Rate of gamma prior for alpha.
-#' @param cluster_concentration Concentration parameter of Dirichlet distribution for cluster probabilities.
-#' @param n_clusters Integer defining the number of clusters.
+#' This function creates a list of hyperparameters for the Bayesian Mallows model
+#' used in sequential Monte Carlo inference. The hyperparameters define the prior
+#' distributions for the model parameters.
 #'
-#' @return A list
+#' @param n_items Integer defining the number of items to be ranked. Must be a
+#'   positive integer.
+#' @param alpha_shape Positive numeric value specifying the shape parameter of 
+#'   the gamma prior distribution for the scale parameter alpha. Default is 1.
+#' @param alpha_rate Positive numeric value specifying the rate parameter of 
+#'   the gamma prior distribution for the scale parameter alpha. Default is 0.5.
+#' @param cluster_concentration Positive numeric value specifying the 
+#'   concentration parameter of the Dirichlet distribution for cluster 
+#'   probabilities. Default is 10.
+#' @param n_clusters Positive integer defining the number of clusters in the 
+#'   mixture model. Default is 1.
+#'
+#' @return A list containing the hyperparameter values with elements:
+#'   \item{n_items}{Number of items}
+#'   \item{alpha_shape}{Shape parameter for alpha prior}
+#'   \item{alpha_rate}{Rate parameter for alpha prior}
+#'   \item{cluster_concentration}{Concentration parameter for cluster probabilities}
+#'   \item{n_clusters}{Number of clusters}
+#'
+#' @examples
+#' # Basic hyperparameters for 5 items
+#' hyper <- set_hyperparameters(n_items = 5)
+#' 
+#' # Custom hyperparameters with multiple clusters
+#' hyper <- set_hyperparameters(
+#'   n_items = 10,
+#'   alpha_shape = 2,
+#'   alpha_rate = 1,
+#'   cluster_concentration = 5,
+#'   n_clusters = 3
+#' )
+#' 
 #' @export
 #'
 set_hyperparameters <- function(

R/set_smc_options.R

@@ -1,26 +1,62 @@
-#' Set SMC options
+#' Set SMC options for sequential inference
 #'
-#' @param n_particles Number of particles
-#' @param n_particle_filters Initial number of particle filters for each
-#'   particle
-#' @param max_particle_filters Maximum number of particle filters.
-#' @param resampling_threshold Effective sample size threshold for resampling
-#' @param doubling_threshold Threshold for particle filter doubling. If the
-#'   acceptance rate of the rejuvenation step falls below this threshold, the
-#'   number of particle filters is doubled. Defaults to 0.2.
-#' @param max_rejuvenation_steps Maximum number of rejuvenation steps. If the
-#'   number of unique particles has not exceeded half the number of particles
-#'   after this many steps, the rejuvenation is still stopped.
-#' @param metric Metric
-#' @param resampler resampler
-#' @param latent_rank_proposal latent rank proposal
-#' @param verbose Boolean
-#' @param trace Logical specifying whether to save static parameters at each
-#'   timestep.
-#' @param trace_latent Logical specifying whether to sample and save one
-#'   complete set of latent rankings for each particle and each timepoint.
+#' This function creates a list of options for the Sequential Monte Carlo (SMC²)
+#' algorithm used in Bayesian inference for the Mallows model. These options
+#' control the behavior of the particle filtering and resampling procedures.
 #'
-#' @return A list
+#' @param n_particles Positive integer specifying the number of particles to use
+#'   in the SMC algorithm. Default is 1000.
+#' @param n_particle_filters Positive integer specifying the initial number of 
+#'   particle filters for each particle. Default is 50.
+#' @param max_particle_filters Positive integer specifying the maximum number 
+#'   of particle filters allowed. Default is 10000.
+#' @param resampling_threshold Positive numeric value specifying the effective 
+#'   sample size threshold for triggering resampling. Default is n_particles/2.
+#' @param doubling_threshold Numeric value between 0 and 1 specifying the 
+#'   threshold for particle filter doubling. If the acceptance rate of the 
+#'   rejuvenation step falls below this threshold, the number of particle 
+#'   filters is doubled. Default is 0.2.
+#' @param max_rejuvenation_steps Positive integer specifying the maximum number 
+#'   of rejuvenation steps. If the number of unique particles has not exceeded 
+#'   half the number of particles after this many steps, the rejuvenation is 
+#'   stopped. Default is 20.
+#' @param metric Character string specifying the distance metric to use. 
+#'   Options include "footrule", "kendall", "spearman", "cayley", "hamming", 
+#'   and "ulam". Default is "footrule".
+#' @param resampler Character string specifying the resampling method. 
+#'   Options include "multinomial", "residual", "stratified", and "systematic". 
+#'   Default is "multinomial".
+#' @param latent_rank_proposal Character string specifying the proposal 
+#'   distribution for latent rankings. Default is "uniform".
+#' @param verbose Logical value indicating whether to print progress messages 
+#'   during computation. Default is FALSE.
+#' @param trace Logical value specifying whether to save static parameters at 
+#'   each timestep. Default is FALSE.
+#' @param trace_latent Logical value specifying whether to sample and save one 
+#'   complete set of latent rankings for each particle and each timepoint. 
+#'   Default is FALSE.
+#'
+#' @return A list containing all the SMC options with the specified values.
+#'
+#' @examples
+#' # Default SMC options
+#' opts <- set_smc_options()
+#' 
+#' # Custom SMC options with fewer particles and Kendall distance
+#' opts <- set_smc_options(
+#'   n_particles = 500,
+#'   n_particle_filters = 25,
+#'   metric = "kendall",
+#'   verbose = TRUE
+#' )
+#' 
+#' # Options for tracing parameters
+#' opts <- set_smc_options(
+#'   n_particles = 100,
+#'   trace = TRUE,
+#'   trace_latent = TRUE
+#' )
+#' 
 #' @export
 #'
 set_smc_options <- function(