write_preflib {prefio}

Write Ordinal Preference Data to PrefLib Formats

Description

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⁠.

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.

Value

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