class svvamp.StudyProfileCriteria(boolean_criteria=None, numerical_criteria=None, special_candidates_criteria=None, array_criteria=None, matrix_criteria=None)

A set of criteria to study for the simulator about the profiles.

Parameters:

• boolean_criteria (List of str) – Each string must correspond to a boolean criterion defined in Profile.

• numerical_criteria (List of tuple) –

  Each tuple is of the form (criterion, func, name), where:

  criterion: the numerical data to be processed. func: an aggregating function. name: the name chosen for this pair criterion / aggregation function.

• special_candidates_criteria (List of str) – Each string must correspond to an attribute defined in Profile that returns the index of a candidate or NaN.

• array_criteria (List of str) – Each string must correspond to a attribute defined in Profile that returns an 1d array of size n_c (the number of candidates).

• matrix_criteria (List of str) – Each string must correspond to a attribute defined in Profile that returns an array (whatever its size).

Examples

For each argument, if None (default), then a quite extensive pre-defined list is used. Hence, the typical usage is simply:

>>> study_profile_criteria = StudyProfileCriteria()

Here is an example of manually defined numerical_criteria:

>>> study_profile_criteria = StudyProfileCriteria(numerical_criteria=[
...     ('total_utility_mean', np.mean, 'total_u_mean_mean')
... ])

For each profile, this will compute total_utility_mean (mean over the candidates). Then it will use np.mean to calculate the mean over the profiles. The result will be called ‘total_u_mean_mean’.

append_array_criterion(criterion)

Add an array criterion

Parameters:

criterion (str) –

Examples

>>> study_profile_criteria = StudyProfileCriteria(
...     boolean_criteria=[],
...     numerical_criteria=[],
...     special_candidates_criteria=[],
...     array_criteria=['plurality_scores_rk'],
...     matrix_criteria=[]
... )
>>> study_profile_criteria.append_array_criterion('plurality_scores_ut')
>>> print(study_profile_criteria)
StudyProfileCriteria with:
    boolean_criteria: None
    numerical_criteria: None
    special_candidates_criteria: None
    array_criteria:
        plurality_scores_rk
        plurality_scores_ut
    matrix_criteria: None

append_boolean_criterion(criterion)

Add a boolean criterion

Parameters:

criterion (str) –

Examples

>>> study_profile_criteria = StudyProfileCriteria(
...     boolean_criteria=['exists_condorcet_admissible'],
...     numerical_criteria=[],
...     special_candidates_criteria=[],
...     array_criteria=[],
...     matrix_criteria=[]
... )
>>> study_profile_criteria.append_boolean_criterion('exists_weak_condorcet_winner')
>>> print(study_profile_criteria)
StudyProfileCriteria with:
    boolean_criteria:
        exists_condorcet_admissible
        exists_weak_condorcet_winner
    numerical_criteria: None
    special_candidates_criteria: None
    array_criteria: None
    matrix_criteria: None

append_matrix_criterion(criterion)

Add a matrix criterion

Parameters:

criterion (str) –

Examples

>>> study_profile_criteria = StudyProfileCriteria(
...     boolean_criteria=[],
...     numerical_criteria=[],
...     special_candidates_criteria=[],
...     array_criteria=[],
...     matrix_criteria=['preferences_ut']
... )
>>> study_profile_criteria.append_matrix_criterion('preferences_borda_rk')
>>> print(study_profile_criteria)
StudyProfileCriteria with:
    boolean_criteria: None
    numerical_criteria: None
    special_candidates_criteria: None
    array_criteria: None
    matrix_criteria:
        preferences_ut
        preferences_borda_rk

append_numerical_criterion(criterion, func, name)

Add a numerical criterion

Parameters:

• criterion (str) – The numerical data to be processed.

• func (callable) – An aggregating function.

• name (str) – The name chosen for this pair criterion / aggregation function.

Examples

>>> study_profile_criteria = StudyProfileCriteria(
...     boolean_criteria=[],
...     numerical_criteria=[],
...     special_candidates_criteria=[],
...     array_criteria=[],
...     matrix_criteria=[]
... )
>>> study_profile_criteria.append_numerical_criterion(
...     'total_utility_mean', np.mean, 'total_u_mean_mean'
... )
>>> print(study_profile_criteria)  
StudyProfileCriteria with:
    boolean_criteria: None
    numerical_criteria:
        ('total_utility_mean', <function mean at ...>, 'total_u_mean_mean')
    special_candidates_criteria: None
    array_criteria: None
    matrix_criteria: None

For each profile, this will compute total_utility_mean (mean over the candidates). Then use np.mean to calculate the mean over the profiles. The result will be called ‘total_u_mean_mean’.

append_special_candidates_criterion(criterion)

Add a ‘special candidates’ criterion

Parameters:

criterion (str) –

Examples

>>> study_profile_criteria = StudyProfileCriteria(
...     boolean_criteria=[],
...     numerical_criteria=[],
...     special_candidates_criteria=['condorcet_winner_rk_ctb'],
...     array_criteria=[],
...     matrix_criteria=[]
... )
>>> study_profile_criteria.append_special_candidates_criterion('condorcet_winner_rk')
>>> print(study_profile_criteria)
StudyProfileCriteria with:
    boolean_criteria: None
    numerical_criteria: None
    special_candidates_criteria:
        condorcet_winner_rk_ctb
        condorcet_winner_rk
    array_criteria: None
    matrix_criteria: None

check_sanity()

Check sanity of the object

Preforms some basic checks. It is recommended to use this method before launching big simulations.

Examples

Confirm that a configuration is sound:

>>> study_profile_criteria = StudyProfileCriteria(
...     boolean_criteria=['exists_condorcet_winner_rk'],
...     numerical_criteria=[('mean_utility_min', np.min, 'mean_u_min_min')],
...     special_candidates_criteria=['condorcet_winner_rk'],
...     array_criteria=['total_utility_c'],
...     matrix_criteria=['matrix_duels_rk']
... )
>>> study_profile_criteria.check_sanity()
StudyProfileCriteria: Sanity check was successful.

Detect an illegal criterion:

>>> study_profile_criteria = StudyProfileCriteria(boolean_criteria=['unexpected_criterion'])
>>> study_profile_criteria.check_sanity()
Traceback (most recent call last):
ValueError: Attribute 'unexpected_criterion' is unknown for Profile.

>>> study_profile_criteria = StudyProfileCriteria(numerical_criteria=[
...     ('unexpected_criterion', np.sum, 'unexpected_criterion_sum')
... ])
>>> study_profile_criteria.check_sanity()
Traceback (most recent call last):
ValueError: Attribute 'unexpected_criterion' is unknown for Profile.

Detect when a aggregation function is not provided:

>>> study_profile_criteria = StudyProfileCriteria(numerical_criteria=[
...     ('mean_utility_min', 'this_is_not_callable', 'mean_u_min_min')
... ])
>>> study_profile_criteria.check_sanity()
Traceback (most recent call last):
TypeError: Expected: callable. Got: 'this_is_not_callable'.

remove(criterion)

Remove a criterion

Parameters:

criterion (str) –

Examples

Remove all occurrences of criterion (generally zero or one):

>>> study_profile_criteria = StudyProfileCriteria(
...     boolean_criteria=['exists_condorcet_admissible', 'exists_weak_condorcet_winner'],
...     numerical_criteria=[],
...     special_candidates_criteria=[],
...     array_criteria=[],
...     matrix_criteria=[]
... )
>>> study_profile_criteria.remove('exists_weak_condorcet_winner')
>>> print(study_profile_criteria)
StudyProfileCriteria with:
    boolean_criteria:
        exists_condorcet_admissible
    numerical_criteria: None
    special_candidates_criteria: None
    array_criteria: None
    matrix_criteria: None

For numerical criteria, use the last element of the triple, i.e. the name:

>>> study_profile_criteria = StudyProfileCriteria(
...     boolean_criteria=[],
...     numerical_criteria=[('mean_utility_min', np.min, 'mean_u_min_min'),
...                         ('mean_utility_min', np.max, 'mean_u_min_max')],
...     special_candidates_criteria=[],
...     array_criteria=[],
...     matrix_criteria=[]
... )
>>> study_profile_criteria.remove('mean_u_min_min')
>>> print(study_profile_criteria)  
StudyProfileCriteria with:
    boolean_criteria: None
    numerical_criteria:
        ('mean_utility_min', <function ...max at ...>, 'mean_u_min_max')
    special_candidates_criteria: None
    array_criteria: None
    matrix_criteria: None

rename_numerical_criterion(old_name, new_name)

Rename a numerical criterion

Parameters:

• old_name (str) –

• new_name (str) –

Examples

>>> study_profile_criteria = StudyProfileCriteria(
...     boolean_criteria=[],
...     numerical_criteria=[('total_utility_mean', np.mean, 'total_u_mean_mean')],
...     special_candidates_criteria=[],
...     array_criteria=[],
...     matrix_criteria=[]
... )
>>> study_profile_criteria.rename_numerical_criterion('total_u_mean_mean', 'the_new_name')
>>> print(study_profile_criteria)  
StudyProfileCriteria with:
    boolean_criteria: None
    numerical_criteria:
        ('total_utility_mean', <function mean at ...>, 'the_new_name')
    special_candidates_criteria: None
    array_criteria: None
    matrix_criteria: None