Scoring model

ScoringModel

Abstract class that defines the interface for models that can score individual entities.

__call__

__call__(
    entity_id: int, entity_features: Optional[Series] = None
) -> Optional[tuple[float, float, float]]

Score a single entity and return its evaluation results.

Parameters:

Name	Type	Description	Default
entity_id	int		required
entity_features	Optional[Series]	Features of the entity that may be used for scoring.	None

Returns:

Type	Description
Optional[tuple[float, float, float]]	If scoring is successful, returns a tuple of three float values representing (score, left_uncertainty, right_uncertainty). Returns None if the entity cannot be scored

scored_entities

scored_entities(
    entities: Optional[DataFrame] = None,
) -> set[int]

Get the set of entity IDs that can be scored by this model.

Parameters:

Name	Type	Description	Default
entities	Optional[DataFrame]	DataFrame containing entities to score with their features. If None, uses internally stored entities.	None

Returns:

Type	Description
set[int]	Set of entity IDs that are available for scoring.

iter_entities

iter_entities(
    entities=None,
) -> Iterable[tuple[int, tuple[float, float, float]]]

Iterate over all available entities and yield their scoring results.

Parameters:

Name	Type	Description	Default
entities	DataFrame	DataFrame containing entity features. If None, uses internally stored entities.	None

Yields:

Type	Description
tuple[int, tuple[float, float, float]]	Pairs of (entity_id, scoring_results) for each entity that can be scored.

Notes

This method provides a default implementation that calls scored_entities() to get available IDs and __call__() to score each entity.

DirectScoringModel

DirectScoringModel(
    dct: Optional[
        dict[int, tuple[float, float, float]]
    ] = None
)

Bases: ScoringModel

A ScoringModel that contains scores directly assigned to each entity.

__call__

__call__(
    entity_id: int, entity_features=None
) -> Optional[tuple[float, float, float]]

__getitem__

__getitem__(
    entity_id: int,
) -> Optional[tuple[float, float, float]]

__setitem__

__setitem__(
    entity_id: int,
    score_and_uncertainties: Union[
        tuple[float, float, float], tuple[float, float]
    ],
)

scored_entities

scored_entities(entities=None) -> set[int]

iter_entities

iter_entities(
    entities=None,
) -> Iterable[tuple[int, tuple[float, float, float]]]

ScaledScoringModel

ScaledScoringModel(
    base_model: ScoringModel,
    multiplicator: float = 1.0,
    translation: float = 0.0,
    multiplicator_left_uncertainty: float = 0.0,
    multiplicator_right_uncertainty: float = 0.0,
    translation_left_uncertainty: float = 0.0,
    translation_right_uncertainty: float = 0.0,
)

Bases: ScoringModel

A ScoringModel with scaling parameters applied.

When base_model is itself a scaled scoring model, the scalings are aggregated, so that the base model is actually the scaled scoring model's base model.

Note

Note that this requires aggregating the uncertainties in a heuristic manner. At the core, this is because the uncertainties should grow quadratically with the size of the scores. Put differently, because of uncertainties, the composition of scaled scoring models is not an internal composition law (but it is if uncertainties are not accounted for).

base_model

base_model = base_model

multiplicator

multiplicator = multiplicator * multiplicator

translation

translation = translation + multiplicator * translation

multiplicator_left_uncertainty

multiplicator_left_uncertainty = (
    multiplicator_left_uncertainty
    + multiplicator * multiplicator_left_uncertainty
)

multiplicator_right_uncertainty

multiplicator_right_uncertainty = (
    multiplicator_right_uncertainty
    + multiplicator * multiplicator_right_uncertainty
)

translation_left_uncertainty

translation_left_uncertainty = (
    translation_left_uncertainty
    + multiplicator * translation_left_uncertainty
)

translation_right_uncertainty

translation_right_uncertainty = (
    translation_right_uncertainty
    + multiplicator * translation_right_uncertainty
)

__call__

__call__(entity_id, entity_features=None)

scale_score

scale_score(
    base_score, base_left_unc, base_right_unc
) -> tuple[float, float, float]

scored_entities

scored_entities(entities=None) -> set[int]

iter_entities

iter_entities(
    entities=None,
) -> Iterable[tuple[int, tuple[float, float, float]]]

compose_scaling_parameters

compose_scaling_parameters(parameters)

PostProcessedScoringModel

PostProcessedScoringModel(
    base_model: ScoringModel, post_process: Callable
)

Bases: ScoringModel

Defines a derived scoring model, based on a base model and a post process

Parameters:

Name	Type	Description	Default
base_model	ScoringModel		required
post_process	Callable	Must be a monotonous function float -> float	required

base_model

base_model = base_model

post_process

post_process = post_process

__call__

__call__(entity_id, entity_features=None)

apply_post_process

apply_post_process(
    base_score, base_left_unc, base_right_unc
)

scored_entities

scored_entities(entities=None) -> set[int]

iter_entities

iter_entities(
    entities=None,
) -> Iterable[tuple[int, tuple[float, float, float]]]