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,versionorinput_typeis missing or malformed. The message names the class and the value.- Return type:
- final estimate(data, *, seed=0)[source]¶
Run the method on
dataand 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:
EstimatorDefinitionError – If the class does not declare its identity.
InvalidInputError – If
datais not an instance ofinput_type.InvalidParameterError – If
seedis not a non-negative integer.
- Return type:
Result[ValueT_co]
Say why no answer exists on
data, or returnNonewhen 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
Unavailablewhen the absence only shows during the computation. NeverNone, never NaN.- Return type:
ValueT_co | Unavailable
- _uncertainty(data, value)[source]¶
Return the uncertainty of
value, orNonewhen the method defines none.Not called when
_compute()returns an absence.- Parameters:
data (DataT_contra)
value (ValueT_co)
- Return type:
Uncertainty | None