Generate Spatial Profiles¶

pref_voting.generate_spatial_profiles.generate_covariance(n_dimensions, std, rho)[source]¶

Generates a covariance matrix for a multivariate normal distribution with the given standard deviation and correlation coefficient.

Parameters:

n_dimensions (int) – The number of dimensions.
std (float) – The standard deviation.
rho (float) – The correlation coefficient.

Returns:

cov – The covariance matrix for a multivariate normal distribution.

Return type:

numpy.ndarray

pref_voting.generate_spatial_profiles.generate_spatial_profile(num_cands, num_voters, num_dims, cand_cov=None, voter_cov=None, num_profiles=1)[source]¶

Generates a spatial profile with the candidate and voter positions generated by a multivariate normal distribution with num_dims dimensions and cand_cov the covariance matrix for candidates and voter_cov the covariance matrix for voters.

Parameters:

num_cands (int) – The number of candidates.
num_voters (int) – The number of voters.
num_dims (int) – The number of dimensions.
cand_cov (numpy.ndarray, optional) – The covariance matrix for the multivariate normal distribution for candidates. The default is None.
voter_cov (numpy.ndarray, optional) – The covariance matrix for the multivariate normal distribution for voters. The default is the identity matrix.

Returns:

A spatial profile with the candidate and voter positions generated by a multivariate normal distribution with num_dims dimensions and cand_cov the covariance matrix for candidates and voter_cov the covariance matrix for voters.

Return type:

SpatialProfile

Generate Spatial Profiles - Polarized¶

pref_voting.generate_spatial_profiles.generate_spatial_profile_polarized(cand_clusters, voter_clusters, cluster_types=None, num_profiles=1)[source]¶

Generates a spatial profile with polarized clusters of candidates and voters.

Parameters:

cand_clusters (list) – A list of tuples of the form (mean, covariance, number of candidates) for each cluster of candidates.
voter_clusters (list) – A list of tuples of the form (mean, covariance, number of voters) for each cluster of voters.
cluster_types (dict, optional) – A list of the same length as cand_cluster that associates each cluster to the type of candidate. The default is None.
num_profiles (int, optional) – The number of profiles to generate. The default is 1.

Returns:

A spatial profile with polarized clusters of candidates and voters.

Return type:

SpatialProfile

Generate Spatial Profiles from Binned Distribution¶

class pref_voting.generate_spatial_profile_from_binned_distribution.BinnedDistribution(bin_lows, bin_highs, bin_probs, regions=None, name=None, metadata=None)[source]¶

A binned empirical distribution: a set of axis-aligned bins (boxes), piecewise-uniform within each bin, with bins grouped into named regions.

Any object with a num_dims attribute and a sample(num, rng) method returning a (num, num_dims) array can serve as a voter distribution for the random candidate model; the structured model additionally needs regions and sample_in_region.

Parameters:

bin_lows – (num_bins, num_dims) lower corner of each bin (a (num_bins,) array is accepted as 1D).
bin_highs – (num_bins, num_dims) upper corner of each bin.
bin_probs – probabilities for the bins (normalized if necessary).
regions (dict, optional) – maps a region name to the list of bin indices it spans, e.g. {"left": [0, 1], "centrist": [2], "right": [3, 4]}.
name (str, optional) – a human-readable name.
metadata (dict, optional) – provenance information.

classmethod from_binned(bin_edges, bin_probs, regions=None, name=None, metadata=None)[source]¶: A 1D distribution that is piecewise-uniform on consecutive bin_edges (length k + 1 for k bins), with optional named regions.

classmethod from_boxes(bin_lows, bin_highs, bin_probs, regions=None, name=None, metadata=None)[source]¶: A binned distribution from explicit bin boxes (any dimension).

classmethod from_ces(region, source='atkinson', bin_edges=None, regions=None, data_path='/home/docs/checkouts/readthedocs.org/user_builds/pref-voting/envs/latest/lib/python3.12/site-packages/pref_voting/voter_distributions/ces2020_voter_distributions.json')[source]¶

Loads a stored CES 2020 voter distribution (1D).

Parameters:

region (str) – a two-letter state abbreviation (e.g. “AK”), or “US”.
source (str) – “atkinson” (5-bin pid7 party ID) or “mccune” (7-bin CC20_340a ideology).
bin_edges (array, optional) – overrides the stored bin edges (one more entry than the number of bins).
regions (dict, optional) – overrides the default left/centrist/right grouping.

plot(ax=None, color_by_region=False, cmap='viridis')[source]¶

Plot the distribution’s density (1D or 2D only).

1D: a histogram of bin densities (bar height = bin_prob / bin_width). 2D: a heatmap of bin densities (each bin shaded by bin_prob / bin_area). With color_by_region=True, bins are instead colored by the region they belong to (1D) or each region is shaded a distinct color (2D), and a legend is drawn; bins in no region are gray.

Returns the matplotlib Axes.

sample(num, rng=None)[source]¶: Returns a (num, num_dims) array of positions from the full distribution.

sample_in_region(region, num, rng=None)[source]¶: Returns a (num, num_dims) array of positions from the distribution restricted to region’s bins (bin chosen in proportion to its probability, then uniform within the bin). If the region’s bins carry no probability mass, the bin is chosen in proportion to its volume instead, so a zero-mass region can still be populated.

property support¶: (num_dims, 2) array of the (lo, hi) extent in each dimension.

pref_voting.generate_spatial_profile_from_binned_distribution.generate_spatial_profile_from_binned_distribution(num_cands, num_voters, voter_dist, cand_dist=None, candidate_counts=None, candidate_type_probs=None, num_profiles=1, seed=None, rng=None)[source]¶

Generate spatial profiles with voter and candidate positions from binned distributions.

Parameters:

num_cands (int) – the number of candidates.
num_voters (int) – the number of voters.
voter_dist (BinnedDistribution) – the voters’ distribution.
cand_dist (BinnedDistribution, optional) – the candidates’ distribution; defaults to voter_dist (candidates come from the voters’ population).
candidate_counts (dict, optional) – exact composition, mapping region name to a count (the counts must sum to num_cands). Selects the structured model.
candidate_type_probs (dict, optional) – probabilistic composition, mapping region name to a probability (summing to 1); each candidate’s region is drawn independently. Selects the structured model.
num_profiles (int) – the number of profiles to generate.
seed (int, optional) – seed for a fresh generator (used when rng is None).
rng (numpy.random.Generator, optional) – generator to draw from; takes precedence over seed.

With neither candidate_counts nor candidate_type_probs (the random model), candidate positions are i.i.d. draws from cand_dist. In the structured model, each candidate’s region is chosen by the given counts/probabilities and its position is drawn from cand_dist restricted to that region’s bins; the regions are recorded in SpatialProfile.candidate_types.

Returns:: A SpatialProfile (or a list of SpatialProfiles if num_profiles > 1).