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, meta=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.
meta (Any, optional) – Meta-data to attach to this parameter

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, meta=None)[source]¶

Bases: Parameter, ShortnameMixin, 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.

meta¶

meta-data that is attached to this object.

Type:: Any

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, meta=None)[source]¶

Bases: 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

meta¶

meta-data that is attached to this constant.

Type:: Any

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, meta=None)[source]¶

Bases: Parameter, 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.

meta¶

meta-data that is attached to this object.

Type:: Any

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, meta=None)[source]¶

Bases: Parameter, 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.

meta¶

meta-data that is attached to this object.

Type:: Any

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, meta=None)[source]¶

Bases: Parameter, 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)
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)
Return type:: int

invert(name)¶

invert a category to an integer

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

meta¶

meta-data that is attached to this object.

Type:: Any

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, meta=None)[source]¶

Bases: Parameter, 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)
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)
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

meta¶

meta-data that is attached to this object.

Type:: Any

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