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 a frozenset. 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

Share of the cluster in the whole, between 0 and 1.

Type:

float

class civiqhub_selene.blocks.partition.ItemBlock(index, ids, share)[source]

Bases: Cluster

A 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 type kind, built once. Arrays are copied and made read-only. Build a partition with from_voter_labels() or from_item_labels().

kind

The type of the clusters: VoterGroup or ItemBlock.

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. None for a plain partition.

Type:

numpy._typing._array_like.NDArray[numpy.float64] | None

shares

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 memberships when they are given, to max(labels) + 1 otherwise.

  • 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:

Partition[VoterGroup]

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().

Parameters:
  • ids (Iterable[str])

  • labels (ArrayLike)

  • n_clusters (int | None)

  • memberships (ArrayLike | None)

  • shares (ArrayLike | None)

  • computation (str | None)

Return type:

Partition[ItemBlock]

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 other are renumbered in the best possible way first, by exhaustive search over the permutations.

Raises:
Parameters:

other (Partition[Any])

Return type:

float

fingerprint()[source]

Return a stable fingerprint: 16 hexadecimal characters.

SHA-256 of the kind, the identifiers and the number of clusters, then the bytes of labels. Memberships and shares are left out: it identifies the arrangement of identifiers in clusters.

Return type:

str

class civiqhub_selene.blocks.partition.VoterGroup(index, ids, share)[source]

Bases: Cluster

A group: a cluster of voters.

Parameters:
  • index (int)

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

  • share (float)

property voters: tuple[str, ...]

The voters of the group.