civiqhub_selene.estimator

Base class of every method of the engine. Standard library only.

An estimator is a fully specified computation: every setting is a field of a frozen dataclass and nothing is ambient. Estimator writes once what every method guarantees: the input is checked, the provenance is recorded, an absence is explicit, and the outcome is wrapped in a Result. A concrete method only writes its computation:

@dataclass(frozen=True, kw_only=True)
class Mean(Estimator[Numbers, float]):
    name = "mean"
    version = "1.0.0"
    reference = "Arithmetic mean."
    input_type = Numbers

    def _compute(self, data: Numbers, *, seed: int, computation: str) -> float:
        return sum(data.values) / len(data.values)

result = Mean().estimate(numbers)

The method is named estimate on purpose: fit would promise the scikit-learn usage, where the method returns the estimator itself.

class civiqhub_selene.estimator.Estimator[source]

Bases: ABC, Generic[DataT_contra, ValueT_co]

A fully specified computation that reads one input and returns a Result.

Concrete subclasses are frozen dataclasses declared with kw_only=True: every setting is a named, typed field, and two estimators with the same fields are the same computation. estimate() is written once, here, and is never overridden; a subclass writes _compute(), and _why_unavailable() and _uncertainty() when they apply.

Determinism: same data, same fields, same seed give the same value and the same fingerprint. Any randomness goes through the seed received.

Class attributes a concrete subclass declares:

name

Stable identifier of the method, lower case and underscores.

Type:

ClassVar[str]

version

X.Y.Z. It changes as soon as the numbers returned can change.

Type:

ClassVar[str]

reference

Citation of the source of the method.

Type:

ClassVar[str]

input_type

The class of the input the method reads.

Type:

ClassVar[type]

stochastic

Whether the method uses randomness. Defaults to False.

Type:

ClassVar[bool]

generator

Name of the bit generator a stochastic method uses.

Type:

ClassVar[str]

dependencies

Names of the third-party packages the method uses.

Type:

ClassVar[tuple[str, …]]

classmethod method()[source]

Return the identity of the method, after checking it is declared.

Raises:

EstimatorDefinitionError – If name, version or input_type is missing or malformed. The message names the class and the value.

Return type:

Method

final estimate(data, *, seed=0)[source]

Run the method on data and return its result.

In this order: the identity of the method is checked, the input is checked, the provenance is written, the subclass says whether an answer exists, the value is computed and wrapped.

Parameters:
  • data (DataT_contra) – The input, an instance of input_type.

  • seed (int) – Seed of every random draw, a non-negative integer. A method without randomness ignores it and leaves it out of the provenance.

Raises:
Return type:

Result[ValueT_co]

_why_unavailable(data)[source]

Say why no answer exists on data, or return None when one does.

Called before _compute(), which is skipped when an absence is returned.

Parameters:

data (DataT_contra)

Return type:

Unavailable | None

abstractmethod _compute(data, *, seed, computation)[source]

Compute the value.

Parameters:
  • data (DataT_contra) – The input, already checked against input_type.

  • seed (int) – Seed of every random draw.

  • computation (str) – Fingerprint the result will carry, for values that cite the computation they come from.

Returns:

The value, or an Unavailable when the absence only shows during the computation. Never None, never NaN.

Return type:

ValueT_co | Unavailable

_uncertainty(data, value)[source]

Return the uncertainty of value, or None when the method defines none.

Not called when _compute() returns an absence.

Parameters:
  • data (DataT_contra)

  • value (ValueT_co)

Return type:

Uncertainty | None

class civiqhub_selene.estimator.Fingerprinted(*args, **kwargs)[source]

Bases: Protocol

Anything with a stable fingerprint. The only requirement on an input.

fingerprint()[source]

Return a stable fingerprint of the content.

Return type:

str