Skip to contents

Preferences Objects

Source: R/preferences.R
preferences.Rd

A tidy interface for working with ordinal preferences.

Usage

long_preferences(
  data,
  col,
  id_cols = NULL,
  rank_col = NULL,
  item_col = NULL,
  item_names = NULL,
  verbose = TRUE,
  unused_fn = NULL,
  na_action = c("drop_rows", "drop_preferences"),
  ...
)

wide_preferences(
  data,
  col = NULL,
  ranking_cols = NULL,
  verbose = TRUE,
  na_action = c("keep_as_partial", "drop_preferences"),
  ...
)

as_preferences(strings, sep = ">", equality = "=", descending = TRUE)

preferences(
  strings = character(0L),
  sep = ">",
  equality = "=",
  descending = TRUE
)

# S3 method for class 'preferences'
format(x, ...)

# S3 method for class 'preferences'
levels(x, ...)

Arguments

data

A data.frame or tibble to extract preferences from

col

The name of the new column, as a string or symbol.

id_cols

<tidy-select> The columns by which to group the dataset to extract a single preference selection.

rank_col

<tidy-select> For data in long-format: the column representing the rank for the associated item.

item_col

<tidy-select> For data in long-format: the column representing the items by name or by index, in which case the item_names parameter should also be passed.

item_names

The names of the full set of items. This is necessary when the dataset specifies items by index rather than by name, or when there are items which do not appear in any preference selection.

verbose

If TRUE, diagnostic messages will be sent to stdout.

unused_fn

When format="long", summarise the values of unused columns (those which are not specified by id_cols, item_col, or rank_col). The default action is to drop all unused columns. This can be a named list (e.g. list(column = function)) if you want to apply different summaries for different columns or keep only specific unused columns, or it can be a single function to be applied across all unused columns.

na_action

Specifies how to handle NA values.

long_preferences
"drop_rows"

Removes individual rows containing NA values before processing

"drop_preferences"

Removes the entire preference selection that contains any NA

wide_preferences
"keep"

Interprets rows containing NAs as partial orderings

"drop"

Removes preferences with any NA ranks

...

Unused.

ranking_cols

<tidy-select> The columns from which to extract wide-format preferences.

strings

A character vector of preference strings

sep

Character separating the items in the string (default: ">")

equality

Character representing equality between items (default: "=")

descending

If TRUE, parse as descending order preferences.

x

A vector of preferences.

format

The format of the data: one of "ordering", "ranking", or "long" (see above). By default, data is assumed to be in "long" format.

Value

A preferences object, or a modified tibble with a column of preferences when data is a data.frame or tibble.

Examples

# Votes cast by two animals ranking a variety of fruits and vegetables.
# This is not real data, I made this up.
x <- tibble::tribble(
  ~voter_id, ~species, ~food, ~ranking,
  1, "Rabbit", "Apple", 1,
  1, "Rabbit", "Carrot", 2,
  1, "Rabbit", "Banana", 3,
  2, "Monkey", "Banana", 1,
  2, "Monkey", "Apple", 2,
  2, "Monkey", "Carrot", 3
)
# Process preferencial data into a single column.
x |>
  long_preferences(
    food_preference,
    id_cols = voter_id,
    item_col = food,
    rank_col = ranking
  )
#> # A tibble: 2 × 2
#>   voter_id           food_preference
#>      <dbl>                <prefrncs>
#> 1        1 [Apple > Carrot > Banana]
#> 2        2 [Banana > Apple > Carrot]
# The same, but keep the species data.
x |>
  long_preferences(
    food_preference,
    id_cols = voter_id,
    item_col = food,
    rank_col = ranking,
    unused_fn = list(species = dplyr::first)
  )
#> # A tibble: 2 × 3
#>   voter_id species           food_preference
#>      <dbl> <chr>                  <prefrncs>
#> 1        1 Rabbit  [Apple > Carrot > Banana]
#> 2        2 Monkey  [Banana > Apple > Carrot]