class svvamp.GeneratorProfileVMFHypercircle(n_v, n_c, vmf_concentration, vmf_probability=None, vmf_pole=None, sort_voters=False)[source]

Profile generator using the Von Mises-Fisher distribution on the n_c - 2-sphere

Parameters:

  • n_v (int) – Number of voters.

  • n_c (int) – Number of candidates.

  • vmf_concentration (number or list or ndarray) – 1d array. Denote k its size (number of ‘groups’). vmf_concentration[i] is the VMF concentration of group i.

  • vmf_probability (number or list or ndarray) – 1d array of size k. vmf_probability[i] is the probability, for a voter, to be in group i (up to normalization). If None, then the groups have equal probabilities.

  • vmf_pole (list or ndarray) – 2d array of size (k, n_c). vmf_pole[i, :] is the pole of the VMF distribution for group i.

  • sort_voters (bool) – This argument is passed to Profile.

Notes

We work on the n_c - 2-sphere: vectors of \(\mathbb{R}^n_c\) with Euclidean norm equal to 1 and that are orthogonal to [1, …, 1]. It is a representation of the classical Von Neumann-Morgenstern utility space. Cf. Durand et al., ‘Geometry on the Utility Sphere’.

Before all computations, the poles are projected onto the hyperplane and normalized. So, the only source of concentration for group i is vmf_concentration[i], not the norm of vmf_pole[i]. If pole is None, then each pole is drawn independently and uniformly on the n_c - 2-sphere.

For each voter c, we draw a group i at random, according to vmf_probability (normalized beforehand if necessary). Then, v’s utility vector is drawn according to a Von Mises-Fisher distribution of pole vmf_pole[i, :] and concentration vmf_concentration[i], using Ulrich’s method modified by Wood.

Once group i is chosen, then up to a normalization constant, the density of probability for a unit vector x is exp(vmf_concentration[i] vmf.pole[i, :].x), where vmf.pole[i, :].x is a dot product.

Examples

Typical usage:

>>> initialize_random_seeds()
>>> generator = GeneratorProfileVMFHypercircle(n_v=5, n_c=3, vmf_concentration=10, sort_voters=True)
>>> profile = generator()
>>> profile.preferences_ut
array([[ 0.67886167, -0.73231774,  0.05345607],
       [ 0.62834837, -0.76570906,  0.1373607 ],
       [ 0.71859954, -0.6950244 , -0.02357514],
       [ 0.49333272, -0.81010857,  0.31677584],
       [ 0.63042345, -0.76457205,  0.1341486 ]])

You can specify a pole:

>>> initialize_random_seeds()
>>> generator = GeneratorProfileVMFHypercircle(n_v=5, n_c=3, vmf_concentration=10, vmf_pole=[.7, 0, -.7],
...                                            sort_voters=True)
>>> profile = generator()
>>> profile.preferences_ut
array([[ 0.8147627 , -0.36132374, -0.45343896],
       [ 0.44917711,  0.36590272, -0.81507983],
       [ 0.71021983, -0.00626776, -0.70395207],
       [ 0.68206757,  0.04766644, -0.72973402],
       [ 0.81591082, -0.38117577, -0.43473505]])

With several poles:

>>> initialize_random_seeds()
>>> generator = GeneratorProfileVMFHypercircle(n_v=5, n_c=3, vmf_concentration=[np.inf, np.inf],
...                                            vmf_probability=[.9, .1], sort_voters=True)
>>> profile = generator()
>>> profile.preferences_ut
array([[ 1.19716876,  0.82383355, -2.02100232],
       [ 0.71640317, -0.64749197, -0.0689112 ],
       [ 0.71640317, -0.64749197, -0.0689112 ],
       [ 0.71640317, -0.64749197, -0.0689112 ],
       [ 0.71640317, -0.64749197, -0.0689112 ]])

If the probabilities are not explicitly given, poles have equal probabilities:

>>> initialize_random_seeds()
>>> generator = GeneratorProfileVMFHypercircle(n_v=5, n_c=3, vmf_concentration=[np.inf, np.inf],
...                                            sort_voters=True)
>>> profile = generator()
>>> profile.preferences_ut
array([[ 1.19716876,  0.82383355, -2.02100232],
       [ 1.19716876,  0.82383355, -2.02100232],
       [ 1.19716876,  0.82383355, -2.02100232],
       [ 0.71640317, -0.64749197, -0.0689112 ],
       [ 0.71640317, -0.64749197, -0.0689112 ]])

References

Ulrich (1984) - Computer Generation of Distributions on the m-Sphere

Wood (1994) - Simulation of the von Mises Fisher distribution