Getting started¶
This page installs the library and runs two computations on synthetic data. The tests of the repository run every Python block of this page and compare what it prints with the output shown.
Install¶
pip install civiqhub-selene
The core and the ordinal family use the standard library only. Co-clustering needs NumPy, behind an optional extra:
pip install "civiqhub-selene[blocks]"
To run what is not released yet, install the development branch:
pip install "civiqhub-selene[blocks] @ git+https://github.com/civiqhub/civiqhub-selene@develop"
The distribution is named civiqhub-selene; the package is imported as civiqhub_selene. Python 3.11 or later is required.
Count the votes of one item¶
A vote is a score on the agreement scale: an integer from -2 (strong disagreement) to +2 (strong agreement). VoteCounts holds how many votes each score received, with exact shares.
from civiqhub_selene.ordinal import VoteCounts
counts = VoteCounts.from_scores([2, 2, 1, -1, -2, 2])
print(counts)
print(counts.total, counts[2], counts.shares[4])
VoteCounts(1, 1, 0, 1, 3; 6 votes)
6 3 1/2
Run a first co-clustering¶
Co-clustering arranges voters in groups and items in blocks, so that the votes of one group on one block look alike. The pair of a group and a block is a co-cluster.
The votes below are synthetic: make_votes() draws them from a truth that it plants, here three groups of 16 voters and two blocks of 7 items.
from civiqhub_selene.blocks import LatentBlockModel
from civiqhub_selene.blocks.synthetic import make_votes, single_memberships
votes, truth = make_votes(
single_memberships((16, 16, 16)),
single_memberships((7, 7)),
seed=0,
)
print(votes)
model = LatentBlockModel(n_groups=3, n_blocks=2)
result = model.estimate(votes, seed=0)
print(result)
VoteMatrix(48 voters x 14 items, 408 votes, 5 levels)
100.0% of the 672 cells shown, 60.7% of the shown cells voted
Result(latent_block_model 0.1.0)
SingleCoclustering(48 voters in 3 groups x 14 items in 2 blocks)
groups of 16, 15, 17 voters; blocks of 7, 7 items
group 0 x block 0: vote rate 0.88, typical score +2, 98 votes
group 0 x block 1: vote rate 0.44, typical score -2, 49 votes
group 1 x block 0: vote rate 0.57, typical score -2, 60 votes
group 1 x block 1: vote rate 0.94, typical score +2, 99 votes
group 2 x block 0: vote rate 0.39, typical score -1, 47 votes
group 2 x block 1: vote rate 0.46, typical score 0, 55 votes
Three things to notice:
The model is a value.
LatentBlockModelis a frozen dataclass: its settings are its fields, and it reads nothing from the environment.The seed is explicit. The same votes, the same settings and the same seed give the same result.
The call is the same for every method.
estimate()is written once, for all estimators.
To build a matrix from your own votes, see the constructors of VoteMatrix: from_records, from_table and from_arrays.
Read the result¶
A Result carries a value and its provenance. Here the value is a SingleCoclustering.
coclustering = result.value
print(coclustering.groups)
print(coclustering.group_of("v1"))
print(coclustering[1, 1])
provenance = result.provenance
print(provenance.method, provenance.seed)
print(result.fingerprint())
Partition(48 voters in 3 mixed groups: 16, 15, 17)
VoterGroup(index=0, 16 voters, share=0.333)
Cocluster(group=1, block=1, vote_rate=0.943, typical_score=+2, n_votes=99)
latent_block_model 0.1.0 0
61c66776052c788a
The fingerprint identifies the computation: the method and its version, the settings, the seed and the input. Two results with the same fingerprint come from the same computation.
A result can be an explained absence¶
When there is nothing to compute, a method does not raise and does not return a default: it returns a result without a value, which says why.
from civiqhub_selene.blocks import VoteMatrix
no_votes = VoteMatrix.from_records([], voters=["ana", "ben", "cleo"], items=["p1", "p2"])
absent = model.estimate(no_votes)
print(absent.is_available)
print(absent.unavailable.reason, "-", absent.unavailable.detail)
False
no_votes - the matrix holds no vote
Reading absent.value raises UnavailableError. Test is_available first.
Next¶
Finding your way says which module holds what.
Architecture explains the contract behind
estimateand how to add a method.The reference documents every public name.