Saving Election Data

The pref_voting.io module provides functionality for saving and loading election data in different formats.

A Profile or ProfileWithTies can be saved in any of the following formats:

  • preflib: The format used by preflib described here: https://www.preflib.org/format#types.

  • csv: There are two formats for the csv file: “rank_columns” and “candidate_columns”. The “rank_columns” format is used when the csv file contains a column for each rank and the rows are the candidates at that rank (or “skipped” if the ranked is skipped). The “candidate_columns” format is used when the csv file contains a column for each candidate and the rows are the rank of the candidates (or the empty string if the candidate is not ranked).

  • abif: This format is explained here: https://electowiki.org/wiki/ABIF

  • json: Save the election data in a json file, where each ranking is a dictionary with the candidate names as keys and the ranks as values.

The pref_voting.io module also provides functionality for reading election data from these formats.

All of these functions are accessible through write and read methods in the Profile and ProfileWithTies classes.

A SpatialProfile can be saved as a json file.

Saving Election Data

pref_voting.io.writers.to_preflib_instance(profile)[source]

Returns an instance of the OrdinalInstance class from the preflibtools package (see https://preflib.github.io/preflibtools/usage.html#ordinal-preferences).

Parameters:

profile – A Profile or ProfileWithTies object.

Returns:

An instance of the OrdinalInstance class from preflibtools.

pref_voting.io.writers.write_preflib(profile, filename)[source]

Write a profile to a file in the PrefLib format.

Parameters:

  • profile – A Profile or ProfileWithTies object.

  • filename – The name of the file to write the profile to.

Returns:

The name of the file the profile was written to.

pref_voting.io.writers.write_csv(profile, filename, csv_format='candidate_columns')[source]

Write a profile to a file in CSV format.

Parameters:

  • profile – A Profile or ProfileWithTies object.

  • filename – The name of the file to write the profile to.

  • csv_format – The format to write the profile in. Defaults to “candidate_columns”. The other option is “rank_columns”.

pref_voting.io.writers.write_json(profile, filename)[source]

Write a profile to a file in JSON format.

Parameters:

  • profile – A Profile or ProfileWithTies object.

  • filename – The name of the file to write the profile to.

Returns:

The name of the file the profile was written to.

pref_voting.io.writers.write_abif(profile, filename)[source]

Write a profile to a file in ABIF format.

The ABIF format is explained here: https://electowiki.org/wiki/ABIF.

Parameters:

  • profile – A Profile or ProfileWithTies object.

  • filename – The name of the file to write the profile to.

Returns:

The name of the file the profile was written to.

pref_voting.io.writers.write(edata, filename, file_format='preflib', csv_format='candidate_columns')[source]

Write election data to filename in the format specified in file_format.

Parameters:

  • edata – Election data to write.

  • filename – The name of the file to write the election data to.

  • file_format – The format to write the election data in. Defaults to “preflib”. The other options are “csv”, “json”, and “abif”.

  • csv_format – The format to write the election data in if the file format is “csv”. Defaults to ‘candidate_columns’. The other option is rank_columns.

Returns:

The name of the file the election data was written to.

Note

There are two formats for the csv file: “rank_columns” and “candidate_columns”. The “rank_columns” format is used when the csv file contains a column for each rank and the rows are the candidates at that rank (or “skipped” if the ranked is skipped). The “candidate_columns” format is used when the csv file contains a column for each candidate and the rows are the rank of the candidates (or the empty string if the candidate is not ranked).

Loading Election Data

pref_voting.io.readers.preflib_to_profile(instance_or_preflib_file, include_cmap=False, use_cand_names=False, as_linear_profile=False)[source]

Read a profile from an OrdinalInstance or a .soc, .soi, .toc, or .toi file used by PrefLib (https://www.preflib.org/format#types).

This function uses the OrdinalInstance class from the preflibtools package to read the profile from the file (see https://preflib.github.io/preflibtools/usage.html#ordinal-preferences).

Parameters:

  • preflib_file (str) – the path to the file

  • include_cmap (bool) – if True, then include the candidate map. Defaults to False.

  • use_cand_names (bool) – if True, then use the candidate map as the candidate names. Defaults to False.

  • as_linear_profile (bool) – if True, then return a Profile object. Defaults to False. If False, then return a ProfileWithTies object.

Returns:

the profile read from the file

Return type:

Profile or ProfileWithTies

pref_voting.io.readers.csv_to_profile(filename, csv_format='candidate_columns', as_linear_profile=False, items_to_skip=None, cand_type=None)[source]

Read a profile from a csv file.

Parameters:

  • filename (str) – the path to the file

  • csv_format (str) – the format of the csv file. Defaults to “candidate_columns”. The other option is “rank_columns”.

  • as_linear_profile (bool) – if True, then return a Profile object. Defaults to False. If False, then return a ProfileWithTies object.

  • items_to_skip (list[str]) – a list of items to skip. Defaults to None. Items in this list are not included in the profile. Only relevant for “rank_columns” csv format.

Returns:

the profile read from the file

Return type:

Profile or ProfileWithTies

Note

There are two formats for the csv file: “rank_columns” and “candidate_columns”. The “rank_columns” format is used when the csv file contains a column for each rank and the rows are the candidates at that rank (or “skipped” if the ranked is skipped). The “candidate_columns” format is used when the csv file contains a column for each candidate and the rows are the rank of the candidates (or the empty string if the candidate is not ranked).

pref_voting.io.readers.json_to_profile(filename, cand_type=None, as_linear_profile=False)[source]

Read a profile from a json file.

Parameters:

  • filename (str) – the path to the file

  • cand_type (type) – the type of the candidates. Defaults to None. If not None, then the candidates are converted to this type.

  • as_linear_profile (bool) – if True, then return a Profile object. Defaults to False. If False, then return a ProfileWithTies object.

Returns:

the profile read from the file

Return type:

Profile or ProfileWithTies

pref_voting.io.readers.abif_to_profile(filename)[source]

Open filename in the abif format and return a Profile object.

Parameters:

filename – The name of the file to read the profile from.

Returns:

A Profile object.

pref_voting.io.readers.abif_to_profile_with_ties(filename, cand_type=None)[source]

Open filename in the abif format and return a ProfileWithTies object.

Parameters:

filename – The name of the file to read the profile from.

Returns:

A ProfileWithTies object.

pref_voting.io.readers.read(filename, file_format, as_linear_profile=False, cand_type=None, csv_format='candidate_columns', items_to_skip=None)[source]

Read election data from filename in the format file_format.

Parameters:

  • filename (str) – the path to the file

  • file_format (str) – the format of the file. The options are “preflib”, “json”, “csv”, and “abif”.

  • as_linear_profile (bool) – if True, then return a Profile object. Defaults to False. If False, then return a ProfileWithTies object.

  • cand_type (type) – the type of the candidates. Defaults to None. If not None, then the candidates are converted to this type.

  • csv_format (str) – the format of the csv file. Defaults to “candidate_columns”. The other option is “rank_columns”.

  • items_to_skip (list[str]) – a list of items to skip. Defaults to None. Items in this list are not included in the profile. Only relevant for “rank_columns” csv format.

Returns:

the profile read from the file

Return type:

Profile or ProfileWithTies

Saving Spatial Profile Data

pref_voting.io.writers.write_spatial_profile_to_json(spatial_profile, filename)[source]

Write a spatial profile to a file in JSON format.

Parameters:

spatial_profile – A SpatialProfile object.

Returns:

The name of the file the spatial profile was written to.

Loading Spatial Profile Data

pref_voting.io.readers.json_to_spatial_profile(filename)[source]

Load a spatial profile from a JSON file.

Parameters:

filename (str) – the path to the file

Returns:

the spatial profile read from the file

Return type:

SpatialProfile