civiqhub_selene.blocks.coclusters

Co-clusters and their table.

A co-cluster is the pair of a group of voters and a block of items: the zone of the matrix where this group answers this block. CoclusterTable summarises each co-cluster by a vote rate and a distribution of the answers.

class civiqhub_selene.blocks.coclusters.Cocluster(group, block, vote_rate, vote_shares, n_votes, latent_mean, latent_spread, scores)[source]

Bases: object

One co-cluster: how a group of voters answers a block of items.

Parameters:
  • group (int)

  • block (int)

  • vote_rate (float)

  • vote_shares (tuple[float, ...])

  • n_votes (float)

  • latent_mean (float | None)

  • latent_spread (float | None)

  • scores (tuple[int, ...])

group

Index of the group of voters.

Type:

int

block

Index of the block of items.

Type:

int

vote_rate

Share of the shown cells that carry a vote.

Type:

float

vote_shares

Distribution of the votes over the scores of the scale, summing to 1.

Type:

tuple[float, …]

n_votes

Number of votes: an integer for plain groups, fractional for a mixed membership.

Type:

float

latent_mean

Mean of the latent opinion under the ordinal probit response model, on the axis of levels; None under another response model.

Type:

float | None

latent_spread

Standard deviation of the latent opinion, likewise.

Type:

float | None

scores

The scores of the scale.

Type:

tuple[int, …]

property typical_score: int

The score with the largest share of votes.

On a tie, the score closest to the middle of the scale; if two tied scores are equally close, the lower one.

class civiqhub_selene.blocks.coclusters.CoclusterTable(scale, vote_rate, vote_shares, n_votes, latent_mean=None, latent_spread=None)[source]

Bases: Displayable

The table of the co-clusters of Q groups and L blocks.

table[q, l] is one Cocluster; iteration yields every co-cluster, group by group. Arrays are copied and made read-only.

scale

The scale of scores, with K levels.

Type:

OrdinalScale

vote_rate

Shape (Q, L): share of the shown cells that carry a vote.

Type:

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

vote_shares

Shape (Q, L, K): distribution of the votes over the scores.

Type:

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

n_votes

Shape (Q, L): number of votes.

Type:

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

latent_mean

Shape (Q, L): mean of the latent opinion under the ordinal probit response model; None otherwise.

Type:

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

latent_spread

Shape (Q, L): standard deviation of the latent opinion, likewise.

Type:

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

Raises:

InvalidInputError – If the shapes do not agree, if a rate is outside [0, 1], if a distribution does not sum to 1 within 1e-6, or if a count is negative.

Parameters:
  • scale (OrdinalScale)

  • vote_rate (NDArray[float64])

  • vote_shares (NDArray[float64])

  • n_votes (NDArray[float64])

  • latent_mean (NDArray[float64] | None)

  • latent_spread (NDArray[float64] | None)

property shape: tuple[int, int]

The number of groups and the number of blocks.

log_probabilities()[source]

Return the log-probability of each state of a shown cell, per co-cluster.

Shape (Q, L, K + 1). State 0 (shown without a vote): log(1 - vote_rate); state k: log(vote_rate) + log(vote_shares[k]). Probabilities are floored at 1e-300 before the logarithm.

Return type:

NDArray[float64]

to_dict()[source]

Return plain lists: the scores, the three tables, and the latent parameters if any.

Return type:

dict[str, Any]