Parameters

A Parameter is used to provide scoping information for a single model input. This can be an exogenous uncertainty, or a policy lever. Invariant input (i.e., constants) can be represented with a Constant, which exposes a very similar set of attributes and methods, but doesn’t allow the value to vary. Neither class object should be instantiated directly, but instead use the make_parameter() function, which will create an object of the appropriate (sub)class.

emat.make_parameter(name, ptype='constant', desc='missing description', min=None, max=None, dist=None, default=None, corr=None, address=None, dtype='infer', values=None, resolution=None, shortname=None, abbrev=None)[source]

Factory method to build a Parameter or Constant for a model.

This function will create an object of the appropriate (sub)class for the parameter or constant.

Parameters:
  • name (str) – A name for this parameter. The name must be a str and ideally a valid Python identifier (i.e., begins with a letter or underscore, contains only letters, numerals, and underscores).
  • ptype (str, default 'constant') – The type for this parameter, one of {‘constant’, ‘uncertainty’, ‘lever’}.
  • min (numeric, optional) – The minimum value for this parameter.
  • max (numeric, optional) – The maximum value for this parameter.
  • dist (str or Mapping or rv_frozen, optional) – A definition of a distribution to use for this parameter. Can be specified just as the name of the distribution when that distribution is parameterized only by the min and max (e.g., ‘uniform’). If the distribution requires other parameters, this argument should be a Mapping, with keys including ‘name’ for the name of the distribution, as well as giving one or more named distributional parameters as appropriate. Or, just pass a rv_frozen object directly (see scipy.stats). The distribution defined here is of primary use for uncertainty parameters, as the features of defined uncertainty distributions can be used to derive probability distributions on outputs. However, distributions can also be used for policy lever parameters to guide the development of appropriate experimental designs.
  • default (Any, optional) – A default value for this parameter. The default value is used as the actual value for constant parameters. It is also used during univariate sensitivity testing as the value for this parameter when other parameters are being evaluated at non-default values.
  • corr (dict, optional) – A correlation definition that relates this parameter to others. Only applicable for uncertainty parameters.
  • address (Any, optional) – The address to use to access this parameter in the model. This is an implementation-specific detail. For example, in an Excel-based model, the address could be a sheet and cell reference given as a string.
  • dtype (str, default 'infer') – A dtype for this parameter, one of {‘cat’, ‘int’, ‘real’, ‘bool’} or some sub-class variant or specialization thereof (e.g., int64).
  • values (Collection, optional) – A collection of possible values, relevant only for categorical parameters.
  • resolution (Collection, optional) – A collection of possible particular values, used to set the possible values considered when sampling with factorial-based designs.
  • shortname (str, optional) – A shorter name, especially useful when the name of this parameter is a long strings that may not display neatly in figures.
  • abbrev (Mapping, optional) – A set of abbreviations used for values, especially useful when the names of values are long strings that may not display neatly in figures.
Returns:

Parameter or Constant

class emat.Parameter(name, dist, *, lower_bound=None, upper_bound=None, resolution=None, default=None, variable_name=None, pff=False, desc='', address=None, ptype=None, corr=None, dist_def=None, shortname=None, abbrev=None, tags=None)[source]

Bases: emat.workbench.em_framework.parameters.Parameter, emat.scope.names.ShortnameMixin, emat.scope.names.TaggableMixin

abbrev

Abbreviations used for long attribute names in figures.

Type:Dict
address

The address to use to access this parameter in the model.

This is an implementation-specific detail. For example, in an Excel-based model, the address could be a sheet and cell reference given as a string.

Type:Any
corr

A correlation definition. Key give names of other parameters, values give correlation.

Type:Dict
desc

Human readable description of this parameter, for reference only

Type:str
dist_def

The arguments that define the underlying distribution.

Type:Dict
get_abbrev(name)[source]

Get an abbreviated name if available.

ptype

Parameter type, one of {‘constant’, ‘uncertainty’, ‘lever’}

Type:str
property shortname

An abbreviated name, or the full name if not otherwise defined.

Type:Str
property shortname_if_any

The abbreviated name, or None.

Type:Str
property tags

A set of tags attached to this object.

Type:Set
class emat.Constant(name, value, desc='', address=None, dtype=None)[source]

Bases: emat.workbench.em_framework.parameters.Constant

address

The address to use to access this parameter in the model.

This is an implementation-specific detail. For example, in an Excel-based model, the address could be a sheet and cell reference given as a string.

Type:Any
property default

Read-only alias for value

desc

Human readable description of this constant, for reference only

Type:str
dtype

The dtype for the value, as a string.

Type:str
ptype = 'constant'

Parameter type, for compatibility with Parameter.

Type:str
property values

The value as a one-item list

Type:list

Float-Valued Parameters

class emat.scope.parameter.RealParameter(name, *, lower_bound=None, upper_bound=None, resolution=None, default=None, variable_name=None, pff=False, dist=None, dist_def=None, desc='', address=None, ptype=None, corr=None, shortname=None, abbrev=None)[source]

Bases: emat.scope.parameter.Parameter, emat.workbench.em_framework.parameters.RealParameter

abbrev

Abbreviations used for long attribute names in figures.

Type:Dict
address

The address to use to access this parameter in the model.

This is an implementation-specific detail. For example, in an Excel-based model, the address could be a sheet and cell reference given as a string.

Type:Any
corr

A correlation definition. Key give names of other parameters, values give correlation.

Type:Dict
desc

Human readable description of this parameter, for reference only

Type:str
dist_def

The arguments that define the underlying distribution.

Type:Dict
get_abbrev(name)

Get an abbreviated name if available.

ptype

Parameter type, one of {‘constant’, ‘uncertainty’, ‘lever’}

Type:str
property shortname

An abbreviated name, or the full name if not otherwise defined.

Type:Str
property shortname_if_any

The abbreviated name, or None.

Type:Str
property tags

A set of tags attached to this object.

Type:Set

Continuous Distributions

Float-valued parameters can use any continuous distribution available in scipy.stats. For convenience, a few extra (and simplified) distributions are available in the emat.util.distributions module.

Integer Parameters

class emat.scope.parameter.IntegerParameter(name, *, lower_bound=None, upper_bound=None, resolution=None, default=None, variable_name=None, pff=False, dist=None, dist_def=None, desc='', address=None, ptype=None, corr=None, shortname=None, abbrev=None)[source]

Bases: emat.scope.parameter.Parameter, emat.workbench.em_framework.parameters.IntegerParameter

abbrev

Abbreviations used for long attribute names in figures.

Type:Dict
address

The address to use to access this parameter in the model.

This is an implementation-specific detail. For example, in an Excel-based model, the address could be a sheet and cell reference given as a string.

Type:Any
corr

A correlation definition. Key give names of other parameters, values give correlation.

Type:Dict
desc

Human readable description of this parameter, for reference only

Type:str
dist_def

The arguments that define the underlying distribution.

Type:Dict
get_abbrev(name)

Get an abbreviated name if available.

ptype

Parameter type, one of {‘constant’, ‘uncertainty’, ‘lever’}

Type:str
property shortname

An abbreviated name, or the full name if not otherwise defined.

Type:Str
property shortname_if_any

The abbreviated name, or None.

Type:Str
property tags

A set of tags attached to this object.

Type:Set

Discrete Distributions

Integer-valued parameters can use any discrete distribution available in scipy.stats. Note that actually using a discrete distribution is required, one cannot use a continuous distribution that loosely approximates a discrete distribution. The only exception to this rule is for “uniform”, which is technically a continuous distribution, but is transparently interpreted by EMAT as an equivalently-bounded “randint”.

Boolean Parameters

class emat.scope.parameter.BooleanParameter(name, *, lower_bound=None, upper_bound=None, resolution=None, default=None, variable_name=None, pff=False, dist=None, dist_def=None, desc='', address=None, ptype=None, corr=None, shortname=None, abbrev=None)[source]

Bases: emat.scope.parameter.Parameter, emat.workbench.em_framework.parameters.BooleanParameter

abbrev

Abbreviations used for long attribute names in figures.

Type:Dict
address

The address to use to access this parameter in the model.

This is an implementation-specific detail. For example, in an Excel-based model, the address could be a sheet and cell reference given as a string.

Type:Any
cat_for_index(index)

return category given index

Parameters:index (int) –
Returns:
Return type:object
corr

A correlation definition. Key give names of other parameters, values give correlation.

Type:Dict
desc

Human readable description of this parameter, for reference only

Type:str
dist_def

The arguments that define the underlying distribution.

Type:Dict
get_abbrev(name)

Get an abbreviated name if available.

index_for_cat(category)

return index of category

Parameters:category (object) –
Returns:
Return type:int
invert(name)

invert a category to an integer

Parameters:name (obj) – category
Raises:ValueError – if category is not found
ptype

Parameter type, one of {‘constant’, ‘uncertainty’, ‘lever’}

Type:str
property shortname

An abbreviated name, or the full name if not otherwise defined.

Type:Str
property shortname_if_any

The abbreviated name, or None.

Type:Str
property tags

A set of tags attached to this object.

Type:Set
property values

The possible discrete values.

Type:List

Categorical Parameters

class emat.scope.parameter.CategoricalParameter(name, categories, *, default=None, variable_name=None, pff=False, multivalue=False, desc='', address=None, ptype=None, corr=None, dist=None, singleton_ok=False, shortname=None, abbrev=None)[source]

Bases: emat.scope.parameter.Parameter, emat.workbench.em_framework.parameters.CategoricalParameter

abbrev

Abbreviations used for long attribute names in figures.

Type:Dict
address

The address to use to access this parameter in the model.

This is an implementation-specific detail. For example, in an Excel-based model, the address could be a sheet and cell reference given as a string.

Type:Any
cat_for_index(index)[source]

return category given index

Parameters:index (int) –
Returns:
Return type:object
corr

A correlation definition. Key give names of other parameters, values give correlation.

Type:Dict
desc

Human readable description of this parameter, for reference only

Type:str
dist_def

The arguments that define the underlying distribution.

Type:Dict
property distdef

Categorical parameters distribution is not implemented.

Type:None
get_abbrev(name)

Get an abbreviated name if available.

index_for_cat(category)[source]

return index of category

Parameters:category (object) –
Returns:
Return type:int
invert(name)[source]

invert a category to an integer

Parameters:name (obj) – category
Raises:ValueError – if category is not found
property max

Categorical parameters are not characterized by an upper bound.

Type:None
property min

Categorical parameters are not characterized by a lower bound.

Type:None
ptype

Parameter type, one of {‘constant’, ‘uncertainty’, ‘lever’}

Type:str
property shortname

An abbreviated name, or the full name if not otherwise defined.

Type:Str
property shortname_if_any

The abbreviated name, or None.

Type:Str
property tags

A set of tags attached to this object.

Type:Set
property values

The possible discrete values.

Type:List