compute_sequentially.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/compute_sequentially.R
\name{compute_sequentially}
\alias{compute_sequentially}
\title{Compute the Bayesian Mallows model sequentially}
\usage{
compute_sequentially(
  data,
  hyperparameters = set_hyperparameters(),
  smc_options = set_smc_options(),
  topological_sorts = NULL
)
}
\arguments{
\item{data}{A dataframe containing partial rankings or pairwise preferences.
If \code{data} contains complete or partial rankings, it must have the following
columns:

\itemize{
\item \code{timepoint}: a numeric vector denoting the timepoint, starting at 1.
\item \code{user}: a vector identifying the user.
\item \code{item1}: ranking of item 1.
\item \code{item2}: ranking of item 2.
\item etc.
}

If data contains pairwise preferences, it must have the following
structure:

\itemize{
\item \code{timepoint}: a numeric vector denoting the timepoint, starting at 1.
\item \code{user}: a vector identifying the user.
\item \code{top_item}: identifier for the preferred item.
\item \code{bottom_item}: identifier for the dispreferred item.
}}

\item{hyperparameters}{A list returned from \code{\link[=set_hyperparameters]{set_hyperparameters()}}.}

\item{smc_options}{A list returned from \code{\link[=set_smc_options]{set_smc_options()}}. Controls the
nested SMC2 algorithm parameters including number of parameter particles,
number of particle filters per parameter particle, and MCMC move parameters.}

\item{topological_sorts}{A list returned from
\code{\link[=precompute_topological_sorts]{precompute_topological_sorts()}}. Only used with preference data, and
defaults to \code{NULL}. Contains precomputed topological sorts for efficient
sampling from constrained ranking spaces.}
}
\value{
An object of class BayesMallowsSMC2 containing posterior samples
and algorithm diagnostics.
}
\description{
This function implements the nested sequential Monte Carlo (SMC2) algorithm
for sequential learning of rank and preference data using the Bayesian
Mallows model. The algorithm processes data sequentially over time,
maintaining a particle approximation to the posterior distribution.
}
\details{
The nested SMC2 algorithm consists of two levels of sequential Monte Carlo:

\strong{Outer SMC (Parameter Level)}: Maintains particles representing samples
from the posterior distribution of static parameters (alpha, rho, tau).
Each particle contains its own set of parameter values.

\strong{Inner SMC (Latent State Level)}: For each parameter particle, maintains
multiple particle filters that track the evolution of latent rankings and
cluster assignments over time. This nested structure allows the algorithm
to handle the complex dependency structure between parameters and latent
states.

At each timepoint, the algorithm:
\enumerate{
\item Propagates each parameter particle forward using MCMC moves
\item For each parameter particle, runs multiple particle filters to sample
latent rankings and cluster assignments
\item Computes importance weights based on the likelihood of observed data
\item Resamples particles when effective sample size drops below threshold
\item Applies rejuvenation moves to maintain particle diversity
}

The nested structure is essential for maintaining proper uncertainty
quantification in the joint parameter-latent state space.
}
\examples{
# Example with complete rankings
library(BayesMallowsSMC2)

# Generate synthetic ranking data
set.seed(123)
n_items <- 5
n_users <- 20
n_timepoints <- 10

# Create synthetic data
data <- expand.grid(
  timepoint = 1:n_timepoints,
  user = 1:n_users
)

# Add random rankings for each item
for(i in 1:n_items) {
  data[[paste0("item", i)]] <- sample(1:n_items, nrow(data), replace = TRUE)
}

# Set hyperparameters
hyperparams <- set_hyperparameters(
  n_items = n_items,
  alpha_shape = 2,
  alpha_rate = 1,
  n_clusters = 2
)

# Set SMC options
smc_opts <- set_smc_options(
  n_particles = 100,
  n_particle_filters = 20,
  metric = "kendall",
  verbose = TRUE
)

# Run sequential computation
result <- compute_sequentially(
  data = data,
  hyperparameters = hyperparams,
  smc_options = smc_opts
)

# Example with pairwise preferences
# First precompute topological sorts
prefs_matrix <- matrix(c(1, 2, 2, 3, 3, 1), ncol = 2, byrow = TRUE)
topo_sorts <- precompute_topological_sorts(
  prefs = prefs_matrix,
  n_items = 3,
  save_frac = 0.1
)

# Create preference data
pref_data <- data.frame(
  timepoint = c(1, 1, 2, 2),
  user = c(1, 2, 1, 2),
  top_item = c(1, 2, 3, 1),
  bottom_item = c(2, 3, 1, 3)
)

# Run with preferences
result_prefs <- compute_sequentially(
  data = pref_data,
  hyperparameters = set_hyperparameters(n_items = 3),
  smc_options = set_smc_options(n_particles = 50),
  topological_sorts = topo_sorts
)

}
\references{
Sørensen, Ø., Stein, A., Netto, W. L., & Leslie, D. S. (2025).
Sequential Rank and Preference Learning with the Bayesian Mallows Model.
\emph{Bayesian Analysis}. DOI: 10.1214/25-BA1564.
}
\seealso{
\code{\link[=set_hyperparameters]{set_hyperparameters()}}, \code{\link[=set_smc_options]{set_smc_options()}}, \code{\link[=precompute_topological_sorts]{precompute_topological_sorts()}}
}