fairical.utils

Shared utilities.

Module Attributes

IndicatorType

Supported indicators type for pareto front estimates.

Functions

extend_indicators(indicators[, radar_axes])

Extend indicators of each system with relative metrics.

make_table(indicators[, table_keys, fmt])

Extract and format table from pre-computed evaluation data.

normalize_onvg(values)

Normalize ONVG indicators so range is \([0, 1]\).

normalized_radar_area(values[, maximum])

Evaluate the radar-chart area formed by indicators of interest.

parse_indicator(ind)

Parse indicator from string.
fairical.utils.IndicatorType

Supported indicators type for pareto front estimates.

alias of Literal[‘hv’, ‘ud’, ‘os’, ‘as’, ‘onvg’, ‘onvgr’, ‘relative-onvg’, ‘area’]

fairical.utils.parse_indicator(ind)[source]

Parse indicator from string.

Parameters:

ind (Union[str, Literal['hv', 'ud', 'os', 'as', 'onvg', 'onvgr', 'relative-onvg', 'area']]) – Indicator prototype to parse.

Return type:

Literal['hv', 'ud', 'os', 'as', 'onvg', 'onvgr', 'relative-onvg', 'area']

Returns:

Parsed indicator value.

fairical.utils.normalize_onvg(values)[source]

Normalize ONVG indicators so range is \([0, 1]\).

This function normalizes the ONVG indicators of multiple systems so that it represents a ratio between the original value and the maximum for all systems compared.

Parameters:

values (list[int]) – The values of all ONVG indicators to normalize.

Return type:

list[float]

Returns:

A new list containing the values of indicators divided by their maximum.

fairical.utils.normalized_radar_area(values, maximum=1.0)[source]

Evaluate the radar-chart area formed by indicators of interest.

This method calculates the “normalized” area (value between \([0, 1]\)) of a radar chart formed by indicators listed in values.

An intuitive way to calculate the area of radar chart is to consider it as a set of triangles, defined by the chart axes and the angles between then, out of which you know the sizes of two sides, which are given, and the angle between them, which is fixed (\(2\pi/n\)). For example, the area of a 3-way radar chart is therefore the total area of 3 triangles with sides equal to each combination of input values, with angles of \(120^o\). More generally, the total area can be defined as:

\[\sum_i^n 0.5 a_i b_i \sin(2\pi/n)\]

Where \(n\) is the total number of axes on the radar chart, and a_i and b_i are the adjacent axes for which we are computing the section area. To normalize this such that all charts have a maximum area of 1.0, one must bind the maximum values in each of the radar chart axes. In this implementation, we bind these maxima to 1.0. With that, one can compute the largest radar chart area and normalize the given area by that value.

If one considers each triangle individually, it becomes clear that the factor \(0.5 \sin(2\pi/n)\) cancels out and only \(a b / max^2\) matters. This simplified version is implemented here for maximum accuracy and speed.

Parameters:

  • values (list[int | float]) – The values of the radar chart plot. Naturally, at least 3 values must be provided. All values are required to lie in the interval \([0, 1]\).

  • maximum (float) – The maximum value one can have in each axis of the radar chart. This value is used to compute the normalization factor.

Return type:

float

Returns:

The “normalized” area (value between \([0, 1]\)) of a radar chart formed by indicators listed in values.

fairical.utils.extend_indicators(indicators, radar_axes=['relative-onvg', 'onvgr', 'ud', 'as', 'hv'])[source]

Extend indicators of each system with relative metrics.

This method adds relative-onvg, and relative radar chart area on area. The radar chart area is calculated based on the axes selected on radar_axes.

Note this function modifies the indicator dictionaries in-place.

Parameters:

  • indicators (Sequence[dict[Literal['hv', 'ud', 'os', 'as', 'onvg', 'onvgr', 'relative-onvg', 'area'], float]]) –

    Indicators organized in a dictionary of dictionaries where keys represent the labels of each system, and values, dictionaries that represent indicators for that system with at least keys listed in table_keys. We assume the following metrics are calculated for every system:

    • hv: the pareto estimate hypervolume (float)

    • onvg: the number of non-dominated solutions (int)

    • onvgr: the ratio between the number of non-dominated solutions and the total number of solutions (int)

    • ud: the uniformity of non-dominated solutions across the estimated front (float)

    • as: the average spread of non-dominated solutions across the estimated front (float)

  • radar_axes (Sequence[Literal['hv', 'ud', 'os', 'as', 'onvg', 'onvgr', 'relative-onvg', 'area']]) – The indicator keys that will be used for estimating the normalized radar surface for each system.

Return type:

None

fairical.utils.make_table(indicators, table_keys=['relative-onvg', 'onvgr', 'ud', 'as', 'hv'], fmt='simple')[source]

Extract and format table from pre-computed evaluation data.

Extracts elements from data that can be displayed on a terminal-style table, format, and return it.

Parameters:

  • indicators (dict[str, dict[Literal['hv', 'ud', 'os', 'as', 'onvg', 'onvgr', 'relative-onvg', 'area'], float]]) –

    Indicators organized in a dictionary of dictionaries where keys represent the labels of each system, and values, dictionaries that represent indicators for that system with at least keys listed in table_keys. We assume the following metrics are calculated for every system:

    • hv: the pareto estimate hypervolume (float)

    • onvg: the number of non-dominated solutions (int)

    • onvgr: the ratio between the number of non-dominated solutions and the total number of solutions (int)

    • ud: the uniformity of non-dominated solutions across the estimated front (float)

    • as: the average spread of non-dominated solutions across the estimated front (float)

  • table_keys (Sequence[Union[Literal['hv', 'ud', 'os', 'as', 'onvg', 'onvgr', 'relative-onvg', 'area'], str]]) – The indicator keys that will be tabulated in the table.

  • fmt (str) – One of the formats supported by python-tabulate. Default is “github”.

Return type:

str

Returns:

A string representation of a table.