civiqhub_selene.blocks.partition¶
Partitions of identifiers into clusters: voters into groups, items into blocks.
A partition can come from a model of the engine or from anywhere else (a k-means, a
list written by hand): this is what lets votes be read through groups whatever their
origin. A partition does not know the vote matrix; the link is made by
GroupedVotes.
Everywhere in the engine, “group” means a cluster of voters and “block” a cluster of items.
- class civiqhub_selene.blocks.partition.Cluster(index, ids, share)[source]¶
Bases:
Set[str]One cluster of a partition: a set of identifiers with its index and its share.
It behaves as a set of identifiers:
in,len, iteration and the set operations, which return afrozenset. Two clusters are equal when they have the same index, the same identifiers and the same share.- Parameters:
index (int)
ids (tuple[str, ...])
share (float)
- index¶
Index of the cluster in its partition.
- Type:
int
- ids¶
The identifiers of the cluster, in the order of the partition.
- Type:
tuple[str, …]
Share of the cluster in the whole, between 0 and 1.
- Type:
float
- class civiqhub_selene.blocks.partition.ItemBlock(index, ids, share)[source]¶
Bases:
ClusterA block: a cluster of items.
- Parameters:
index (int)
ids (tuple[str, ...])
share (float)
- property items: tuple[str, ...]¶
The items of the block.
- class civiqhub_selene.blocks.partition.Partition(kind, ids, labels, n_clusters, memberships=None, shares=None, computation=None)[source]¶
Bases:
Displayable,Sequence[ClusterT],Generic[ClusterT]Identifiers arranged in clusters. A sequence of its clusters.
len(partition)is the number of clusters,partition[k]is a cluster of the typekind, built once. Arrays are copied and made read-only. Build a partition withfrom_voter_labels()orfrom_item_labels().- kind¶
The type of the clusters:
VoterGrouporItemBlock.- Type:
type[civiqhub_selene.blocks.partition.ClusterT]
- ids¶
Every identifier, in order.
- Type:
tuple[str, …]
- labels¶
For each identifier, the index of its cluster.
- Type:
numpy._typing._array_like.NDArray[numpy.int64]
- n_clusters¶
The number of clusters, empty clusters included.
- Type:
int
- memberships¶
Shape (n, n_clusters): degree of membership of each identifier to each cluster, rows summing to 1.
Nonefor a plain partition.- Type:
numpy._typing._array_like.NDArray[numpy.float64] | None
The share of each cluster. Defaults to the sizes divided by n, or to the mean of the memberships when they are given.
- Type:
numpy._typing._array_like.NDArray[numpy.float64] | None
- computation¶
Fingerprint of the computation the partition comes from, if any.
- Type:
str | None
- Raises:
InvalidInputError – If there are not as many labels as identifiers, if a label is not an integer from 0 to
n_clusters - 1, if an identifier is repeated, or if the memberships have the wrong shape, a negative value or a row that does not sum to 1 within 1e-6.- Parameters:
kind (type[ClusterT])
ids (tuple[str, ...])
labels (NDArray[int64])
n_clusters (int)
memberships (NDArray[float64] | None)
shares (NDArray[float64] | None)
computation (str | None)
- classmethod from_voter_labels(ids, labels, *, n_clusters=None, memberships=None, shares=None, computation=None)[source]¶
Build a partition of voters into groups from one label per voter.
- Parameters:
ids (Iterable[str]) – The voters, in order.
labels (ArrayLike) – For each voter, the index of its group.
n_clusters (int | None) – The number of groups. Defaults to the number of columns of
membershipswhen they are given, tomax(labels) + 1otherwise.memberships (ArrayLike | None) – Degree of membership of each voter to each group, if any.
shares (ArrayLike | None) – The share of each group, if it is not the one of the sizes.
computation (str | None) – Fingerprint of the computation the partition comes from.
- Return type:
- classmethod from_item_labels(ids, labels, *, n_clusters=None, memberships=None, shares=None, computation=None)[source]¶
Build a partition of items into blocks from one label per item.
Same arguments as
from_voter_labels().
- cluster_of(identifier)[source]¶
Return the cluster of an identifier.
- Raises:
InvalidInputError – If the identifier is not in the partition.
- Parameters:
identifier (str)
- Return type:
ClusterT
- property sizes: tuple[int, ...]¶
The number of identifiers in each cluster.
- property is_mixed: bool¶
Whether degrees of membership are given.
- agreement_with(other)[source]¶
Return the share of identifiers the two partitions arrange in the same way.
The clusters of
otherare renumbered in the best possible way first, by exhaustive search over the permutations.- Raises:
InvalidInputError – If the two partitions do not cover the same identifiers in the same order, or if they are empty.
InvalidParameterError – If a partition has more than 8 clusters.
- Parameters:
other (Partition[Any])
- Return type:
float