rankings: Rankings Object

In PlackettLuce: Plackett-Luce Models for Rankings

Rankings Object

Description

Create a "rankings" object from data or convert a matrix of rankings or ordered items to a "rankings" object.

Usage

rankings(data, id, item, rank, aggregate = FALSE, verbose = TRUE, ...)

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

## Default S3 method:
as.rankings(
  x,
  input = c("rankings", "orderings"),
  freq = NULL,
  index = NULL,
  aggregate = FALSE,
  items = NULL,
  labels = NULL,
  ...,
  verbose = TRUE
)

## S3 method for class 'grouped_rankings'
as.rankings(x, ..., verbose = TRUE)

## S3 method for class 'matrix'
as.rankings(
  x,
  input = c("rankings", "orderings"),
  freq = NULL,
  index = NULL,
  aggregate = FALSE,
  items = NULL,
  labels = NULL,
  ...,
  verbose = TRUE
)

## S3 method for class 'rankings'
x[i, j, ..., drop = TRUE, as.rankings = TRUE]

## S3 method for class 'rankings'
format(x, width = 40L, ...)

Arguments

data	a data frame with columns specified by id, item and rank.
id	an index of data specifying the column containing ranking IDs.
item	an index of data specifying the column containing item IDs,
rank	an index of data specifying the column containing item ranks.
aggregate	if TRUE, aggregate the rankings via aggregate() before returning.
verbose	logical; if TRUE print messages when changes are made to rankings data.
...	further arguments passed to/from methods.
x	for as.rankings, a matrix with one column per item and one row per ranking, or an object that can be coerced to such as matrix; for [ and format, a "rankings" object.
input	for as.rankings, whether rows in the input matrix contain numeric "rankings" (dense, standard/modified competition or fractional rankings) or "orderings", i.e. the items ordered by rank.
freq	an optional column index (number, character or logical) specifying a column of x that holds ranking frequencies, or a vector of ranking frequencies. If provided, an "aggregated_rankings" object will be returned.
index	an optional column index (number, character or logical) specifying a column of x that holds a grouping index, or a numeric vector to for grouping. If provided, the rankings will be grouped by group() before returning.
items	for input = "orderings", a character vector specifying the full set of items. Values in x are matched to this by value (if character) or position (if numeric). Use decode() for orderings requiring more complex decoding.
labels	for input = "orderings" an optional vector of labels for the items, corresponding to the sorted unique values of x.
i	indices specifying rankings to extract, as for [.
j	indices specifying items to extract, as for [.
drop	if TRUE return single row/column matrices as a vector.
as.rankings	if TRUE return a rankings object, otherwise return a matrix/vector.
width	the width in number of characters to format each ranking - rankings that are too wide will be truncated.

Details

Each ranking in the input data will be converted to a dense ranking, which rank items from 1 (first place) to n_r (last place). Items not ranked should have a rank of 0 or NA. Tied items are given the same rank with no rank skipped. For example {1, 0, 2, 1}, ranks the first and fourth items in first place and the third item in second place; the second item is unranked.

Records in data with missing id or item are dropped. Duplicated items in the rankings are resolved if possible: redundant or inconsistent ranks are set to NA. Rankings with only 1 item are set to NA (rankings with zero items are automatically treated as NA). Any issues causing records to be removed or recoded produce a message if verbose = TRUE.

For as.rankings with input = "orderings", unused ranks may be filled with zeroes for numeric x or NA. It is only necessary to have as many columns as ranks that are used.

The method for [ will return a reduced rankings object by default, recoding as dense rankings and setting invalid rankings to NA as necessary. To extract rows and/or columns of the rankings as a matrix or vector, set as.rankings = FALSE, see examples.

Value

By default, a "rankings" object, which is a matrix of dense rankings with methods for several generics including aggregate, [, format, rbind() and as.matrix().

If the object is created with aggregate = TRUE, or ranking frequencies are specified via freq, the rankings are post-processed to create an "aggregated_rankings" object.

If a group index is specified via index, the (possibly aggregated) rankings are post-processed to create a "grouped_rankings" object.

Examples

# create rankings from data in long form

# example long form data
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))

# ranking 1 has different rank for same item, but order of items unambiguous
# all ranks are missing in ranking 2
# some ranks are missing in ranking 3
# ranking 4 has inconsistent ranks for two items and a rank with missing item
# ranking 5 is fine - an example of a tie
split(x, x$ranking)

# fix issues when creating rankings object
rankings(x, id = "ranking", item = "letter", rank = "rank")

# convert existing matrix of rankings

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)

# first three rankings
R[1:3,]

# exclude pear from the rankings
R[, -4]

# extract rankings 2 and 3 as numeric matrix
R[2:3, , as.rankings = FALSE]

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

# extract rankings for item 1 as a vector
R[,1, as.rankings = FALSE]

PlackettLuce documentation built on Sept. 9, 2025, 5:22 p.m.