rapid.robustness.metrics.transforms package¶
Subpackages¶
Submodules¶
rapid.robustness.metrics.transforms.t1 module¶
Contains the T1 functions (performance value transformations).
- In general, T1 will take one of 3 forms:
- Identity transform - for understanding actual performance
- Regret transform - for understanding cost of making wrong decision
- Satisficing transform - for understanding how often constraints are satisfied.
It is expected that after T1, the aim is to maximise performance. i.e. Even for the identity transform, if minimising, then values will be returned as negative.
-
rapid.robustness.metrics.transforms.t1.identity(f, maximise=True)¶ Keeps values the same unless minimising.
If minimising, values are made negative so that the aim becomes to maximise performance.
Parameters: - f (np.ndarray, shape=(m, n)) – Performance values, f, for m decision alternatives and n scenarios.
- maximise (bool) – Is the performance metric to be maximised or minimised. (The default is True, which implies high values of f are better than low values of f).
Returns: Transformed performance values, f’, for m decision alternatives and n scenarios
Return type: np.ndarray, shape=(m, n)
-
rapid.robustness.metrics.transforms.t1.regret_from_best_da(f, maximise=True)¶ T1: Regret from best decision alternative
Returns negative regret, so that from this point on, the aim is to maximise the negative regret (towards 0).
Parameters: - f (np.ndarray, shape=(m, n)) – Performance values, f, for m decision alternatives and n scenarios.
- maximise (bool) – Is the performance metric to be maximised or minimised. (The default is True, which implies high values of f are better than low values of f).
Returns: Transformed performance values, f’, for m decision alternatives and n scenarios
Return type: np.ndarray, shape=(m, n)
-
rapid.robustness.metrics.transforms.t1.regret_from_median(f, maximise=True)¶ T1: Regret from median values
For a given decision alternative, this function compares its performance in each scenario to median performance for that decision alternative
For a given decision alternative, this function compares its performance in each scenario to given performance value for that decision alternative Returns negative regret, so that from this point on, the aim is to maximise the negative regret (towards 0).
Parameters: - f (np.ndarray, shape=(m, n)) – Performance values, f, for m decision alternatives and n scenarios.
- maximise (bool) – Is the performance metric to be maximised or minimised. (The default is True, which implies high values of f are better than low values of f).
Returns: Transformed performance values, f’, for m decision alternatives and n scenarios
Return type: np.ndarray, shape=(m, n)
-
rapid.robustness.metrics.transforms.t1.regret_from_values(f, values, maximise=True)¶ T1: Regret from given values
For a given decision alternative, this function compares its performance in each scenario to given performance value for that decision alternative Returns negative regret, so that from this point on, the aim is to maximise the negative regret (towards 0).
Parameters: - f (np.ndarray, shape=(m, n)) – Performance values, f, for m decision alternatives and n scenarios.
- values (np.ndarray, shape=(n, ) or float) – The values to compare the performance values to. i.e. The values you would regret not getting, relative to f. Can be a different value for each scenario or one value across all scenarios.
- maximise (bool) – Is the performance metric to be maximised or minimised. (The default is True, which implies high values of f are better than low values of f).
Returns: Transformed performance values, f’, for m decision alternatives and n scenarios
Return type: np.ndarray, shape=(m, n)
-
rapid.robustness.metrics.transforms.t1.satisfice(f, maximise=True, threshold=0.0, accept_equal=True)¶ Transform performance how many scenarios are satisficed
Parameters: - f (np.ndarray, shape=(m, n)) – Performance values, f, for m decision alternatives and n scenarios.
- maximise (bool) – Is the performance metric to be maximised or minimised. (The default is True, which implies high values of f are better than low values of f).
- threshold (float, optional) – A minimum value where f >= threshold to be satisficed (The default is 0.0, which implies that any f value above 0 is of satisfactory performance).
- accept_equal (bool, optional) – Whether or not an f value equal to the threshold is acceptable. (The default is True, which implies a >= comparison, whereas False would imply a > comparison).
Returns: Transformed performance values, f’, for m decision alternatives and n scenarios
Return type: np.ndarray, shape=(m, n)
-
rapid.robustness.metrics.transforms.t1.satisficing_regret(f, threshold, maximise=True)¶ T1: Satisficing regret
For a given decision alternative, this function compares its performance in each scenario to a threshold (threshold can be different for each decision alternative), and calculates the magnitude from the threshold (if it fails) or returns 0 if it meets the threshold Returns negative regret, so that from this point on, the aim is to maximise the negative regret (towards 0).
Parameters: - f (np.ndarray, shape=(m, n)) – Performance values, f, for m decision alternatives and n scenarios.
- threshold (np.ndarray, shape=(n, ) or float) – The values to compare the performance values to. i.e. The values you would regret not getting, relative to f. Can be a different value for each scenario or one value across all scenarios.
- maximise (bool) – Is the performance metric to be maximised or minimised. (The default is True, which implies high values of f are better than low values of f).
Returns: Transformed performance values, f’, for m decision alternatives and n scenarios
Return type: np.ndarray, shape=(m, n)
rapid.robustness.metrics.transforms.t2 module¶
Contains the T2 transformations (scenario subset selection).
This is related to the level of risk averseness of the decision-maker.
-
rapid.robustness.metrics.transforms.t2.all_scenarios(f)¶ Use all scenarios. Provided for completeness.
Parameters: f (np.ndarray, shape=(m, n)) – Transformed performance values to be maximised. m decision alternatives and n scenarios Returns: The selected n’ performance values In this case n’ = n Return type: np.ndarray, shape=(m, n’)
-
rapid.robustness.metrics.transforms.t2.best_case(f)¶ Assume the best-case scenario for each decision alternative.
Parameters: f (np.ndarray, shape=(m, n)) – Transformed performance values to be maximised. m decision alternatives and n scenarios Returns: The selected n’ performance values In this case n’ = 1 Return type: np.ndarray, shape=(m, n’)
-
rapid.robustness.metrics.transforms.t2.select_percentiles(f, percentiles)¶ Select particular percentiles of f for each decision alternative.
Parameters: - f (np.ndarray, shape=(m, n)) – Transformed performance values to be maximised. m decision alternatives and n scenarios
- percentiles (np.ndarray, shape=(n', ), dtype=float) – Which percentile of to select for each decision alternative. E.g. [0.2, 0.75] would get the 20th and 75th percentiles for each decision alternative. That is to say, the f values for each decision alternative where 20% and 75% of values are worse.
Returns: The selected n’ performance values n’ is given by the percentiles parameter
Return type: np.ndarray, shape=(m, n’)
-
rapid.robustness.metrics.transforms.t2.worst_and_best_cases(f)¶ Work with the most extreme worst- and best-case scenarios.
Parameters: f (np.ndarray, shape=(m, n)) – Transformed performance values to be maximised. m decision alternatives and n scenarios Returns: The selected n’ performance values In this case n’ = 2 Return type: np.ndarray, shape=(m, n’)
-
rapid.robustness.metrics.transforms.t2.worst_case(f)¶ Assume the worst-case scenario for each decision alternative.
Parameters: f (np.ndarray, shape=(m, n)) – Transformed performance values to be maximised. m decision alternatives and n scenarios Returns: The selected n’ performance values In this case n’ = 1 Return type: np.ndarray, shape=(m, n’)
-
rapid.robustness.metrics.transforms.t2.worst_half(f)¶ Work with the worst half of scenarios
Parameters: f (np.ndarray, shape=(m, n)) – Transformed performance values to be maximised. m decision alternatives and n scenarios Returns: The selected n’ performance values In this case n’ = 0.5*n (round up to nearest whole number) Return type: np.ndarray, shape=(m, n’)
rapid.robustness.metrics.transforms.t3 module¶
Contains T3 performance transformations (aggregation to robustness)
Generally the selected and transformed performance values, f, are transformed to an expected value of performance.
However, supplementary metrics may consider the variance in f, or higher-order moments of f.
-
rapid.robustness.metrics.transforms.t3.f_identity(f)¶ Identity transform included for completeness.
Parameters: f (np.ndarray, shape=(m, 1)) – Transformed performance values to be maximised. m decision alternatives and n scenarios Returns: The robustness value for each of the m decision alternatives Return type: np.ndarray, shape=(m, )
-
rapid.robustness.metrics.transforms.t3.f_kurtosis(f)¶ Calculate robustness as the kurtosis of f
Parameters: f (np.ndarray, shape=(m, 4)) – Transformed performance values. m decision alternatives and 4 scenarios. Those 4 scenarios must be (in order) the 10th, 25th, 75th and 90th percentiles, where the 10th percentile, q10, is f where only 10% of f is worse than q10. Returns: The robustness value for each of the m decision alternatives Return type: np.ndarray, shape=(m, )
-
rapid.robustness.metrics.transforms.t3.f_mean(f)¶ Calculate robustness as mean of f
Parameters: f (np.ndarray, shape=(m, n)) – Transformed performance values to be maximised. m decision alternatives and n scenarios Returns: The robustness value for each of the m decision alternatives Return type: np.ndarray, shape=(m, )
-
rapid.robustness.metrics.transforms.t3.f_mean_variance(f)¶ Calculate robustness as a combination of mean and variance of f
Parameters: f (np.ndarray, shape=(m, n)) – Transformed performance values to be maximised. m decision alternatives and n scenarios Returns: The robustness value for each of the m decision alternatives Return type: np.ndarray, shape=(m, )
-
rapid.robustness.metrics.transforms.t3.f_range(f)¶ Calculate robustness as range of f
Parameters: f (np.ndarray, shape=(m, n)) – Transformed performance values to be maximised. m decision alternatives and n scenarios Returns: The robustness value for each of the m decision alternatives Return type: np.ndarray, shape=(m, )
-
rapid.robustness.metrics.transforms.t3.f_skew(f, reverse=False)¶ Calculate robustness as the skew of f
It assumes that it is best to have most values skewed towards high performance, with a larger tail for low performance.
Parameters: - f (np.ndarray, shape=(m, 3)) – Transformed performance values to be maximised. m decision alternatives and 3 scenarios. Those 3 scenarios must be (in order) the 10th, 50th and 90th percentiles, where the 10th percentile, p10, is f where only 10% of f is worse than p10. If wanting the reverse of this, see arg ‘reverse’ below.
- reverse (bool, optional) – Reverses the skew calculation to have a preference for a larger tail of higher-performance values. (The default is False, which implies it is best to have a skew towards high f with a larger tail towards low f).
Returns: The robustness value for each of the m decision alternatives
Return type: np.ndarray, shape=(m, )
-
rapid.robustness.metrics.transforms.t3.f_sum(f)¶ Calculate robustness as sum of f (/ n_scenarios)
Parameters: f (np.ndarray, shape=(m, n)) – Transformed performance values to be maximised. m decision alternatives and n scenarios Returns: The robustness value for each of the m decision alternatives Return type: np.ndarray, shape=(m, )
-
rapid.robustness.metrics.transforms.t3.f_variance(f)¶ Calculate robustness as variance of f
Parameters: f (np.ndarray, shape=(m, n)) – Transformed performance values to be maximised. m decision alternatives and n scenarios Returns: The robustness value for each of the m decision alternatives Return type: np.ndarray, shape=(m, )
-
rapid.robustness.metrics.transforms.t3.f_w_sum(f, weights)¶ Calculate robustness as weighted sum of f
Parameters: - f (np.ndarray, shape=(m, n)) – Transformed performance values to be maximised. m decision alternatives and n scenarios
- weights (np.ndarray, shape=(n, )) – Weights to apply to each scenario E.g. for n=3, you could use weights = [0.5, 0.25, 0.25]
Returns: The robustness value for each of the m decision alternatives
Return type: np.ndarray, shape=(m, )