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.

Example:

>>> # Create base scenario definitions
>>> base_defs = (
...     FlagAggKPIBuilder()
...     .for_flag('BZ.Results.price')
...     .with_aggregation(Aggregations.Mean)
...     .build()
... )
>>>
>>> # Create comparison definitions
>>> comp_builder = ComparisonKPIBuilder(base_defs)
>>> comp_defs = (
...     comp_builder
...     .with_comparisons([
...         ValueComparisons.Increase,
...         ValueComparisons.PercentageIncrease
...     ])
...     .build()
... )
>>> # Creates 2 comparison definitions (1 base × 2 comparisons)
Source code in submodules/mesqual/mesqual/kpis/builders/comparison_builder.py 
 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
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
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.

    Example:

        >>> # Create base scenario definitions
        >>> base_defs = (
        ...     FlagAggKPIBuilder()
        ...     .for_flag('BZ.Results.price')
        ...     .with_aggregation(Aggregations.Mean)
        ...     .build()
        ... )
        >>>
        >>> # Create comparison definitions
        >>> comp_builder = ComparisonKPIBuilder(base_defs)
        >>> comp_defs = (
        ...     comp_builder
        ...     .with_comparisons([
        ...         ValueComparisons.Increase,
        ...         ValueComparisons.PercentageIncrease
        ...     ])
        ...     .build()
        ... )
        >>> # Creates 2 comparison definitions (1 base × 2 comparisons)
    """

    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

        Example:

            >>> base_defs = [def1, def2, def3]  # 3 base definitions
            >>> comp_builder = ComparisonKPIBuilder(base_defs)
            >>> comp_defs = comp_builder.with_comparisons([ValueComparisons.Increase, ValueComparisons.PercentageIncrease]).build()
            >>> len(comp_defs)  # 3 base × 2 comparisons = 6
                6
        """
        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 submodules/mesqual/mesqual/kpis/builders/comparison_builder.py 
45
46
47
48
49
50
51
52
53
54
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 submodules/mesqual/mesqual/kpis/builders/comparison_builder.py 
56
57
58
59
60
61
62
63
64
65
66
67
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 submodules/mesqual/mesqual/kpis/builders/comparison_builder.py 
69
70
71
72
73
74
75
76
77
78
79
80
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

Example:

>>> base_defs = [def1, def2, def3]  # 3 base definitions
>>> comp_builder = ComparisonKPIBuilder(base_defs)
>>> comp_defs = comp_builder.with_comparisons([ValueComparisons.Increase, ValueComparisons.PercentageIncrease]).build()
>>> len(comp_defs)  # 3 base × 2 comparisons = 6
    6
Source code in submodules/mesqual/mesqual/kpis/builders/comparison_builder.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def build(self) -> list[ComparisonKPIDefinition]:
    """
    Generate all comparison KPI definitions.

    Creates the Cartesian product of base_definitions × comparisons.

    Returns:
        List of ComparisonKPIDefinition instances

    Example:

        >>> base_defs = [def1, def2, def3]  # 3 base definitions
        >>> comp_builder = ComparisonKPIBuilder(base_defs)
        >>> comp_defs = comp_builder.with_comparisons([ValueComparisons.Increase, ValueComparisons.PercentageIncrease]).build()
        >>> len(comp_defs)  # 3 base × 2 comparisons = 6
            6
    """
    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