civiqhub_selene.blocks.results¶
What a co-clustering returns.
Coclustering carries what every model returns: the groups of voters, the
blocks of items, the table of the co-clusters, and what it takes to judge the
computation. SingleCoclustering and MixedCoclustering add what is
proper to a single and to a mixed membership; their names take the two words of the
membership choice.
Two protocols, checkable at run time, say what a value can do: a criterion relies on them, not on the name of a class.
- class civiqhub_selene.blocks.results.Coclustering(*, computation, voters, items, scale, group_index, block_index, group_memberships, block_memberships, coclusters, objective, history, selection=None)[source]¶
Bases:
DisplayableGroups of voters, blocks of items and their co-clusters, as a model found them.
coclustering[q, l]is the co-cluster of the groupqand the blockl. Arrays are copied and made read-only.- computation¶
Fingerprint of the computation that produced the value.
- Type:
str
- voters¶
The voters, in the order of the matrix.
- Type:
tuple[str, …]
- items¶
The items, in the order of the matrix.
- Type:
tuple[str, …]
- scale¶
The scale of scores.
- Type:
- group_index¶
Shape (M,): for each voter, the index of its main group.
- Type:
numpy._typing._array_like.NDArray[numpy.int64]
- block_index¶
Shape (P,): for each item, the index of its main block.
- Type:
numpy._typing._array_like.NDArray[numpy.int64]
- group_memberships¶
Shape (M, Q): degree of membership of each voter to each group, rows summing to 1.
- Type:
numpy._typing._array_like.NDArray[numpy.float64]
- block_memberships¶
Shape (P, L): the same for items and blocks.
- Type:
numpy._typing._array_like.NDArray[numpy.float64]
- coclusters¶
The table of the Q x L co-clusters.
- Type:
- objective¶
The quantity the algorithm maximised. It only compares computations of the same method on the same data.
- Type:
float
- history¶
The objective after each iteration of the start that was kept, and whether it converged.
- Type:
civiqhub_selene.blocks._numerics.History
- selection¶
The trace of the choice of shape, when the shape was chosen by comparison.
- Type:
Selection | None
- Raises:
InvalidInputError – If the shapes of the arrays do not agree with the voters, the items and the table.
- Parameters:
computation (str)
voters (tuple[str, ...])
items (tuple[str, ...])
scale (OrdinalScale)
group_index (NDArray[int64])
block_index (NDArray[int64])
group_memberships (NDArray[float64])
block_memberships (NDArray[float64])
coclusters (CoclusterTable)
objective (float)
history (History)
selection (Selection | None)
- property n_groups: int¶
The number of groups of voters.
- property n_blocks: int¶
The number of blocks of items.
Return the share of each cluster: its size over the number of identifiers.
- Parameters:
index (NDArray[int64])
memberships (NDArray[float64])
- Return type:
NDArray[float64]
- property groups: Partition[VoterGroup][source]¶
The groups of voters, as a partition that cites this computation.
- property blocks: Partition[ItemBlock][source]¶
The blocks of items, as a partition that cites this computation.
- group_of(voter)[source]¶
Return the main group of a voter.
- Raises:
InvalidInputError – If the voter is not in the co-clustering.
- Parameters:
voter (str)
- Return type:
- block_of(item)[source]¶
Return the main block of an item.
- Raises:
InvalidInputError – If the item is not in the co-clustering.
- Parameters:
item (str)
- Return type:
- display_order()[source]¶
Return the order of voters and of items that sorts the matrix by groups and blocks.
The sort is stable: the order inside a group, or inside a block, is kept.
- Return type:
tuple[NDArray[int64], NDArray[int64]]
- fingerprint()[source]¶
Return a stable fingerprint of what was found: 16 hexadecimal characters.
SHA-256 of the voters, the items and the scores, then the bytes of the indices, the memberships, and the vote rates and vote shares of the table. The history, the objective and the trace of the choice of shape are left out.
- Return type:
str
- class civiqhub_selene.blocks.results.HasIntegratedLikelihood(*args, **kwargs)[source]¶
Bases:
ProtocolA value that carries an integrated likelihood, for the criterion of that name.
- property integrated_likelihood: float¶
The integrated completed likelihood; larger is better.
- class civiqhub_selene.blocks.results.MixedCoclustering(*, computation, voters, items, scale, group_index, block_index, group_memberships, block_memberships, coclusters, objective, history, selection=None, role_by_block, profiles, profile_probabilities, log_likelihood)[source]¶
Bases:
CoclusteringA co-clustering where a voter can follow different groups on different blocks.
A profile is one choice of a group per block; with Q groups and L blocks there are Q**L of them.
- Parameters:
computation (str)
voters (tuple[str, ...])
items (tuple[str, ...])
scale (OrdinalScale)
group_index (NDArray[int64])
block_index (NDArray[int64])
group_memberships (NDArray[float64])
block_memberships (NDArray[float64])
coclusters (CoclusterTable)
objective (float)
history (History)
selection (Selection | None)
role_by_block (NDArray[float64])
profiles (NDArray[int64])
profile_probabilities (NDArray[float64])
log_likelihood (float)
- role_by_block¶
Shape (M, L, Q): for each voter and each block, the probability that the voter follows each group on this block.
- Type:
numpy._typing._array_like.NDArray[numpy.float64]
- profiles¶
Shape (Q**L, L), integers: every profile, the group followed on each block, in the order of
itertools.product(range(Q), repeat=L).- Type:
numpy._typing._array_like.NDArray[numpy.int64]
- profile_probabilities¶
Shape (M, Q**L): for each voter, the probability of each profile.
- Type:
numpy._typing._array_like.NDArray[numpy.float64]
- log_likelihood¶
The observed log-likelihood.
- Type:
float
Return the share of each cluster: the mean of the memberships.
- Parameters:
index (NDArray[int64])
memberships (NDArray[float64])
- Return type:
NDArray[float64]
- property mixedness: NDArray[float64]¶
Shape (M,): one minus the largest membership of each voter.
0 for a voter who belongs to a single group. It is published as a histogram over the voters, never as a list by voter.
- role_changes(block_a=0, block_b=1)[source]¶
Count the voters by the group they follow on two blocks.
- Returns:
Integers of shape (Q, Q) – entry
[q, r]is the number of voters whose most probable group isqonblock_aandronblock_b. Off the diagonal, a voter changes role.- Raises:
InvalidInputError – If a block does not exist.
- Parameters:
block_a (int)
block_b (int)
- Return type:
NDArray[int64]
- log_probability(votes)[source]¶
Return, for each cell, the log-probability of its state under the model.
Shape (M, P). For the cell of the voter
iand the itemj, in the states(its vote or its absence of vote, read withoutshown):log( sum_c profile_probabilities[i, c] * sum_l block_memberships[j, l] * P(s | co-cluster (c_l, l)) )
where
cruns over the profiles andc_lis the group of the profile on the blockl.- Raises:
InvalidInputError – If
votesdoes not have the voters, the items and the scale of the co-clustering.- Parameters:
votes (VoteMatrix)
- Return type:
NDArray[float64]
- class civiqhub_selene.blocks.results.PredictsVotes(*args, **kwargs)[source]¶
Bases:
ProtocolA value that gives the probability of the state of each cell of a vote matrix.
- log_probability(votes)[source]¶
Return, for each cell, the log-probability of its state, of shape (M, P).
- Parameters:
votes (VoteMatrix)
- Return type:
NDArray[float64]
- class civiqhub_selene.blocks.results.Selection(*, criterion, n_groups, n_blocks, scores, standard_errors=None, best, alternatives=())[source]¶
Bases:
DisplayableThe trace of a choice of shape.
- criterion¶
Key of the criterion that compared the shapes.
- Type:
str
- n_groups¶
The numbers of groups compared.
- Type:
tuple[int, …]
- n_blocks¶
The numbers of blocks compared.
- Type:
tuple[int, …]
- scores¶
Shape (len(n_groups), len(n_blocks)): the score of each shape; larger is better.
- Type:
numpy._typing._array_like.NDArray[numpy.float64]
- standard_errors¶
The standard error of each score, when the criterion gives one.
- Type:
numpy._typing._array_like.NDArray[numpy.float64] | None
- best¶
The shape kept,
(n_groups, n_blocks).- Type:
tuple[int, int]
- alternatives¶
The shapes within one standard error of the best one.
- Type:
tuple[tuple[int, int], …]
- Raises:
InvalidInputError – If the scores do not have the shape of the grid, or if the best shape is not on the grid.
- Parameters:
criterion (str)
n_groups (tuple[int, ...])
n_blocks (tuple[int, ...])
scores (NDArray[float64])
standard_errors (NDArray[float64] | None)
best (tuple[int, int])
alternatives (tuple[tuple[int, int], ...])
- class civiqhub_selene.blocks.results.SingleCoclustering(*, computation, voters, items, scale, group_index, block_index, group_memberships, block_memberships, coclusters, objective, history, selection=None, integrated_likelihood)[source]¶
Bases:
CoclusteringA co-clustering where each voter belongs to one group and each item to one block.
- Parameters:
computation (str)
voters (tuple[str, ...])
items (tuple[str, ...])
scale (OrdinalScale)
group_index (NDArray[int64])
block_index (NDArray[int64])
group_memberships (NDArray[float64])
block_memberships (NDArray[float64])
coclusters (CoclusterTable)
objective (float)
history (History)
selection (Selection | None)
integrated_likelihood (float)
- integrated_likelihood¶
The integrated completed likelihood criterion (ICL, Biernacki, Celeux and Govaert 2000); larger is better.
- Type:
float
- log_probability(votes)[source]¶
Return, for each cell, the log-probability of its state under the model.
Shape (M, P). The state of a cell is its vote or its absence of vote, read without
shown; its probability is the one of the co-cluster of its voter and of its item.- Raises:
InvalidInputError – If
votesdoes not have the voters, the items and the scale of the co-clustering.- Parameters:
votes (VoteMatrix)
- Return type:
NDArray[float64]