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:
objectThe 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: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));
the block of each cell: for each item then each voter, drawn from the memberships of the item (uniform numbers of shape (P, M));
the co-cluster of a cell is (role of the voter on the block of the cell, block of the cell);
whether the cell carries a vote, with the vote rate of its co-cluster (uniform numbers of shape (M, P));
the latent opinion of the cell, normal with the mean and the spread of its co-cluster (standard normal numbers of shape (M, P));
the level of the vote: 1 plus the number of thresholds 1.5, 2.5, …,
n_levels - 0.5below 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 itemsi1, 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_levelsorseedis 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]