PlackettLuce

https://hturner.github.io/PlackettLuce/
Admin
The PlackettLuce package implements a generalization of the Plackett-Luce model for modelling...
Tokens:47,136
Snippets:466
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Load Example Data

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Loads the example 'beans' dataset from the PlackettLuce package to demonstrate Plackett-Luce tree functionality.

```R
example("beans", package = "PlackettLuce")
```

--------------------------------

### Install PlackettLuce Package

Source: https://hturner.github.io/PlackettLuce/index.html

Installs the PlackettLuce package from GitHub using the devtools package. Ensure devtools is installed first.

```r
install.packages("devtools")
devtools::install_github("hturner/PlackettLuce")
```

--------------------------------

### Example: All Items in Separate Clusters

Source: https://hturner.github.io/PlackettLuce/reference/connectivity.html

Demonstrates connectivity for a case where all items are in separate clusters, representing a strict hierarchy (e.g., 1 > 2 > 3 > 4). This example also includes miscoded and redundant rankings to show how the function handles them, along with messages about data recoding and network connectivity.

```R
X <- matrix(c(1, 2, 3, 4,
              1, 0, 2, 3,
              1, 1, 2, 0,
              1, 0, 3, 4,
              2, 2, 0, 4,
              0, 0, 3, 0,
              2, 4, 0, 0), ncol = 4, byrow = TRUE)
res <- connectivity(as.rankings(X))
#> Recoded rankings that are not in dense form
#> Rankings with only 1 item set to `NA`
#> Network of items is not strongly connected
res$membership
#> 1 2 3 4 
#> 1 2 3 4 
```

--------------------------------

### Example: Weakly Connected Network

Source: https://hturner.github.io/PlackettLuce/reference/connectivity.html

Demonstrates checking connectivity for a weakly connected network where there is one win between two clusters. The output shows the membership of items in different clusters and how to filter rankings based on cluster membership.

```R
X <- matrix(c(1, 2, 0, 0,
              2, 1, 3, 0,
              0, 0, 1, 2,
              0, 0, 2, 1), ncol = 4, byrow = TRUE)
X <- as.rankings(X)
res <- connectivity(X)
#> Network of items is not strongly connected
res$membership
#> 1 2 3 4 
#> 1 1 2 2 
## keep items in cluster 1
na.omit(X[,res$membership == 1])
#> [1] "1 > 2" "2 > 1"
```

--------------------------------

### Load the pudding dataset

Source: https://hturner.github.io/PlackettLuce/reference/pudding.html

This code snippet loads the 'pudding' dataset, which is an example dataset for paired comparisons.

```r
pudding
```

--------------------------------

### Convert Rankings to Matrix

Source: https://hturner.github.io/PlackettLuce/reference/rankings.html

Demonstrates an alternative way to convert the `rankings` object to a standard matrix, showing equivalent output to the previous example.

```R
# same as
as.matrix(R)[2:3,]
```

--------------------------------

### Read Preference Data from URL with Incomplete Orderings

Source: https://hturner.github.io/PlackettLuce/reference/preflib.html

Reads preference data from a TOI file hosted on GitHub using `read.toi` and `file.path`. This example demonstrates handling incomplete orderings with ties and is wrapped in `if (FALSE)` to prevent execution by default.

```r
if (FALSE) { # \dontrun{
# incomplete orderings with ties: most important qualities for success
# from 20 in total
preflib <- "https://raw.githubusercontent.com/PrefLib/PrefLib-Data/main/datasets"
qualities2 <- read.toi(file.path(preflib, "00032%20-%20education/00032-00000007.toi"))
all.equal(qualities, qualities2)
} # }
```

--------------------------------

### Example: Two Weakly Connected Items

Source: https://hturner.github.io/PlackettLuce/reference/connectivity.html

Illustrates checking connectivity for a network with two weakly connected items, where one item consistently loses and another only wins against the losing item. The results display the cluster membership for each item.

```R
X <- matrix(c(4, 1, 2, 3,
              0, 2, 1, 3), nr = 2, byrow = TRUE)
X <- as.rankings(X)
res <- connectivity(X)
#> Network of items is not strongly connected
res$membership
#> 1 2 3 4 
#> 3 1 1 2 
```

--------------------------------

### Create Example Long Form Data

Source: https://hturner.github.io/PlackettLuce/reference/rankings.html

This snippet demonstrates how to create a sample data frame in long format for testing the `rankings` function. It includes various scenarios like missing ranks and duplicated items.

```R
x <- data.frame(ranking = c(rep(1:4, each = 4), 5, 5, 5),
                letter = c(LETTERS[c(1:3, 3, 1:4, 2:5, 1:2, 1)], NA,
                           LETTERS[3:5]),
                rank = c(4:1, rep(NA, 4), 3:4, NA, NA, 1, 3, 4, 2, 2, 2, 3))
```

--------------------------------

### Example: Item 1 Always Wins, Item 4 Always Loses

Source: https://hturner.github.io/PlackettLuce/reference/connectivity.html

Shows connectivity check for a scenario where item 1 always wins and item 4 always loses against all other items. The output provides the cluster membership for each item.

```R
X <- matrix(c(1, 2, 3, 4,
              1, 3, 2, 4), nr = 2, byrow = TRUE)
res <- connectivity(as.rankings(X))
#> Network of items is not strongly connected
res$membership
#> 1 2 3 4 
#> 1 2 2 3 
```

--------------------------------

### Install PlackettLuce Package

Source: https://hturner.github.io/PlackettLuce/index.html

Use this command to install the stable version of the PlackettLuce package from CRAN. Ensure you have a stable internet connection and R package management set up.

```r
install.packages("PlackettLuce")
```

--------------------------------

### Ties Data Frame Example

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Shows the first two rows of the 'ties' data frame, illustrating how pairs of items involved in a tie are represented. The 'Loser' column is NA for ties.

```r
##   Winner Loser
## 1   1, 2    NA
## 2   1, 3    NA
```

--------------------------------

### Plackett-Luce Model Data Expansion

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

This example shows how a single ranking is expanded into multiple choices and counts for fitting using generalized linear models. Each row represents a choice or an item within a choice.

```r
##      choice item 1 item 2 item 3 count
## [1,]      1      1      0      0     0
## [2,]      1      0      1      0     0
## [3,]      1      0      0      1     1
## [4,]      2      1      0      0     1
## [5,]      2      0      1      0     0
```

--------------------------------

### Create Rankings Matrix

Source: https://hturner.github.io/PlackettLuce/reference/rankings.html

Initializes a matrix of rankings and converts it using `as.rankings`.

```R
R <- matrix(c(1, 2, 0, 0,
              4, 1, 2, 3,
              2, 1, 1, 1,
              1, 2, 3, 0,
              2, 1, 1, 0,
              1, 0, 3, 2), nrow = 6, byrow = TRUE)
colnames(R) <- c("apple", "banana", "orange", "pear")
R <- as.rankings(R)
```

--------------------------------

### Get Fitted Values with `fitted`

Source: https://hturner.github.io/PlackettLuce/articles/PLADMM.html

Retrieve the fitted values (predicted log-worths) for the items included in the original model training data.

```r
fitted(regressionPL)
```

--------------------------------

### Get Item Worth Estimates with `itempar`

Source: https://hturner.github.io/PlackettLuce/articles/PLADMM.html

Use the `itempar` function to retrieve the estimated worth of items from a fitted Plackett-Luce model.

```r
itempar(standardPL)
```

--------------------------------

### Pass R CMD check without suggested packages

Source: https://hturner.github.io/PlackettLuce/news/index.html

Modified tests to ensure R CMD check passes even when suggested packages are not installed.

```R
Make tests (and hence R CMD check) pass without suggested packages
```

--------------------------------

### PlackettLuce Model Fitting

Source: https://hturner.github.io/PlackettLuce/articles/PLADMM.html

Fits a PlackettLuce model to the salad dressing ranking data. Sets npseudo to 0 to avoid adding pseudocounts. Use this to get a baseline comparison.

```R
standardPL_PlackettLuce <- PlackettLuce(salad, npseudo = 0)
summary(standardPL_PlackettLuce)
```

--------------------------------

### Create and Aggregate Rankings

Source: https://hturner.github.io/PlackettLuce/reference/aggregate.html

Demonstrates how to create a rankings object with duplicate entries and then aggregate them using the aggregate function. This is useful for simplifying datasets with repeated rankings.

```R
# create a rankings object with duplicated rankings
R <- matrix(c(1, 2, 0, 0,
              0, 1, 2, 3,
              2, 1, 1, 0,
              1, 2, 0, 0,
              2, 1, 1, 0,
              1, 0, 3, 2), nrow = 6, byrow = TRUE)
colnames(R) <- c("apple", "banana", "orange", "pear")
R <- as.rankings(R)

# aggregate the rankings
A <- aggregate(R)
```

--------------------------------

### Get Variance-Covariance Matrix for PlackettLuce Model

Source: https://hturner.github.io/PlackettLuce/reference/summaries.html

Calculates the variance-covariance matrix for parameters in a PlackettLuce model. Specify the 'ref' item and the 'type' of Fisher information ('expected' or 'observed') to use for estimation.

```R
vcov(object, ref = 1L, type = c("expected", "observed"), ...)
```

--------------------------------

### Prepare Data for PlackettLuce Model

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Converts the raw preference data (wins for i, wins for j, and ties) into a format suitable for the PlackettLuce model by creating 'Winner' and 'Loser' data frames. Ties are represented with a missing 'Loser'.

```r
i_wins <- data.frame(Winner = pudding$i, Loser = pudding$j)
j_wins <- data.frame(Winner = pudding$j, Loser = pudding$i)
if (getRversion() < "3.6.0"){
  n <- nrow(pudding)
  ties <- data.frame(Winner = array(split(pudding[c("i", "j")], 1:n), n),
                     Loser = rep(NA, 15))
} else {
  ties <- data.frame(Winner = asplit(pudding[c("i", "j")], 1),
                     Loser = rep(NA, 15))
}
head(ties, 2)
```

--------------------------------

### Get Coefficients from Plackett-Luce Tree

Source: https://hturner.github.io/PlackettLuce/reference/pltree-summaries.html

Retrieve the coefficients for specified nodes from a fitted Plackett-Luce tree model. Use 'drop = TRUE' to return coefficients as a vector when only one node is selected.

```R
data(beans)
# fit tree based on pairwise comparisons with variety B
pairB <- data.frame(Winner = ifelse(beans$var_b == "Worse",
                                    "Local", beans$variety_b),
                    Loser = ifelse(beans$var_b == "Worse",
                                   beans$variety_b, "Local"),
                    stringsAsFactors = FALSE, row.names = NULL)eans$G <- as.rankings(pairB, input = "orderings",
                       index = rep(seq(nrow(beans)), 1))

mod <- pltree(G ~ ., data = beans[c("G", "maxTN")])

coef(mod, node = 3)
```

--------------------------------

### Prepare Data for Prediction

Source: https://hturner.github.io/PlackettLuce/articles/PLADMM.html

Create a data frame with features for new items to predict their log-worth. Ensure the data frame includes columns for the covariates used in the model.

```r
features2 <- data.frame(salad = LETTERS[5:6],
                        acetic = c(0.5, 0),
                        gluconic = c(5, 5))
```

--------------------------------

### Simulating Rankings from a PlackettLuce Model

Source: https://hturner.github.io/PlackettLuce/reference/simulate.PlackettLuce.html

Demonstrates how to fit a PlackettLuce model to ranking data and then simulate new rankings from the fitted model. The `seed` argument ensures reproducibility.

```R
R <- matrix(c(1, 2, 0, 0,
              4, 1, 2, 3,
              2, 1, 1, 1,
              1, 2, 3, 0,
              2, 1, 1, 0,
              1, 0, 3, 2), nrow = 6, byrow = TRUE)
colnames(R) <- c("apple", "banana", "orange", "pear")
mod <- PlackettLuce(R)
simulate(mod, 5)
```

--------------------------------

### Load and view salad data

Source: https://hturner.github.io/PlackettLuce/articles/PLADMM.html

Loads the `salad` dataset and displays the first few rows to inspect its structure.

```R
library(PlackettLuce)
head(salad, 4)
```

--------------------------------

### Get Coefficients from PlackettLuce Model

Source: https://hturner.github.io/PlackettLuce/reference/summaries.html

Extracts coefficients from a fitted PlackettLuce model. Use 'ref' to specify the reference item and 'log' to control the scale of parameters. 'type' allows selection of 'ties', 'worth', or 'all' coefficients.

```R
coef(object, ref = 1L, log = TRUE, type = "all", ...)
```

--------------------------------

### Read PrefLib file formats

Source: https://hturner.github.io/PlackettLuce/news/index.html

Added `read.soi()`, `read.toc()`, and `read.toi()` functions to read corresponding PrefLib file formats. An `as.aggregated_rankings()` method is provided for conversion.

```R
New `read.soi()`, `read.toc()` and `read.toi()` to read the corresponding PrefLib file formats (for data types “Strict Orders - Incomplete List”, “Orders with Ties - Complete List” and “Orders with Ties - Incomplete List”). An `as.aggregated_rankings()` method is provided to convert the data frame of aggregated orderings to an `"aggregated_rankings"` object.
```

--------------------------------

### complete() and decode() for pre-processing orderings

Source: https://hturner.github.io/PlackettLuce/news/index.html

Added `complete()` and `decode()` functions to assist in pre-processing orderings. `complete()` infers missing items in a rank, and `decode()` converts coded partial orderings to full item orderings.

```R
New `complete()` and `decode()` functions to help pre-process orderings before converting to rankings, `complete()` infers the item(s) in r’th rank given the items in the other (r - 1) ranks. `decode()` converts coded (partial) orderings to orderings of the items in each ordering.
```

--------------------------------

### Prepare Data for Pairwise Comparisons

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Creates vectors 'trial_variety' and 'outcome' by unlisting the variety names and comparison outcomes, respectively. This prepares the data for deriving winners and losers in each comparison.

```R
trial_variety <- unlist(beans[c("variety_a", "variety_b", "variety_c")])
outcome <- unlist(beans[c("var_a", "var_b", "var_c")] )
```

--------------------------------

### Advice on analyzing data with higher order ties

Source: https://hturner.github.io/PlackettLuce/news/index.html

Added guidance in `?PlackettLuce` on how to analyze data that includes higher-order ties.

```R
`?PlackettLuce` now gives advice on analysing data with higher order ties.
```

--------------------------------

### Compare Item Parameters Before and After Pseudo-Rankings

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Compares the log-worth parameters for the first three drivers between the model fitted without pseudo-rankings and the model fitted with default pseudo-rankings. This demonstrates the shrinkage effect towards zero.

```R
coefs2 <- round(coef(mod2), 2)
coefs2[names(coefs)[1:3]]
```

--------------------------------

### Display Parameters for New Items in Full Model

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Shows the log-worth parameters for items (drivers) that were not included in the initial model (drivers 84-87). These new items have relatively large negative log worth parameters.

```R
coefs2[84:87]
```

--------------------------------

### Create Grouped Rankings Object

Source: https://hturner.github.io/PlackettLuce/reference/group.html

Demonstrates how to create a 'grouped_rankings' object by grouping existing rankings. This is useful for analyses that require group-specific covariate information.

```R
R <- as.rankings(matrix(c(1, 2, 0, 0,
                          0, 2, 1, 0,
                          0, 0, 1, 2,
                          2, 1, 0, 0,
                          0, 1, 2, 3), ncol = 4, byrow = TRUE))
length(R)
#> [1] 5
R
#> [1] "1 > 2"     "3 > 2"     "3 > 4"     "2 > 1"     "2 > 3 > 4"

# group rankings (first three in group 1, next two in group 2)
G <- group(R, c(1, 1, 1, 2, 2))
length(G)
#> [1] 2

## by default up to 2 rankings are shown per group, "..." indicates if
## there are further rankings
G
#>                   1                   2 
#> "1 > 2, 3 > 2, ..."  "2 > 1, 2 > 3 > 4"
print(G, max = 1)
#>            1            2 
#> "1 > 2, ..." "2 > 1, ..." 
```

--------------------------------

### Load Salad Dressings Data

Source: https://hturner.github.io/PlackettLuce/reference/salad.html

Access the 'salad' dataset, which contains rankings of four salad dressings based on their acetic and gluconic acid content.

```R
salad
```

--------------------------------

### Enable Overview vignette without kableExtra

Source: https://hturner.github.io/PlackettLuce/news/index.html

Ensured the Overview vignette can build without requiring the kableExtra package.

```R
Enable Overview vignette to build without kableExtra package
```

--------------------------------

### Load Strict Complete Orderings (Netflix Data)

Source: https://hturner.github.io/PlackettLuce/reference/preflib.html

Reads strict complete orderings from a .soc file. Useful for analyzing complete rankings where every item is ranked.

```R
netflix <- read.soc(system.file("extdata", "netflix.soc",
                                package = "PlackettLuce"))
head(netflix)
#>   Freq Rank 1 Rank 2 Rank 3 Rank 4
#> 1   68      2      1      4      3
#> 2   53      1      2      4      3
#> 3   49      2      1      3      4
#> 4   44      1      2      3      4
#> 5   39      2      4      1      3
#> 6   37      3      2      1      4
attr(netflix, "items")
#>                        1                        2                        3 
#>             "Mean Girls"      "Beverly Hills Cop"      "The Mummy Returns" 
#>                        4 
#> "Mission: Impossible II"

head(as.aggregated_rankings(netflix))
#>                                    ranking freq
#> 1 Beverly Hills Cop > Mean Girls > Mis ...   68
#> 2 Mean Girls > Beverly Hills Cop > Mis ...   53
#> 3 Beverly Hills Cop > Mean Girls > The ...   49
#> 4 Mean Girls > Beverly Hills Cop > The ...   44
#> 5 Beverly Hills Cop > Mission: Impossi ...   39
#> 6 The Mummy Returns > Beverly Hills Co ...   37
```

--------------------------------

### PlackettLuce Model Fitting and Fitted Probabilities Extraction

Source: https://hturner.github.io/PlackettLuce/reference/fitted.PlackettLuce.html

Demonstrates fitting a PlackettLuce model to choice data and then extracting the fitted probabilities for each choice-alternative combination. This is useful for understanding the model's predictions.

```R
R <- matrix(c(1, 2, 0, 0,
              4, 1, 2, 3,
              2, 1, 1, 1,
              1, 2, 3, 0,
              2, 1, 1, 0,
              1, 0, 3, 2), nrow = 6, byrow = TRUE)
colnames(R) <- c("apple", "banana", "orange", "pear")

mod <- PlackettLuce(R)
fit <- fitted(mod)
fit
```

--------------------------------

### Open PlackettLuce Package Vignette

Source: https://hturner.github.io/PlackettLuce/index.html

Opens the "Overview" vignette for the PlackettLuce package. This vignette provides a detailed illustration of the package's core functionality, the model used, and comparisons with other packages.

```R
vignette("Overview", package = "PlackettLuce")
```

--------------------------------

### Handle incomplete rankings in read.soi/read.toi

Source: https://hturner.github.io/PlackettLuce/news/index.html

Ensured `read.soi()` and `read.toi()` correctly handle incomplete rankings with irregular lengths.

```R
`read.soi()` and `read.toi()` now handle incomplete rankings with very irregular lengths correctly.
```

--------------------------------

### Use bookdown vs BiocStyle for vignettes

Source: https://hturner.github.io/PlackettLuce/news/index.html

Switched from BiocStyle to bookdown for vignette compilation.

```R
Use bookdown vs BiocStyle for vignettes
```

--------------------------------

### simulate.PlackettLuce

Source: https://hturner.github.io/PlackettLuce/reference/simulate.PlackettLuce.html

Simulates rankings from a fitted PlackettLuce model. This S3 method allows for generating multiple simulated response vectors based on the estimated item utilities.

```APIDOC
## simulate.PlackettLuce

### Description
Simulates rankings from a fitted `PlackettLuce` object.

### Method Signature
```R
simulate(object, nsim = 1L, seed = NULL, multinomial = FALSE, max_combinations = 20000, ...)
```

### Arguments

*   `object` (object): An object representing a fitted PlackettLuce model.
*   `nsim` (integer): The number of response vectors to simulate. Defaults to 1.
*   `seed` (integer | NULL): An optional seed for the random number generator to ensure reproducibility. If `NULL`, the current state of the random generator is used.
*   `multinomial` (boolean): Whether to use multinomial sampling. Defaults to `FALSE`. See Details for conditions.
*   `max_combinations` (numeric): A positive number used to limit the number of combinations for direct multinomial sampling. Defaults to 20000.
*   `...` (any): Additional optional arguments.

### Value
A `data.frame` containing simulated `rankings` objects, with the same dimensions as the `object$rankings`.

### Details

If `multinomial` is `FALSE` and the fitted model does not include tie parameters (i.e., `length(object$ties) == 1`), rankings are sampled by ordering exponential random variates. The rates of these variates are scaled by the estimated item-worth parameters (`object$coefficients`).

In all other cases (including when `length(object$ties) > 1`), the function defaults to direct multinomial sampling. An error will be raised if the number of possible item combinations exceeds `max_combinations` to prevent memory issues.

### Examples
```R
# Example data
R <- matrix(c(1, 2, 0, 0,
              4, 1, 2, 3,
              2, 1, 1, 1,
              1, 2, 3, 0,
              2, 1, 1, 0,
              1, 0, 3, 2), nrow = 6, byrow = TRUE)
colnames(R) <- c("apple", "banana", "orange", "pear")

# Fit a PlackettLuce model
mod <- PlackettLuce(R)

# Simulate 5 rankings
simulated_rankings <- simulate(mod, nsim = 5)
print(simulated_rankings)

# Simulate with a specific seed for reproducibility
s1 <- simulate(mod, nsim = 3, seed = 112)
s2 <- simulate(mod, nsim = 2, seed = 112)

# Check if the first two simulations are identical
print(identical(s1[1:2], s2[1:2]))
```
```

--------------------------------

### Handling orderings

Source: https://hturner.github.io/PlackettLuce/reference/index.html

Functions for completing and decoding orderings.

```APIDOC
## Handling orderings 

`complete()` 
    Complete Orderings with the Missing Redundant Rank 

`decode()` 
    Decode Orderings using a Key to Item Names
```

--------------------------------

### Calculate Quasi Variances for PlackettLuce Model

Source: https://hturner.github.io/PlackettLuce/reference/qvcalc.PlackettLuce.html

This snippet demonstrates how to fit a Plackett-Luce model to partial rankings and then compute the quasi variances for the item parameters using `qvcalc`. The results, including estimates, standard errors, quasi standard errors, and quasi variances, are printed. A plot of the quasi variances is also generated.

```R
R <- matrix(c(1, 2, 0, 0,
              4, 1, 2, 3,
              2, 1, 1, 1,
              1, 2, 3, 0,
              2, 1, 1, 0,
              1, 0, 3, 2), nrow = 6, byrow = TRUE)
colnames(R) <- c("apple", "banana", "orange", "pear")

mod <- PlackettLuce(R)
qv <- qvcalc(mod)
qv
#>           estimate       SE   quasiSE  quasiVar
#> apple   0.00000000 0.000000 0.6655053 0.4428973
#> banana  0.25287379 1.042049 0.8372194 0.7009362
#> orange -0.61350684 1.115181 0.8320735 0.6923463
#> pear   -0.08688475 1.067688 0.8632849 0.7452608
plot(qv)
```

--------------------------------

### Load and view beans dataset

Source: https://hturner.github.io/PlackettLuce/reference/beans.html

Loads the 'beans' dataset and displays the first two rows of the 'best' and 'worst' ranking columns.

```R
data(beans)
head(beans[c("best", "worst")], 2)
```

--------------------------------

### First Two Rankings

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Displays the first two rankings from the 'R' object, showing the format 'item1 > item2' for a win.

```r
## [1] "1 > 2" "1 > 3"
```

--------------------------------

### Handling rankings

Source: https://hturner.github.io/PlackettLuce/reference/index.html

Functions for creating, aggregating, grouping, and formatting rankings.

```APIDOC
## Handling rankings 

`adjacency()` 
    Create an Adjacency Matrix for a set of Rankings 

`aggregate(_<rankings>_)``as.aggregated_rankings()` ``[`(_<aggregated_rankings>_)``freq()` 
    Aggregate Rankings 

`choices()` 
    Choices Object 

`connectivity()` 
    Check Connectivity of Rankings 

`group()` `as.grouped_rankings()` ``[`(_<grouped_rankings>_)``format(_<grouped_rankings>_)`
    Group Rankings 

`rankings()` `as.rankings()` ``[`(_<rankings>_)``format(_<rankings>_)`
    Rankings Object
```

--------------------------------

### Other

Source: https://hturner.github.io/PlackettLuce/reference/index.html

Function for simulating from fitted PlackettLuce objects.

```APIDOC
## Other 

`simulate(_<PlackettLuce>_)`
    Simulate from `PlackettLuce` fitted objects
```

--------------------------------

### complete

Source: https://hturner.github.io/PlackettLuce/reference/complete.html

Completes orderings with one missing rank by assigning remaining items to the final rank.

```APIDOC
## complete

### Description
Given orderings with one rank missing, complete the ordering by assigning the remaining item(s) to the final rank.

### Usage
```
complete(orderings, items)
```

### Arguments 

* `orderings` (data.frame) - A data frame of orderings with one rank missing.
* `items` (vector) - A vector of item names.

### Value
A vector of the missing items, which will be a list if there are any ties.

### Examples
```R
# Orderings of 3 items, when only the best and worst are recorded
orderings <- data.frame(best = c("A", "B", "A"),
                        worst = c("C", "C", NA))
orderings$middle <- complete(orderings, items = c("A", "B", "C"))
```
```

--------------------------------

### Extract Log-Abilities with Reference Item

Source: https://hturner.github.io/PlackettLuce/reference/itempar.PlackettLuce.html

Extract log-abilities from a PlackettLuce model, using the first item as a reference for normalization.

```R
# equivalent to default coefficients, i.e. log abilities
itempar(mod, ref= 1, log = TRUE)
#> Item response item parameters (PlackettLuce):
#>    apple   banana   orange     pear 
#>  0.00000  0.25287 -0.61351 -0.08688 
```

--------------------------------

### as.matrix methods for rankings

Source: https://hturner.github.io/PlackettLuce/news/index.html

Introduced new `as.matrix()` methods for rankings and aggregated rankings to extract the underlying matrix, including frequencies in the last column if applicable.

```R
New `as.matrix()` methods for rankings and aggregated rankings to extract the underlying matrix of rankings, with frequencies in the final column if relevant. This means rankings can be saved easily with `write.table()`.
```

--------------------------------

### Load and Inspect Pudding Data

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Loads the 'pudding' dataset from the PlackettLuce package and displays the first few rows to understand its structure.

```r
library(PlackettLuce)
head(pudding)
```

--------------------------------

### Restore vcov.PlackettLuce for ref=NULL

Source: https://hturner.github.io/PlackettLuce/news/index.html

Resolved a bug in `vcov.PlackettLuce()` that prevented it from working when `ref = NULL`.

```R
`vcov.PlackettLuce()` works again for `ref = NULL` (bug introduced with vcov method in version 0.2-4)
```

--------------------------------

### View local variety comparison results

Source: https://hturner.github.io/PlackettLuce/reference/beans.html

Displays the first two rows of the 'var_a', 'var_b', and 'var_c' columns, which indicate how each variety was compared to the local variety.

```R
head(beans[c("var_a", "var_b", "var_c")], 2)
```

--------------------------------

### Meaningful errors for non-existent/corrupt Preflib files

Source: https://hturner.github.io/PlackettLuce/news/index.html

Improved error handling in `read.*()` functions for Preflib formats to provide meaningful messages for non-existent or corrupt files.

```R
`read.*()` functions for Preflib formats now give a meaningful error when the file or URL does not exist, and a warning if the file is corrupt.
```

--------------------------------

### Pudding Data Structure

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Displays the first few rows of the 'pudding' dataset, showing columns for item indices (i, j), preference counts (r_ij, w_ij, w_ji), and tie counts (t_ij).

```r
##   i j r_ij w_ij w_ji t_ij
## 1 1 2   57   19   22   16
## 2 1 3   47   16   19   12
## 3 2 3   48   19   19   10
## 4 1 4   54   18   23   13
## 5 2 4   51   23   19    9
## 6 3 4   54   19   20   15
```

--------------------------------

### as.rankings Method for Matrix

Source: https://hturner.github.io/PlackettLuce/reference/rankings.html

Specifically handles the conversion of matrices to 'rankings' objects. Users can define whether the matrix represents rankings or orderings and provide optional frequency or grouping information.

```APIDOC
## as.rankings(x, input = c("rankings", "orderings"), freq = NULL, index = NULL, aggregate = FALSE, items = NULL, labels = NULL, ..., verbose = TRUE)

### Description
S3 method for coercing a matrix to a "rankings" object. Allows specifying input format, frequency, grouping, and item details.

### Arguments
* `x` (matrix): A matrix with one column per item and one row per ranking.
* `input` (character): Whether rows contain numeric "rankings" or "orderings". Defaults to "rankings".
* `freq` (optional): Column index or vector for ranking frequencies. If provided, an "aggregated_rankings" object is returned.
* `index` (optional): Column index or vector for grouping. If provided, rankings are grouped.
* `aggregate` (logical): If `TRUE`, aggregate the rankings. Defaults to `FALSE`.
* `items` (character vector): For `input = "orderings"`, the full set of items.
* `labels` (vector): For `input = "orderings"`, optional labels for items.
* `verbose` (logical): If `TRUE`, print messages. Defaults to `TRUE`.
* `...`: Further arguments.

### Value
Returns a "rankings" object, potentially "aggregated_rankings" or "grouped_rankings".
```

--------------------------------

### Reproducibility Check for PlackettLuce Simulation

Source: https://hturner.github.io/PlackettLuce/reference/simulate.PlackettLuce.html

Compares simulations generated with the same seed to verify reproducibility. It shows that simulating a subset of rankings with a specific seed yields identical results to simulating those same rankings as part of a larger simulation with the same seed.

```R
s1 <- simulate(mod, 3, seed = 112)
s2 <- simulate(mod, 2, seed = 112)

identical(s1[1:2], s2[1:2])
```

--------------------------------

### Load Strict Incomplete Orderings (Cities Data)

Source: https://hturner.github.io/PlackettLuce/reference/preflib.html

Reads strict incomplete orderings from a .soi file. Use this for datasets where not all items are ranked in every observation.

```R
cities <- read.soi(system.file("extdata", "cities.soi",
                                package = "PlackettLuce"))
```

--------------------------------

### Convert Orderings to Rankings with Item Names

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Converts raw race orderings into a ranking format using driver names as item identifiers. This step is crucial for interpreting the model results.

```R
R <- as.rankings(nascar, input = "orderings", items = attr(nascar, "drivers"))
R[1:2]
```

--------------------------------

### Model Coefficients Output

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Shows the estimated worth parameters for each of the six pudding brands and a parameter for ties. These are reported on the original scale (not log scale).

```r
##         1         2         3         4         5         6      tie2 
## 0.1388005 0.1729985 0.1617420 0.1653930 0.1586805 0.2023855 0.7468147
```

--------------------------------

### Summarize PlackettLuce Model

Source: https://hturner.github.io/PlackettLuce/reference/summaries.html

Generates a summary of a fitted PlackettLuce model, including coefficients and potentially other model diagnostics. The 'ref' argument specifies the reference item.

```R
summary(object, ref = 1L, ...)
```

--------------------------------

### Convert Orderings to Rankings

Source: https://hturner.github.io/PlackettLuce/reference/nascar.html

Converts the 'nascar' dataset from race orderings to rankings and displays the first two races and drivers.

```R
R <- as.rankings(nascar, input = "orderings",
                 items = attr(nascar, "drivers"))
R[1:2, 1:4, as.rankings = FALSE]
```

--------------------------------

### Update CVXR::solve to CVXR::psolve

Source: https://hturner.github.io/PlackettLuce/news/index.html

Replaced the defunct CVXR::solve function with CVXR::psolve for improved functionality.

```R
Replace defunct CVXR::solve with CVXR::psolve
```

--------------------------------

### Data sets/importing data

Source: https://hturner.github.io/PlackettLuce/reference/index.html

Functions for accessing built-in datasets and reading data from Preflib election data files.

```APIDOC
## Data sets/importing data 

`beans` 
    Preferred Bean Varieties in Nicaragua 

`nascar` 
    Results from 2002 NASCAR Season 

`pudding` 
    Paired Comparisons of Chocolate Pudding 

`read.soc()` `read.soi()` `read.toc()` `read.toi()` `as.aggregated_rankings(_<preflib>_)`
    Read Preflib Election Data Files 

`salad` 
    Rankings of Salad Dressings
```

--------------------------------

### Check coded values in as.rankings

Source: https://hturner.github.io/PlackettLuce/news/index.html

Added a check in `as.rankings` (with `input = "orderings"`) to ensure coded values can be matched to item names if provided.

```R
`as.rankings` with `input = "orderings"` now checks coded values can be matched to item names, if provided.
```

--------------------------------

### read.soi

Source: https://hturner.github.io/PlackettLuce/reference/preflib.html

Reads strict orderings from an incomplete list PrefLib election data file (.soi).

```APIDOC
## read.soi

### Description
Reads strict orderings from an incomplete list PrefLib election data file (.soi).

### Usage
```R
read.soi(file)
```

### Arguments
* **file** (string) - An election data file, conventionally with extension `.soi`.

### Value
A data frame of class `"preflib"` with first column `Freq`, giving the frequency of the ranking in that row, and remaining columns `Rank 1`, ..., `Rank r` giving the items ranked from first to last place in that ranking. Ties are represented by vector elements in list columns. The data frame has an attribute `"items"` giving the labels corresponding to each item number.
```

--------------------------------

### Read Preference Data from Local File

Source: https://hturner.github.io/PlackettLuce/reference/preflib.html

Reads preference data from a local TOI file using the `read.toi` function. This is useful for loading datasets stored on your system.

```r
qualities <- read.toi(system.file("extdata", "education_qualities.toi",
                      package = "PlackettLuce"))
```

--------------------------------

### Fit Plackett-Luce Model with Default Settings (Shrinkage)

Source: https://hturner.github.io/PlackettLuce/reference/PlackettLuce.html

Fit a Plackett-Luce model using the default settings, which include shrinkage of log-worths towards zero. This is useful for regularization and handling sparse data.

```R
# Fit with default settings
mod <- PlackettLuce(R)
# log-worths are shrunk towards zero
coef(mod)
#>       apple      banana      orange        pear        tie2        tie3 
#>  0.00000000  0.25287379 -0.61350684 -0.08688475 -2.15068111 -0.79245358 
```

--------------------------------

### summary.PlackettLuce

Source: https://hturner.github.io/PlackettLuce/reference/summaries.html

Generates a summary of a PlackettLuce model, including coefficients and potentially other model statistics. It can pass additional arguments to the `vcov` function.

```APIDOC
## summary.PlackettLuce

### Description
Generates a summary of a PlackettLuce model.

### Usage
```R
summary(object, ref = 1L, ...)
```

### Arguments
* `object` (PlackettLuce): An object of class "PlackettLuce" as returned by `PlackettLuce`.
* `ref` (integer or character): Specifies the reference item. If `NULL`, the sum of log worth parameters is set to zero.
* `...`: Additional arguments, passed to `vcov`.
```

--------------------------------

### PlackettLuce with npseudo > 0 and no paired comparisons

Source: https://hturner.github.io/PlackettLuce/news/index.html

Enabled `PlackettLuce()` to work with `nspeudo > 0` even when no observed paired comparisons exist.

```R
`PlackettLuce()` now works with `nspeudo > 0` when there are no observed paired comparisons.
```

--------------------------------

### Calculate Sushi Timings

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Calculates the timings for the Sushi dataset using the `timings` function with 5 iterations for StatRank and excluding 'pmr'.

```R
sushi_timings <- timings(sushi, 5,
                         fun = c("pl", "hyper2", "plmix", "statrank"))
```

--------------------------------

### Convert Aggregated Rankings to Matrix

Source: https://hturner.github.io/PlackettLuce/reference/aggregate.html

Illustrates how to convert an aggregated_rankings object into a standard matrix format. This can be useful for compatibility with other functions or for inspection.

```R
# convert to a matrix
as.matrix(A)
```

--------------------------------

### Accessing Indirect Item Worth Estimates

Source: https://hturner.github.io/PlackettLuce/articles/PLADMM.html

Retrieve the estimates of item worths (tilde_pi) derived from the estimated coefficients (beta) from the last iteration of the ADMM algorithm. These provide an alternative estimation of item worths based on the model parameters.

```r
regressionPL$tilde_pi
```

--------------------------------

### Update Preflib functions for updated formats

Source: https://hturner.github.io/PlackettLuce/news/index.html

Updated `read.soc` and related functions to support the latest Preflib Election Data File formats.

```R
Update functions to read Preflib Election Data Files (`read.soc` etc) so that they work for updated Preflib file formats.
```

--------------------------------

### Fit PlackettLuce Model with Aggregated Rankings

Source: https://hturner.github.io/PlackettLuce/reference/aggregate.html

Shows how to use an aggregated_rankings object as input for fitting a PlackettLuce model. The frequencies from the aggregated object are automatically used as weights.

```R
# frequencies are automatically used as weights by PlackettLuce()
mod <- PlackettLuce(A)
mod$weights
```

--------------------------------

### Combine and display rankings

Source: https://hturner.github.io/PlackettLuce/reference/beans.html

Combines the order 3 rankings (from 'best', 'middle', 'worst') and order 2 rankings (from pairwise comparisons) into a single ranking object 'R'. Displays the head and tail of the combined rankings.

```R
R <- rbind(as.rankings(order3, input = "orderings"),
           as.rankings(order2, input = "orderings"))
head(R)
tail(R)
```

--------------------------------

### Compare Item Parameters for Previously Excluded Drivers

Source: https://hturner.github.io/PlackettLuce/articles/Overview.html

Compares the log-worth parameters for the last three drivers from the initial subset (drivers 81-83) between the model fitted without pseudo-rankings and the model fitted with default pseudo-rankings.

```R
coefs2[names(coefs)[81:83]]
```

--------------------------------

### Load Complete Orderings with Ties (Skaters Data)

Source: https://hturner.github.io/PlackettLuce/reference/preflib.html

Reads complete orderings that may include ties from a .toc file. Suitable for analyses where items can share ranks.

```R
skaters <- read.toc(system.file("extdata", "skaters.toc",
                                package = "PlackettLuce"))
```

--------------------------------

### Convert Orderings to Rankings

Source: https://hturner.github.io/PlackettLuce/index.html

Converts movie orderings from the Netflix dataset into a rankings object suitable for the PlackettLuce model. The 'items' attribute is preserved.

```r
R <- as.rankings(netflix[,-1], input = "orderings",
                 items = attr(netflix, "items"))
R[1:3, as.rankings = FALSE]
```

--------------------------------

### Convert Matrix to Rankings Object

Source: https://hturner.github.io/PlackettLuce/reference/rankings.html

Use as.rankings() to convert a matrix to a rankings object. Specify input as 'rankings' or 'orderings'. Optionally provide frequencies or an index for grouping.

```R
as.rankings(x, ..., verbose = TRUE)
```

--------------------------------

### Add salad data to remove prefmod dependency

Source: https://hturner.github.io/PlackettLuce/news/index.html

Included the salad data to eliminate the dependency on the prefmod package.

```R
Add salad data to remove prefmod dependency
```

--------------------------------

### Update Preflib URLs

Source: https://hturner.github.io/PlackettLuce/news/index.html

Ensured that URLs pointing to Preflib data sets are up-to-date.

```R
Update Preflib URLs.
```
Tokens:
Raw