preflibtools.instances package

This package provides all kinds of ways to deal with PrefLib instances.

preflibtools.instances.preflibinstance

This module describes the main class to deal with PrefLib instances..

class preflibtools.instances.preflibinstance.Graph

Bases: object

This class is used to represent (weighted) graphs.

Variables

  • dict – The dictionary representing the graph mapping each node to its neighbourhood (set of nodes to which it is connected). A node can be of any hashable type.

  • weight – The dictionary mapping every node to its weight.

add_edge(node1, node2, weight)

Adds an edge to the graph. If the nodes do not exist in the graph, those are also added.

Parameters

  • node1 – The departure node of the edge.

  • node2 – The arrival node of the edge.

  • weight – The weight of the edge.

add_node(node)

Adds a node to the graph if the node does not already exist.

Parameters

node – The node to add.

edges()

Returns the set of all the edges of the graph.

Returns

A set of tuples (node, neighbour, weight) representing (weighted) edges.

Return type

set of tuples

neighbours(node)

Returns all the neighbours of a given node.

Parameters

node – The node whose neighbours we want to know.

Returns

The set of the neighbours of the node.

Return type

set

nodes()

Returns the set of all the nodes of the graph.

Returns

The set of all the nodes of the graph.

Return type

set

outgoing_edges(node)

Returns all the edges leaving a given node.

Parameters

node – The node whose edges we want to get.

Returns

The set of the tuples (node, neighbour, edgeWeight) representing (weighted) edges.

Return type

set of tuples

class preflibtools.instances.preflibinstance.PreflibInstance(filepath='')

Bases: object

This is the class representing a PrefLib instance. It basically contains the data and information

written within a PrefLib file.

Parameters

filepath (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

  • filepath – The path to the file the instance is taken from.

  • fileName – 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.

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

  • sum_vote_count – The sum of the weights of the voters. In most cases, it is equal to the nbVoters, but not if we have induced a relation like generating a pairwise graph from a set of linear orders for instance.

  • num_unique_order – The number of unique orders in the instance.

  • order_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.

  • graph – An instance of the preflibtools.instances.graph for when the instance represents a graph.

append_order_list(orders)

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

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()

Because strict orders are represented as orders with indifference classes of size 1, this function flattens them.

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_orders()

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

Returns

The data type of the instance.

Return type

str

parse(filepath)

Parses the file whose path is provided as argument 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

filepath (str) – The path to the file to be parsed.

parse_graph(filepath, is_WMD=False)

Parses the file whose path is provided as argument, assuming that the latter describes a graph.

Parameters

  • filepath (str) – The path to the file to be parsed.

  • is_WMD (bool) – True if the graph to parse represents weighted matching data, default is False.

parse_order(filepath)

Parses the file whose path is provided as argument, assuming that the latter describes an order.

Parameters

filepath (str) – The path to the file to be parsed.

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.

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 to the file whose path is provided as argument. If the file path does not contain a file extension, is provided the data type of the instance is used. The function to call (whether the instance describes a graph or an order for instance) is deduced based on the data type of the instance.

Parameters

filepath (str) – The path where to write the file.

write_graph(filepath, is_WMD=False)

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.

Parameters

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

  • is_WMD (bool) – True if the graph to parse represents weighted matching data, default is False.

write_order(filepath)

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

Parameters

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

preflibtools.instances.sampling

This module describes procedures to sample preferences for different probability distributions.

preflibtools.instances.sampling.generate_IC(num_voters, alternatives)

Generates a profile of strict preferences following the impartial culture.

Parameters

  • num_voters (int) – Number of orders to sample.

  • alternatives (list of int) – List of alternatives.

Returns

A vote map, i.e., a dictionary whose keys are orders, mapping to the number of voters with the given order as their preferences.

Return type

dict

preflibtools.instances.sampling.generate_IC_anon(num_voters, alternatives)

Generates a profile of strict preferences following the anonymous impartial culture.

Parameters

  • num_voters (int) – Number of orders to sample.

  • alternatives (list of int) – List of alternatives.

Returns

A vote map, i.e., a dictionary whose keys are orders, mapping to the number of voters with the given order as their preferences.

Return type

dict

preflibtools.instances.sampling.generate_IC_ballot(alternatives)

Generates a strict order over the set of alternatives following the impartial culture.

Parameters

alternatives (list of int) – List of alternatives.

Returns

A strict order over the alternatives, i.e., a tuple of tuples of size 1.

Return type

tuple

preflibtools.instances.sampling.generate_mallows(num_voters, num_alternatives, mixture, dispersions, references)

Generates a profile following a mixture of Mallow’s models.

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.

Returns

A vote map, i.e., a dictionary whose keys are orders, mapping to the number of voters with the given order as their preferences.

Return type

dict

preflibtools.instances.sampling.generate_mallows_mix(num_voters, alternatives, num_references)

Generates a profile following a mixture of Mallow’s models for which reference points and dispersion coefficients are independently and identically distributed.

Parameters

  • num_voters (int) – Number of orders to sample.

  • alternatives (list of int) – List of alternatives for the sampled orders.

  • num_references (int) – Number of element

Returns

A vote map, i.e., a dictionary whose keys are orders, mapping to the number of voters with the given order as their preferences.

Return type

dict

preflibtools.instances.sampling.generate_urn(num_voters, alternatives, replace)

Generates a profile following the urn model.

Parameters

  • num_voters (int) – Number of orders to sample.

  • alternatives (list of int) – List of alternatives.

  • replace (int) – The number of replacements for the urn model.

Returns

A vote map, i.e., a dictionary whose keys are orders, mapping to the number of voters with the given order as their preferences.

Return type

dict

preflibtools.instances.drawing

This module describes procedures to draw images out of PrefLib instances.

preflibtools.instances.drawing.draw_graph(instance, img_file_path, max_num_node=100, is_WMD=False)

Generates the image file for an instance representing a graph.

Parameters

  • instance (preflibtools.instances.preflibinstance.PreflibInstance) – The instance to draw.

  • img_file_path (str or path) – Path to which save the image.

  • max_num_node (int) – The maximum number of nodes of the graph to draw, default is 100.

  • is_WMD (bool) – True if the graph to parse represents weighted matching data, default is False.

preflibtools.instances.drawing.draw_instance(instance, img_file_path)

Generate an image file of the instance.

Parameters
preflibtools.instances.drawing.draw_order(instance, img_file_path)

Generates the image file for an instance representing orders.

Parameters