Performance Measures

A Measure is used to provide scoping information for a single model output.

class emat.Measure(name, kind=0, min=None, max=None, address=None, dtype=None, function=None, transform=None, variable_name=None, metamodeltype=None, shortname=None, desc=None, formula=None, tags=None, parser=None)[source]

Bases: emat.workbench.em_framework.outcomes.ScalarOutcome, emat.scope.names.ShortnameMixin, emat.scope.names.TaggableMixin

Measure represents an outcome measure of the model.

Parameters:
  • name (str) – Name of the measure.
  • kind (str or int, optional) – one of {‘info’, ‘minimize’, ‘maximize’}, defaults to ‘info’ if not given. This represents the generally preferred direction of the measure.
  • min (number, optional) – An expected minimum value that might be observed under any policy and scenario. This value is currently only used by the HyperVolume convergence metric.
  • max (number, optional) – An expected maximum value that might be observed under any policy and scenario. This value is currently only used by the HyperVolume convergence metric.
  • address (obj, optional) – The address or instruction for how to extract this measure from the model. This is model-specific and can potentially be any Python object. For example, if the model is an Excel model, this can be a cell reference given as a str.
  • dtype ({'real','int','bool','cat'}, default 'real') – The desired dtype to be enforced for this measure.
  • function (callable, optional) – A callable function that will be used to transform the raw measure as returned by a core model. This transformation will be applied to core model results by the evaluator before they are returned to the user or stored in a database. It is recommended that EMAT analysis work with the original untransformed raw values, and employ the metamodeltype functionality as required for non-linear responses.
  • transform (str, optional) – As an alternative to passing a callable object, use this argument to pass the name of a numpy function. This argument is ignored if function is given.
  • variable_name (str, optional) – The name of the raw measure as output by the underlying core model. If not given, this name is assumed to be the same as name. If no transform is set, it is strongly recommended to not give this argument either. A principal use of this argument is to descriptively rename measures that have been transformed, for example if the raw output measure is ‘Total VMT’ and a log transform function is applied, the result can be more descriptively renamed as ‘log(Total VMT)’.
  • metamodeltype (str, optional) –

    The transformation type to use for metamodel estimation. This transformation is applied only internally within the metamodel, and all inputs and outputs passed to or from the metamodel will not appear in a transformed state, including measure values stored within the database. Available metamodel types include:

    • log: The natural log of the performance measure is taken before fitting the regression model. This is appropriate only when the performance measure will always give a strictly positive outcome. If the performance measure can take on non-positive values, this may result in errors.
    • log1p: The natural log of 1 plus the performance measure is taken before fitting the regression model. This is preferred to log-linear when the performance measure is only guaranteed to be non-negative, rather than strictly positive.
    • logxp(X): The natural log of X plus the performance measure is taken before fitting the regression model. This allows shifting the position of the regression intercept to a point other than 0.
    • linear: No transforms are made. This is the default.
name

Name of the measure.

Type:str
kind

{MINIMIZE, MAXIMIZE, INFO}

Type:int
transform

The name of the transform function, if any.

Type:str
address

The address or instruction for how to extract this measure from the model.

Type:obj
metamodeltype

The transformation type to use for metamodel estimation.

Type:str
desc

Human readable description of this performance measure, for reference only

Type:str
formula

An eval-able expression to compute this performance measure from other measures

Type:str
info(return_string=False)[source]

Print some information about this measure

Parameters:return_string (bool) – Defaults False (print to stdout) but if given as True then this function returns the string instead of printing it.
parser

Instructions for how to parse this performance measure from raw output files

Type:dict
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