preflibinstance

class CategoricalInstance(file_path='')

Bases: PrefLibInstance

This is the class representing a PrefLib instance of categorical preferences. It basically contains the data and information written within a PrefLib file.

factorise_instance(reset_multiplicity=False): Factorises the instance, i.e., remove duplicated preferences and updates the multiplicity dictionary accordingly.

classmethod from_ordinal(instance, num_indif_classes=None, size_truncators=None, relative_size_truncators=None, category_name=None)

Converts an ordinal instance into a categorical one. The parameters size_truncators and relative_size_truncators determine where breaking points are.

Parameters:

instance (OrdinalInstance) – The ordinal instance.
num_indif_classes – List of number of indifference classes. Each category will contain the union of the alternatives present in the specified number of positions of the ranking. If not all ranked alternative fit in the provided categories, and additional one will be created. This parameter cannot be used together with size_truncators and/or relative_size_truncators.
size_truncators (list of int) – List of truncation points. Each category will contain at least the truncation point number of alternatives. In case of ties, all tied alternatives are in the same category. If not all ranked alternative fit in the provided categories, and additional one will be created. This parameter cannot be used together with num_indif_classes and/or relative_size_truncators.
relative_size_truncators (list of float) – List of truncation points expressed in relative terms with respect to the total number of alternatives ranked. The truncation points will thus differ for each order. All categories need to be described. In case the values do not add up to one, they are normalised. This parameter cannot be used together with num_indif_classes and/or size_truncators.
category_name (list of str) – List of category names.

parse(lines, autocorrect=False, header_only=False)

Parses the strings provided as argument, assuming that the latter describes categorical preferences.

Parameters:

lines (list) – A list of string, each string being one line of the instance to parse.
autocorrect (bool) – A boolean indicating whether we should try to automatically correct the potential errors in the file. Default is False.
header_only (bool) – A boolean indicating whether we should stop after having read the header. Default is False.

recompute_cardinality_param(): Recomputes the basic cardinality parameters based on the preferences list in the instance. Numbers that are recomputed are the number of voters and the number of unique preferences.

type_validator(data_type)

Returns a boolean indicating whether the data_type given as argument is a valid one for the python class.

Parameters:: data_type (str) – A strong representing a data type.
Returns:: True if the data type is valid for the class and False otherwise.
Return type:: bool

write(filepath)

Writes the instance into a file whose destination has been given as argument. If no file extension is: provided the data type of the instance is used.

Also sets self.file_name correctly (according to filepath), if self.file_name is empty.

Parameters:: filepath (str) – The destination where to write the instance.

class MatchingInstance(file_path='')

Bases: PrefLibInstance, WeightedDiGraph

This is the class representing a PrefLib instance for matching preferences. It basically contains the data and information written within a PrefLib file.

parse(lines, autocorrect=False, header_only=False)

Parses the strings, assuming that the latter describes a graph.

Parameters:

lines (list) – A list of string, each string being one line of the instance to parse.
autocorrect (bool) – A boolean indicating whether we should try to automatically correct the potential errors in the file. Default is False.
header_only (bool) – A boolean indicating whether we should stop after having read the header. Default is False.

parse_old(lines, autocorrect=False)

Parses the strings, assuming that the latter describes a graph.

Parameters:

lines (list) – A list of string, each string being one line of the instance to parse.
autocorrect (bool) – A boolean indicating whether we should try to automatically correct the potential errors in the file. Default is False.

type_validator(data_type)

Returns a boolean indicating whether the data_type given as argument is a valid one for the python class.

Parameters:: data_type (str) – A strong representing a data type.
Returns:: True if the data type is valid for the class and False otherwise.
Return type:: bool

write(filepath)

Writes the instance into a file whose destination has been given as argument, assuming the instance represents a graph. If no file extension is provided the data type of the instance is used.

Also sets self.file_name correctly (according to filepath), if self.file_name is empty.

Parameters:: filepath (str) – The destination where to write the instance.

class OrdinalInstance(file_path='')

Bases: PrefLibInstance

This is the class representing a PrefLib instance of ordinal preferences. It basically contains the data and information written within a PrefLib file.

Parameters:

file_path (str, optional) – The path to the file the instance is taken from. If a path is provided as a parameter, the file is immediately parsed and the instance populated accordingly.

Variables:

num_unique_orders – The number of unique orders in the instance.
multiplicity – A dictionary mapping each order to the number of voters who submitted that order.
orders – The list of all the distinct orders in the instance.
preferences – A pointer to the orders attribute so that it can be accessed both ways.

append_order(order)

Appends an order to the instance. That function incorporates the new order into the instance and updates the set of alternatives if needed.

Parameters:: order (Iterable) – An order.

append_order_array(orders)

Appends an array of orders to the instance. That function incorporates the new orders into the instance and updates the set of alternatives if needed.

Parameters:: orders (np.ndarray) – A 2D numpy array where each row represents a preference order.

append_order_list(orders)

Appends a list of orders to the instance. That function incorporates the new orders into the instance and updates the set of alternatives if needed.

Parameters:: orders (list) – A list of tuples of tuples, each tuple representing a preference order.

append_vote_map(vote_map)

Appends a vote map to the instance. That function incorporates the new orders into the instance and updates the set of alternatives if needed.

Parameters:: vote_map (dict of (tuple, int)) – A vote map representing preferences. A vote map is a dictionary whose keys represent orders (tuples of tuples of int) that are mapped to the number of voters with the given order as their preferences. We re-map the orders to tuple of tuples to be sure we are dealing with the correct type.

flatten_strict()

Strict orders are represented as orders with indifference classes of size 1. This is somewhat heavy when working with strict preferences. This function flattens strict preferences by removing the indifference class.

Returns:: A list of tuples of preference order and multiplicity.
Return type:: list[tuple[tuple[int], int]]

full_profile()

Returns a list containing all the orders appearing in the preferences, with each order appearing as many times as their multiplicity.

Returns:: A list of preferences (lists of alternatives).
Return type:: list

infer_type()

Loops through the orders of the instance to infer whether the preferences strict and/or complete,.

Returns:: The data type of the instance.
Return type:: str

parse(lines, autocorrect=False, header_only=False)

Parses the strings provided as argument, assuming that the latter describes an order.

Parameters:

lines (list) – A list of string, each string being one line of the instance to parse.
autocorrect (bool) – A boolean indicating whether we should try to automatically correct the potential errors in the file. Default is False.
header_only (bool) – A boolean indicating whether we should stop after having read the header. Default is False.

parse_old(lines, autocorrect=False)

Parses the strings provided as argument, assuming that the latter describes an order, in the old PrefLib format.

Parameters:

lines (list) – A list of string, each string being one line of the instance to parse.
autocorrect (bool) – A boolean indicating whether we should try to automatically correct the potential errors in the file. Default is False.

populate_IC(num_voters, num_alternatives)

Populates the instance with a random profile of strict preferences taken from the impartial culture distribution. Uses \(preflibtools.instances.sampling.urnModel\) for sampling.

Parameters:

num_voters (int) – Number of orders to sample.
num_alternatives (int) – Number of alternatives for the sampled orders.

populate_IC_anon(num_voters, num_alternatives)

Populates the instance with a random profile of strict preferences taken from the impartial anonymous culture distribution. Uses preflibtools.instances.sampling for sampling.

Parameters:

num_voters (int) – Number of orders to sample.
num_alternatives (int) – Number of alternatives for the sampled orders.

populate_mallows(num_voters, num_alternatives, mixture, dispersions, references)

Populates the instance with a random profile of strict preferences taken from a mixture of Mallows’ models. Uses preflibtools.instances.sampling for sampling.

Parameters:

num_voters (int) – Number of orders to sample.
num_alternatives (int) – Number of alternatives for the sampled orders.
mixture (list of positive numbers) – A list of the weights of each element of the mixture.
dispersions (list of float) – A list of the dispersion coefficient of each element of the mixture.
references (list of tuples of tuples of int) – A list of the reference orders for each element of the mixture.

populate_mallows_mix(num_voters, num_alternatives, num_references)

Populates the instance with a random profile of strict preferences taken from a mixture of Mallows’ models for which reference points and dispersion coefficients are independently and identically distributed. Uses preflibtools.instances.sampling for sampling.

Parameters:

num_voters (int) – Number of orders to sample.
num_alternatives (int) – Number of alternatives for the sampled orders.
num_references (int) – Number of element

populate_urn(num_voters, num_alternatives, replace)

Populates the instance with a random profile of strict preferences taken from the urn distribution. Uses preflibtools.instances.sampling for sampling.

Parameters:

num_voters (int) – Number of orders to sample.
num_alternatives (int) – Number of alternatives for the sampled orders.
replace (int) – The number of replacements for the urn model.

recompute_cardinality_param(): Recomputes the basic cardinality parameters based on the order list in the instance. Numbers that are recomputed are the number of voters and the number of unique orders.

type_validator(data_type)

Returns a boolean indicating whether the data_type given as argument is a valid one for the python class.

Parameters:: data_type (str) – A strong representing a data type.
Returns:: True if the data type is valid for the class and False otherwise.
Return type:: bool

vote_map()

Returns the instance described as a vote map, i.e., a dictionary whose keys are orders, mapping to the number of voters with the given order as their preferences. This format can be useful for some applications. It also ensures interoperability with the old preflibtools (vote maps were the main object).

Returns:: A vote map representing the preferences in the instance.
Return type:: dict of (tuples, int)

write(filepath)

Writes the instance into a file whose destination has been given as argument. If no file extension is provided the data type of the instance is used.

Also sets self.file_name correctly (according to filepath), if self.file_name is empty.

Parameters:: filepath (str) – The destination where to write the instance.

class PrefLibInstance

Bases: object

This class provide a general template to implement specific classes representing PrefLib instances. It should mainly be used as an abstract class.

Variables:

file_path – The path to the file the instance is taken from.
file_name – The name of the file the instance is taken from.
data_type – The data type of the instance. Whenever a function only applies to certain types of data (strict and complete orders for instance), we do so by checking this value.
modification_type – The modification type of the file: original if it represents original data; induced or imbued it is derived from some other data; synthetic if it is synthetically generated.
relates_to – The data file this instance relates to, typically the original data file for induced preferences.
related_files – The data files that are to the instance.
title – The title of the instance.
description – A description of the instance.
publication_date – Date at which the corresponding file has been added to PrefLib.com.
modification_date – Last date the file has been modified on PrefLib.com.
num_alternatives – The number of alternatives in the instance.
alternatives_name – A dictionary mapping alternative (int) to their name (str).
num_voters – The number of voters in the instance.

parse(lines, autocorrect=False, header_only=False)

parse_file(filepath, autocorrect=False, header_only=False)

Parses the file whose path is provided as argument and populates the PreflibInstance object accordingly. The parser to be used is deduced from the file extension.

Parameters:

filepath (str) – The path to the file to be parsed.
autocorrect (bool) – A boolean indicating whether we should try to automatically correct the potential errors in the file. Default is False.
header_only (bool) – A boolean indicating whether we should stop after having read the header. Default is False.

parse_lines(lines, autocorrect=False, header_only=False)

Parses the lines provided as argument. The parser to be used is deducted from the instance’s inner value of data_type.

Parameters:

lines (list) – A list of string, each string being one line of the instance to parse.
autocorrect (bool) – A boolean indicating whether we should try to automatically correct the potential errors in the file. Default is False.
header_only (bool) – A boolean indicating whether we should stop after having read the header. Default is False.

parse_metadata(line, autocorrect=False)

A helper function that parses metadata.

Parameters:

line (str) – The line to parse.
autocorrect (bool) – A boolean indicating whether we should try to automatically correct the potential errors in the file. Default is False.

parse_str(string, data_type, file_name='', autocorrect=False, header_only=False)

Parses the string provided as argument and populates the PreflibInstance object accordingly. The parser to be used is deduced from the file extension passed as argument.

Parameters:

string (str) – The string to parse.
data_type (str) – The data type represented by the string.
file_name (str) – The value to store in the file_name member of the instance. Default is the empty string.
autocorrect (bool) – A boolean indicating whether we should try to automatically correct the potential errors in the file. Default is False.
header_only (bool) – A boolean indicating whether we should stop after having read the header. Default is False.

parse_url(url, autocorrect=False, header_only=False)

Parses the file located at the provided URL and populates the PreflibInstance object accordingly. The parser to be used (whether the file describes a graph or an order for instance) is deduced based on the file extension.

Parameters:

url (str) – The target URL.
autocorrect (bool) – A boolean indicating whether we should try to automatically correct the potential errors in the file. Default is False.
header_only (bool) – A boolean indicating whether we should stop after having read the header. Default is False.

set_file_name(filepath)

Set self.filename according to a given filepath.

Parameters:: filepath (str) – The filepath to a (preflib) file.

type_validator(data_type)

Returns a boolean indicating whether the data_type given as argument is a valid one for the python class.

Parameters:: data_type (str) – A strong representing a data type.
Returns:: True if the data type is valid for the class and False otherwise.
Return type:: bool

write(filepath)

write_metadata(file)

A helper function that writes the metadata in the file.

Parameters:: file – The file to write into as a file object.

get_parsed_instance(file_path, autocorrect=False, header_only=False)

Infers from the extension of the file given as input the correct instance to use. Parses the file and return the instance.

Parameters:

file_path (str) – The path to the file to be parsed.
autocorrect (bool) – A boolean indicating whether we should try to automatically correct the potential errors in the file. Default is False.
header_only (bool) – A boolean indicating whether we should stop after having read the header. Default is False.

Returns:

The instance with the file already parsed.

Return type:

preflibtools.instances.preflibinstance.PrefLibInstance