Source code for civiqhub_selene.blocks.coclusters

# Copyright 2026 CiviqHub SAS
# SPDX-License-Identifier: Apache-2.0

"""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. :class:`CoclusterTable` summarises each
co-cluster by a vote rate and a distribution of the answers.
"""

from collections.abc import Iterator
from dataclasses import dataclass
from typing import Any

import numpy as np
from numpy.typing import ArrayLike

from civiqhub_selene.blocks._arrays import FloatArray
from civiqhub_selene.blocks.data import OrdinalScale
from civiqhub_selene.errors import InvalidInputError
from civiqhub_selene.types import Displayable

__all__ = ["Cocluster", "CoclusterTable"]

_MIN_PROBABILITY = 1e-300
_SUM_TOLERANCE = 1e-6


[docs] @dataclass(frozen=True, repr=False) class Cocluster: """One co-cluster: how a group of voters answers a block of items. Attributes: group: Index of the group of voters. block: Index of the block of items. vote_rate: Share of the shown cells that carry a vote. vote_shares: Distribution of the votes over the scores of the scale, summing to 1. n_votes: Number of votes: an integer for plain groups, fractional for a mixed membership. latent_mean: Mean of the latent opinion under the ordinal probit response model, on the axis of levels; ``None`` under another response model. latent_spread: Standard deviation of the latent opinion, likewise. scores: The scores of the scale. """ 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, ...] @property def typical_score(self) -> 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. """ middle = (len(self.scores) - 1) / 2 best = max( range(len(self.scores)), key=lambda rank: (self.vote_shares[rank], -abs(rank - middle), -rank), ) return self.scores[best] def __repr__(self) -> str: typical = self.typical_score return ( f"Cocluster(group={self.group}, block={self.block}, " f"vote_rate={self.vote_rate:.3f}, typical_score={typical:+d}, " f"n_votes={self.n_votes:g})" )
def state_log_probabilities(vote_rate: FloatArray, vote_shares: FloatArray) -> FloatArray: """Return the log-probability of each state of a shown cell, per co-cluster. Shape (Q, L, K + 1) from a vote rate of shape (Q, L) and vote shares of shape (Q, L, K). 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. """ rate = vote_rate[..., np.newaxis] probabilities = np.concatenate([1.0 - rate, rate * vote_shares], axis=-1) logs: FloatArray = np.log(np.maximum(probabilities, _MIN_PROBABILITY)) return logs def _array(values: ArrayLike, name: str) -> FloatArray: try: array: FloatArray = np.array(values, dtype=np.float64) except (TypeError, ValueError) as error: raise InvalidInputError(f"{name} is an array of numbers: {error}") from error if not np.isfinite(array).all(): raise InvalidInputError(f"{name} holds a value that is not finite") array.setflags(write=False) return array
[docs] @dataclass(frozen=True, eq=False, repr=False) class CoclusterTable(Displayable): """The table of the co-clusters of Q groups and L blocks. ``table[q, l]`` is one :class:`Cocluster`; iteration yields every co-cluster, group by group. Arrays are copied and made read-only. Attributes: scale: The scale of scores, with K levels. vote_rate: Shape (Q, L): share of the shown cells that carry a vote. vote_shares: Shape (Q, L, K): distribution of the votes over the scores. n_votes: Shape (Q, L): number of votes. latent_mean: Shape (Q, L): mean of the latent opinion under the ordinal probit response model; ``None`` otherwise. latent_spread: Shape (Q, L): standard deviation of the latent opinion, likewise. 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. """ scale: OrdinalScale vote_rate: FloatArray vote_shares: FloatArray n_votes: FloatArray latent_mean: FloatArray | None = None latent_spread: FloatArray | None = None def __post_init__(self) -> None: if not isinstance(self.scale, OrdinalScale): raise InvalidInputError(f"the scale is an OrdinalScale, got {self.scale!r}") vote_rate = _array(self.vote_rate, "vote_rate") vote_shares = _array(self.vote_shares, "vote_shares") n_votes = _array(self.n_votes, "n_votes") if vote_rate.ndim != 2: raise InvalidInputError( f"vote_rate has the shape (groups, blocks), got {vote_rate.shape}" ) expected = (*vote_rate.shape, self.scale.n_levels) if vote_shares.shape != expected: raise InvalidInputError( f"vote_shares has the shape (groups, blocks, levels) = {expected}, " f"got {vote_shares.shape}" ) if n_votes.shape != vote_rate.shape: raise InvalidInputError( f"n_votes has the shape {vote_rate.shape} of vote_rate, got {n_votes.shape}" ) if ((vote_rate < 0) | (vote_rate > 1)).any(): raise InvalidInputError("a vote rate is between 0 and 1") if (vote_shares < 0).any() or ( np.abs(vote_shares.sum(axis=-1) - 1.0) > _SUM_TOLERANCE ).any(): raise InvalidInputError("the vote shares of a co-cluster are not negative and sum to 1") if (n_votes < 0).any(): raise InvalidInputError("a number of votes is not negative") object.__setattr__(self, "vote_rate", vote_rate) object.__setattr__(self, "vote_shares", vote_shares) object.__setattr__(self, "n_votes", n_votes) for name in ("latent_mean", "latent_spread"): received = getattr(self, name) if received is None: continue latent = _array(received, name) if latent.shape != vote_rate.shape: raise InvalidInputError( f"{name} has the shape {vote_rate.shape} of vote_rate, got {latent.shape}" ) object.__setattr__(self, name, latent) @property def shape(self) -> tuple[int, int]: """The number of groups and the number of blocks.""" n_groups, n_blocks = self.vote_rate.shape return (n_groups, n_blocks) def __getitem__(self, key: tuple[int, int]) -> Cocluster: """Return the co-cluster of the group ``q`` and the block ``l``. Raises: IndexError: If the group or the block does not exist. """ n_groups, n_blocks = self.shape try: group, block = key inside = 0 <= group < n_groups and 0 <= block < n_blocks except (TypeError, ValueError): inside = False if not inside: raise IndexError( f"a co-cluster is read as table[group, block] with group < {n_groups} " f"and block < {n_blocks}, got {key!r}" ) return Cocluster( group=int(group), block=int(block), vote_rate=float(self.vote_rate[group, block]), vote_shares=tuple(float(share) for share in self.vote_shares[group, block]), n_votes=float(self.n_votes[group, block]), latent_mean=None if self.latent_mean is None else float(self.latent_mean[group, block]), latent_spread=( None if self.latent_spread is None else float(self.latent_spread[group, block]) ), scores=self.scale.scores, ) def __iter__(self) -> Iterator[Cocluster]: n_groups, n_blocks = self.shape for group in range(n_groups): for block in range(n_blocks): yield self[group, block] def __len__(self) -> int: n_groups, n_blocks = self.shape return n_groups * n_blocks
[docs] def log_probabilities(self) -> FloatArray: """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 state_log_probabilities(self.vote_rate, self.vote_shares)
[docs] def to_dict(self) -> dict[str, Any]: """Return plain lists: the scores, the three tables, and the latent parameters if any.""" data: dict[str, Any] = { "scores": list(self.scale.scores), "vote_rate": self.vote_rate.tolist(), "vote_shares": self.vote_shares.tolist(), "n_votes": self.n_votes.tolist(), } if self.latent_mean is not None: data["latent_mean"] = self.latent_mean.tolist() if self.latent_spread is not None: data["latent_spread"] = self.latent_spread.tolist() return data
def _describe(self) -> list[str]: n_groups, n_blocks = self.shape lines = [ f"CoclusterTable({n_groups} group{'' if n_groups == 1 else 's'} x " f"{n_blocks} block{'' if n_blocks == 1 else 's'}, {self.scale.n_levels} levels)" ] for cocluster in self: typical = self.scale.format_score(cocluster.typical_score) lines.append( f"group {cocluster.group} x block {cocluster.block}: " f"vote rate {cocluster.vote_rate:.2f}, typical score {typical}, " f"{cocluster.n_votes:g} votes" ) return lines