network: Leabra network class
In johannes-titz/leabRa: The Artificial Neural Networks Algorithm Leabra

Description Usage Format Details Value Fields Methods References Examples

Class to simulate a biologically realistic network of neurons (units) organized in layers

network

R6Class object.

This class simulates a biologically realistic artificial neuronal network in the Leabra framework (e.g. O'Reilly et al., 2016). It consists of several layer objects in the variable (field) layers and some network-specific variables.

Object of R6Class with methods for calculating changes of activation in a network of neurons organized in layers.

layers: A list of layer objects.
lrate: Learning rate, gain factor for how much the connection weights should change when the method chg_wt() is called.

new(dim_lays, cxn, g_i_gain = rep(2, length(dim_lays)), w_init_fun = function(x) runif(x, 0.3, 0.7), w_init = NULL)

Creates an object of this class with default parameters.

dim_lays: List of number pairs for rows and columns of the layers, e.g. list(c(5, 5), c(10, 10), c(5, 5)) for a 25 x 100 x 25 network.
cxn: Matrix specifying connection strength between layers, if layer j sends projections to layer i, then cxn[i, j] = strength > 0 and 0 otherwise. Strength specifies the relative strength of that connection with respect to the other projections to layer i.
g_i_gain: Vector of inhibitory conductance gain values for every layer. This comes in handy to control overall level of inhibition of specific layers. Default is 2 for every layer.
w_init_fun: Function that specifies how random weights should be created, default value is to generate weights between 0.3 and 0.7 from a uniform distribution. It is close to 0.5 because the weights are contrast enhanced internally, so will actually be in a wider range.
w_init: Matrix of initial weight matrices (like a cell array in 'MATLAB'), this is analogous to cxn, i.e. w_init[i, j] contains the initial weight matrix for the connection from layer j to i. If you specify a w_init, w_init_fun is ignored. You can use this if you want to have full control over the weight matrix.

cycle(ext_inputs, clamp_inp)

Iterates one time step with the network object with external inputs.

ext_inputs: A list of matrices; ext_inputs[[i]] is a matrix that for layer i specifies the external input to each of its units. An empty matrix (NULL) denotes no input to that layer. You can also use a vector instead of a matrix, because the matrix is vectorized anyway.
clamp_inp: Logical variable; TRUE: external inputs are clamped to the activities of the units in the layers, FALSE: external inputs are summed to excitatory conductance values (note: not to the activation) of the units in the layers.

chg_wt()

Changes the weights of the entire network with the XCAL learning equation.

reset(random = F)

Sets the activation of all units in all layers to 0, and sets all activation time averages to that value. Used to begin trials from a random stationary point. The activation values may also be set to a random value.

random: Logical variable, if TRUE set activation randomly between .05 and .95, if FALSE set activation to 0, which is the default.

create_inputs(which_layers, n_inputs, prop_active = 0.3)

Returns a list of length n_inputs with random input patterns (either 0.05, or. 0.95) for the layers specified in which_layers. All other layers will have an input of NULL.

which_layers: Vector of layer numbers, for which you want to create random inputs.
n_inputs: Single numeric value, how many inputs should be created.
prop_active: Average proportion of active units in the input patterns, default is 0.3.

learn_error_driven(inputs_minus, inputs_plus, lrate = 0.1, n_cycles_minus = 50, n_cycles_plus = 25, random_order = FALSE, show_progress = TRUE)

Learns to associate specific inputs with specific outputs in an error-driven fashion.

inputs_minus: Inputs for the minus phase (the to be learned output is not presented).
inputs_plus: Inputs for the plus phase (the to be learned output is presented).
lrate: Learning rate, default is 0.1.
n_cycles_minus: How many cycles to run in the minus phase, default is 50.
n_cycles_plus: How many cycles to run in the plus phase, default is 25.
random_order: Should the order of stimulus presentation be randomized? Default is FALSE.
show_progress: Whether progress of learning should be shown. Default is TRUE.

learn_self_organized(inputs, lrate = 0.1, n_cycles = 50, random_order = FALSE, show_progress = TRUE)

Learns to categorize inputs in a self-organized fashion.

inputs: Inputs for cycling.
lrate: Learning rate, default is 0.1.
n_cycles: How many cycles to run, default is 50.
random_order: Should the order of stimulus presentation be randomized? Default is FALSE.
show_progress: Whether progress of learning should be shown. Default is TRUE.

test_inputs = function(inputs, n_cycles = 50, show_progress = FALSE)

Tests inputs without changing the weights (without learning). This is usually done after several learning runs.

inputs: Inputs for cycling.
n_cycles: How many cycles to run, default is 50.
show_progress: Whether progress of learning should be shown. Default is FALSE.

mad_per_epoch(outs_per_epoch, inputs_plus, layer)

Calculates mean absolute distance for two lists of activations for a specific layer. This can be used to compare whether the network has learned what it was supposed to learn.

outs_per_epoch: Output activations for entire network for each trial for every epoch. This is what the network produced on its own.
inputs_plus: Original inputs for the plus phase. This is what the network was supposed to learn.
layer: Single numeric, for which layer to calculate the mean absolute distance. Usually, this is the "output" layer.

set_weights(weights)

Sets new weights for entire network, useful to load networks that have already learned and thus very specific weights.

weights: Matrix of matrices (like a cell array in 'MATLAB') with new weight values.

get_weights()

Returns the complete weight matrix, w[i, j] contains the weight matrix for the projections from layer j to layer i. Note that this is a matrix of matrices (equivalent to a 'MATLAB' cell array).

get_layer_and_unit_vars(show_dynamics = T, show_constants = F)

Returns a data frame with the current state of all layer and unit variables. Every row is a unit. You can choose whether you want dynamic values and / or constant values. This might be useful if you want to analyze what happens in the network overall, which would otherwise not be possible, because most of the variables (fields) are private in the layer and unit class.

show_dynamics: Should dynamic values be shown? Default is TRUE.
show_constants: Should constant values be shown? Default is FALSE.

get_network_vars(show_dynamics = T, show_constants = F)

Returns a data frame with 1 row with the current state of the variables in the network. You can choose whether you want dynamic values and / or constant values. This might be useful if you want to analyze what happens in a network, which would otherwise not be possible, because some of the variables (fields) are private in the network class. There are some additional variables in the network class that cannot be extracted this way because they are matrices; if it is necessary to extract them, look at the source code.

show_dynamics: Should dynamic values be shown? Default is TRUE.
show_constants: Should constant values be shown? Default is FALSE.

O'Reilly, R. C., Munakata, Y., Frank, M. J., Hazy, T. E., and Contributors (2016). Computational Cognitive Neuroscience. Wiki Book, 3rd (partial) Edition. URL: http://ccnbook.colorado.edu

Have also a look at https://grey.colorado.edu/emergent/index.php/Leabra (especially the link to the 'MATLAB' code) and https://en.wikipedia.org/wiki/Leabra

# create a small network with 3 layers
dim_lays <- list(c(2, 5), c(2, 10), c(2, 5))
cxn <- matrix(c(0, 0, 0,
                1, 0, 0.2,
                0, 1, 0), nrow = 3, byrow = TRUE)
net <- network$new(dim_lays, cxn)

net$m_in_s # private values cannot be accessed
# if you want to see alle variables, you need to use the function
net$get_network_vars(show_dynamics = TRUE, show_constants = TRUE)
# if you want to see a summary of all units (with layer information) without
# constant values
net$get_layer_and_unit_vars(show_dynamics = TRUE, show_constants = FALSE)

# let us create 10 random inputs for layer 1 and 3
inputs <- net$create_inputs(c(1, 3), 10)
inputs # a list of lists

# the input in layer 1 should be associated with the output in layer 3; we
# can use error driven learning to achieve this

# first we will need the input for the minus phase (where no correct output
# is presented; layer 3 is NULL)
inputs_minus <- lapply(inputs, function(x) replace(x, 3, list(NULL)))
inputs_minus # layer 3 is indeed NULL
# now we can learn with default parameters; we will run 10 epochs,
# inputs_plus is equivalent to inputs; the output will be activations after
# each trial for the wohle network; this might take a while depending on your
# system
n_epochs <- 10
## Not run: 
output <- lapply(seq(n_epochs),
                 function(x) net$learn_error_driven(inputs_minus,
                                                    inputs,
                                                    lrate = 0.5))
# let's compare the actual output with what should have been learned we can
# use the method mad_per_epoch for this; it will calculate the mean absolute
# distance for each epoch; we are interested in layer 3
mad <- net$mad_per_epoch(output, inputs, 3)
# the error should decrease with increasing epoch number
plot(mad)
## End(Not run)