outcome_in_range

negmas.outcomes.outcome_in_range(outcome, outcome_range, *, strict=False, fail_incomplete=False)[source]

Tests that the outcome is contained within the given range of outcomes.

An outcome range defines a value or a range of values for each issue.

Parameters:

  • outcome (tuple) – “Outcome” being tested

  • outcome_range (Mapping[int, Any]) – “Outcome” range being tested against

  • strict – Whether to enforce that all issues in the outcome must be mentioned in the outcome_range

  • fail_incomplete – If True then outcomes that do not sepcify a value for all keys in the outcome_range

  • falling (will be considered not falling within it. If False then these outcomes will be considered)

  • range (within the range given that the values for the issues mentioned in the outcome satisfy the)

  • constraints.

Examples

>>> outcome_range = {
...     "price": (0.0, 2.0),
...     "distance": [0.3, 0.4],
...     "type": ["a", "b"],
...     "area": 3,
... }
>>> outcome_range_2 = {"price": [(0.0, 1.0), (1.5, 2.0)], "area": [(3, 4), (7, 9)]}
>>> outcome_in_range({"price": 3.0}, outcome_range)
False
>>> outcome_in_range({"date": "2018.10.4"}, outcome_range)
True
>>> outcome_in_range({"date": "2018.10.4"}, outcome_range, strict=True)
False
>>> outcome_in_range({"area": 3}, outcome_range, fail_incomplete=True)
False
>>> outcome_in_range({"area": 3}, outcome_range)
True
>>> outcome_in_range({"type": "c"}, outcome_range)
False
>>> outcome_in_range({"type": "a"}, outcome_range)
True
>>> outcome_in_range({"date": "2018.10.4"}, outcome_range_2)
True
>>> outcome_in_range({"area": 3.1}, outcome_range_2)
True
>>> outcome_in_range({"area": 3}, outcome_range_2)
False
>>> outcome_in_range({"area": 5}, outcome_range_2)
False
>>> outcome_in_range({"price": 0.4}, outcome_range_2)
True
>>> outcome_in_range({"price": 0.4}, outcome_range_2, fail_incomplete=True)
False
>>> outcome_in_range({"price": 1.2}, outcome_range_2)
False
>>> outcome_in_range({"price": 0.4, "area": 3.9}, outcome_range_2)
True
>>> outcome_in_range({"price": 0.4, "area": 10}, outcome_range_2)
False
>>> outcome_in_range({"price": 1.2, "area": 10}, outcome_range_2)
False
>>> outcome_in_range({"price": 1.2, "area": 4}, outcome_range_2)
False
>>> outcome_in_range({"type": "a"}, outcome_range_2)
True
>>> outcome_in_range({"type": "a"}, outcome_range_2, strict=True)
False
>>> outcome_range = {"price": 10}
>>> outcome_in_range({"price": 10}, outcome_range)
True
>>> outcome_in_range({"price": 11}, outcome_range)
False
Returns:

Success or failure

Return type:

bool

Remarks:

Outcome ranges specify regions in an outcome space. They can have any of the following conditions:

  • A key/issue not mentioned in the outcome range does not add any constraints meaning that All values are acceptable except if strict == True. If strict == True then NO value will be accepted for issues not in the outcome_range.

  • A key/issue with the value None in the outcome range means All values on this issue are acceptable. This is the same as having this key/issue removed from the outcome space

  • A key/issue withe the value [] (empty list) accepts NO outcomes

  • A key/issue with a single value means that it is the only one acceptable

  • A key/issue with a single 2-items tuple (min, max) means that any value within that range is acceptable.

  • A key/issue with a list of values means an output is acceptable if it falls within the condition specified by any of the values in the list (list == union). Each such value can be a single value, a 2-items tuple or another list. Notice that lists of lists can always be combined into a single list of values