Finding your way

This page says where each thing lives: which module to import, which page of the reference to read, which file to open. To understand why the engine is built this way, read Architecture.

Three parts

Part

What it is for

Needs

civiqhub_selene

The contract every method shares. You meet it through every result, whatever the method

The standard library

civiqhub_selene.ordinal

The ordinal reading: the votes of one item on the agreement scale

The standard library

civiqhub_selene.blocks

Co-clustering: the vote matrix, the block models and their values

NumPy, behind the blocks extra

Importing civiqhub_selene or civiqhub_selene.ordinal never loads NumPy. Importing civiqhub_selene.blocks without NumPy raises MissingExtraError, which says how to install the extra.

I want to…

Hold votes

I want to

Use

Module

Count the votes of one item

VoteCounts

ordinal.counts

Hold the votes of many voters on many items

VoteMatrix

blocks.data

Use another scale than -2 to +2

OrdinalScale

blocks.data

Draw synthetic votes with a known truth

make_votes()

blocks.synthetic

Read a matrix through groups and blocks

VoteMatrix.group_by, GroupedVotes

blocks.data

In a vote matrix, a cell is voted, shown without a vote, or not shown. An empty cell is never a zero nor a neutral answer.

Run a method

I want to

Use

Module

Co-cluster with one group per voter

LatentBlockModel

blocks.single

Choose how the votes of a co-cluster are modelled

OrdinalProbit, Categorical

blocks.responses

Get a model from a plain word such as "single"

estimator_for(), memberships()

blocks.base

List the methods that are installed

default_registry()

registry

Every method is run the same way: estimator.estimate(data, seed=0), documented once on Estimator.estimate.

Read a result

I want to

Use

Module

Know whether there is a value, and read it

Result, Unavailable

types

Know which method, settings, seed and input gave it

Provenance, Result.fingerprint

types

Read a co-clustering

Coclustering, SingleCoclustering

blocks.results

Read the groups of voters and the blocks of items

Partition

blocks.partition

Read the vote rate and the scores of each co-cluster

CoclusterTable

blocks.coclusters

Handle an error of the engine

SeleneError and its subclasses; each carries a hint

errors

Write a method

I want to

Use

Module

Write an estimator

Estimator

estimator

Prove that it honours the contract

EstimatorContract

testing

Write a block model

BlockModel, IterativeEstimator

blocks.base, blocks.iterative

Write a response model

ResponseModel

blocks.responses

Declare it so that the registry finds it

The entry-point group GROUP

registry

Architecture walks through these steps.

Two names for one object

Many objects have two import paths: the module that defines them, and the package that exports them.

from civiqhub_selene import Result
from civiqhub_selene.types import Result as SameResult

print(Result is SameResult)
True

Import from the package when the name is exported there: it is the shorter path, and the one that stays stable. The reference documents each object once, on the page of the module that defines it; the page of a package lists what the package exports.

Where the files are

Path

Content

src/civiqhub_selene/

The library. One file per module of the reference: civiqhub_selene.blocks.data is src/civiqhub_selene/blocks/data.py

tests/

Unit tests (one file per module), property-based tests, and reference vectors with their tolerance

docs/

The pages of this site

examples/

Runnable examples on synthetic data

services/api/

The HTTP wrapper of the engine. It installs the library and never reimplements it

In the reference, the [source] link next to a name opens the code that defines it.

A module whose name starts with an underscore, such as civiqhub_selene.blocks._numerics, is internal: it has no page in the reference and may change without notice.

Not written yet

The dissensus index and the collective regime of the ordinal family, the mixed-membership block model, the choice of the number of groups and blocks, the consensus between groups and the cocluster function are planned. The changelog lists what each version adds.