civiqhub_selene.blocks.synthetic

Synthetic votes with a planted truth.

The engine is tested and documented on synthetic data only. make_votes() draws a collective whose truth is known: who belongs to which group, which item to which block, and how each group answers each block. No identifier resembles real data: voters are v1, v2, ... and items i1, i2, ....

civiqhub_selene.blocks.synthetic.DEFAULT_LATENT_MEAN = ((4.7, 1.4), (1.3, 4.6), (3.0, 3.0))

Mean of the latent opinion on the axis of levels, from 1 to 5.

Group 0 approves block 0 and rejects block 1, group 1 does the opposite, group 2 is neutral.

civiqhub_selene.blocks.synthetic.DEFAULT_LATENT_SPREAD = ((0.6, 0.7), (0.7, 0.6), (1.0, 1.0))

Standard deviation of the latent opinion, for 3 groups and 2 blocks.

civiqhub_selene.blocks.synthetic.DEFAULT_VOTE_RATE = ((0.85, 0.45), (0.55, 0.9), (0.4, 0.4))

Share of cells that carry a vote, for 3 groups (rows) and 2 blocks (columns).

class civiqhub_selene.blocks.synthetic.PlantedTruth(voter_memberships, item_memberships, roles)[source]

Bases: object

The truth planted in a synthetic collective.

Parameters:
  • voter_memberships (NDArray[float64])

  • item_memberships (NDArray[float64])

  • roles (NDArray[int64])

voter_memberships

Shape (M, Q): degree of membership of each voter to each group.

Type:

numpy._typing._array_like.NDArray[numpy.float64]

item_memberships

Shape (P, L): degree of membership of each item to each block.

Type:

numpy._typing._array_like.NDArray[numpy.float64]

roles

Shape (M, L): the group each voter follows on each block.

Type:

numpy._typing._array_like.NDArray[numpy.int64]

civiqhub_selene.blocks.synthetic.make_votes(voter_memberships, item_memberships, *, vote_rate=DEFAULT_VOTE_RATE, latent_mean=DEFAULT_LATENT_MEAN, latent_spread=DEFAULT_LATENT_SPREAD, n_levels=5, seed=0)[source]

Draw synthetic votes from a planted truth. These are not real data.

With memberships to a single cluster on both sides, this is exactly the latent block model; with spread memberships, it is the mixed-membership model.

The draw is made with numpy.random.default_rng(seed), in this exact order, which is part of the reproducibility contract:

  1. the roles: for each voter then each block, the group the voter follows on this block, drawn from the memberships of the voter (uniform numbers of shape (M, L));

  2. the block of each cell: for each item then each voter, drawn from the memberships of the item (uniform numbers of shape (P, M));

  3. the co-cluster of a cell is (role of the voter on the block of the cell, block of the cell);

  4. whether the cell carries a vote, with the vote rate of its co-cluster (uniform numbers of shape (M, P));

  5. the latent opinion of the cell, normal with the mean and the spread of its co-cluster (standard normal numbers of shape (M, P));

  6. the level of the vote: 1 plus the number of thresholds 1.5, 2.5, …, n_levels - 0.5 below the opinion; 0 when the cell carries no vote.

Every cell of the matrix is shown: a cell without a vote is an abstention.

Parameters:
  • voter_memberships (ArrayLike) – Shape (M, Q): for each voter, its degree of membership to each group. Rows sum to 1. Use single_memberships() for plain groups.

  • item_memberships (ArrayLike) – Shape (P, L): for each item, its degree of membership to each block. Rows sum to 1.

  • vote_rate (ArrayLike) – Shape (Q, L): share of the cells of each co-cluster that carry a vote, between 0 and 1.

  • latent_mean (ArrayLike) – Shape (Q, L): where each group stands on each block, on the axis of levels from 1 to n_levels.

  • latent_spread (ArrayLike) – Shape (Q, L): how much the opinions of a group vary on a block, strictly positive.

  • n_levels (int) – The number of scores of the scale. With 5, the scale is the agreement scale from -2 to +2; otherwise the scores are 1 to n_levels.

  • seed (int) – Seed of every draw, a non-negative integer.

Returns:

The vote matrix, with voters v1, v2, ... and items i1, i2, ..., and the planted truth.

Raises:

InvalidParameterError – If a row of memberships does not sum to 1, if a parameter table does not have the shape (Q, L), if a rate is outside [0, 1], if a spread is not strictly positive, or if n_levels or seed is out of range.

Return type:

tuple[VoteMatrix, PlantedTruth]

civiqhub_selene.blocks.synthetic.single_memberships(sizes)[source]

Return the memberships of identifiers that each belong to a single cluster.

Rows are indicators, cluster after cluster: single_memberships((2, 1)) is [[1, 0], [1, 0], [0, 1]].

Raises:

InvalidParameterError – If a size is not a non-negative integer.

Parameters:

sizes (tuple[int, ...])

Return type:

NDArray[float64]