Election

class Election(experiment_id=None, election_id=None, culture_id=None, votes=None, instance_type: str = None, num_voters: int = None, num_candidates: int = None, label=None, fast_import=False, is_shifted=False, is_imported=False, is_exported=True, params=None, **kwargs)

(Abstract) Election class.

all_dist_zeros(object_type)

Return True when the distance matrix for object_type is missing or all zeros.

compute_alternative_winners(method=None, party_id=None, committee_size=None)

Compute winners for the election after removing a party block of candidates.

The method removes the specified party (party_id, party_size=committee_size), computes winners using the requested rule and stores the remapped winners in self.alternative_winners keyed by party_id.

abstract compute_distances()

Abstract method: compute and populate self.distances for this election.

Concrete subclasses must implement this to fill distance matrices for supported object types (e.g. ‘vote’ and ‘candidate’).

compute_feature(feature_id, feature_long_id=None, **kwargs)

Compute and store a local feature for this election.

The computed feature is stored in self.features under feature_long_id.

compute_potes(mapping=None)

Convert votes to positional scores (potes) and store them in self.potes.

If mapping is provided, candidate indices are remapped before converting. Returns the computed potes array, or None for pseudo-cultures.

compute_rule(rule_id, **kwargs)

Compute an ABC voting rule for this election (delegates to abcvoting helper).

embed(algorithm='mds', object_type=None)

Compute 2D coordinates for instances using PCA or MDS and optionally export.

Parameters:

• algorithm (str) – ‘mds’ or ‘pca’ (case-insensitive).

• object_type (str or None) – Object type to embed; defaults to the election’s current default.

export_to_file(path_to_folder, is_aggregated=False)

Export the election to a folder outside of an experiment context.

get_coordinates(object_type)

Return coordinates for the given object_type, importing them if missing.

get_feature(feature_id, feature_long_id=None, overwrite=False, compute_if_missing=True, **kwargs)

Return a feature value, computing it if missing or when overwrite is True.

Raises:

ValueError – If overwrite is requested but compute_if_missing is False.

import_coordinates() → None

Imports coordinates from a .csv file.

Return type:

None

import_distances() → None

Imports distances from a .csv file.

Return type:

None

import_matrix() → ndarray

Load a candidate-by-candidate matrix CSV from the experiment’s matrices folder.

Returns:

Square matrix with shape (num_candidates, num_candidates).

Return type:

np.ndarray

rotate(angle, object_type) → None

Rotate all stored coordinates for object_type around point (0.5, 0.5).

static rotate_point(cx, cy, angle, px, py) → Tuple[float, float]

Rotate a 2D point (px,py) around center (cx,cy) by angle radians.

Returns the rotated (x, y) tuple.

set_default_object_type(object_type)

Set the default object type used by methods like embed and get_coordinates.

Parameters:

object_type (str) – One of OBJECT_TYPES (e.g. ‘vote’ or ‘candidate’).

update_votes()

Export the election’s votes within its experiment (delegates to persistence layer).

vector_to_interval(vector, precision=None) → list

Convert a vector of length num_candidates into a discretized interval list.

• If precision is None, it defaults to num_candidates (one sample per candidate).

• Ensures the returned list has roughly precision elements (uses integer division per-candidate and guarantees at least one sample per candidate).

Raises:

ValueError – if vector length doesn’t match num_candidates or if: num_candidates is not a positive integer.