Skip to content

Comparison KPI Builder

ComparisonKPIBuilder

Bases: KPIBuilder[ComparisonKPIDefinition]

Builder for creating comparison KPI definitions from scenario KPIs.

Takes existing KPI definitions (typically for scenarios) and creates comparison definitions that compute differences, percentage changes, or other comparisons between datasets.

Examples:

>>> from mesqual.kpis import Aggregations, FlagAggKPIBuilder, ValueComparisons
>>> base_definitions = FlagAggKPIBuilder().for_flag('Country.Results.price').with_aggregation(Aggregations.Mean).build()
>>> comparison_definitions = (
...     ComparisonKPIBuilder(base_definitions)
...     .with_comparisons([ValueComparisons.Increase, ValueComparisons.PercentageIncrease])
...     .build()
... )
>>> len(comparison_definitions)  # 1 base definition, 2 comparisons
2
>>> study.comp.add_kpis_from_definitions_to_all_child_datasets(comparison_definitions)
Source code in src/mesqual/kpis/builders/comparison_builder.py
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class ComparisonKPIBuilder(KPIBuilder[ComparisonKPIDefinition]):
    """
    Builder for creating comparison KPI definitions from scenario KPIs.

    Takes existing KPI definitions (typically for scenarios) and creates
    comparison definitions that compute differences, percentage changes,
    or other comparisons between datasets.

    Examples:
        >>> from mesqual.kpis import Aggregations, FlagAggKPIBuilder, ValueComparisons
        >>> base_definitions = FlagAggKPIBuilder().for_flag('Country.Results.price').with_aggregation(Aggregations.Mean).build()
        >>> comparison_definitions = (
        ...     ComparisonKPIBuilder(base_definitions)
        ...     .with_comparisons([ValueComparisons.Increase, ValueComparisons.PercentageIncrease])
        ...     .build()
        ... )
        >>> len(comparison_definitions)  # 1 base definition, 2 comparisons
        2
        >>> study.comp.add_kpis_from_definitions_to_all_child_datasets(comparison_definitions)
    """

    def __init__(self, base_definitions: list[KPIDefinition]):
        """
        Initialize builder with base KPI definitions.

        Args:
            base_definitions: List of KPI definitions to create comparisons from
        """
        super().__init__()
        self._base_definitions = base_definitions
        self._comparisons: list[ValueComparison] = []

    def with_comparison(self, comp: ValueComparison) -> ComparisonKPIBuilder:
        """
        Set a single comparison operation.

        Args:
            comp: Comparison operation (e.g., ValueComparisons.Increase)

        Returns:
            Self for chaining
        """
        self._comparisons = [comp]
        return self

    def with_comparisons(self, comps: list[ValueComparison]) -> ComparisonKPIBuilder:
        """
        Set multiple comparison operations.

        Args:
            comps: List of comparison operations

        Returns:
            Self for chaining
        """
        self._comparisons = comps
        return self

    def build(self) -> list[ComparisonKPIDefinition]:
        """
        Generate all comparison KPI definitions.

        Creates the Cartesian product of base_definitions × comparisons.

        Returns:
            List of ComparisonKPIDefinition instances
        """
        definitions = []

        for base_def in self._base_definitions:
            for comp in self._comparisons:
                comp_def = ComparisonKPIDefinition(
                    base_definition=base_def,
                    comparison=comp,
                    name_prefix=self._name_prefix,
                    name_suffix=self._name_suffix,
                    custom_name=self._custom_name,
                    extra_attributes=self._extra_attributes,
                )
                definitions.append(comp_def)

        return definitions

__init__

__init__(base_definitions: list[KPIDefinition])

Initialize builder with base KPI definitions.

Parameters:

Name Type Description Default
base_definitions list[KPIDefinition]

List of KPI definitions to create comparisons from

required
Source code in src/mesqual/kpis/builders/comparison_builder.py
30
31
32
33
34
35
36
37
38
39
def __init__(self, base_definitions: list[KPIDefinition]):
    """
    Initialize builder with base KPI definitions.

    Args:
        base_definitions: List of KPI definitions to create comparisons from
    """
    super().__init__()
    self._base_definitions = base_definitions
    self._comparisons: list[ValueComparison] = []

with_comparison

with_comparison(comp: ValueComparison) -> ComparisonKPIBuilder

Set a single comparison operation.

Parameters:

Name Type Description Default
comp ValueComparison

Comparison operation (e.g., ValueComparisons.Increase)

required

Returns:

Type Description
ComparisonKPIBuilder

Self for chaining

Source code in src/mesqual/kpis/builders/comparison_builder.py
41
42
43
44
45
46
47
48
49
50
51
52
def with_comparison(self, comp: ValueComparison) -> ComparisonKPIBuilder:
    """
    Set a single comparison operation.

    Args:
        comp: Comparison operation (e.g., ValueComparisons.Increase)

    Returns:
        Self for chaining
    """
    self._comparisons = [comp]
    return self

with_comparisons

with_comparisons(comps: list[ValueComparison]) -> ComparisonKPIBuilder

Set multiple comparison operations.

Parameters:

Name Type Description Default
comps list[ValueComparison]

List of comparison operations

required

Returns:

Type Description
ComparisonKPIBuilder

Self for chaining

Source code in src/mesqual/kpis/builders/comparison_builder.py
54
55
56
57
58
59
60
61
62
63
64
65
def with_comparisons(self, comps: list[ValueComparison]) -> ComparisonKPIBuilder:
    """
    Set multiple comparison operations.

    Args:
        comps: List of comparison operations

    Returns:
        Self for chaining
    """
    self._comparisons = comps
    return self

build

build() -> list[ComparisonKPIDefinition]

Generate all comparison KPI definitions.

Creates the Cartesian product of base_definitions × comparisons.

Returns:

Type Description
list[ComparisonKPIDefinition]

List of ComparisonKPIDefinition instances

Source code in src/mesqual/kpis/builders/comparison_builder.py
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def build(self) -> list[ComparisonKPIDefinition]:
    """
    Generate all comparison KPI definitions.

    Creates the Cartesian product of base_definitions × comparisons.

    Returns:
        List of ComparisonKPIDefinition instances
    """
    definitions = []

    for base_def in self._base_definitions:
        for comp in self._comparisons:
            comp_def = ComparisonKPIDefinition(
                base_definition=base_def,
                comparison=comp,
                name_prefix=self._name_prefix,
                name_suffix=self._name_suffix,
                custom_name=self._custom_name,
                extra_attributes=self._extra_attributes,
            )
            definitions.append(comp_def)

    return definitions