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:
DisplayableA 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:
- groups¶
A partition of the voters of the matrix, in the same order.
- Type:
- Raises:
InvalidInputError – If a partition does not cover the voters, or the items, of the matrix in the same order.
- Parameters:
votes (VoteMatrix)
groups (Partition[VoterGroup])
- 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 rankk. 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_rateis the number of votes over the number of shown cells (0 when no cell is shown);vote_sharesis the count of each level over the number of votes (a uniform distribution when there is no vote).- Return type:
- 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:
- property lineage: tuple[str, ...]¶
Fingerprints of the computations the two partitions come from, without repeat.
Estimatorcopies it into the provenance: a result computed on groups cites the computation that produced them.
- class civiqhub_selene.blocks.data.OrdinalScale(scores=(-2, -1, 0, 1, 2))[source]¶
Bases:
objectAn 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
- class civiqhub_selene.blocks.data.Vote(voter, item, score)[source]¶
Bases:
NamedTupleOne 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:
DisplayableVotes of M voters on P items, by opaque identifiers.
A cell has three states. It is not shown when
shownis false, whateverlevelsholds; an abstention when it is shown andlevelsis 0; voted when it is shown andlevelsis 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;
kfrom 1 ton_levels: vote at rankkof 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:
- 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, unlessvotersoritemsfix it.Without
shown, every cell counts as shown: an empty cell is then read as an abstention. Withshown, 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
votersoritemsleaves out.- Return type:
- classmethod from_table(table, *, voters=None, items=None, scale=None)[source]¶
Build a matrix from a voters by items table of scores.
Noneor NaN marks an empty cell. Every cell is shown: an empty cell is an abstention. Without identifiers, voters arev1, v2, ...and itemsi1, 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:
- 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 rankkof 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:
- 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:
groups (Partition[VoterGroup] | None)
- Return type:
- hold_out(cells)[source]¶
Return the same matrix where
cellsare treated as never shown.Their votes stay in
levels, to be predicted; this matrix is unchanged.- Raises:
InvalidInputError – If
cellsis not a boolean array of the same shape.- Parameters:
cells (NDArray[bool])
- Return type:
- 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 ofshown.- 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 rankk. A cell that is not shown is zero everywhere, unlessignore_shownis true: the mask is then left out and every cell is read throughlevelsalone.Computed once and read-only. Models read the matrix through this array only.
- Parameters:
ignore_shown (bool)
- Return type:
NDArray[float64]