civiqhub_selene.blocks.data

Votes of voters on items, as a matrix with three states per cell.

VoteMatrix is the input of all co-clustering. Its central rule: a cell is voted, shown without a vote, or not shown. An empty cell is never a zero nor a neutral answer, and only shown cells enter a computation.

class civiqhub_selene.blocks.data.GroupedVotes(votes, groups, blocks)[source]

Bases: Displayable

A vote matrix read through groups of voters and blocks of items.

The groups and the blocks can come from a model or from anywhere else. Only the plain labels of the partitions are read here: a degree of membership is not.

votes

The vote matrix.

Type:

VoteMatrix

groups

A partition of the voters of the matrix, in the same order.

Type:

Partition[VoterGroup]

blocks

A partition of the items of the matrix, in the same order.

Type:

Partition[ItemBlock]

Raises:

InvalidInputError – If a partition does not cover the voters, or the items, of the matrix in the same order.

Parameters:
property shape: tuple[int, int]

The number of groups and the number of blocks.

counts()[source]

Count the shown cells of each co-cluster in each state.

Shape (Q, L, K + 1). Index 0: shown without a vote; index k: vote at rank k. A cell that is not shown is counted nowhere.

Return type:

NDArray[float64]

to_table()[source]

Return the table of co-clusters as it is counted, without a model.

vote_rate is the number of votes over the number of shown cells (0 when no cell is shown); vote_shares is the count of each level over the number of votes (a uniform distribution when there is no vote).

Return type:

CoclusterTable

vote_counts(group, block)[source]

Return the five vote counts of a co-cluster, ready for the ordinal family.

The counts are named "group {group} x block {block}". They follow the rank of the scores on the scale.

Raises:

InvalidInputError – If the scale does not have five scores, or if the group or the block does not exist.

Parameters:
  • group (int)

  • block (int)

Return type:

VoteCounts

property lineage: tuple[str, ...]

Fingerprints of the computations the two partitions come from, without repeat.

Estimator copies it into the provenance: a result computed on groups cites the computation that produced them.

fingerprint()[source]

Return a stable fingerprint of the votes and the two partitions.

Return type:

str

class civiqhub_selene.blocks.data.OrdinalScale(scores=(-2, -1, 0, 1, 2))[source]

Bases: object

An ordered scale of scores. Defaults to the five-score agreement scale.

A score is the answer of a vote, for example from -2 to +2. A level is the rank of a score on the scale, from 1 to n_levels; level 0 means “no vote” and is internal to matrices.

scores

The scores, strictly increasing integers, at least two.

Type:

tuple[int, …]

Raises:

InvalidParameterError – If the scores are not strictly increasing integers, or if there are fewer than two.

Parameters:

scores (tuple[int, ...])

property n_levels: int

The number of scores on the scale.

level_of(score)[source]

Return the rank of a score, from 1 to n_levels.

Raises:

InvalidInputError – If the score is not on the scale.

Parameters:

score (int)

Return type:

int

score_of(level)[source]

Return the score at a rank from 1 to n_levels.

Raises:

InvalidInputError – If the level is not a rank of the scale.

Parameters:

level (int)

Return type:

int

format_score(score)[source]

Return the score with its sign: "+2", "0", "-1".

Parameters:

score (int)

Return type:

str

class civiqhub_selene.blocks.data.Vote(voter, item, score)[source]

Bases: NamedTuple

One vote: a voter gave a score to an item.

Parameters:
  • voter (str)

  • item (str)

  • score (int)

voter: str

Alias for field number 0

item: str

Alias for field number 1

score: int

Alias for field number 2

class civiqhub_selene.blocks.data.VoteMatrix(levels, shown, voters, items, scale=<factory>)[source]

Bases: Displayable

Votes of M voters on P items, by opaque identifiers.

A cell has three states. It is not shown when shown is false, whatever levels holds; an abstention when it is shown and levels is 0; voted when it is shown and levels is positive. A vote at the neutral score is a vote.

The arrays are copied and made read-only. Two matrices with the same content are equal: equality and hash follow fingerprint().

levels

Integers of shape (M, P). 0: no vote; k from 1 to n_levels: vote at rank k of the scale.

Type:

numpy._typing._array_like.NDArray[numpy.int64]

shown

Booleans of shape (M, P): the item was shown to the voter.

Type:

numpy._typing._array_like.NDArray[numpy.bool]

voters

Opaque identifiers of the rows, unique.

Type:

tuple[str, …]

items

Opaque identifiers of the columns, unique.

Type:

tuple[str, …]

scale

The scale of scores. Defaults to the five-score agreement scale.

Type:

OrdinalScale

Raises:

InvalidInputError – If the arrays are not two matrices of the same shape, if a level is outside 0..n_levels, if the identifiers do not follow the shape, or if an identifier is repeated.

Parameters:
  • levels (NDArray[int64])

  • shown (NDArray[bool])

  • voters (tuple[str, ...])

  • items (tuple[str, ...])

  • scale (OrdinalScale)

classmethod from_records(votes, *, shown=None, voters=None, items=None, scale=None)[source]

Build a matrix from (voter, item, score) triples.

Rows and columns follow the order of first appearance, in the votes and then in shown, unless voters or items fix it.

Without shown, every cell counts as shown: an empty cell is then read as an abstention. With shown, only these (voter, item) pairs and the voted cells are shown; the other cells are not shown.

Parameters:
  • votes (Iterable[tuple[str, str, int]]) – The votes, as (voter, item, score) triples.

  • shown (Iterable[tuple[str, str]] | None) – The (voter, item) pairs where the item was shown to the voter.

  • voters (Iterable[str] | None) – The voters in the order of the rows. It may name voters without any vote; it must name every voter of the records.

  • items (Iterable[str] | None) – The items in the order of the columns, likewise.

  • scale (OrdinalScale | None) – The scale of scores. Defaults to the five-score agreement scale.

Raises:

InvalidInputError – If a score is not on the scale, if a voter votes twice on the same item, or if a record names an identifier that voters or items leaves out.

Return type:

VoteMatrix

classmethod from_table(table, *, voters=None, items=None, scale=None)[source]

Build a matrix from a voters by items table of scores.

None or NaN marks an empty cell. Every cell is shown: an empty cell is an abstention. Without identifiers, voters are v1, v2, ... and items i1, i2, ....

Raises:

InvalidInputError – If the rows have different lengths or if a score is not on the scale.

Parameters:
  • table (Iterable[Iterable[float | None]])

  • voters (Iterable[str] | None)

  • items (Iterable[str] | None)

  • scale (OrdinalScale | None)

Return type:

VoteMatrix

classmethod from_arrays(levels, *, shown=None, voters=None, items=None, scale=None)[source]

Build a matrix from its internal encoding, as NumPy arrays or lists.

Parameters:
  • levels (ArrayLike) – Shape (M, P). 0: no vote; k: vote at rank k of the scale.

  • shown (ArrayLike | None) – Shape (M, P). Defaults to every cell shown.

  • voters (Iterable[str] | None) – Identifiers of the rows. Defaults to v1, v2, ....

  • items (Iterable[str] | None) – Identifiers of the columns. Defaults to i1, i2, ....

  • scale (OrdinalScale | None) – The scale of scores. Defaults to the five-score agreement scale.

Return type:

VoteMatrix

property shape: tuple[int, int]

The number of voters and the number of items.

property n_levels: int

The number of scores on the scale.

property voted: NDArray[bool][source]

Booleans of shape (M, P): the cell is shown and carries a vote.

property n_votes: int

The number of voted cells.

property n_shown: int

The number of shown cells, voted or not.

property n_active_voters: int

The number of voters with at least one vote.

property n_active_items: int

The number of items with at least one vote.

to_records()[source]

Yield the votes one by one, voter by voter, in scores of the scale.

Only voted cells are yielded: a vote held out by hold_out() is not.

Return type:

Iterator[Vote]

group_by(groups=None, blocks=None)[source]

Read the matrix through groups of voters and blocks of items.

A side left out counts as a single cluster that holds everyone.

Raises:

InvalidInputError – If a partition does not cover the voters, or the items, of the matrix in the same order.

Parameters:
Return type:

GroupedVotes

hold_out(cells)[source]

Return the same matrix where cells are treated as never shown.

Their votes stay in levels, to be predicted; this matrix is unchanged.

Raises:

InvalidInputError – If cells is not a boolean array of the same shape.

Parameters:

cells (NDArray[bool])

Return type:

VoteMatrix

fingerprint()[source]

Return a stable fingerprint of the content: 16 hexadecimal characters.

SHA-256 of the shape, the scores, the identifiers, then the bytes of levels (little-endian 64-bit integers) and of shown.

Return type:

str

_states(*, ignore_shown=False)[source]

Return the indicator of the state of each cell, of shape (M, P, K + 1).

Index 0: shown without a vote; index k: vote at rank k. A cell that is not shown is zero everywhere, unless ignore_shown is true: the mask is then left out and every cell is read through levels alone.

Computed once and read-only. Models read the matrix through this array only.

Parameters:

ignore_shown (bool)

Return type:

NDArray[float64]