forked from ocbe-uio/BayesMallows
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
139 lines (89 loc) · 6.27 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
---
output:
github_document:
fig_width: 6
fig_height: 4
bibliography: ./inst/REFERENCES.bib
link-citations: true
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
eval = TRUE
)
```
# BayesMallows
[](https://cran.r-project.org/package=BayesMallows)
[](https://github.com/ocbe-uio/BayesMallows/actions)
[](https://app.codecov.io/gh/ocbe-uio/BayesMallows?branch=master)
[](https://www.codefactor.io/repository/github/ocbe-uio/bayesmallows/overview/master)
This package provides a general framework for analyzing rank and preference data based on the Bayesian Mallows model.
## Installation
To install the current release, use
```{r,eval=FALSE}
install.packages("BayesMallows")
```
To install the current development version, use
```{r,eval=FALSE}
# install.packages("remotes")
remotes::install_github("ocbe-uio/BayesMallows")
```
## Basic Usage Example
To get started, load the package with
```{r}
library(BayesMallows)
set.seed(123)
```
The package comes with several example datasets. The simplest one contains 12 persons' assessments of the weights of 20 potatoes, either by visual inspection (`potato_visual`) or by lifting the potatoes and comparing their relative weights by hand (`potato_weighing`).
### Metropolis-Hastings Algorithm
To fit a Bayesian Mallows model on the `potato_visual` dataset using the Metropolis-Hastings algorithm first described in @vitelli2018, we do
```{r}
potato_data <- setup_rank_data(potato_visual)
fit <- compute_mallows(data = potato_data)
```
Next, we can see a diagnostic plot for the Metropolis-Hastings algorithm with `assess_convergence()`. The plot below is for the scale parameter, which measures the variation between the individual rankings.
```{r}
assess_convergence(fit)
```
Setting the burnin to 500, we obtain a plot of the posterior distribution of the scale parameter with:
```{r}
burnin(fit) <- 500
plot(fit)
```
For more examples, please see our [the introductory vignette](https://ocbe-uio.github.io/BayesMallows/articles/BayesMallows.html), and the function documentation. The use of parallel chains are described in [this vignette](https://ocbe-uio.github.io/BayesMallows/articles/parallel_chains.html).
### Sequential Monte Carlo Algorithm
The package also supports updating a Bayesian Mallows model using sequential Monte Carlo, with the algorithm described in @steinSequentialInferenceMallows2023. For example, in order to update the model fitted above with the potato ranks based on comparing their relative weights by hand, we do
```{r}
new_data <- setup_rank_data(rankings = potato_weighing)
updated_fit <- update_mallows(model = fit, new_data = new_data)
```
We can go on to plot the posterior distribution of the scale parameter for this updated model.
```{r}
plot(updated_fit)
```
Sequential Monte Carlo can typically be useful when new data arrives in batches, as it does not require the Metropolis-Hastings algorithm to be rerun. See [this vignette](https://ocbe-uio.github.io/BayesMallows/articles/SMC-Mallows.html) for more information.
## The Bayesian Mallows Model
### Methodology
The BayesMallows package currently implements the complete model described in @vitelli2018, which includes a large number of distance metrics, handling of missing ranks and pairwise comparisons, and clustering of users with similar preferences. The extension to non-transitive pairwise comparisons by @crispino2019 is also implemented. In addition, the partition function of the Mallows model can be estimated using the importance sampling algorithm of @vitelli2018 and the asymptotic approximation of @mukherjee2016. For a review of ranking models in general, see @liu2019. @crispino2022 outlines how informative priors can be used within the model.
Updating of the posterior distribution based on new data, using sequential Monte Carlo methods, is implemented and described in [a separate vignette](https://ocbe-uio.github.io/BayesMallows/articles/SMC-Mallows.html). The computational algorithms are described in further detail in @steinSequentialInferenceMallows2023.
### Applications
Among the current applications, @liu2019b applied the Bayesian Mallows model for providing personalized recommendations based on clicking data, and @barrett2018 used the model of @crispino2019 to analyze listeners' understanding of music. @eliseussenRankbasedBayesianVariable2022 presented an extended model for variable selection in genome-wide transcriptomic analyses.
### Future Extensions
Plans for future extensions of the package include implementation of a variational Bayes algorithm for approximation the posterior distribution. The sequential Monte Carlo algorithms will also be extended to cover a larger part of the model framework, and we will add more options for specifications of prior distributions.
## Compilation with Thread Building Blocks (TBB)
Parts of the underlying C++ code can be easily parallelized. We have support for this through [oneAPI Threading Building Blocks](https://github.com/oneapi-src/oneTBB). If you want to make use of this, build the package from source with the `-ltbb` argument. On an M1 Mac this can be achieved by first installing TBB through `brew install tbb` and then adding the following line to `~/.R/Makevars`:
```{sh, eval=FALSE}
CXX17=g++-13 -I/opt/homebrew/include -L/opt/homebrew/lib -ltbb
```
The arguments on other platforms should be similar. If TBB is not available, the package will fall back on sequential processing.
## Citation
If using the BayesMallows package in academic work, please cite @sorensen2020, in addition to the relevant methodological papers.
```{r}
citation("BayesMallows")
```
## Contribution
This is an open source project, and all contributions are welcome. Feel free to open an [Issue](https://github.com/ocbe-uio/BayesMallows/issues), a [Pull Request](https://github.com/ocbe-uio/BayesMallows/pulls), or to e-mail us.
## References