KohonenMechanism

Overview

A KohonenMechanism is a subclass of RecurrentTransferMechanism that implements a Kohonen network (brief explanation; nice demo), which is a particular form of self-organized map (SOM). By default, a KohonenMechanism uses a KohonenLearningMechanism and the Kohonen LearningFunction to implement implement a form of unsupervised learning that produces the self-organized map.

Creating a KohonenMechanism

A KohonenMechanism can be created directly by calling its constructor.

Structure

XXX

Execution

XXX

Class Reference

class psyneulink.library.components.mechanisms.processing.transfer.kohonenmechanism.KohonenMechanism(default_variable=None, size=None, function=Linear, matrix=None, integrator_function=AdaptiveIntegrator, initial_value=None, noise=0.0, integration_rate=1.0, clip=None, enable_learning=True, learning_function=Kohonen(distance_function=GAUSSIAN), learning_rate=None, params=None, name=None, prefs=None)

Subclass of TransferMechanism that learns a self-organized map of its input.

Parameters:
  • default_variable (number, list or np.ndarray : default Transfer_DEFAULT_BIAS) – specifies the input to the mechanism to use if none is provided in a call to its execute or run method; also serves as a template to specify the length of variable for function, and the primary OutputState of the mechanism.
  • size (int, list or np.ndarray of ints) –

    specifies variable as array(s) of zeros if variable is not passed as an argument; if variable is specified, it takes precedence over the specification of size. As an example, the following mechanisms are equivalent:

    T1 = TransferMechanism(size = [3, 2])
    T2 = TransferMechanism(default_variable = [[0, 0, 0], [0, 0]])
    
  • function (TransferFunction : default Linear) – specifies the function used to transform the input.
  • integrator_function (IntegratorFunction : default AdaptiveIntegrator) – specifies IntegratorFunction to use in integration_mode.
  • initial_value (value, list or np.ndarray : default Transfer_DEFAULT_BIAS) – specifies the starting value for time-averaged input (only relevant if integration_rate is not 1.0).
  • noise (float or function : default 0.0) – a value added to the result of the function or to the result of integrator_function, depending on whether integrator_mode is True or False. See noise for more details.
  • integration_rate (float : default 0.5) –

    the smoothing factor for exponential time averaging of input when integrator_mode is set to True

    result = (integration_rate * current input) +
    (1-integration_rate * result on previous time_step)
    
  • clip (list [float, float] : default None (Optional)) – specifies the allowable range for the result of function the item in index 0 specifies the minimum allowable value of the result, and the item in index 1 specifies the maximum allowable value; any element of the result that exceeds the specified minimum or maximum value is set to the value of clip that it exceeds.
  • enable_learning (boolean : default True) – specifies whether the Mechanism should be configured for learning; if it is not (the default), then learning cannot be enabled until it is configured for learning by calling the Mechanism’s configure_learning method.
  • learning_rate (scalar, or list, 1d or 2d np.array, or np.matrix of numeric values: default False) – specifies the learning rate used by its learning function. If it is None, the default learning_rate for a LearningMechanism is used; if it is assigned a value, that is used as the learning_rate (see learning_rate for details).
  • learning_function (LearningFunction, function or method : default Kohonen(distance_function=GUASSIAN)) – specifies function used by learning_mechanism to update matrix of `learned_projection <KohonenMechanism.learned_projection>.
  • params (Dict[param keyword: param value] : default None) – a parameter dictionary that can be used to specify the parameters for the mechanism, 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 Kohonen Mechanism.
  • prefs (PreferenceSet or specification dict : default Mechanism.classPreferences) – specifies the PreferenceSet for the Kohonen Mechanism; see prefs for details.
  • context (str : default componentType+INITIALIZING) – string used for contextualization of instantiation, hierarchical calls, executions, etc.
variable

value – the input to Mechanism’s function.

function

Function – the Function used to transform the input.

distance_function

Function, function or method : default Gaussian – determines the function used to evaluate the distance of each element from the most active one one identified by selection_function

matrix

2d np.arraymatrix parameter of the learned_projection.

learning_enabled

bool – indicates whether learning is enabled; see learning_enabled for additional details.

learning_rate

float, 1d or 2d np.array, or np.matrix of numeric values : default None – determines the learning rate used by the learning_function of the learning_mechanism (see learning_rate for details concerning specification and default value assignment).

learned_projection

MappingProjectionMappingProjection that projects to the Mechanism and is trained by its learning_mechanism.

learning_function

LearningFunction, function or method – function used by learning_mechanism to update matrix of `learned_projection <KohonenMechanism.learned_projection>.

learning_mechanism

LearningMechanism – created automatically if learning is specified, and used to train the learned_projection.

integrator_function

IntegratorFunction – the IntegratorFunction used when integrator_mode is set to True (see integrator_mode for details).

Note

The KohonenMechanism’s integration_rate, noise, and initial_value parameters specify the respective parameters of its integrator_function (with initial_value corresponding to initializer of integrator_function.

initial_value

value, list or np.ndarray : Transfer_DEFAULT_BIAS – determines the starting value for time-averaged input (only relevant if integration_rate parameter is not 1.0).

noise

float or function : default 0.0 – When integrator_mode is set to True, noise is passed into the integrator_function. Otherwise, noise is added to the output of the function.

If noise is a list or array, it must be the same length as variable.

If noise is specified as a single float or function, while variable is a list or array, noise will be applied to each variable element. In the case of a noise function, this means that the function will be executed separately for each variable element.

Note

In order to generate random noise, we recommend selecting a probability distribution function (see Distribution Functions for details), which will generate a new noise value from its distribution on each execution. If noise is specified as a float or as a function with a fixed output, then the noise will simply be an offset that remains the same across all executions.

integration_rate

float : default 0.5 – the smoothing factor for exponential time averaging of input when integrator_mode is set to True:

result = (integration_rate * current input) + (1-integration_rate * result on previous time_step)
integrator_function

When integrator_mode is set to True, the KohonenMechanism executes its integrator_function, which is the AdaptiveIntegrator. See AdaptiveIntegrator for more details on what it computes. Keep in mind that the integration_rate parameter of the KohonenMechanism corresponds to the rate of the integrator_function.

integrator_mode

When integrator_mode is set to True:

the variable of the mechanism is first passed into the following equation:

\[value = previous\_value(1-smoothing\_factor) + variable \cdot smoothing\_factor + noise\]

The result of the integrator function above is then passed into the mechanism's function. Note that on the first execution, initial_value sets previous_value.

When integrator_mode is set to False:

The variable of the mechanism is passed into the function of the mechanism. The mechanism’s integrator_function is skipped entirely, and all related arguments (noise, leak, initial_value, and time_step_size) are ignored.

clip

list [float, float] : default None (Optional) – specifies the allowable range for the result of function

the item in index 0 specifies the minimum allowable value of the result, and the item in index 1 specifies the maximum allowable value; any element of the result that exceeds the specified minimum or maximum value is set to

the value of clip that it exceeds.
previous_input

1d np.array of floats – the value of the input on the previous execution, including the value of recurrent_projection.

value

2d np.array [array(float64)] – result of executing function; same value as first item of output_values.

output_states

Dict[str, OutputState] – an OrderedDict with the following OutputStates:

  • TRANSFER_RESULT, the value of which is the result of function;
  • MOST_ACTIVE, the value of which is a “one hot” encoding of the most active element of the Mechanism’s value in the last execution (used by the learning_mechanism to modify the learned_projection.
output_values

List[array(float64), array(float64)] – a list with the value of each of the Mechanism’s output_states.

name

str – the name of the Kohonen Mechanism; if it is not specified in the name argument of the constructor, a default is assigned by MechanismRegistry (see Naming for conventions used for default and duplicate names).

prefs

PreferenceSet or specification dict – the PreferenceSet for the Kohonen Mechanism; 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).

Returns:instance of KohonenMechanism
Return type:KohonenMechanism
configure_learning(learning_function: <typecheck.framework.optional object at 0x114216da0> = None, learning_rate: <typecheck.framework.optional object at 0x114216e48> = None, learned_projection: <typecheck.framework.optional object at 0x114216e80> = None, context=None)

Provide user-accessible-interface to _instantiate_learning_mechanism

Configure KohonenMechanism for learning. Creates the following Components:

  • a Learning Mechanism – if the learning_function and/or learning_rate arguments are specified, they are used to construct the LearningMechanism, otherwise the values specified in the KohonenMechanism’s constructor are used;
  • a LearningProjection from the LearningMechanism’s LEARNING_SIGNAL OutputState to the learned_projection; by default this is the KohonenMechanism’s learned_projection; however a different one can be specified.