Preference Libraries

parse_pabulib(file_path: str) → tuple[Instance, Profile]

Parses a PaBuLib files and returns the corresponding instance and profile. The returned profile will be of the correct type depending on the metadata in the file.

Parameters:

file_path (str) – Path to the PaBuLib file to be parsed.

Returns:

The instance and the profile corresponding to the file.

Return type:

tuple[Instance, Profile]

write_pabulib(instance: Instance, profile: AbstractProfile, file_path: str) → None

Writes an instance and a profile to a file using the pabulib format (as specified in https://arxiv.org/pdf/2305.11035.pdf).

Parameters:

• instance (Instance) – The instance.

• profile (Profile) – The profile.

• file_path (str) – The path to the output file. Defaults to None.

election_as_pabulib_string(instance: Instance, profile: AbstractProfile) → str

Creates a string representing the instance and the profile according to the Pabulib standard (as specified in https://arxiv.org/pdf/2305.11035.pdf).

Parameters:

• instance (Instance) – The instance.

• profile (Profile) – The profile.

Returns:

The instance and profile represented as a Pabulib string

Return type:

str

init_preflib_instance(preflib_inst: PrefLibInstance, instance: Instance, file_path: str, file_name: str, modification_type: str, relates_to: str, related_files: str, title: str, description: str, publication_date: str, modification_date: str, alternative_names: dict[Project, str]) → None

Initialises a PrefLib instance with all the necessary parameters.

Parameters:

• preflib_inst (preflibtools.instances.PrefLibInstance) – The PrefLib instance to initialise.

• instance (Instance) – The Pabutools instance used to define the PrefLib one.

• file_path (str) – The path to the file containing the details of the instance.

• file_name (str) – The name to the file containing the details of the instance.

• modification_type (str) – The modification type as described by the PrefLib documentation.

• relates_to (str) – The files that the PrefLib instance relates to.

• related_files (str) – The related files to the PrefLib instance.

• title (str) – The title of the PrefLib instance.

• description (str) – The description of the PrefLib instance.

• publication_date (str) – The publication date of the PrefLib instance.

• modification_date (str) – The last modification date of the PrefLib instance.

• alternative_names (dict[Project, str]) – A mapping of projects to names of the corresponding alternatives.

approval_to_preflib(instance: Instance, profile: AbstractApprovalProfile, file_path: str = '', file_name: str = '', modification_type: str = 'original', relates_to: str = '', related_files: str = '', title: str = '', description: str = '', publication_date: str = '', modification_date: str = '', alternative_names: dict[Project, str] | None = None) → CategoricalInstance

Converts a participatory budgeting instance and profile of approval ballots into a PrefLib instance.

Parameters:

• instance (Instance) – The Pabutools instance used to define the PrefLib one.

• profile (py:class:~pabutools.election.profile.approvalprofile.AbstractApprovalProfile) – The Pabutools profile of approval ballots.

• file_path (str) – The path to the file containing the details of the instance.

• file_name (str) – The name to the file containing the details of the instance.

• modification_type (str) – The modification type as described by the PrefLib documentation.

• relates_to (str) – The files that the PrefLib instance relates to.

• related_files (str) – The related files to the PrefLib instance.

• title (str) – The title of the PrefLib instance.

• description (str) – The description of the PrefLib instance.

• publication_date (str) – The publication date of the PrefLib instance.

• modification_date (str) – The last modification date of the PrefLib instance.

• alternative_names (dict[Project, str]) – A mapping of projects to names of the corresponding alternatives.

cardinal_to_preflib(instance: Instance, profile: AbstractCardinalProfile, file_path: str = '', file_name: str = '', modification_type: str = 'original', relates_to: str | None = None, related_files: str | None = None, title: str = '', description: str = '', publication_date: str = '', modification_date: str = '', alternative_names: dict[Project, str] | None = None) → OrdinalInstance

Converts a participatory budgeting instance and profile of cardinal ballots into a PrefLib instance.

Parameters:

• instance (Instance) – The Pabutools instance used to define the PrefLib one.

• profile (py:class:~pabutools.election.profile.cardinalprofile.AbstractCardinalProfile) – The Pabutools profile of approval ballots.

• file_path (str) – The path to the file containing the details of the instance.

• file_name (str) – The name to the file containing the details of the instance.

• modification_type (str) – The modification type as described by the PrefLib documentation.

• relates_to (str) – The files that the PrefLib instance relates to.

• related_files (str) – The related files to the PrefLib instance.

• title (str) – The title of the PrefLib instance.

• description (str) – The description of the PrefLib instance.

• publication_date (str) – The publication date of the PrefLib instance.

• modification_date (str) – The last modification date of the PrefLib instance.

• alternative_names (dict[Project, str]) – A mapping of projects to names of the corresponding alternatives.

ordinal_to_preflib(instance: Instance, profile: AbstractOrdinalProfile, file_path: str = '', file_name: str = '', modification_type: str = 'original', relates_to: str | None = None, related_files: str | None = None, title: str = '', description: str = '', publication_date: str = '', modification_date: str = '', alternative_names: dict[Project, str] | None = None) → OrdinalInstance

Converts a participatory budgeting instance and profile of ordinal ballots into a PrefLib instance.

Parameters:

• instance (Instance) – The Pabutools instance used to define the PrefLib one.

• profile (py:class:~pabutools.election.profile.ordinalprofile.AbstractOrdinalProfile) – The Pabutools profile of approval ballots.

• file_path (str) – The path to the file containing the details of the instance.

• file_name (str) – The name to the file containing the details of the instance.

• modification_type (str) – The modification type as described by the PrefLib documentation.

• relates_to (str) – The files that the PrefLib instance relates to.

• related_files (str) – The related files to the PrefLib instance.

• title (str) – The title of the PrefLib instance.

• description (str) – The description of the PrefLib instance.

• publication_date (str) – The publication date of the PrefLib instance.

• modification_date (str) – The last modification date of the PrefLib instance.

• alternative_names (dict[Project, str]) – A mapping of projects to names of the corresponding alternatives.