Write Ordinal Preference Data to PrefLib Formats

Write preferences to .soc, .soi, .toc or .toi file types, as defined by the PrefLib specification: {PrefLib}: A Library for Preferences.

Usage

write_preflib(
  x,
  file = "",
  title = NULL,
  publication_date = NULL,
  modification_type = NULL,
  modification_date = NULL,
  description = NULL,
  relates_to = NULL,
  related_files = NULL
)

Arguments

x: An aggregated_preferences object to write to file. If x is of a different class, it attempts to coerce x into an aggregated_preferences object via as.aggregated_preferences().
file: Either a character string naming the a file or a writeable, open connection. The empty string "" will write to stdout.
title: The title of the data file, for instance the name of the election represented in the data file. If not provided, we check for the presence of attr(x, "preflib"), and if it exists we check for TITLE.
publication_date: The date at which the data file was published for the first time. If not provided, we check for the presence of attr(x, "preflib"), and if it exists we check for PUBLICATION DATE.
modification_type: The modification type of the data: one of original, induced, imbued or synthetic (see Details). If not provided, we check for the presence of attr(x, "preflib"), and if it exists we check for MODIFICATION TYPE.
modification_date: The last time the data was modified. If not provided, we check for the presence of attr(x, "preflib"), and if it exists we check for MODIFICATION DATE.
description: A description of the data file, providing additional information about it. If not provided, we check for the presence of attr(x, "preflib"), and if it exists we check for DESCRIPTION.
relates_to: The name of the data file that the current file relates to, typically the source file in case the current file has been derived from another one. If not provided, we check for the presence of attr(x, "preflib"), and if it exists we check for RELATES TO.
related_files: The list of all the data files related to this one, comma separated. If not provided, we check for the presence of attr(x, "preflib"), and if it exists we check for RELATED FILES.

Value

No return value. Output will be written to file or stdout.

Details

The file types supported are

.soc: Strict Orders - Complete List
.soi: Strict Orders - Incomplete List
.toc: Orders with Ties - Complete List
.toi: Orders with Ties - Incomplete List

The PrefLib format specification requires some additional metadata. Note that the additional metadata required for the PrefLib specification is not necessarily required for the write_preflib method; any missing fields required by the PrefLib format will simply show "NA".

TITLE (required)

The title of the data file, for instance the year of the election represented in the data file.

DESCRIPTION (optional)

A description of the data file, providing additional information about it.

RELATES TO (optional)

The name of the data file that the current file relates to, typically the source file in case the current file has been derived from another one.

RELATED FILES (optional)

The list of all the data files related to this one, comma separated.

PUBLICATION DATE (required)

The date at which the data file was published for the first time.

MODIFICATION TYPE (required)

The modification type of the data. One of:

original: Data that has only been converted into a PrefLib format.
induced: Data that has been induced from another context. For example, computing a pairwise relation from a set of strict total orders. No assumptions have been made to create these files, just a change in the expression language.
imbued: Data that has been imbued with extra information. For example, extending an incomplete partial order by placing all unranked candidates tied at the end.
synthetic: Data that has been generated artificially.

MODIFICATION DATE (optional)

The last time the data was modified.

In addition to these fields, some required PrefLib fields will be generated automatically depending on arguments to write_preflib() and the attributes of the aggregated_preferences object being written to file:

FILE NAME: The name of the output file.
DATA TYPE: The data type (one of soc, soi, toc or toi).
NUMBER ALTERNATIVES: The number of items.
ALTERNATIVE NAME X: The name of each item, where X ranges from 0 to length(items).
NUMBER VOTERS: The total number of orderings.
NUMBER UNIQUE ORDERS: The number of distinct orderings.

Note that PrefLib refers to the items as "alternatives". The "alternatives" in the output file will be the same as the "items" in the aggregated_preferences object.