civiqhub_selene.blocks.base

Base classes of the co-clustering estimators.

CoclusteringEstimator says what an estimator of co-clustering answers and under which plain word it is chosen. BlockModel joins it with IterativeEstimator and carries the settings every block model shares. A concrete model then only writes three hooks:

Estimator                      estimate()     written once
|- IterativeEstimator          _compute()     written once
'- CoclusteringEstimator       with_shape()
BlockModel(IterativeEstimator, CoclusteringEstimator)
|- LatentBlockModel            "single"
'- MixedMembershipBlockModel   "mixed"
civiqhub_selene.blocks.base.FAMILY = 'coclustering'

Family of the co-clustering estimators in the registry: keys read coclustering.word.

class civiqhub_selene.blocks.base.BlockModel(*, n_groups=2, n_blocks=2, response_model=<factory>, n_starts=6, max_iterations=200, tolerance=1e-06)[source]

Bases: IterativeEstimator[VoteMatrix, StateT, ValueT_co], CoclusteringEstimator[ValueT_co], Generic[StateT, ValueT_co]

Settings and guarantees every block model shares.

A block model is a latent structure (groups of voters, blocks of items) and a response model for its co-clusters. A concrete model declares its identity and writes _start, _step and _finish.

n_groups

Number of groups of voters, at least 1. Defaults to 2.

Type:

int

n_blocks

Number of blocks of items, at least 1. Defaults to 2.

Type:

int

response_model

The response model of the co-clusters. Defaults to OrdinalProbit().

Type:

ResponseModel[Any]

n_starts

Number of random starts, at least 1; the best one is kept. Defaults to 6.

Type:

int

max_iterations

Largest number of iterations of a start, at least 1. Defaults to 200.

Type:

int

tolerance

Gain of objective under which a start stops, at least 0. Defaults to 1e-6.

Type:

float

Raises:

InvalidParameterError – If a setting is outside its range.

Parameters:
  • n_groups (int)

  • n_blocks (int)

  • response_model (ResponseModel[Any])

  • n_starts (int)

  • max_iterations (int)

  • tolerance (float)

with_shape(n_groups, n_blocks)[source]

Return the same model at another shape.

Parameters:
  • n_groups (int)

  • n_blocks (int)

Return type:

Self

class civiqhub_selene.blocks.base.CoclusteringEstimator[source]

Bases: Estimator[VoteMatrix, ValueT_co]

An estimator that reads a vote matrix and returns groups, blocks and co-clusters.

Class attributes a concrete subclass declares, besides those of Estimator:

membership

The plain word under which the estimator is chosen, for example "single".

Type:

ClassVar[str]

meaning

One sentence in plain words, for example “each voter belongs to one group”.

Type:

ClassVar[str]

default_criterion

Key of the criterion that chooses its shape by default.

Type:

ClassVar[str]

Instance attributes a concrete subclass carries:

n_groups

Number of groups of voters.

Type:

int

n_blocks

Number of blocks of items.

Type:

int

input_type

alias of VoteMatrix

abstractmethod with_shape(n_groups, n_blocks)[source]

Return the same estimator at another shape.

Parameters:
  • n_groups (int)

  • n_blocks (int)

Return type:

Self

civiqhub_selene.blocks.base.availability(votes, n_groups=1, n_blocks=1)[source]

Say why no co-clustering of this shape exists on votes, or return None.

A co-clustering needs at least one vote, at least max(2, n_groups) voters with a vote and at least max(2, n_blocks) items with a vote.

Parameters:
  • votes (VoteMatrix)

  • n_groups (int)

  • n_blocks (int)

Return type:

Unavailable | None

civiqhub_selene.blocks.base.estimator_for(membership, registry=None)[source]

Return the default estimator behind a plain word, built without argument.

Parameters:
  • membership (str) – The plain word, for example "single" or "mixed".

  • registry (Registry | None) – Where to look. Defaults to the installed entry points.

Raises:

InvalidParameterError – If the word is unknown. The message lists each installed choice with its meaning, one per line.

Return type:

CoclusteringEstimator[Any]

civiqhub_selene.blocks.base.memberships(registry=None)[source]

Return the meaning of each installed choice of co-clustering, by its plain word.

Parameters:

registry (Registry | None) – Where to look. Defaults to the installed entry points.

Return type:

dict[str, str]