class svvamp.StudyRuleCriteria(manipulation_criteria=None, manipulation_criteria_c=None, manipulation_only=False, result_criteria=None, utility_criteria=None, numerical_criteria=None)

A set of criteria to study for the simulator about one or several voting rules.

Parameters:

• manipulation_criteria (List of str) – Manipulation criteria that need to be studied. If None (default), then all criteria related to collective manipulation are taken: [‘is_tm_’, ‘is_um_’, ‘is_icm_’, ‘is_cm_’]. If [], then no criterion is taken. Note that by default, ‘is_iia_’ and ‘is_im_’ are NOT included.

• manipulation_criteria_c (List of str) – This is where you put criteria such as ‘candidates_cm_’, ‘candidates_tm_’, etc.

• manipulation_only (bool) – If True, then result_criteria and utility criteria are ignored, i.e. set to [].

• result_criteria (List of str) – Result criteria that need to be studied. If None(default), then all criteria are taken: [‘w_is_weak_condorcet_winner_’, ‘w_missed_weak_condorcet_winner_’, …].

• utility_criteria (List) – List of tuples (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. Example: (‘total_utility_w_’, np.mean, ‘total_u_mean’). Will compute the mean of total_utility_w over the populations and the result will be called ‘total_u_mean’. If utility_criteria is None (default), then use: [(‘total_utility_w_’, np.max, ‘total_u_max’), (‘total_utility_w_’, np.min, ‘total_u_min’), (‘total_utility_w_’, np.mean, ‘total_u_mean’), (‘total_utility_w_’, np.std, ‘total_u_std’)].

• numerical_criteria (List of str) – Other numerical criteria that need to be studied. These criteria must correspond to attributes in the rule that output a pair (inf, sup), for example nb_candidates_cm_ or worst_relative_welfare_with_cm_.

append_manipulation_criterion(criterion)

Add a manipulation criterion

Parameters:

criterion (str)

Examples

>>> study_rule_criteria = StudyRuleCriteria(
...     manipulation_criteria=[],
...     result_criteria=[],
...     utility_criteria=[],
...     numerical_criteria=[],
... )
>>> study_rule_criteria.append_manipulation_criterion('is_im_')
>>> study_rule_criteria.append_manipulation_criterion('is_iia_')
>>> print(study_rule_criteria)  
StudyRuleCriteria with:
    manipulation_criteria:
        is_im_
        is_iia_
    manipulation_criteria_c: None
    result_criteria: None
    utility_criteria: None
    numerical_criteria: None

append_manipulation_criterion_c(criterion)

Add a manipulation criterion (for candidates)

Parameters:

criterion (str)

Examples

>>> study_rule_criteria = StudyRuleCriteria(
...     manipulation_criteria=[],
...     manipulation_criteria_c=[],
...     result_criteria=[],
...     utility_criteria=[],
...     numerical_criteria=[],
... )
>>> study_rule_criteria.append_manipulation_criterion_c('candidates_cm_')
>>> study_rule_criteria.append_manipulation_criterion_c('candidates_tm_')
>>> print(study_rule_criteria)  
StudyRuleCriteria with:
    manipulation_criteria: None
    manipulation_criteria_c:
        candidates_cm_
        candidates_tm_
    result_criteria: None
    utility_criteria: None
    numerical_criteria: None

append_numerical_criterion(criterion)

Add a numerical criterion

Parameters:

criterion (str)

Examples

>>> study_rule_criteria = StudyRuleCriteria(
...     manipulation_criteria=[],
...     result_criteria=[],
...     utility_criteria=[],
...     numerical_criteria=[],
... )
>>> study_rule_criteria.append_numerical_criterion('nb_candidates_cm_')
>>> print(study_rule_criteria)  
StudyRuleCriteria with:
    manipulation_criteria: None
    manipulation_criteria_c: None
    result_criteria: None
    utility_criteria: None
    numerical_criteria:
        nb_candidates_cm_

append_result_criterion(criterion)

Add a result criterion

Parameters:

criterion (str)

Examples

>>> study_rule_criteria = StudyRuleCriteria(
...     manipulation_criteria=[],
...     result_criteria=[],
...     utility_criteria=[],
...     numerical_criteria=[],
... )
>>> study_rule_criteria.append_result_criterion('w_is_condorcet_admissible_')
>>> print(study_rule_criteria)  
StudyRuleCriteria with:
    manipulation_criteria: None
    manipulation_criteria_c: None
    result_criteria:
        w_is_condorcet_admissible_
    utility_criteria: None
    numerical_criteria: None

append_utility_criterion(criterion, func, name)

Add a utility 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_rule_criteria = StudyRuleCriteria(
...     manipulation_criteria=[],
...     result_criteria=[],
...     utility_criteria=[],
...     numerical_criteria=[],
... )
>>> study_rule_criteria.append_utility_criterion('total_utility_w_', np.sum, 'total_u_sum')
>>> print(study_rule_criteria)  
StudyRuleCriteria with:
    manipulation_criteria: None
    manipulation_criteria_c: None
    result_criteria: None
    utility_criteria:
        ('total_utility_w_', <function sum at ...>, 'total_u_sum')
    numerical_criteria: None

In the above example, the criterion will be used to compute the sum of total_utility_w_ over all the profiles, and the result will be called ‘total_u_sum’.

check_sanity(rule_class)

Check sanity of the object

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

Parameters:

rule_class (class) – Subclass of Rule.

Examples

Detect an illegal manipulation criterion:

>>> study_rule_criteria = StudyRuleCriteria(manipulation_criteria=['unexpected_criterion'])
>>> study_rule_criteria.check_sanity(rule_class=RuleIRV)
Traceback (most recent call last):
ValueError: Criterion 'unexpected_criterion' is unknown for RuleIRV.

Detect an illegal manipulation criterion (for candidates):

>>> study_rule_criteria = StudyRuleCriteria(manipulation_criteria_c=['unexpected_criterion'])
>>> study_rule_criteria.check_sanity(rule_class=RuleIRV)
Traceback (most recent call last):
ValueError: Criterion 'unexpected_criterion' is unknown for RuleIRV.

Detect an illegal result criterion:

>>> study_rule_criteria = StudyRuleCriteria(
...     manipulation_criteria=[],
...     result_criteria=['unexpected_criterion'])
>>> study_rule_criteria.check_sanity(rule_class=RuleIRV)
Traceback (most recent call last):
ValueError: Criterion 'unexpected_criterion' is unknown for RuleIRV.

Detect an illegal utility criterion:

>>> study_rule_criteria = StudyRuleCriteria(
...     manipulation_criteria=[],
...     utility_criteria=[('unexpected_criterion', np.sum, 'the_name')])
>>> study_rule_criteria.check_sanity(rule_class=RuleIRV)
Traceback (most recent call last):
ValueError: Criterion 'unexpected_criterion' is unknown for RuleIRV.

Detect when a aggregation function is not provided:

>>> study_rule_criteria = StudyRuleCriteria(
...     manipulation_criteria=[],
...     utility_criteria=[('mean_utility_w_', 'this_is_not_callable', 'the_name')])
>>> study_rule_criteria.check_sanity(rule_class=RuleIRV)
Traceback (most recent call last):
TypeError: Expected: callable. Got: 'this_is_not_callable'.

Detect an illegal numerical criterion:

>>> study_rule_criteria = StudyRuleCriteria(
...     manipulation_criteria=[],
...     numerical_criteria=['unexpected_criterion'])
>>> study_rule_criteria.check_sanity(rule_class=RuleIRV)
Traceback (most recent call last):
ValueError: Criterion 'unexpected_criterion' is unknown for RuleIRV.

remove(criterion)

Remove a criterion

Remove all occurrences of a criterion (generally zero or one) from this StudyRuleCriteria object.

Parameters:

criterion (str)

Returns:

The object itself.

Return type:

StudyRuleCriteria

Examples

>>> study_rule_criteria = StudyRuleCriteria(
...     manipulation_criteria=['is_cm_', 'is_tm_'],
...     result_criteria=['w_is_condorcet_admissible_', 'w_is_weak_condorcet_winner_'],
...     utility_criteria=[('mean_utility_w_', np.max, 'mean_u_max'),
...                       ('mean_utility_w_', np.min, 'mean_u_min')],
...     numerical_criteria=['nb_candidates_cm_', 'worst_relative_welfare_with_cm_'],
... )
>>> study_rule_criteria.remove('is_cm_')
>>> study_rule_criteria.remove('w_is_weak_condorcet_winner_')
>>> study_rule_criteria.remove('mean_u_max')
>>> study_rule_criteria.remove('worst_relative_welfare_with_cm_')
>>> print(study_rule_criteria)  
StudyRuleCriteria with:
    manipulation_criteria:
        is_tm_
    manipulation_criteria_c: None
    result_criteria:
        w_is_condorcet_admissible_
    utility_criteria:
        ('mean_utility_w_', <function ...min at ...>, 'mean_u_min')
    numerical_criteria:
        nb_candidates_cm_