Analysis module

Module containing all kinds of tools to analyse participatory budgeting elections and their outcomes.

Basic Properties

avg_project_cost(instance: Instance) → int | float | mpq

Returns the average cost of a project.

Parameters:

instance (Instance) – The instance.

Returns:

The average cost of a project.

Return type:

Numeric

funding_scarcity(instance: Instance) → int | float | mpq

Returns the ratio of the total cost of the instance, divided by the budget limit. This measure is called the funding scarcity.

Parameters:

instance (Instance) – The instance.

Returns:

The funding scarcity of the instance.

Return type:

Numeric

median_project_cost(instance: Instance) → int | float | mpq

Returns the median cost of a project.

Parameters:

instance (Instance) – The instance.

Returns:

The median cost of a project.

Return type:

Numeric

std_dev_project_cost(instance: Instance) → int | float | mpq

Returns the standard deviation of the costs of the projects.

Parameters:

instance (Instance) – The instance.

Returns:

The standard deviation.

Return type:

Numeric

sum_project_cost(instance: Instance) → int | float | mpq

Returns the total cost of all the projects in the instance.

Parameters:

instance (Instance) – The instance.

Returns:

The total cost.

Return type:

Numeric

avg_approval_score(instance: Instance, profile: AbstractApprovalProfile) → int | float | mpq

Returns the average approval score of projects.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractApprovalProfile) – The profile.

Returns:

The average approval score of projects.

Return type:

Numeric

avg_ballot_cost(instance: Instance, profile: AbstractProfile) → int | float | mpq

Returns the average cost of the ballots in the profile.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

Returns:

The average cost of the ballots in the profile.

Return type:

Numeric

avg_ballot_length(instance: Instance, profile: AbstractProfile) → int | float | mpq

Returns the average length of the ballots in the profile.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

Returns:

The average length of the ballots in the profile.

Return type:

Numeric

avg_total_score(instance: Instance, profile: AbstractCardinalProfile) → int | float | mpq

Returns the average score assigned to a project by the voters.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractCardinalProfile) – The profile.

Returns:

The average score assigned to a project.

Return type:

Numeric

median_approval_score(instance: Instance, profile: AbstractApprovalProfile) → int | float | mpq

Returns the median approval score of projects.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractApprovalProfile) – The profile.

Returns:

The median approval score of projects.

Return type:

Numeric

median_ballot_cost(instance: Instance, profile: AbstractProfile) → int | float | mpq

Returns the median cost of the ballots in the profile.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

Returns:

The median cost of the ballots in the profile.

Return type:

Numeric

median_ballot_length(instance: Instance, profile: AbstractProfile) → int

Returns the median length of the ballots in the profile.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

Returns:

The median length of the ballots in the profile.

Return type:

Numeric

median_total_score(instance: Instance, profile: AbstractCardinalProfile) → int | float | mpq

Returns the median score assigned to a project by the voters.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractCardinalProfile) – The profile.

Returns:

The median score assigned to a project.

Return type:

Numeric

voter_flow_matrix(instance: Instance, profile: AbstractCardinalProfile) → dict[str, dict[str, int]]

Returns the voter flow matrix. The voter flow matrix is a 2D dictionary where voter_flow[a][b] is the number of voters for ‘a’ who voted for ‘b’

Parameters:

instance (Instance) – The instance.

Returns:

The voter flow matrix.

Return type:

dict[str, dict[str, int]]

votes_count_by_project(profile: AbstractCardinalProfile) → dict[str, int]

Returns the number of votes for each project.

Parameters:

profile (AbstractCardinalProfile) – The profile.

Returns:

The number of votes for each project.

Return type:

dict[str, int]

Voters’ Satisfaction Properties

avg_satisfaction(instance: Instance, profile: AbstractProfile, budget_allocation: Collection[Project], sat_class: type[SatisfactionMeasure]) → int | float | mpq

Computes the average satisfaction for a given instance, profile and satisfaction measure.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

• budget_allocation (Iterable[Project]) – Collection of projects.

• sat_class (type[SatisfactionMeasure]) – The satisfaction measure used to do the comparison.

Returns:

The average satisfaction of a voter for the budget allocation.

Return type:

Numeric

gini_coefficient_of_satisfaction(instance: Instance, profile: AbstractProfile, budget_allocation: Collection[Project], sat_class: type[SatisfactionMeasure], invert: bool = False) → int | float | mpq

Computes the Gini coefficient of the satisfaction of the voters.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

• budget_allocation (Iterable[Project]) – Collection of projects.

• sat_class (type[SatisfactionMeasure]) – The satisfaction measure used to do the comparison.

• invert (bool, optional) – Set to True to return 1 minus the Gini coefficient. Defaults to False.

Returns:

The Gini coefficient of the satisfaction of the voters.

Return type:

Numeric

percent_non_empty_handed(instance: Instance, profile: AbstractProfile, budget_allocation: Collection[Project]) → int | float | mpq

Computes the percentage of voter for which at least one project from the budget allocation also appears in their ballot.

It mostly makes sense for approval ballots, though any profile of ballots supporting the in operator can be used.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

• budget_allocation (Iterable[Project]) – Collection of projects.

Returns:

The percentage of non-empty handed voters.

Return type:

Numeric

percent_positive_satisfaction(profile: AbstractProfile, budget_allocation: Collection[Project], sat_class: type[SatisfactionMeasure]) → int | float | mpq

Computes the percentage of voter who enjoy a positive (thus non-zero) satisfaction.

Parameters:

• profile (AbstractProfile) – The profile.

• budget_allocation (Iterable[Project]) – Collection of projects.

• sat_class (type[SatisfactionMeasure]) – The class defining the satisfaction function used to measure the social welfare. It should be a class inhereting from SatisfactionMeasure.

Returns:

The percentage of non-empty handed voters.

Return type:

Numeric

satisfaction_histogram(instance: Instance, profile: AbstractProfile, budget_allocation: Collection[Project], sat_class: type[SatisfactionMeasure], max_satisfaction: int | float | mpq, num_bins: int = 21) → list[int | float | mpq]

Computes the data necessary to plot a histogram of the satisfaction of the voters. Each bin contains the percentage of voters whose satisfaction corresponds to the bin.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

• budget_allocation (Iterable[Project]) – Collection of projects.

• sat_class (type[SatisfactionMeasure]) – The satisfaction measure used to do the comparison.

• max_satisfaction (Numeric) – The normaliser for the satisfaction.

• num_bins (int, optional) – The number of bins of the histogram. Defaults to 20.

Returns:

A list of values, one per bin of the histogram.

Return type:

list[Numeric]

Projects’ Categories Properties

category_proportionality(instance: Instance, profile: AbstractApprovalProfile, budget_allocation: Collection[Project]) → int | float | mpq

Computes the difference between the cost allocated per category, and that existing in the profile. More specifically, for each category (an error is raised if not category are specified) we compute the amount of money dedicated to projects from the category in the budget allocation; together with the amount of money allocated to the category in the ballots of the voters. For each category, the average between these two scores is raised to the power 2, the global average over all categories is then considered and we return the exponential of minus that value.

It mostly makes sense for approval ballots, though any profile of ballots supporting the in operator can be used.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

• budget_allocation (Iterable[Project]) – The selected collection of projects.

Returns:

The score for the category proportionality.

Return type:

Numeric

Justified Representation Axioms

is_EJR_any_approval(instance: Instance, profile: AbstractApprovalProfile, sat_class: type[SatisfactionMeasure], budget_allocation: Collection[Project]) → bool

Test if a budget allocation satisfies EJR up to any project for the given instance and the given profile of approval ballots.

is_EJR_any_cardinal(instance: Instance, profile: AbstractCardinalProfile, budget_allocation: Collection[Project]) → bool

Test if a budget allocation satisfies EJR up to any project for the given instance and the given profile of cardinal ballots.

is_EJR_approval(instance: Instance, profile: AbstractApprovalProfile, sat_class: type[SatisfactionMeasure], budget_allocation: Collection[Project], up_to_func: Callable[[Iterable[int | float | mpq]], int | float | mpq] | None = None) → bool

Test if a budget allocation satisfies EJR for the given instance and the given profile of approval ballots.

is_EJR_cardinal(instance: Instance, profile: AbstractCardinalProfile, budget_allocation: Collection[Project], sat_class: type[SatisfactionMeasure] | None = None, up_to_func: Callable[[Iterable[int | float | mpq]], int | float | mpq] | None = None) → bool

Test if a budget allocation satisfies EJR for the given instance and the given profile of cardinal ballots.

is_EJR_one_approval(instance: Instance, profile: AbstractApprovalProfile, sat_class: type[SatisfactionMeasure], budget_allocation: Collection[Project]) → bool

Test if a budget allocation satisfies EJR up to one project for the given instance and the given profile of approval ballots.

is_EJR_one_cardinal(instance: Instance, profile: AbstractCardinalProfile, budget_allocation: Collection[Project]) → bool

Test if a budget allocation satisfies EJR up to one project for the given instance and the given profile of cardinal ballots.

is_PJR_any_approval(instance: Instance, profile: AbstractApprovalProfile, sat_class: type[SatisfactionMeasure], budget_allocation: Collection[Project]) → bool

Test if a budget allocation satisfies PJR up to any project for the given instance and the given profile of approval ballots.

is_PJR_any_cardinal(instance: Instance, profile: AbstractCardinalProfile, budget_allocation: Iterable[Project]) → bool

Test if a budget allocation satisfies PJR up to any project for the given instance and the given profile of cardinal ballots.

is_PJR_approval(instance: Instance, profile: AbstractApprovalProfile, sat_class: type[SatisfactionMeasure], budget_allocation: Collection[Project], up_to_func: Callable[[Iterable[int | float | mpq]], int | float | mpq] | None = None) → bool

Test if a budget allocation satisfies PJR for the given instance and the given profile of approval ballots.

is_PJR_cardinal(instance: Instance, profile: AbstractCardinalProfile, budget_allocation: Iterable[Project], up_to_func: Callable[[Iterable[int | float | mpq]], int | float | mpq] | None = None) → bool

Test if a budget allocation satisfies PJR for the given instance and the given profile of cardinal ballots.

is_PJR_one_approval(instance: Instance, profile: AbstractApprovalProfile, sat_class: type[SatisfactionMeasure], budget_allocation: Collection[Project]) → bool

Test if a budget allocation satisfies PJR up to one project for the given instance and the given profile of approval ballots.

is_PJR_one_cardinal(instance: Instance, profile: AbstractCardinalProfile, budget_allocation: Iterable[Project]) → bool

Test if a budget allocation satisfies PJR up to one project for the given instance and the given profile of cardinal ballots.

is_in_core(instance: Instance, profile: AbstractProfile, sat_class: type[SatisfactionMeasure], budget_allocation: Collection[Project], up_to_func: Callable[[Iterable[int | float | mpq]], int | float | mpq] | None = None) → bool

Test if a given budget allocation is in the core of the instance.

is_strong_EJR_approval(instance: Instance, profile: AbstractApprovalProfile, sat_class: type[SatisfactionMeasure], budget_allocation: Collection[Project]) → bool

Test if a budget allocation satisfies strong EJR for the given instance and the given profile of approval ballots.

is_strong_EJR_cardinal(instance: Instance, profile: AbstractCardinalProfile, budget_allocation: Collection[Project], sat_class: type[SatisfactionMeasure] | None = None) → bool

Test if a budget allocation satisfies strong EJR for the given instance and the given profile of cardinal ballots.

Priceability Axiom

Module with tools for analysis of the priceability / stable-priceability property of budget allocation.

class PriceableResult(status: OptimizationStatus, allocation: list[Project] | None = None, relaxation_beta: float | dict = None, voter_budget: float | None = None, payment_functions: list[dict[Project, float]] | None = None)

Result of priceable(). Contains information about the optimization status of ILP outcome. If the status is valid (i.e. OPTIMAL / FEASIBLE), the class contains the budget allocation, as well as the price system (voter_budget, payment_functions) that satisfies the priceable / stable-priceable property.

Parameters:

• status (OptimizationStatus) – Optimization status of the ILP outcome.

• allocation (Collection[Project], optional) – The selected collection of projects. Defaults to None.

• voter_budget (float, optional) – Voter initial endowment. Defaults to None.

• payment_functions (list[dict[Project, Numeric]], optional) – List of payment functions for each voter. A payment function indicates the amounts paid for each project by a voter. Defaults to None.

status

Optimization status of the ILP outcome.

Type:

OptimizationStatus

allocation

The selected collection of projects. None if the optimization status is not OPTIMAL / FEASIBLE.

Type:

Collection[Project] or None

voter_budget

Voter initial endowment. None if the optimization status is not OPTIMAL / FEASIBLE.

Type:

bool or None

payment_functions

List of payment functions for each voter. A payment function indicates the amounts paid for each project by a voter. None if the optimization status is not OPTIMAL / FEASIBLE.

Type:

list[dict[Project, Numeric]] or None

validate() → bool | None

Checks if the optimization status is OPTIMAL / FEASIBLE. :returns: Validity of optimization status. :rtype: bool

priceable(instance: Instance, profile: AbstractApprovalProfile, budget_allocation: Collection[Project] | None = None, voter_budget: int | float | mpq | None = None, payment_functions: list[dict[Project, int | float | mpq]] | None = None, stable: bool = False, exhaustive: bool = True, relaxation: Relaxation | None = None, *, max_seconds: int = 600, verbose: bool = False) → PriceableResult

Finds a priceable / stable-priceable budget allocation for approval profile using Linear Programming via mip Python package.

Reference paper: https://www.cs.utoronto.ca/~nisarg/papers/priceability.pdf

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

• budget_allocation (Collection[Project], optional) – The selected collection of projects. If specified, the allocation is hardcoded into the model. Defaults to None.

• voter_budget (Numeric) – Voter initial endowment. If specified, the voter budget is hardcoded into the model. Defaults to None.

• payment_functions (Collection[dict[Project, Numeric]]) – Collection of payment functions for each voter. If specified, the payment functions are hardcoded into the model. Defaults to None.

• stable (bool, optional) – Search stable-priceable allocation. Defaults to False.

• exhaustive (bool, optional) – Search exhaustive allocation. Defaults to True.

• relaxation (Relaxation, optional) – Relaxation method to the stable-priceability condition. Defaults to None.

• **max_seconds (int, optional) – Model’s maximum runtime in seconds. Defaults to 600.

• **verbose (bool, optional) – Display additional information. Defaults to False.

Returns:

Dataclass containing priceable result details.

Return type:

PriceableResult

validate_price_system(instance: Instance, profile: AbstractApprovalProfile, budget_allocation: Collection[Project], voter_budget: int | float | mpq, payment_functions: list[dict[Project, int | float | mpq]], stable: bool = False, exhaustive: bool = True, relaxation: Relaxation | None = None, *, verbose: bool = False) → bool

Given a price system (voter_budget, payment_functions), verifies whether budget_allocation is priceable / stable-priceable.

round_cmp(): is used across the implementation to ensure no rounding errors.

Reference paper: https://www.cs.utoronto.ca/~nisarg/papers/priceability.pdf

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

• budget_allocation (Collection[Project]) – The selected collection of projects.

• voter_budget (Numeric) – Voter initial endowment.

• payment_functions (list[dict[Project, Numeric]]) – Collection of payment functions for each voter. A payment function indicates the amounts paid for each project by a voter.

• stable (bool, optional) – Verify for stable-priceable allocation. Defaults to False.

• exhaustive (bool, optional) – Verify for exhaustiveness of the allocation. Defaults to True.

• relaxation (Relaxation, optional) – Relaxation method to the stable-priceability condition. Defaults to None.

• **verbose (bool, optional) – Display additional information. Defaults to False.

Returns:

Boolean value specifying whether budget_allocation is priceable / stable-priceable.

Return type:

bool

Stable-Priceability Axiom Relaxations

Module for relaxation of the stable-priceability constraint.

class MinAdd(instance: Instance, profile: Profile)

A beta in (-inf, inf) is added to the right-hand side of the condition. The objective function minimizes beta.

add_beta(mip_model: Model) → None

Add beta variable to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

add_objective(mip_model: Model) → None

Add objective function to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

add_stability_constraint(mip_model: Model) → None

Add relaxed stability constraint to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

get_beta(mip_model: Model) → Real | dict

Get the value of beta from the model. This method implicitly saves internally the value of beta variable from mip_model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

Returns:

The value of beta from the model.

Return type:

Real | dict

get_relaxed_cost(project: Project) → float

Get relaxed cost of a project.

Parameters:

project (Project) – The project to get the relaxed cost for.

Returns:

Relaxed cost of the project.

Return type:

float

class MinAddOffset(instance: Instance, profile: Profile)

A mixture of MinAdd and MinAddVector relaxation methods. A separate beta[c] in [0, inf) for each project c is added to the right-hand side of the condition. The sum of beta[c] for each project c is in [0, 0.025 * instance.budget_limit]. Additionally, a global beta in (-inf, inf) is added to the right-hand side of the condition. The objective function minimizes the global beta.

add_beta(mip_model: Model) → None

Add beta variable to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

add_objective(mip_model: Model) → None

Add objective function to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

add_stability_constraint(mip_model: Model) → None

Add relaxed stability constraint to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

get_beta(mip_model: Model) → Real | dict

Get the value of beta from the model. This method implicitly saves internally the value of beta variable from mip_model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

Returns:

The value of beta from the model.

Return type:

Real | dict

get_relaxed_cost(project: Project) → float

Get relaxed cost of a project.

Parameters:

project (Project) – The project to get the relaxed cost for.

Returns:

Relaxed cost of the project.

Return type:

float

class MinAddVector(instance: Instance, profile: Profile)

A separate beta[c] in (-inf, inf) for each project c is added to the right-hand side of the condition. The objective function minimizes the sum of beta[c] for each project c.

add_beta(mip_model: Model) → None

Add beta variable to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

add_objective(mip_model: Model) → None

Add objective function to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

add_stability_constraint(mip_model: Model) → None

Add relaxed stability constraint to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

get_beta(mip_model: Model) → Real | dict

Get the value of beta from the model. This method implicitly saves internally the value of beta variable from mip_model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

Returns:

The value of beta from the model.

Return type:

Real | dict

get_relaxed_cost(project: Project) → float

Get relaxed cost of a project.

Parameters:

project (Project) – The project to get the relaxed cost for.

Returns:

Relaxed cost of the project.

Return type:

float

class MinAddVectorPositive(instance: Instance, profile: Profile)

A separate beta[c] in [0, inf) for each project c is added to the right-hand side of the condition. The objective function minimizes the sum of beta[c] for each project c.

add_beta(mip_model: Model) → None

Add beta variable to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

class MinMul(instance: Instance, profile: Profile)

The right-hand side of the condition is multiplied by a beta in [0, inf). The objective function minimizes beta.

add_beta(mip_model: Model) → None

Add beta variable to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

add_objective(mip_model: Model) → None

Add objective function to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

add_stability_constraint(mip_model: Model) → None

Add relaxed stability constraint to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

get_beta(mip_model: Model) → Real | dict

Get the value of beta from the model. This method implicitly saves internally the value of beta variable from mip_model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

Returns:

The value of beta from the model.

Return type:

Real | dict

get_relaxed_cost(project: Project) → float

Get relaxed cost of a project.

Parameters:

project (Project) – The project to get the relaxed cost for.

Returns:

Relaxed cost of the project.

Return type:

float

class Relaxation(instance: Instance, profile: Profile)

Base class for stable-priceability condition relaxation methods.

Parameters:

• instance (Instance) – An instance the relaxation is operating on.

• profile (Profile) – A profile the relaxation is operating on.

instance

An instance the relaxation is operating on.

Type:

Instance

profile

A profile the relaxation is operating on.

Type:

Profile

abstract add_beta(mip_model: Model) → None

Add beta variable to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

abstract add_objective(mip_model: Model) → None

Add objective function to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

abstract add_stability_constraint(mip_model: Model) → None

Add relaxed stability constraint to the model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

abstract get_beta(mip_model: Model) → Real | dict

Get the value of beta from the model. This method implicitly saves internally the value of beta variable from mip_model.

Parameters:

mip_model (Model) – The stable-priceability MIP model.

Returns:

The value of beta from the model.

Return type:

Real | dict

abstract get_relaxed_cost(project: Project) → float

Get relaxed cost of a project.

Parameters:

project (Project) – The project to get the relaxed cost for.

Returns:

Relaxed cost of the project.

Return type:

float

Properties Specific to the Method of Equal Shares

class ProjectLoss(project: Project, supporters_budget: int | float | mpq, budget_lost: dict[Project, int | float | mpq])

Class used to represent the projects and how much budget they lost due to other projects being picked. This extends the Project and thus represents the project itself.

Parameters:

• project (Project) – Project for which analytics is calculated.

• supporters_budget (Numeric) – The collective budget of the project supporters when project was considered by a rule.

• budget_lost (dict[Project, Numeric]) – Describes the amount of budget project supporters spent on other projects prior to this projects’ consideration.

supporters_budget

The collective budget of the project supporters when project was considered by rule.

Type:

Numeric

budget_lost

Describes the amount of budget project supporters spent on other projects prior to this projects’ consideration.

Type:

dict[Project, Numeric]

total_budget_lost() → int | float | mpq

Returns the total budget spent by project supporters on prior projects.

Returns:

The total budget spent.

Return type:

Numeric

calculate_effective_support(instance: Instance, profile: Profile, project: Project, was_picked: bool, mes_params: dict | None = None) → int

Calculates the effective support of a given project in a given instance, profile and mes election. Effective support for a project is an analytical metric which allows to measure the ratio of initial budget received to minimal budget required to win. Effective support is represented in percentages.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

• project (Project) – Project for which effective support is calculated. Must be a part of the instance.

• was_picked (bool) – Whether the considerd project was picked as a winner in the allocation.

• mes_params (dict, optional) – Dictionary of additional parameters that are passed as keyword arguments to the MES rule. Defaults to {}.

Returns:

The effective support value in percentages for project.

Return type:

int

calculate_effective_supports(instance: Instance, profile: Profile, allocation: BudgetAllocation, mes_params: dict | None = None, final_budget: int | float | mpq | None = None) → dict[Project, int]

Returns a dictionary of project and their effective support in a given instance, profile and mes election. Effective support for a project is an analytical metric which allows to measure the ratio of initial budget received to minimal budget required to win. Effective support is represented in percentages.

Parameters:

• instance (Instance) – The instance.

• profile (AbstractProfile) – The profile.

• allocation (BudgetAllocation) – Resulting allocation of the above instance & profile.

• mes_params (dict, optional) – Dictionary of additional parameters that are passed as keyword arguments to the MES rule. Defaults to None.

• final_budget (Numeric, optional) – Numeric value of the final budget which will replace the instance budget. Allows for simulating exhaustive MES.

Returns:

Dictionary of pairs (Project, effective support).

Return type:

dict[Project, int]

calculate_project_loss(allocation_details: AllocationDetails, verbose: bool = False) → list[ProjectLoss]

Returns a list of ProjectLoss objects for the projects.

Parameters:

• allocation_details (AllocationDetails) – The details of the budget allocation considered.

• verbose (bool, optional) – (De)Activate the display of additional information. Defaults to False.

Returns:

List of ProjectLoss objects.

Return type:

list[ProjectLoss]