Boxes¶

A Box represents a constrained subset of experiments, containing only those cases that meet certain restrictions. These restrictions are expressed as limited ranges on a particular set of named parameters or measures. A Box can also designate a set of relevant features, which are not themselves constrained but should be considered in any analytical report developed based on that Box.

A Box can be created manually as part of the scoping process. For example, the initially defined scope may be too broad or may include more uncertainties or policy levers than an analyst wishes to study at a particular time. For this situation, a Box can be used to define a more limited scope for study, by limiting the ranges of some set of parameters. It is possible to effectively remove parameters from analysis by setting the minimum and maximum values to the same value (for scalar parameters) or by limiting the allowed set of values to a single value (for categorical parameters). It is also possible to include measures in the set of restrictions, which results in a different kind of exploratory analysis, where the analyst can undertake scenario discovery, to analyze the variety of input values that might lead to certain kinds of output values.

Box¶

class emat.Box(name, parent=None, scope=None, upper_bounds=None, lower_bounds=None, bounds=None, allowed=None, relevant=None)[source]¶

A Box defines a set of restricted dimensions for a Scope.

Parameters:

name (str) – The name for this Box.
parent (str, optional) – The name of the parent for this Box. When extracted as a ChainedBox from a collection of Boxes, the thresholds will also include any thresholds inherited from this box’s ancestor(s).
scope (Scope, optional) – A scope to associate with this box.
upper_bounds (Mapping[str, numeric], optional) – If given, a mapping with keys giving feature names and values giving an upper bound for each feature.
lower_bounds (Mapping[str, numeric], optional) – If given, a mapping with keys giving feature names and values giving a lower bound for each feature.
bounds (Mapping[str, Bounds], optional) – If given, a mapping with keys giving feature names and values giving Bounds for each feature.
allowed (Mapping[str, Set], optional) – If given, a mapping with keys giving feature names and values giving the available Set for each feature.
relevant (Iterable, optional) – If given, a set of names of relevant features.

thresholds¶

The restricted dimensions in this Box, with feature names as keys and Bounds or a Set of available discrete values as the dictionary values.

Type:	Dict[str,Union[Bounds,Set]]

relevant_features¶

A Set of features that are relevant for this Box. These are features, which are not themselves constrained, but should be considered in any analytical report developed based on this Box.

Type:	Set[str]

property scope¶

A scope associated with this Box.

Type:	Scope

property measure_thresholds¶

Dict[str,Union[Bounds,Set]]: The thresholds in this Box associated with performance measures.

A Scope must be associated with this Box to access this property.

property uncertainty_thresholds¶

Dict[str,Union[Bounds,Set]]: The thresholds in this Box associated with exogenous uncertainties.

A Scope must be associated with this Box to access this property.

property lever_thresholds¶

Dict[str,Union[Bounds,Set]]: The thresholds in this Box associated with policy levers.

A Scope must be associated with this Box to access this property.

Box.set_lower_bound(key, value)¶

Set a lower bound, retaining existing upper bound.

Parameters:	key (str) – The feature name to which this lower bound will be attached. value (numeric or None) – The lower bound. Set explicitly to ‘None’ to leave unbounded from below.
Raises:	ScopeError – If a scope is attached to this box but the key cannot be found in the scope.

Box.set_upper_bound(key, value)¶

Set an upper bound, retaining existing lower bound.

Parameters:	key (str) – The feature name to which this upper bound will be attached. value (numeric or None) – The upper bound. Set explicitly to ‘None’ to leave unbounded from above.
Raises:	ScopeError – If a scope is attached to this box but the key cannot be found in the scope.

Box.set_bounds(key, lowerbound, upperbound=None)[source]¶

Set both lower and upper bounds.

If values are both set to None and this key becomes unbounded but it was not previously unbounded, it is moved from thresholds to relevant_features. Conversely, if no bounds were previously set but the key appears in relevant_features, it is removed from that set.

Parameters:

key (str) – The feature name to which these bounds will be attached.
lowerbound (numeric, None, or Bounds) – The lower bound, or a Bounds object that gives upper and lower bounds (in which case the upperbound argument is ignored). Set explicitly to ‘None’ to leave unbounded from below.
upperbound (numeric or None, default None) – The upper bound. Set to ‘None’ to leave unbounded from above.

Raises:

ScopeError – If a scope is attached to this box but the key cannot be found in the scope.

Box.add_to_allowed_set(key, value)¶

Add a value to the allowed set

Parameters:	key (str) – The feature name to which these allowed values will be attached. value (Any) – A value to add to the allowed set.
Raises:	ValueError – If there is already a directional Bounds set for key. ScopeError – If a scope is attached to this box but the key cannot be found in the scope.

Box.remove_from_allowed_set(key, value)¶

Remove a value from the allowed set

Parameters:	key (str) – The feature name to which these allowed values will be attached. value (Any) – A value to remove from the allowed set.
Raises:	ValueError – If the threshold set for key is a directional Bounds instead of a set. ScopeError – If a scope is attached to this box but the key cannot be found in the scope. KeyError – If the value to be removed was not already in the allowed set.

Box.replace_allowed_set(key, values)[source]¶

Replace the allowed set.

If the new allowed set is the same as the complete set of possible values defined in the scope, this key becomes unbounded and it is moved from thresholds to relevant_features. Conversely, if no bounds were previously set but the key appears in relevant_features, it is removed from that set.

Parameters:	key (str) – The feature name to which these bounds will be attached. values (set) – A set of values to use as the allowed set. If an empty set or None is given, then any values are allowed.

Boxes¶

class emat.Boxes(*args, scope=None, **kw)[source]¶: Bases: collections.abc.MutableMapping

ChainedBox¶

class emat.ChainedBox(boxes, name)[source]¶

A Box defines a set of restricted dimensions for a Scope.

Parameters:	boxes (Boxes) – A collection of Boxes from which to assemble a chain. name (str) – The name for this ChainedBox. This must be the name of a Box in boxes, which serves as the seed for the chain. Ancestors are added recursively by finding the parent box of each box in the chain, until a box is found with no parent.

measure_thresholds()[source]¶

The thresholds in this Box or its ancestor(s) associated with performance measures.