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)
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.
- 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)
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.
- 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
- 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)
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.
- 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)
- parse_file(filepath, autocorrect=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.
- parse_lines(lines, autocorrect=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.
- 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)
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.
- parse_url(url, autocorrect=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.
- 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)
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.
- Returns
The instance with the file already parsed.
- Return type