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: Displayable

Groups of voters, blocks of items and their co-clusters, as a model found them.

coclustering[q, l] is the co-cluster of the group q and the block l. 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:

OrdinalScale

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:

CoclusterTable

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.

_shares(index, memberships)[source]

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:

VoterGroup

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:

ItemBlock

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

to_dict()[source]

Return plain lists and numbers, ready for JSON.

A float that is not finite becomes None. The fields proper to a subclass are added by it.

Return type:

dict[str, Any]

class civiqhub_selene.blocks.results.HasIntegratedLikelihood(*args, **kwargs)[source]

Bases: Protocol

A 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: Coclustering

A 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

_shares(index, memberships)[source]

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 is q on block_a and r on block_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 i and the item j, in the state s (its vote or its absence of vote, read without shown):

log( sum_c profile_probabilities[i, c]
           * sum_l block_memberships[j, l] * P(s | co-cluster (c_l, l)) )

where c runs over the profiles and c_l is the group of the profile on the block l.

Raises:

InvalidInputError – If votes does not have the voters, the items and the scale of the co-clustering.

Parameters:

votes (VoteMatrix)

Return type:

NDArray[float64]

to_dict()[source]

Return the common fields, the roles, the profiles and the log-likelihood.

Return type:

dict[str, Any]

class civiqhub_selene.blocks.results.PredictsVotes(*args, **kwargs)[source]

Bases: Protocol

A 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: Displayable

The 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], ...])

to_dict()[source]

Return plain lists; a score that is not finite becomes None.

Return type:

dict[str, Any]

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: Coclustering

A 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 votes does not have the voters, the items and the scale of the co-clustering.

Parameters:

votes (VoteMatrix)

Return type:

NDArray[float64]

to_dict()[source]

Return the common fields and the integrated likelihood.

Return type:

dict[str, Any]