metrics

appointment.metrics provides diagnostics to analyze the results of elections, apportionments, and other political science scenarios.

Functions

• poli_sci_kit.appointment.metrics.ideal_share()

• poli_sci_kit.appointment.metrics.alloc_to_share_ratio()

• poli_sci_kit.appointment.metrics.sqr_alloc_to_share_error()

• poli_sci_kit.appointment.metrics.total_alloc_to_share_error()

• poli_sci_kit.appointment.metrics.rep_weight()

• poli_sci_kit.appointment.metrics.sqr_rep_weight_error()

• poli_sci_kit.appointment.metrics.total_rep_weight_error()

• poli_sci_kit.appointment.metrics.div_index()

• poli_sci_kit.appointment.metrics.effective_number_of_groups()

• poli_sci_kit.appointment.metrics.dispr_index()

poli_sci_kit.appointment.metrics.ideal_share(share, total_shares, total_alloc)

Calculate the ideal share of proportions and totals.

Parameters:

shareint

The proportion to be checked.

total_sharesint

The total amount of shares.

total_allocint

The number of allocations to provide.

Returns:

idealfloat

The ideal share that would be allocated.

poli_sci_kit.appointment.metrics.alloc_to_share_ratio(share, total_shares, allocation, total_alloc)

Calculate the allocation to share (advantage) ratio given to a region or group.

Parameters:

shareint

The proportion to be checked.

total_sharesint

The total amount of shares.

allocationint

The share of allocations given to the region or group.

total_allocint

The number of allocations to provide.

Returns:

asrfloat

The ratio of the allocations the region or group received to their proportion of the original shares.

poli_sci_kit.appointment.metrics.sqr_alloc_to_share_error(share, total_shares, allocation, total_alloc)

Calculate the squared error of an assignment’s allocation to share ratio for a population or group.

Parameters:

shareint

The proportion to be checked.

total_sharesint

The total amount of shares.

allocationint

The share of allocations given to the region or group.

total_allocint

The number of allocations to provide.

Returns:

sqr_asr_errfloat

The squared of the error of the allocation to share ratio.

poli_sci_kit.appointment.metrics.total_alloc_to_share_error(shares, allocations, proportional=True)

Calculate the total squared error of an assignment’s allocation to share ratio.

Parameters:

shareslist

The proportion of the original shares for the regions or groups.

allocationslist

The share of allocations given to the regions or groups.

proportionalbool (default=False)

Whether the assignment’s error is calculated as proportional to the region or group shares.

Returns:

total_asr_errfloat

The summation of the allocation to share ratio error for all populations or groups.

poli_sci_kit.appointment.metrics.rep_weight(share, allocation)

Calculate the representative weight of an allocation to a region or group.

Parameters:

shareint

The proportion to be checked.

allocationint

The allocation provided.

Returns:

rep_weightfloat

The number of shares per allocation.

poli_sci_kit.appointment.metrics.sqr_rep_weight_error(share, total_shares, allocation, total_alloc)

Calculate the squared error of an assignment’s representative weight for a population or group.

Parameters:

shareint

The proportion to be checked.

total_sharesint

The total amount of shares.

allocationint

The share of allocations given to the region or group.

total_allocint

The number of allocations to provide.

Returns:

sqr_rw_errfloat

The squared of the error of the allocation to share ratio.

poli_sci_kit.appointment.metrics.total_rep_weight_error(shares, allocations, proportional=True)

Calculate the total squared error of an assignment’s representative weight error.

Parameters:

shareslist

The proportion of the original shares for the regions or groups.

allocationslist

The share of allocations given to the regions or groups.

proportionalbool (default=False)

Whether the assignment’s error is calculated as proportional to the region or group shares.

Returns:

total_rw_errfloat

The summation of the representative weight error for all populations or groups.

poli_sci_kit.appointment.metrics.div_index(shares, q=None, metric_type='Shannon')

Calculates the diversity index: the uncertainty associated with predicting further elements within the vote or population distributions.

Parameters:

shareslist

The proportion of the original shares for the regions or groups.

qfloat

The order of diversity (a weight value for the sensitivity of the diversity value to rare vs. abundant).

metric_typestr (default=Shannon)

The type of formula to use.

Options:

The available measures of diversity.

• Shannon : approaches zero (one) when shares are concentrated (dispersed), uncertainty (certainty) of the next element goes to zero.

• Renyi : generalization of the Shannon diversity.

• Simpson : probability that two entities taken at random from the dataset of interest represent the same type (assumes replacement).

• Gini-Simpson : opposite of the Simpson diversity, the probability that two entities are from different types.

• Berger-Parker : proportional abundance of the most abundant type.

• Effective : number of equally abundant types needed for the average proportional abundance of types to equal that of the dataset.

Returns:

indexfloat

The measure of diversity given the share distribution.

poli_sci_kit.appointment.metrics.effective_number_of_groups(shares, metric_type='Laakso-Taagepera')

Calculates the effective number of groups given vote or population distributions.

Parameters:

shareslist

The proportion of the original shares for the regions or groups.

metric_typestr (default=Laakso-Taagepera, options=Golosov, Inverse-Simpson)

The type of formula to use.

Returns:

num_groupsfloat

A float representing the efficient number of groups given the share distributions.

poli_sci_kit.appointment.metrics.dispr_index(shares, allocations, metric_type='Gallagher')

Measures of the degree to which the actual allocations deviates from the shares, with larger indexes implying greater disproportionality.

Parameters:

shareslist

The proportion of the original shares for the regions or groups.

allocationslist

The share of allocations given to the regions or groups.

metric_typestr (default=Gallagher)

The type of formula to use.

Options:

The available measures of disproportionality.

• Gallagher : measure of absolute difference in percent of allocations received to true proportion.

  Note 1: accounts for magnitudes of the individual shifts.

  Note 2: deals with the magnitudes of the disproportionality, not the percentage differences from ideality.

  Note 3: a general form with k instead of the square root, 1/2 and second power is not monotone to k, as is thus not included.

• Loosemore–Hanby : the total excess of allocated shares of overrepresented groups over the exact quota and the total shortage accruing to other groups.

  Note 1: is not consistent (it fails Dalton’s principle of transfers, where transfering shares may lead to adverse effects on allocations).

  Note 2: does not account for the magnitude of individual disproportionality (that few large shifts should potentially be worse than many small).

• Rose : 100 minus the Loosemore–Hanby index, so in this case larger numbers are better (suffers from similar issues).

• Rae : measure of the average absolute difference in percent of allocations received to true proportion.

  Note 1: includes the number of groups in the calculation, and thus is effected if there are many small groups.

  Note 2: don’t use to compare appointments across situations with different numbers of groups.

• Sainte-Laguë (chi-squared) : measure of relative difference in percent of allocations received to true proportion.

  Note 1: has no upper limit.

  Note 2: downplays the disproportionality that effects larger groups.

  Note 3: sensitive to if there are is large portion of the shares that are ‘other’ and don’t receive votes.

• d’Hondt : measure of relative difference in percent of allocations received to true proportion.

  Note: does not account for the magnitude of individual disproportionality (that few large shifts should be worse than many small).

• Cox-Shugart : the slope of the line of best fit between the shares and allocations.

  Note 1: main advantage is directly showing whether larger or smaller groups are benefitting (>1 or <1 respectively).

  Note 2: this index can be negative, and if it is, that implies a negative shares-allocations ratio.

Note: the Gini index as a measure of disproportionality is not included, as in many cases smaller groups have a greater allocation proportion.

Returns:

indexfloat

A measure of disproportionality between allocations and original shares.