OutputState

Overview

OutputState(s) represent the result(s) of executing a Mechanism. This may be the result(s) of its function and/or values derived from that result. The full set of results are stored in the Mechanism’s output_values attribute. OutputStates are used to represent individual items of the Mechanism’s value, and/or useful quantities derived from them. For example, the function of a TransferMechanism generates a single result (the transformed value of its input); however, a TransferMechanism can also be assigned OutputStates that represent its mean, variance or other derived values. In contrast, the function of a DDM Mechanism generates several results (such as decision accuracy and response time), each of which can be assigned as the value of a different OutputState. The OutputState(s) of a Mechanism can serve as the input to other Mechanisms (by way of projections), or as the output of a Process and/or System. The OutputState’s efferents attribute lists all of its outgoing projections.

Creating an OutputState

An OutputState can be created by calling its constructor. However, in general this is not necessary, as a Mechanism automatically creates a default OutputState if none is explicitly specified, that contains the primary result of its function. For example, if the Mechanism is created within the pathway of a Process, an OutputState is created and assigned as the sender of a MappingProjection to the next Mechanism in the pathway, or to the Process’ output if the Mechanism is a TERMINAL Mechanism for that Process. Other configurations can also easily be specified using a Mechanism’s output_states argument (see OutputState Specification below). If it is created using its constructor, and a Mechanism is specified in the owner argument, it is automatically assigned to that Mechanism. If its **owner* is not specified, `initialization is deferred.

Owner Assignment and Deferred Initialization

An OutputState must be owned by a Mechanism. When OutputState is specified in the constructor for a Mechanism (see below), it is automatically assigned to that Mechanism as its owner. If the OutputState is created directly, its owner Mechanism can specified in the owner argument of its constructor, in which case it is assigned to the specified Mechanism. Otherwise, its initialization is deferred until the OutputState is assigned to a Mechanism using the Mechanism’s add_states method.

Primary OutputState

Every Mechanism has at least one OutputState, referred to as its primary OutputState. If OutputStates are not explicitly specified for a Mechanism, a primary OutputState is automatically created and assigned to its output_state attribute (note the singular), and also to the first entry of the Mechanism’s output_states attribute (note the plural). The primary OutputState is assigned an index of ‘0’, and therefore its value is assigned as the first (and often only) item of the Mechanism’s value attribute.

OutputState Specification

Specifying OutputStates when a Mechanism is created

OutputStates can be specified for a Mechanism when it is created, in the output_states argument of the Mechanism’s constructor (see examples in State), or in an OUTPUT_STATES entry of a parameter dictionary assigned to the constructor’s params argument. The latter takes precedence over the former (that is, if an OUTPUT_STATES entry is included in the parameter dictionary, any specified in the output_states argument are ignored).

Note

Assigning OutputStates to a Mechanism in its constructor replaces any that are automatically generated for that Mechanism (i.e., those that it creates for itself by default). If any of those need to be retained, they must be explicitly specified in the list assigned to the output_states argument or the OUTPUT_STATES entry of the parameter dictionary in the params argument). In particular, if the default OutputState – that usually contains the result of the Mechanism’s function – is to be retained, it too must be specified along with any additional OutputStates desired.

Adding OutputStates to a Mechanism after it is created

OutputStates can also be added to a Mechanism, using the Mechanism’s add_states method. Unlike specification in the constructor, this does not replace any OutputStates already assigned to the Mechanism. Doing so appends them to the list of OutputStates in the Mechanism’s output_states attribute, and their values are appended to its output_values attribute. If the name of an OutputState added to a Mechanism is the same as one that is already exists on the Mechanism, its name is suffixed with a numerical index (incremented for each OutputState with that name; see Naming), and the OutputState is added to the list (that is, it does not replace the one that was already there).

OutputStates variable and value

Each OutputState created with or assigned to a Mechanism must reference one or more items of the Mechanism’s attributes, that serve as the OutputState’s variable, and are used by its function to generate the OutputState’s value. By default, it uses the first item of its owner Mechanism’s value. However, other attributes (or combinations of them) can be specified in the variable argument of the OutputState’s constructor, or the VARIABLE entry in an OutputState specification dictionary (see OutputState Customization). The specification must be compatible (in the number and type of items it generates) with the input expected by the OutputState’s function. The OutputState’s variable is used as the input to its function to generate the OutputState’s value, possibly modulated by a GatingSignal (see below). The OutputState’s value must, in turn, be compatible with any Projections that are assigned to it, or used to specify it.

The value of each OutputState of a Mechanism is assigned to a corresponding item of the Mechanism’s output_values attribute, in the order in which they are assigned in the output_states argument of its constructor, and listed in its output_states attribute.

Note

The output_values attribute of a Mechanism is not the same as its value attribute:

  • a Mechanism’s value attribute contains the full and unmodified results of its function;
  • a Mechanism’s output_values attribute contains a list of the value of each of its OutputStates.

Forms of Specification

OutputStates can be specified in a variety of ways, that fall into three broad categories: specifying an OutputState directly; use of a State specification dictionary; or by specifying one or more Components to which it should project. Each of these is described below:

Direct Specification of an OutputState

  • existing OutputState object or the name of one – it cannot belong to another Mechanism, and the format of its variable must be compatible with the aributes of the owner Mechanism specified for the OutputState’s variable (see OutputState Customization).
  • OutputState class, keyword OUTPUT_STATE, or a string – creates a default OutputState that uses the first item of the owner Mechanism’s value as its variable, and assigns it as the owner Mechanism’s primary OutputState. If the class name or OUTPUT_STATE keyword is used, a default name is assigned to the State; if a string is specified, it is used as the name of the OutputState (see Naming).
  • variable – creates an OutputState using the specification as the OutputState’s variable (see OutputState Customization). This must be compatible with (have the same number and type of elements as) the OutputState’s function. A default name is assigned based on the name of the Mechanism (see Naming).

OutputState Specification Dictionary

  • OutputState specification dictionary – this can be used to specify the attributes of an OutputState, using any of the entries that can be included in a State specification dictionary (see examples in State), including:

    • VARIABLE:<keyword or list> - specifies the attribute(s) of its owner Mechanism to use as the input to the OutputState’s function (see OutputState Customization); this must be compatible (in the number and format of the items it specifies) with the OutputState’s function.

    • FUNCTION:<Function, function or method> - specifies the function used to transform and/or combine the item(s) specified for the OutputState’s variable into its value; its input must be compatible (in the number and format of elements) with the specification of the OutputState’s variable (see OutputState Customization).

    • PROJECTIONS or MECHANISMS:<list of Projections and/or Mechanisms> - specifies one or more efferent MappingProjections from the OutputState, Mechanims that should receive them, and/or ModulatoryProjections for it to receive; this may be constrained by or have consequences for the OutputState’s variable and/or its value (see OutputState variable and value: Compatibility and Constraints).

      Note

      The INDEX and ASSIGN attributes described below have been deprecated in version 0.4.5, and should be replaced by use of the VARIABLE and FUNCTION entries, respectively. Although use of INDEX and ASSIGN is currently being supported for backward compatibility, this may be eliminated in a future version.

    • INDEX:<int> [DEPRECATED in version 0.4.5] - specifies the item of the owner Mechanism’s value to be used for the OutputState’s variable; equivalent to specifying (OWNER_VALUE, <int>) for VARIABLE (see OutputState Customization), which should be used for compatibility with future versions.


    • ASSIGN:<function> [DEPRECATED in version 0.4.5] - specifies the OutputState’s function <OutputState.assign>` attribute; FUNCTION should be used for compatibility with future versions.

Specifying an OutputState by Components to which it Projects

An OutputState can also be specified by specifying one or more Components to or from which it should be assigned Projection(s). Specifying an OutputState in this way creates both the OutputState and any of the specified or implied Projection(s) (if they don’t already exist). MappingProjections are assigned to the OutputState’s efferents attribute, and GatingProjections to its mod_afferents attribute. Any of the following can be used to specify an InputState by the Components that projection to it (see below for an explanation of the relationship between the variable of these Components and the OutputState’s value):

  • InputState, GatingSignal, Mechanism, or list with any of these – creates an OutputState with the relevant Projection(s). A MappingProjection is created to each InputState or ProcessingMechanism specified (for a Mechanism, its primary InputState is used). A GatingProjection is created for each GatingSignal or GatingMechamism specified (for a GatingMechanism, its first GatingSignal is used).
  • Projection – any form of Projection specification can be used; creates an OutputState and assigns it as the sender for any MappingProjections specified, and as the receiver for any GatingProjections specified.
  • OutputState specification tuples – these are convenience formats that can be used to compactly specify an OutputState along with Projections to or from it in any of the following ways:

    • 2-item tuple: (State name or list of State names, Mechanism) – 1st item must be the name of an InputState or Modulatory Signals, or a list of such names, and the 2nd item must be the Mechanism to which they all belong. Projections of the relevant types are created for each of the specified States (see State 2-item tuple for additional details).

    • 2-item tuple: (<State, Mechanism, or list of them>, Projection specification) – this is a contracted form of the 3-item tuple described below

    • 3-item tuple: (<value, State spec, or list of State specs>, variable spec, Projection specification) – this allows the specification of State(s) to which the OutputState should project, together with a specification of its variable attribute, and (optionally) parameters of the Projection(s) to use (e.g., their weight and/or exponent attributes. Each tuple must have at least the first two items (in the order listed), and can include the third:

      • value, State specification, or list of State specifications – specifies either the variable of the InputState, or one or more States that should project to it. The State specification(s) can be a (State name, Mechanism) tuple (see above), and/or include Mechanisms, in which case their primary InputState is used. All of the State specifications must be consistent with (that is, their value must be compatible with the variable of) the Projection specified in the fourth item if that is included.


      • Projection specification (optional) – specifies a Projection that must be compatible with the State specification(s) in the 1st item; if there is more than one State specified, and the Projection specification is used, all of the States must be of the same type (i.e.,either InputStates or GatingSignals), and the Projection Specification cannot be an instantiated Projection (since a Projection cannot be assigned more than one receiver).

OutputState variable and value: Compatibility and Constraints

The format of an OutputStates’ variable may have consequences that must be taken into account when specifying an OutputState by Components to which it projects. These depend on the context in which the specification is made, and possibly the value of other specifications. These considerations and how they are handled are described below, starting with constraints that are given the highest precedence:

  • OutputState’s value not constrained by any of the conditions above – then its variable is determined by the default for an OutputState (the format of the first item of its owner Mechanism’s value ). If the OutputState is specified to project to any other Components, then if the Component is a:



    • MappingProjection – if its matrix is specified, then the sender dimensionality of the matrix must be the same as that of the OutputState’s value; if its receiver is specified, but not its matrix, then a matrix is chosen that appropriately maps from the OutputState to the receiver (as described just above); if neither its matrix or its receiver are specified, then the Projection’s initialization is deferred until its receiver is specified.

    • GatingProjection, GatingSignal or GatingMechanism – any of these can be used to specify an OutputState; their value does not need to be compatible with the OutputState’s variable or value, however it does have to be compatible with the modulatory parameter of the OutputState’s function.

Standard OutputStates

Most types of Mechanisms have a standard_output_states class attribute, that contains a list of predefined OutputStates relevant to that type of Mechanism (for example, the TransferMechanism class has OutputStates for calculating the mean, median, variance, and standard deviation of its result). The names of these are listed as attributes of a class with the name <ABBREVIATED_CLASS_NAME>_OUTPUT. For example, the TransferMechanism class defines TRANSFER_OUTPUT, with attributes MEAN, MEDIAN, VARIANCE and STANDARD_DEVIATION that are the names of predefined OutputStates in its standard_output_states attribute. These can be used in the list of OutputStates specified for a TransferMechanism object, as in the following example:

>>> import psyneulink as pnl
>>> my_mech = pnl.TransferMechanism(default_variable=[0,0],
...                                 function=pnl.Logistic(),
...                                 output_states=[pnl.TRANSFER_OUTPUT.RESULT,
...                                                pnl.TRANSFER_OUTPUT.MEAN,
...                                                pnl.TRANSFER_OUTPUT.VARIANCE])

In this example, my_mech is configured with three OutputStates; the first will be named RESULT and will represent logistic transform of the 2-element input vector; the second will be named MEAN and will represent mean of the result (i.e., of its two elements); and the third will be named VARIANCE and contain the variance of the result.

OutputState Customization

An OutputState’s value can be customized by specifying its variable and/or function in the variable and function arguments of the OutputState’s constructor, the corresponding entries (VARIABLE and FUNCTION) of an OutputState specification dictionary, or in the variable spec (2nd) item of a 3-item tuple for the OutputState.

OutputState variable

By default, an OutputState uses the first (and usually only) item of the owner Mechanism’s value as its variable. However, this can be customized by specifying any other item of its owners value, the full value itself, other attributes of the owner, or any combination of these using the following keywords:

OWNER_VALUE – the entire value of the OutputState’s owner.

(OWNER_VALUE, <int>) – tuple specifying an item of the owner’s value indexed by the int; indexing begins with 0 (e.g.; 1 references the 2nd item).

<attribute name> – the name of an attribute of the OutputState’s owner (must be one in the owner’s params_dict dictionary); returns the value of the named attribute for use in the OutputState’s variable.

PARAMS_DICT – the owner Mechanism’s entire params_dict dictionary, that contains entries for all of it accessible attributes. The OutputState’s function must be able to parse the dictionary.

List[<any of the above items>] – this assigns the value of each item in the list to the corresponding item of the OutputState’s variable. This must be compatible (in number and type of elements) with the input expected by the OutputState’s function.

OutputState function

By default, the function of an OutputState is Linear, which simply assigns the OutputState’s variable as its value. However, a different function can be assigned, to transform and/or combine the item(s) of the OutputState’s variable for use as its value. The function can be a PsyNeuLink Function or any Python function or method, so long as the input it expects is compatible (in number and format of elements) with the OutputState’s variable.

Examples

In the following example, a DDM Mechanism named my_mech is configured with three OutputStates:

>>> my_mech = pnl.DDM(function=pnl.BogaczEtAl(),
...                   output_states=[pnl.DDM_OUTPUT.DECISION_VARIABLE,
...                                  pnl.DDM_OUTPUT.PROBABILITY_UPPER_THRESHOLD,
...                                  {pnl.NAME: 'DECISION ENTROPY',
...                                   pnl.VARIABLE: (pnl.OWNER_VALUE, 2),
...                                   pnl.FUNCTION: pnl.Stability(metric=pnl.ENTROPY) }])

The first two are Standard OutputStates that represent the decision variable of the DDM and the probability of it crossing of the upper (vs. lower) threshold. The third is a custom OutputState, that computes the entropy of the probability of crossing the upper threshold. It uses the 3rd item of the DDM’s value (items are indexed starting with 0), which contains the probability of crossing the upper threshold, and uses this as the input to the Stability Function assigned as the OutputState’s function, that computes the entropy of the probability. The three OutputStates will be assigned to the output_states attribute of my_mech, and their values will be assigned as items in its output_values attribute, in the order in which they are listed in the output_states argument of the constructor for my_mech.

Custom OutputStates can also be created on their own, and separately assigned or added to a Mechanism. For example, the DECISION ENTROPY OutputState could be created as follows:

>>> decision_entropy_output_state = pnl.OutputState(name='DECISION ENTROPY',
...                                                 variable=(OWNER_VALUE, 2),
...                                                 function=pnl.Stability(metric=pnl.ENTROPY))

and then assigned either as:

>>> my_mech = pnl.DDM(function=pnl.BogaczEtAl(),
...                   output_states=[pnl.DDM_OUTPUT.DECISION_VARIABLE,
...                                  pnl.DDM_OUTPUT.PROBABILITY_UPPER_THRESHOLD,
...                                  decision_entropy_output_state])

or:

>>> another_decision_entropy_output_state = pnl.OutputState(name='DECISION ENTROPY',
...                                                variable=(OWNER_VALUE, 2),
...                                                function=pnl.Stability(metric=pnl.ENTROPY))
>>> my_mech2 = pnl.DDM(function=pnl.BogaczEtAl(),
...                    output_states=[pnl.DDM_OUTPUT.DECISION_VARIABLE,
...                                   pnl.DDM_OUTPUT.PROBABILITY_UPPER_THRESHOLD])

>>> my_mech2.add_states(another_decision_entropy_output_state) 

Note that another new OutputState had to be used for the second example, as trying to add the first one created for my_mech to my_mech2 would have produced an error (since a State already belonging to one Mechanism can’t be added to another.

Structure

Every OutputState is owned by a Mechanism. It can send one or more MappingProjections to other Mechanisms. If its owner is a TERMINAL Mechanism of a Process and/or System, then the OutputState will also be treated as the output of that Process and/or of a System. It has the following attributes, some of which can be specified in ways that are specific to, and that can be used to customize, the OutputState:

  • variable – references attributes of the OutputState’s owner that are used as the input to the OutputState’s function, to determine its value. The specification must match (in both the number and types of elements it generates) the input to the OutputState’s function. By default, the first item of the owner Mechanisms’ value is used. However, this can be customized as described under OutputState Customization.
  • function – takes the OutputState’s variable as its input, and generates the OutputState’s value as its result. The default function is Linear that simply assigns the OutputState’s variable as its value. However, the parameters of the function – and thus the value of the OutputState – can be modified by GatingProjections received by the OutputState (listed in its mod_afferents attribute. A custom function can also be specified, so long as it can take as its input a value that is compatible with the OutputState’s variable.
  • projections – all of the Projections sent and received by the OutputState;
  • mod_afferentsGatingProjections that project to the OutputState, the value of which can modify the OutputState’s value (see the descriptions of Modulation under ModulatorySignals and GatingSignals for additional details). If the OutputState receives more than one GatingProjection, their values are combined before they are used to modify the value of the OutputState.
  • value: assigned the result of the OutputState’s function, possibly modified by any GatingProjections received by the OutputState. It is used as the input to any projections that the OutputStatue sends.

Execution

An OutputState cannot be executed directly. It is executed when the Mechanism to which it belongs is executed. When the Mechanism is executed, the values of its attributes specified for the OutputState’s variable (see OutputState Customization) are used as the input to the OutputState’s function. The OutputState is updated by calling its function. The result, modified by any GatingProjections the OutputState receives (listed in its mod_afferents attribute), is assigned as the value of the OutputState. This is assigned to a corresponding item of the Mechanism’s output_values attribute, and is used as the input to any projections for which the OutputState is the sender.

Class Reference

class psyneulink.components.states.outputstate.OutputState(owner, reference_value, variable=None, size=None, function=Linear(), index=PRIMARY, assign=None, projections=None, params=None, name=None, prefs=None, context=None)

Subclass of State that calculates and represents an output of a Mechanism.

Parameters:
  • owner (Mechanism) – the Mechanism to which the OutputState belongs; it must be specified or determinable from the context in which the OutputState is created.
  • reference_value (number, list or np.ndarray) – a template that specifies the format of the OutputState’s variable; if it is specified in addition to the variable argument, then these must be compatible (both in the number and type of elements). It is used to insure the compatibility of the source of the input for the OutputState with its function.
  • variable (number, list or np.ndarray) – specifies the attributes of the OutputState’s owner Mechanism to be used by the OutputState’s function in generating its value.
  • function (Function, function, or method : default Linear) – specifies the function used to transform and/or combine the items designated by the OutputState’s variable into its value, under the possible influence of GatingProjections received by the OutputState.
  • projections (list of Projection specifications) – species the MappingProjection(s) to be sent by the OutputState, and/or GatingProjections(s) to be received (see OutputState_Projections for additional details); these will be listed in its efferents and mod_afferents attributes, respectively (see OutputState_Projections for additional details).
  • params (Dict[param keyword: param value] : default None) – a parameter dictionary that can be used to specify the parameters for the OutputState, its function, and/or a custom function and its parameters. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
  • name (str : default see name) – specifies the name of the OutputState; see OutputState name for details.
  • prefs (PreferenceSet or specification dict : default State.classPreferences) – specifies the PreferenceSet for the OutputState; see prefs for details.
owner

Mechanism – the Mechanism to which the OutputState belongs.

mod_afferents

List[GatingProjection]GatingProjections received by the OutputState.

variable

value, list or np.ndarray – the value(s) of the item(s) of the owner Mechanism’s attributes specified in the variable argument of the constructor, or a VARIABLE entry in the OutputState specification dictionary used to construct the OutputState.

function

Function, function, or method – function used to transform and/or combine the value of the items of the OutputState’s variable into its value, under the possible influence of GatingProjections received by the OutputState.

value

number, list or np.ndarray – assigned the result of function; the same value is assigned to the corresponding item of the owner Mechanism’s output_values attribute.

efferents

List[MappingProjection]MappingProjections sent by the OutputState (i.e., for which the OutputState is a sender).

projections

List[Projection] – all of the Projections received and sent by the OutputState.

name

str – the name of the OutputState; if it is not specified in the name argument of the constructor, a default is assigned by the OutputStateRegistry of the Mechanism to which the OutputState belongs. Note that most Mechanisms automatically create one or more Standard OutputStates, that have pre-specified names. However, if any OutputStates are specified in the input_states argument of the Mechanism’s constructor, those replace its Standard OutputStates (see note); standard naming conventions apply to the OutputStates specified, as well as any that are added to the Mechanism once it is created.

Note

Unlike other PsyNeuLink components, State names are “scoped” within a Mechanism, meaning that States with the same name are permitted in different Mechanisms. However, they are not permitted in the same Mechanism: States within a Mechanism with the same base name are appended an index in the order of their creation.

prefs

PreferenceSet or specification dict – the PreferenceSet for the OutputState; if it is not specified in the prefs argument of the constructor, a default is assigned using classPreferences defined in __init__.py (see PreferenceSet for details).

owner_value_index

Return index or indices of items of owner.value for any to which OutputState’s variable has been assigned If the OutputState has been assigned to: - the entire owner value (i.e., OWNER_VALUE on its own, not in a tuple)

return owner.value
  • a single item of owner.value (i.e., owner.value==(OWNER,index))
    return the index of the item
  • more than one, return a list of indices
  • to no items of owner.value (but possibly other params), return None
class psyneulink.components.states.outputstate.StandardOutputStates(owner: psyneulink.components.component.Component, output_state_dicts: list, indices: <typecheck.framework.optional object at 0x1043f0b70> = None)

Collection of OutputState specification dicts for standard OutputStates of a class.

Parses specification of VARIABLE, assigning indices to OWNER_VALUE if specified. Adds <NAME_INDEX> of each OutputState as property of the owner’s class, that returns the index of the OutputState in the list.

Parameters:
  • owner (Component) – the Component to which this OutputState belongs
  • output_state_dicts (list of dicts) – list of dictionaries specifying OutputStates for the Component specified by owner
  • indices (PRIMARY,) –
  • list of ints (SEQUENTIAL,) –

    specifies how to assign the (OWNER_VALUE, int) entry for each dict listed in output_state_dicts;

    The effects of each value of indices are as follows:

    • PRIMARY – assigns (OWNER_VALUE, PRIMARY) to all output_states for which a VARIABLE entry is not specified;
    • SEQUENTIAL – assigns sequentially incremented int to (OWNER_VALUE, int) spec of each OutputState, ignoring any VARIABLE entries previously specified for individual OutputStates;
    • list of ints – assigns each int to an (OWNER_VALUE, int) entry of the corresponding OutputState in `output_state_dicts, ignoring any VARIABLE entries previously specified for individual OutputStates;
    • None – assigns None to VARIABLE entries for all OutputStates for which it is not already specified.
data

dict – dictionary of OutputState specification dictionaries

indices

list – list of default indices for each OutputState specified

names

list – list of the default names for each OutputState

get_state_dict(name)

returns a copy of the designated OutputState specification dictionary

get_state_dict(name: str)

Return a copy of the named OutputState dict

psyneulink.components.states.outputstate.make_readonly_property(val)

Return property that provides read-only access to its value