Source code for civiqhub_selene.blocks.responses

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

"""Response models: how the cells of a co-cluster spread over the states of a cell.

A block model is made of two independent things: a latent structure (who belongs to
which group, which item to which block) and a response model, which says how the cells
of a co-cluster spread between "shown without a vote" and each score.

A shown cell has K + 1 states: state 0 (shown without a vote) and state ``k`` (vote at
rank ``k``, from 1 to K). A response model reads counts of cells per state and does
not know whether they are integers (single membership) or fractional (mixed
membership).

A response model is a frozen dataclass: its settings enter the provenance of the
estimator that carries it as they are.
"""

import math
from dataclasses import dataclass
from itertools import pairwise
from typing import Protocol, TypeVar

import numpy as np

from civiqhub_selene.blocks._arrays import FloatArray
from civiqhub_selene.blocks._numerics import fit_latent_normal, level_probabilities
from civiqhub_selene.blocks.coclusters import CoclusterTable, state_log_probabilities
from civiqhub_selene.blocks.data import OrdinalScale, VoteMatrix
from civiqhub_selene.errors import InvalidParameterError

__all__ = [
    "Categorical",
    "CategoricalParameters",
    "OrdinalProbit",
    "OrdinalProbitParameters",
    "ResponseModel",
]

ParametersT = TypeVar("ParametersT")

_EMPTY_COCLUSTER = 1e-12
_MIN_VOTE_SHARE = 1e-12


[docs] class ResponseModel(Protocol[ParametersT]): """What a block model asks of the response model of its co-clusters. ``ParametersT`` is the type of the parameters of the model, for Q x L co-clusters. """
[docs] def initial_parameters( self, shape: tuple[int, int], votes: VoteMatrix, rng: np.random.Generator ) -> ParametersT: """Return starting parameters for ``shape = (Q, L)`` co-clusters.""" ...
[docs] def log_probabilities(self, params: ParametersT) -> FloatArray: """Return the log-probability of each state in each co-cluster, shape (Q, L, K + 1).""" ...
[docs] def update(self, counts: FloatArray, previous: ParametersT) -> ParametersT: """Return the parameters that maximise the expected likelihood. ``counts[q, l, s]`` is the number, integer or fractional, of cells of the co-cluster ``(q, l)`` in the state ``s``. """ ...
[docs] def complexity_penalty(self, shape: tuple[int, int], votes: VoteMatrix) -> float: """Return the penalty of the parameters in the integrated likelihood. Half a logarithm of the sample size per free parameter. """ ...
[docs] def to_table( self, params: ParametersT, counts: FloatArray, scale: OrdinalScale ) -> CoclusterTable: """Return the readable table of the co-clusters.""" ...
def _vote_rate(counts: FloatArray, previous: FloatArray, min_probability: float) -> FloatArray: """Return the vote rate of each co-cluster, bounded away from 0 and 1. ``votes / cells`` where the co-cluster has cells (a sum above 1e-12), the previous value elsewhere; the whole bounded between ``min_probability`` and ``1 - min_probability``. """ n_cells = counts.sum(axis=-1) n_votes = counts[..., 1:].sum(axis=-1) rate = np.divide(n_votes, n_cells, out=previous.copy(), where=n_cells > _EMPTY_COCLUSTER) bounded: FloatArray = np.clip(rate, min_probability, 1.0 - min_probability) return bounded def _overall_vote_rate(votes: VoteMatrix, min_probability: float) -> float: """Return the votes over the shown cells of the matrix, bounded away from 0 and 1.""" rate = votes.n_votes / max(votes.n_shown, 1) return min(max(rate, min_probability), 1.0 - min_probability)
[docs] @dataclass(frozen=True, eq=False) class CategoricalParameters: """Parameters of the :class:`Categorical` response model. Attributes: vote_rate: Shape (Q, L): probability that a shown cell carries a vote. vote_shares: Shape (Q, L, K): distribution of the votes over the scores. """ vote_rate: FloatArray vote_shares: FloatArray
[docs] @dataclass(frozen=True) class Categorical: """A vote rate per co-cluster, then a free distribution over the K scores. Definition. For a shown cell of the co-cluster ``(q, l)``:: P(no vote) = 1 - vote_rate[q, l] P(vote at rank k) = vote_rate[q, l] * vote_shares[q, l, k] with K - 1 free parameters per co-cluster for the distribution and no constraint on its shape. The update is the maximum of the expected likelihood: the vote rate is the share of cells that carry a vote, and the distribution is the share of votes at each rank, after ``smoothing`` is added to each count. It is the simple reference against which the cost and the benefit of the ordinal probit model are judged. Attributes: smoothing: Pseudo-count added to the number of votes at each rank before the distribution is normalised, at least 0. Defaults to 0.5. min_probability: Bound that keeps a vote rate away from 0 and from 1, strictly between 0 and 0.5. Defaults to 1e-6. Raises: InvalidParameterError: If a setting is outside its range. """ smoothing: float = 0.5 min_probability: float = 1e-6 def __post_init__(self) -> None: if not self.smoothing >= 0 or math.isinf(self.smoothing): raise InvalidParameterError( f"smoothing is a finite number of at least 0, got {self.smoothing!r}" ) if not 0 < self.min_probability < 0.5: raise InvalidParameterError( f"min_probability is strictly between 0 and 0.5, got {self.min_probability!r}" )
[docs] def initial_parameters( self, shape: tuple[int, int], votes: VoteMatrix, rng: np.random.Generator ) -> CategoricalParameters: """Return starting parameters: the overall vote rate, and drawn distributions. The vote rate is the same everywhere: the votes over the shown cells of the matrix, bounded. Each distribution is drawn from a Dirichlet law of concentration 5 on each of the K scores. """ rate = _overall_vote_rate(votes, self.min_probability) vote_shares: FloatArray = rng.dirichlet(np.full(votes.n_levels, 5.0), size=shape) return CategoricalParameters(np.full(shape, rate), vote_shares)
[docs] def log_probabilities(self, params: CategoricalParameters) -> FloatArray: """Return the log-probability of each state in each co-cluster, shape (Q, L, K + 1).""" return state_log_probabilities(params.vote_rate, params.vote_shares)
[docs] def update(self, counts: FloatArray, previous: CategoricalParameters) -> CategoricalParameters: """Return the vote rates and the distributions that the counts call for. A co-cluster without any cell keeps its previous vote rate. A co-cluster without any vote keeps its previous distribution when ``smoothing`` is 0. """ smoothed = counts[..., 1:] + self.smoothing total = smoothed.sum(axis=-1, keepdims=True) vote_shares = np.divide( smoothed, total, out=previous.vote_shares.copy(), where=total > _EMPTY_COCLUSTER ) vote_rate = _vote_rate(counts, previous.vote_rate, self.min_probability) return CategoricalParameters(vote_rate, vote_shares)
[docs] def complexity_penalty(self, shape: tuple[int, int], votes: VoteMatrix) -> float: """Return half a logarithm of the sample size per free parameter. ``0.5 * Q * L * (K - 1) * log(max(n_votes, 1))`` for the distributions, plus ``0.5 * Q * L * log(max(n_shown, 1))`` for the vote rates. """ n_groups, n_blocks = shape n_coclusters = n_groups * n_blocks distributions = 0.5 * n_coclusters * (votes.n_levels - 1) * math.log(max(votes.n_votes, 1)) vote_rates = 0.5 * n_coclusters * math.log(max(votes.n_shown, 1)) return distributions + vote_rates
[docs] def to_table( self, params: CategoricalParameters, counts: FloatArray, scale: OrdinalScale ) -> CoclusterTable: """Return the table of the co-clusters, with the number of votes of the counts.""" return CoclusterTable( scale, params.vote_rate, params.vote_shares, n_votes=counts[..., 1:].sum(axis=-1) )
[docs] @dataclass(frozen=True, eq=False) class OrdinalProbitParameters: """Parameters of the :class:`OrdinalProbit` response model. Attributes: vote_rate: Shape (Q, L): probability that a shown cell carries a vote. latent_mean: Shape (Q, L): mean of the latent opinion, on the axis of levels. latent_spread: Shape (Q, L): standard deviation of the latent opinion. thresholds: The K - 1 thresholds between levels, fixed during the computation. """ vote_rate: FloatArray latent_mean: FloatArray latent_spread: FloatArray thresholds: FloatArray
[docs] @dataclass(frozen=True) class OrdinalProbit: """A vote rate per co-cluster, then a latent normal opinion cut into K levels. Definition. In a co-cluster, a shown cell carries a vote with the probability ``vote_rate``. The vote comes from a hidden continuous opinion, normal with mean ``latent_mean`` and standard deviation ``latent_spread``, which fixed thresholds ``t_1 < ... < t_{K-1}`` cut into K levels, with ``t_0 = -inf`` and ``t_K = +inf``:: P(no vote) = 1 - vote_rate P(vote at rank k) = vote_rate * p_k p_k = cdf((t_k - latent_mean) / latent_spread) - cdf((t_{k-1} - latent_mean) / latent_spread) where ``cdf`` is the standard normal distribution function. Two numbers then sum up how a group answers a block: where the opinion stands and how spread it is. The thresholds default to ``k + 1/2`` for ``k`` from 1 to K - 1. They are fixed, not estimated: ``latent_mean`` then reads directly on the axis of levels, from 1 to K. The mean and the spread are estimated by expectation-maximisation on the hidden opinion (see ``fit_latent_normal``). Reference: Corneli, Bouveyron, Latouche (2020), Co-clustering of ordinal data via latent continuous random variables and not missing at random entries. Attributes: thresholds: The K - 1 thresholds, strictly increasing, or ``None`` for the default ones. min_spread: Lower bound of ``latent_spread``, strictly positive. It keeps a unanimous co-cluster from sending its spread to zero. Defaults to 0.3. min_probability: Bound that keeps a vote rate away from 0 and from 1, strictly between 0 and 0.5. Defaults to 1e-6. max_inner_iterations: Largest number of expectation-maximisation steps on the hidden opinion at each update, at least 1. Defaults to 10. Raises: InvalidParameterError: If a setting is outside its range. """ thresholds: tuple[float, ...] | None = None min_spread: float = 0.3 min_probability: float = 1e-6 max_inner_iterations: int = 10 def __post_init__(self) -> None: if self.thresholds is not None: try: thresholds = tuple(float(threshold) for threshold in self.thresholds) except (TypeError, ValueError): raise InvalidParameterError( f"thresholds are numbers, got {self.thresholds!r}" ) from None _check_thresholds(thresholds, len(thresholds) + 1) object.__setattr__(self, "thresholds", thresholds) if not self.min_spread > 0 or math.isinf(self.min_spread): raise InvalidParameterError( f"min_spread is a finite number above 0, got {self.min_spread!r}" ) if not 0 < self.min_probability < 0.5: raise InvalidParameterError( f"min_probability is strictly between 0 and 0.5, got {self.min_probability!r}" ) steps = self.max_inner_iterations if isinstance(steps, bool) or not isinstance(steps, int) or steps < 1: raise InvalidParameterError( f"max_inner_iterations is an integer of at least 1, got {steps!r}" )
[docs] def initial_parameters( self, shape: tuple[int, int], votes: VoteMatrix, rng: np.random.Generator ) -> OrdinalProbitParameters: """Return starting parameters: the overall vote rate and opinions near the middle. The vote rate is the same everywhere: the votes over the shown cells of the matrix, bounded. Each mean is the middle of the axis of levels, ``(K + 1) / 2``, plus a normal draw of standard deviation 0.5; each spread is 1. Raises: InvalidParameterError: If the thresholds given are not K - 1 values. """ n_levels = votes.n_levels if self.thresholds is None: thresholds = tuple(level + 0.5 for level in range(1, n_levels)) else: thresholds = self.thresholds _check_thresholds(thresholds, n_levels) rate = _overall_vote_rate(votes, self.min_probability) latent_mean: FloatArray = (n_levels + 1) / 2 + rng.normal(0.0, 0.5, size=shape) return OrdinalProbitParameters( np.full(shape, rate), latent_mean, np.ones(shape), np.array(thresholds) )
[docs] def log_probabilities(self, params: OrdinalProbitParameters) -> FloatArray: """Return the log-probability of each state in each co-cluster, shape (Q, L, K + 1).""" return state_log_probabilities(params.vote_rate, self._vote_shares(params))
[docs] def update( self, counts: FloatArray, previous: OrdinalProbitParameters ) -> OrdinalProbitParameters: """Return the vote rates and the latent opinions that the counts call for. The mean and the spread restart from the previous ones and take at most ``max_inner_iterations`` steps. A co-cluster without any cell keeps its previous vote rate; a co-cluster without any vote keeps its previous opinion. """ latent_mean, latent_spread = fit_latent_normal( counts[..., 1:], previous.latent_mean, previous.latent_spread, previous.thresholds, min_spread=self.min_spread, max_iterations=self.max_inner_iterations, ) vote_rate = _vote_rate(counts, previous.vote_rate, self.min_probability) return OrdinalProbitParameters(vote_rate, latent_mean, latent_spread, previous.thresholds)
[docs] def complexity_penalty(self, shape: tuple[int, int], votes: VoteMatrix) -> float: """Return half a logarithm of the sample size per free parameter. Two parameters of opinion and one vote rate per co-cluster: ``Q * L * log(max(n_votes, 1)) + 0.5 * Q * L * log(max(n_shown, 1))``. """ n_groups, n_blocks = shape n_coclusters = n_groups * n_blocks opinions = n_coclusters * math.log(max(votes.n_votes, 1)) vote_rates = 0.5 * n_coclusters * math.log(max(votes.n_shown, 1)) return opinions + vote_rates
[docs] def to_table( self, params: OrdinalProbitParameters, counts: FloatArray, scale: OrdinalScale ) -> CoclusterTable: """Return the table of the co-clusters, with their latent mean and spread.""" return CoclusterTable( scale, params.vote_rate, self._vote_shares(params), n_votes=counts[..., 1:].sum(axis=-1), latent_mean=params.latent_mean, latent_spread=params.latent_spread, )
[docs] def _vote_shares(self, params: OrdinalProbitParameters) -> FloatArray: """Return the probability of each level, floored at 1e-12.""" shares: FloatArray = np.maximum( level_probabilities(params.latent_mean, params.latent_spread, params.thresholds), _MIN_VOTE_SHARE, ) return shares
def _check_thresholds(thresholds: tuple[float, ...], n_levels: int) -> None: if len(thresholds) != n_levels - 1 or len(thresholds) < 1: raise InvalidParameterError( f"a scale of {n_levels} scores has {n_levels - 1} thresholds, " f"got {len(thresholds)}: {thresholds!r}" ) if not all(math.isfinite(threshold) for threshold in thresholds) or any( low >= high for low, high in pairwise(thresholds) ): raise InvalidParameterError( f"thresholds are finite and strictly increasing, got {thresholds!r}" )