CARLsim  6.1.0
CARLsim: a GPU-accelerated SNN simulator
Chapter 9: MATLAB Offline Analysis Toolbox (OAT)

In addition to the real-time monitors (see Chapter 7: Monitoring), CARLsim provides a versatile Offline Analysis Toolbox (OAT) written in MATLAB for the visualization and analysis of neuronal, synaptic, and network information.

The OAT is built to work straight out of the box, by operating on binary files that the CARLsim simulation creates by default. The easiest way to visualize network activity is to run a NetworkMonitor (see 9.2 NetworkMonitor). However, it is also possible to look at specific groups (see 9.3 GroupMonitor) or connections (see 9.4 Connection Monitor), and to access the associated spike file binaries (see 9.5.2 Spike Reader) and weight file binaries (see 9.5.3 Connection Reader) directly.

Every Monitor comes with an InteractiveMode for plotting activity and weights over time, which allows the use of keyboard commands to step through frames, pause or quit (see 9.2.3 Plotting Activity, 9.3.3 Plotting Activity, and 9.4.3 Plotting Weights).

Every Monitor also provides a whole range of settings to customize the plotting (see 9.2.5 NetworkMonitor Plotting Attributes, 9.3.5 GroupMonitor Plotting Attributes, and 9.4.5 ConnectionMonitor Plotting Attributes) or recording (see 9.2.7 NetworkMonitor Recording Attributes, 9.3.7 GroupMonitor Recording Attributes, or 9.4.7 ConnectionMonitor Recording Attributes) of activity and weights.

For users migrating from CARLsim 2.2, please note that readNetwork.m has been replaced with NetworkMonitors (see 9.2 NetworkMonitor) and readSpikes.m has been replaced with Spike Readers (see 9.5.2 Spike Reader). For more information please refer to 9.6 Migrating from CARLsim 2.2.

9.1 Getting Started

Author
Michael Beyeler

Before the OAT can be used, the directory "tools/offline_analysis_toolbox" must be added to the MATLAB path.

The "Hello World" project (see 1.3 Project Workflow) provides a short MATLAB script for this in the scripts subdirectory:

>> initOAT % adds OAT relative path to MATLAB paths

Alternatively, the path can be added manually, making changes either permanent by using the MATLAB path tool:

>> pathtool

and selecting the directory %%CARLSIM_ROOT_DIR%%/tools/offline_analysis_toolbox, or just for the current session by explicitly running:

>> addpath "%%CARLSIM_ROOT_DIR%%/tools/offline_analysis_toolbox"

Now it should be possible to display the code documentation for different classes by using MATLAB's help browser:

>> doc NetworkMonitor % open help browser for NetworkMonitor class

9.2 NetworkMonitor

Author
Michael Beyeler

A NetworkMonitor can be used to monitor properties as well as the activity of a number of neuronal groups in a network. The monitor will parse a simulation file of the form sim_{name of network}.dat that is automatically generated by a CARLsim simulation, determine the network structure (such as number of groups and connections), find all associated spike files, and plot group activity accordingly.

The following methods are available:

>> methods NetworkMonitor
addAllGroupsFromFile % registers all groups specified in the simulation file
addGroup % registers a specific group
getError % returns the current error status (flag and message)
getGroupGrid3D % returns the Grid3D dimensions of a group
getGroupNumNeurons % returns the number of neurons in a group
plot % plots data in current figure/axes
recordMovie % records data from current figure/axes to AVI movie file
setErrorMode % set error mode ('standard', 'warning', 'silent')
setGroupGrid3D % set the Grid3D dimensions of a group (for plotting and recording)
setGroupPlotType % set default plot type of a group (raster plot, flow field, etc.)
setGroupSubPlot % sets the subplot in which to plot a group's activity
setPlottingAttributes % settings for customizing the plotting process
setRecordingAttributes % settings for customizing the recording process (to AVI file)
setSpikeFileAttributes % set prefix/suffix of spike file naming template

The following public members (properties) are available:

>> properties NetworkMonitor
simObj % SimulationReader object
resultsFolder % path to results folder
groupNames % list of group names
groupSubPlots % list of subplots for all groups
groupMonObj % list of GroupMonitor objects for all groups
errorMode % current error mode
supportedErrorModes % list of supported error modes

9.2.1 Creating a NetworkMonitor

In order to open a NetworkMonitor, specify the path to a simulation file (of the form sim_{network name}.dat) that has been created automatically during a CARLsim simulation, or by explicitly calling CARLsim::saveSimulation:

>> NM = NetworkMonitor('results/sim_random.dat')
NM =
simObj: [1x1 SimulationReader]
resultsFolder: 'results'
groupNames: {'excit' 'inhib' 'input'}
groupSubPlots: {[1] [2] [3]}
groupMonObj: {[1x1 GroupMonitor] [1x1 GroupMonitor] [1x1 GroupMonitor]}
errorMode: 'standard'
supportedErrorModes: {'standard' 'warning' 'silent'}

The NetworkMonitor will use a SimulationReader (see 9.5.1 Simulation Reader) to parse the simulation file results/sim_random.dat, and open a GroupMonitor (see 9.3 GroupMonitor) on each group that was specified therein. The resulting NetworkMonitor object should contain a list of all groups in the network (see public member groupNames) with associated GroupMonitor objects (see public member groupMonObj) and associated subplots (see public member groupSubPlots).

In order to find the list of all associated groups, the NetworkMonitor constructor will implicitly call the public method addAllGroupsFromFile. Alternatively, the user can opt not to automatically add all groups from file, by setting input argument loadGroupsFromFile to false:

>> NM = NetworkMonitor('results/sim_random.dat', false) % loadGroupsFromFile
NM =
simObj: [1x1 SimulationReader]
resultsFolder: 'results'
groupNames: {}
groupSubPlots: {}
groupMonObj: {}
errorMode: 'standard'
supportedErrorModes: {'standard' 'warning' 'silent'}

Groups to be included in a NetworkMonitor plot can then be added one-by-one via addGroup. This allows to directly specify additional attributes such as plot type, Grid3D dimensions, which subplot to occupy, etc.:

>> NM.addGroup('input', 'heatmap', [10 10 1]); % name, plotType, grid3D
>> NM.addGroup('output', 'raster'); % name

Note that the name strings must match the name the group was given during the CARLsim simulation, and the Grid3D dimensions must add up to the correct total number of neurons in the group

Since
v3.0

9.2.2 Setting the Spike File Attributes

In case the spike files do not follow the default pattern, NetworkMonitor will not be able to locate the spike files, which will be evident by an empty list of groupNames, groupSubPlots, and groupMonObj:

>> NM = NetworkMonitor('results/sim_random.dat', false) % loadGroupsFromFile
NM =
simObj: [1x1 SimulationReader]
resultsFolder: 'results'
groupNames: {}
groupSubPlots: {}
groupMonObj: {}
errorMode: 'standard'
supportedErrorModes: {'standard' 'warning' 'silent'}

and trying to call the plot method will result in a warning:

>> NM.plot
Warning: Nothing to plot. Try adding some groups first.

In this case, the method setSpikeFileAttributes can be used to change the default prefix and suffix of the spike file names. By default, spike files follow the pattern spk_{group name}.dat, so the prefix would be spk_ and the suffix would be .dat, as dictated by the GroupMonitor object (see 9.3.2 Setting the Spike File Attributes). Analogously, for spike files following the naming convention spike_{group name}.ext the prefix would be spike_ and the suffix would be .ext. After prefix/suffix have been set accordingly, the spike file will be found and activity can be plotted:

>> NM
simObj: [1x1 SimulationReader]
resultsFolder: 'results'
groupNames: {}
groupSubPlots: {}
groupMonObj: {}
errorMode: 'standard'
supportedErrorModes: {'standard' 'warning' 'silent'}
>> NM.setSpikeFileAttributes('spike_','.ext');
>> NM.addAllGroupsFromFile();
>> NM
NM =
simObj: [1x1 SimulationReader]
resultsFolder: 'results'
groupNames: {'excit' 'inhib' 'input'}
groupSubPlots: {[1] [2] [3]}
groupMonObj: {[1x1 GroupMonitor] [1x1 GroupMonitor] [1x1 GroupMonitor]}
errorMode: 'standard'
supportedErrorModes: {'standard' 'warning' 'silent'}
Since
v3.0

9.2.3 Plotting Activity

Once a NetworkMonitor has been set up, activity can be plotted using the plot method:

>> NM.plot

This will plot the data in bins of 1000 ms in the current figure/axes, one group per subplot, using a default plot type, which is determined by the Grid3D dimensions of each group (see 9.2.4 NetworkMonitor Plot Types and 9.3.4 GroupMonitor Plot Types). An example is shown in the figure below.

9_nm_example.jpg
Example NetworkMonitor plot with all raster plots.

A list of frames to be plotted as well as the histogram bin window (ms) can be specified directly. For example, the following command would bin the data into frames 500 ms length, and display the first, second, and eighth frame using default plot types for each group:

>> NM.plot([1 2 8],500);

The default plot type for each group can be changed via setGroupPlotType:

>> NM.setGroupPlotType('excit','raster'); % plotting activity of group "excit" as raster plot
>> NM.setGroupPlotType('inhib','heatmap'); % plotting activity of group "inhib" as heat map

Plot types are managed by the GroupMonitor object. For a list of available plot types, please refer to 9.2.4 NetworkMonitor Plot Types.

Every Monitor comes with an InteractiveMode for plotting activity and weights. By default, plotting will occur at a predefined speed (5 frames per second), unless otherwise specified using the method setPlottingAttributes (see 9.2.5 NetworkMonitor Plotting Attributes). At any time, the user can hit key 'p' to pause plotting, or 'q' to quit. Hitting key 's' will enter stepping mode, which will freeze the current frame until the user either hits the 'right arrow' key (in order to step one frame forward) or the 'left arrow' key (in order to step one frame backward).

A number of additional plotting attributes can be set via setPlottingAttributes, such as the background color of the figure and the number of frames to be displayed per second (see 9.2.5 NetworkMonitor Plotting Attributes).

Certain plot types, such as 'heatmap' or 'flowfield' depend on appropriate Grid3D dimensions (2D for the former, 3D for the latter). For example, the heatmap of a population with 100 neurons on a 100x1x1 grid will be a single row. But, the grid dimensions can be reshaped on-the-fly, to make them easier to visualize:

>> NM.setGroupGrid3D('excit',10,10,1); % reshape 100x1x1 grid into 10x10x1 grid
>> NM.setGroupPlotType('excit','heatmap');

Note that the overall number of neurons must not change when specifying new grid dimensions.

Sometimes it is useful to manually assign subplots to each group, especially for groups whose 2D grid representations are relatively wide or tall (e.g., 5x100 neurons). In this case, setGroupSubPlots can be used to make a group plot span across multiple subplots:

>> NM.setGroupGrid3D('excit', 5, 100, 1) % 2D representation extremely wide
>> NM.setGroupSubPlot('excit', [1 2]) % make "excit" span two subplots

By default, each group gets assigned just one subplot. Make sure that each subplot is occupied by at most one group, otherwise the plot method will break.

The raw data of a spike file can also be read directly using a SpikeReader (see 9.5.2 Spike Reader).

See also
9.2.4 NetworkMonitor Plot Types
9.2.5 NetworkMonitor Plotting Attributes
9.5.2 Spike Reader
Since
v3.0

9.2.4 NetworkMonitor Plot Types

NetworkMonitor follows the plot types that are specified and managed by GroupMonitor. For a complete list of available plot types, please refer to 9.3.4 GroupMonitor Plot Types.

Plot types can be mixed-and-matched within a NetworkMonitor plot. For example, a network containing three groups "excit", "inhib", and "input" might be visualized with three different types:

>> NM = NetworkMonitor('results/sim_random.dat')
NM =
simObj: [1x1 SimulationReader]
resultsFolder: 'results'
groupNames: {'excit' 'inhib' 'input'}
groupSubPlots: {[1] [2] [3]}
groupMonObj: {[1x1 GroupMonitor] [1x1 GroupMonitor] [1x1 GroupMonitor]}
errorMode: 'standard'
supportedErrorModes: {'standard' 'warning' 'silent'}
>> NM.setGroupPlotType('excit','histogram') % plot "excit" as histogram
>> NM.setGroupPlotType('inhib','flowfield') % plot "inhib" as flow field
>> NM.setGroupGrid3D('inhib', 20, 20, 4) % make sure group "inhib" has the right dimensions
>> NM.setGroupPlotType('input','raster') % plot "input" as raster plot

The result of this code snippet is shown in the figure below.

9_nm_plottypes.jpg
Example NetworkMonitor plot with mixed plot types.
Note
Make sure the Grid3D dimensions are appropriate for the current plot type (change dimensions via setGrid3D).
See also
9.3.4 GroupMonitor Plot Types
Since
v3.0

9.2.5 NetworkMonitor Plotting Attributes

The method setPlottingAttributes(varargin) can be used to set default plotting attributes. These default settings will apply to all activity plots, unless their values are overwritten explicitly in the plot method (see 9.2.3 Plotting Activity).

The following command sets the value of variable propertyName1 to value value1:

>> NM.setPlottingAttributes('propertyName1',value1);

Additional variables can be flexibly appended; order or capitalization does not matter. A list of available attributes can be displayed via:

>> help NetworkMonitor.setPlottingAttributes
NM.setPlottingAttributes(varargin) can be used to set default
settings that will apply to all activity plots.
This function provides control over additional attributes
that are not available as input arguments to GM.plot or
NM.plotFrame.
NM.setPlottingAttributes('propertyName1',value1,...) sets the
value of 'propertyName1' to value1.
Calling the function without input arguments will restore the
default settings.
BGCOLOR - Set background color for figure. Must be of
type ColorSpec (char such as 'w','b','k' or
a 3-element vector for RGB channels). The
default is white.
BINWINDOWMS - The binning window (ms) in which the data
will be displayed. Default: 1000.
DISPFRAMENR - A boolean flag that indicates whether to
display the frame number. Default: true.
FPS - The frames per second for the plotting loop.
The default is 5.
BINWINDOWMS - The binning window (ms) in which the data
will be displayed. Default: 1000.
Since
v3.0

9.3.6 Recording a Movie

Activity plots can be directly saved to AVI movie files via the following command:

>> NM.recordMovie;

This will generate a default NetworkMonitor plot (see 9.2.3 Plotting Activity) and save the frames to an .avi binary using the MATLAB VideoWriter utility.

The following command will generate file called myMovie.avi that shows group activity with default plot types, binning window 500 ms, and display the first, second, and eighth frame at a playback rate of 1 fps:

>> GM.recordMovie('myMovie.avi', [1 2 8], 500, 1);
created file "myMovie.avi"

Plot types for each group can be set via setGroupPlotType (see 9.2.4 NetworkMonitor Plot Types).

Note
Make sure the Grid3D dimensions are appropriate for the current plot type (change dimensions via setGrid3D).
See also
9.2.7 NetworkMonitor Recording Attributes
Since
v3.0

9.2.7 NetworkMonitor Recording Attributes

The method setRecordingAttributes(varargin) can be used to set default recording attributes. These default settings will apply to all recordings, unless their values are overwritten explicitly in the recordMovie method (see 9.3.6 Recording a Movie).

The following command sets the value of variable propertyName1 to value value1:

>> NM.setRecordingAttributes('propertyName1',value1);

Additional variables can be flexibly appended; order or capitalization does not matter. A list of available attributes can be displayed via:

>> help NetworkMonitor.setRecordingAttributes
NM.setRecordingAttributes(varargin) can be used to set
default settings that will apply to all activity recordings.
This function provides control over additional attributes
that are not available as input arguments to GM.recordMovie.
GM.setRecordingAttributes('propertyName1',value1,...) sets
the value of 'propertyName1' to value1.
Calling the function without input arguments will restore the
default settings.
BGCOLOR - Set background color for figure. Must be of
type ColorSpec (char such as 'w','b','k' or
a 3-element vector for RGB channels). The
default is white.
FILENAME - File name where movie will be stored.
Currently the only supported file ending is
".avi".
FPS - The frames per second for the movie. The
default is 10.
WINSIZE - A 2-element vector specifying the window
size of the video as width x height in
pixels.Set to [0 0] in order to
automatically make the movie window fit to
the size of the plot window.
Since
v3.0

9.3 GroupMonitor

Author
Michael Beyeler

A GroupMonitor can be used to monitor properties as well as the activity of a specific neuronal group in a network. The monitor will assume that a corresponding spike file was created via SpikeMonitor during the CARLsim simulation.

The following methods are available:

>> methods GroupMonitor
getDefaultPlotType % returns the default plot type for the group
getError % returns the current error status (flag and message)
getGrid3D % returns the Grid3D dimensions of the group
getNumNeurons % returns the number of neurons in the group
getSimDurMs % returns the estimated simulation duration (ms)
getSpikeFileName % returns spike file name created from template
hasValidSpikeFile % returns a flag whether valid spike file was found
plot % plots data in current figure/axes
recordMovie % records data from current figure/axes to AVI movie file
setDefaultPlotType % set default plot type of a group (raster plot, flow field, etc.)
setErrorMode % set error mode ('standard', 'warning', 'silent')
setGrid3D % set the Grid3D dimensions of the group (for plotting and recording)
setPlottingAttributes % settings for customizing the plotting process
setRecordingAttributes % settings for customizing the recording process (to AVI file)
setSpikeFileAttributes % set prefix/suffix of spike file naming template

The following public members (properties) are available:

>> properties GroupMonitor
name % name of the group
resultsFolder % path to results folder
supportedErrorModes % list of supported error modes
supportedPlotTypes % list of supported plot types

9.3.1 Creating a GroupMonitor

In order to open a GroupMonitor, specify the name of the group (given during a CARLsim simulation via CARLsim::createGroup or CARLsim::createSpikeGeneratorGroup) and the directory in which the spike file resides (results/ by default):

>> GM = GroupMonitor('excit','results/');
GM =
GroupMonitor with properties:
name: 'excit'
resultsFolder: 'results/'
errorMode: []
supportedErrorModes: {'standard' 'warning' 'silent'}
supportedPlotTypes: {'flowfield' 'heatmap' 'histogram' 'raster'}

By default, this will look for a spike file named spk_{group name}.dat in the results/ directory, which is the default name pattern for spike files created with CARLsim::setSpikeMonitor.

Since
v3.0

9.3.2 Setting the Spike File Attributes

In case the spike file does not follow the default pattern, creating a GroupMonitor will result in the following warning:

>> GM = GroupMonitor('excit','results/');
Warning: Could not find valid spike file "results/spk_excit.dat". Use setSpikeFileAttributes to
set a proper spike file prefix/suffix

and trying to call the plot method will result in an error message:

>> GM.plot
Error using GroupMonitor/throwError (line 1133)
Could not open file "results/spk_excit.dat" with read permission

In this case, the method setSpikeFileAttributes can be used to change the default prefix and suffix of the spike file name. In the above case, the prefix would be spk_ and the suffix would be .dat. Analogously, for a spike file following the naming convention spike_{group name}.ext the prefix would be spike_ and the suffix would be .ext. After prefix/suffix have been set accordingly, the spike file will be found and activity can be plotted:

>> GM.hasValidSpikeFile()
ans =
0
>> GM.setSpikeFileAttributes('spike_','.ext');
>> GM.hasValidSpikeFile()
ans =
1
>> GM.plot
Since
v3.0

9.3.3 Plotting Activity

Once a GroupMonitor has been set up, activity can be plotted using the plot method:

>> GM.plot

This will plot the data in bins of 1000 ms in the current figure/axes using a default plot type, which is determined by the Grid3D dimensions of the group (see 9.3.4 GroupMonitor Plot Types).

A list of frames to be plotted as well as the histogram bin window (ms) can be specified directly. For example, the following command would bin the data into frames 500 ms length, and display the first, second, and eighth frame as a heat map:

>> GM.plot('heatmap',[1 2 8],500);

Every Monitor comes with an InteractiveMode for plotting activity and weights. By default, plotting will occur at a predefined speed (5 frames per second), unless otherwise specified using the method setPlottingAttributes (see 9.3.5 GroupMonitor Plotting Attributes). At any time, the user can hit key 'p' to pause plotting, or 'q' to quit. Hitting key 's' will enter stepping mode, which will freeze the current frame until the user either hits the 'right arrow' key (in order to step one frame forward) or the 'left arrow' key (in order to step one frame backward).

It is also possible to set the default plot type directly, so it does not have to be specified each time data is plotted or recorded:

>> GM.setDefaultPlotType('histogram')

For a list of available plot types, please refer to 9.3.4 GroupMonitor Plot Types.

A number of additional plotting attributes can be set via setPlottingAttributes, such as the background color of the figure and the number of frames to be displayed per second (see 9.3.5 GroupMonitor Plotting Attributes).

Certain plot types, such as 'heatmap' or 'flowfield' depend on appropriate Grid3D dimensions (2D for the former, 3D for the latter). For example, the heatmap of a population with 100 neurons on a 100x1x1 grid will be a single row. But, the grid dimensions can be reshaped on-the-fly, to make them easier to visualize:

>> GM.setGrid3D(10,10,1); % reshape 100x1x1 grid into 10x10x1 grid
>> GM.plot('heatmap')

Note that the overall number of neurons must not change when specifying new grid dimensions.

The raw data of a spike file can also be read directly using a SpikeReader (see 9.5.2 Spike Reader).

See also
9.3.4 GroupMonitor Plot Types
9.3.5 GroupMonitor Plotting Attributes
9.5.2 Spike Reader
Since
v3.0

9.3.4 GroupMonitor Plot Types

The following image illustrates the different plot types that are available (applied to an arbitrary network):

9_gm_plottypes.jpg
Supported GroupMonitor plot types: 'raster', 'heatmap', 'histogram', and 'flowfield'.

A specific default plot type can be set using setDefaultPlotType:

>> GM.setDefaultPlotType(str);

where str is either 'flowfield', 'heatmap', 'histogram', or 'raster'. This type will then apply to all subsequent plotting and recording commands, unless it is overwritten explicitly with one of the method's input arguments.

This value can be overwritten by explicitly specifying a plot type when using the methods plot (see 9.3.3 Plotting Activity) or recordMovie (see 9.3.6 Recording a Movie).

Plot type 'flowfield' will plot a 2D vector field where the length of the vector is given as the firing rsate of the neuron times the corresponding vector orientation. The latter is inferred from the third Grid3D dimension, z. For example, Grid3D(10,10,4) plots a 10x10 vector flow field, assuming that neurons with z=0 code for direction=0deg, z=1 corresponds to direction=90deg, z=2 is 180deg, and z=3 is 270deg. Vectors with length smaller than 10% of the max in each frame are not shown.

Plot type 'heatmap' will plot a topographical map of group activity (based on Grid3D) where hotter colors mean higher firing rate.

Plot type 'histogram' will plot a histogram of firing rates in the group. The number of bins and whether to plot firing rates (Hz) instead of number of spikes can be set with options 'histNumBins' and 'histShowRate' in method setPlottingAttributes.

Plot type 'raster' will output the data as a raster plot with bin window binWindowMs.

Note
Make sure the Grid3D dimensions are appropriate for the current plot type (change dimensions via setGrid3D).
Since
v3.0

9.3.5 GroupMonitor Plotting Attributes

The method setPlottingAttributes(varargin) can be used to set default plotting attributes. These default settings will apply to all activity plots, unless their values are overwritten explicitly in the plot method (see 9.3.3 Plotting Activity).

The following command sets the value of variable propertyName1 to value value1:

>> GM.setPlottingAttributes('propertyName1',value1);

Additional variables can be flexibly appended; order or capitalization does not matter. A list of available attributes can be displayed via:

>> help GroupMonitor.setPlottingAttributes
GM.setPlottingAttributes(varargin) can be used to set default
settings that will apply to all activity plots.
This function provides control over additional attributes
that are not available as input arguments to GM.plot.
GM.setPlottingAttributes('propertyName1',value1,...) sets the
value of 'propertyName1' to value1.
Calling the function without input arguments will restore the
default settings.
BGCOLOR - Set background color for figure. Must be of
type ColorSpec (char such as 'w','b','k' or
a 3-element vector for RGB channels).
Default: 'w'.
BINWINDOWMS - The binning window (ms) in which the data
will be displayed. Default: 1000.
DISPFRAMENR - A boolean flag that indicates whether to
display the frame number. Default: true.
FPS - The frames per second for the plotting
loop. Default: 5.
HISTNUMBINS - Number of bins for histogram. Default: 10.
HISTSHOWRATE - A boolean flag to plot mean firing rates
(Hz) for plotType='histogram' instead of
mere number of spikes. Default: true.
INTERACTIVEMODE - A boolean flag to set InteractiveMode on or
off. If it is off, key events/FPS/stepping
will take no effect (helpful if you want to
take over control yourself). Default: true.
Since
v3.0

9.3.6 Recording a Movie

Activity plots can be directly saved to AVI movie files via the following command:

>> GM.recordMovie;

This will generate a default GroupMonitor plot (see 9.3.3 Plotting Activity) and save the frames to an .avi binary using the MATLAB VideoWriter utility.

The following command will generate file called myMovie.avi that shows a heat map of group activity with binning window 500 ms, and display the first, second, and eighth frame at a playback rate of 1 fps:

>> GM.recordMovie('myMovie.avi', 'heatmap', [1 2 8], 500, 1);
created file "myMovie.avi"
Note
Make sure the Grid3D dimensions are appropriate for the current plot type (change dimensions via setGrid3D).
See also
9.3.7 GroupMonitor Recording Attributes
Since
v3.0

9.3.7 GroupMonitor Recording Attributes

The method setRecordingAttributes(varargin) can be used to set default recording attributes. These default settings will apply to all recordings, unless their values are overwritten explicitly in the recordMovie method (see 9.3.6 Recording a Movie).

The following command sets the value of variable propertyName1 to value value1:

>> GM.setRecordingAttributes('propertyName1',value1);

Additional variables can be flexibly appended; order or capitalization does not matter. A list of available attributes can be displayed via:

>> help GroupMonitor.setRecordingAttributes
GM.setRecordingAttributes(varargin) can be used to set
default settings that will apply to all activity recordings.
This function provides control over additional attributes
that are not available as input arguments to GM.recordMovie.
GM.setRecordingAttributes('propertyName1',value1,...) sets
the value of 'propertyName1' to value1.
Calling the function without input arguments will restore the
default settings.
BGCOLOR - Set background color for figure. Must be of
type ColorSpec (char such as 'w','b','k' or
a 3-element vector for RGB channels). The
default is white.
FILENAME - File name where movie will be stored.
Currently the only supported file ending is
".avi".
FPS - The frames per second for the movie. The
default is 10.
WINSIZE - A 2-element vector specifying the window
size of the video as width x height in
pixels.Set to [0 0] in order to
automatically make the movie window fit to
the size of the plot window.
Since
v3.0

9.4 Connection Monitor

Author
Michael Beyeler

A ConnectionMonitor can be used to monitor properties as well as the synaptic weights of a specific connection in a network (specified via CARLsim::connect). The monitor will assume that a corresponding weight file was created via ConnectionMonitor during the CARLsim simulation.

The following methods are available:

getConnectFileName % returns the name of the connect file
getDefaultPlotType % returns the default plot type for the group
getError % returns the current error status (flag and message)
getGrid3DPre % returns the Grid3D dimensions of the pre-synaptic group
getGrid3DPost % returns the Grid3D dimensions of the post-synaptic group
getNeuronLocation3DPre % returns the 3D location of a neuron ID in the pre-synaptic group
getNeuronLocation3DPost % returns the 3D location of a neuron ID in the post-synaptic group
getNumSnapshots % returns the number of snapshots present in the connect file
getSnapshots % returns the weight snapshots present in the connect file
hasValidSpikeFile % returns a flag whether valid connect file was found
plot % plots data in current figure/axes
recordMovie % records data from current figure/axes to AVI movie file
setConnectFileAttributes % set prefix/suffix/separator of connect file naming template
setDefaultPlotType % set default plot type of the connection (histogram, heat map, etc.)
setPlottingAttributes % settings for customizing the plotting process
setRecordingAttributes % settings for customizing the recording process (to AVI file)

The following public members (properties) are available:

>> properties ConnectionMonitor
connId % connection ID (same as in CARLsim::connect)
grpPreName % name of pre-synaptic group
grpPostName % name of post-synaptic group
errorMode % current error mode
resultsFolder % path to results folder
supportedErrorModes % list of supported error modes
supportedPlotTypes % list of supported plot types

9.4.1 Creating a ConnectionMonitor

In order to open a ConnectionMonitor, specify the name of the pre-synaptic and post-synaptic group (given during a CARLsim simulation via CARLsim::createGroup or CARLsim::createSpikeGeneratorGroup) and the directory in which the connect file resides (results/ by default):

>> CM = ConnectionMonitor('input','output','results/');
CM =
ConnectionMonitor with properties:
connId: []
grpPreName: 'input'
grpPostName: 'output'
resultsFolder: 'results'
errorMode: 'standard'
supportedErrorModes: {'standard' 'warning' 'silent'}
supportedPlotTypes: {'heatmap' 'histogram' 'receptivefield' 'responsefield'}

By default, this will look for a connect file named conn_{pre-group name}_{post-group name}.dat in the results/ directory, which is the default name pattern for connect files created with CARLsim::setConnectionMonitor.

Since
v3.0

9.4.2 Setting the Connect File Attributes

In case the connect file does not follow the default pattern, creating a ConnectionMonitor will result in the following warning:

>> CM = ConnectionMonitor('input,'output','results/');
Warning: Could not find valid connect file "results/conn_input_output.dat". Use
setConnectFileAttributes to set a proper connect file prefix/suffix/separator

and trying to call the plot method will result in an error message:

>> GM.plot
Error using ConnectionMonitor/throwError (line 1129)
Could not open file "results/conn_input_output.dat" with read permission

In this case, the method setConnectFileAttributes can be used to change the default prefix, suffix, and separator of the connect file name. In the above case, the prefix would be conn_, the separator would be _, and the suffix would be .dat. Note that only the "_" between group names counts as the separator. Analogously, for a connect file following the naming convention connect_{pre-group name}-{post-group name}.ext the prefix would be connect_, the separator would be -, and the suffix would be .ext. After prefix/suffix/separator have been set accordingly, the connect file will be found and weights can be plotted:

>> CM.hasValidConnectFile()
ans =
0
>> CM.setSpikeFileAttributes('connect_','-','.ext');
>> CM.hasValidConnectFile()
ans =
1
>> CM.plot
Since
v3.0

9.4.3 Plotting Weights

Once a ConnectionMonitor has been set up, synaptic weights can be plotted using the plot method:

>> CM.plot

This will plot each weight snapshot (or frame) in the current figure/axes using a default plot type, which is determined by the size of the weight matrix (see 9.4.4 ConnectionMonitor Plot Types).

A list of frames (or snapshots) and neurons to be plotted can be specified directly. For example, the following command would display the first, second, and eighth weight snapshot as a 2D heat map:

>> CM.plot('heatmap',[1 2 8]);

Every Monitor comes with an InteractiveMode for plotting activity and weights. By default, plotting will occur at a predefined speed (5 frames per second), unless otherwise specified using the method setPlottingAttributes (see 9.4.5 ConnectionMonitor Plotting Attributes). At any time, the user can hit key 'p' to pause plotting, or 'q' to quit. Hitting key 's' will enter stepping mode, which will freeze the current frame until the user either hits the 'right arrow' key (in order to step one frame forward) or the 'left arrow' key (in order to step one frame backward).

It is also possible to set the default plot type directly, so it does not have to be specified each time data is plotted or recorded:

>> CM.setDefaultPlotType('histogram')

For a list of available plot types, please refer to 9.4.4 ConnectionMonitor Plot Types.

A number of additional plotting attributes can be set via setPlottingAttributes, such as the background color of the figure and the number of frames to be displayed per second (see 9.4.5 ConnectionMonitor Plotting Attributes).

It is also possible to display weight data only for a subset of pre-synaptic or post-synaptic neurons. This makes it possible to visualize the receptive field of a post-synaptic neuron, or the response field of a pre-synaptic neuron.

The raw data of a connect file can also be read directly using a ConnectionReader (see 9.5.3 Connection Reader).

See also
9.4.4 ConnectionMonitor Plot Types
9.4.5 ConnectionMonitor Plotting Attributes
9.5.3 Connection Reader
Since
v3.0

9.4.4 ConnectionMonitor Plot Types

The following image illustrates the different plot types that are available (applied to the small "Hello World" network, which consists of 13x9 neurons projecting to 3x3 neurons with Gaussian connectivity):

9_cm_plottypes.jpg
Supported ConnectionMonitor plot types: 'heatmap', 'histogram', 'receptivefield', and 'responsefield'.

A specific default plot type can be set using setDefaultPlotType:

>> CM.setDefaultPlotType(str);

where str is either 'heatmap', 'histogram', 'receptivefield', or 'responsefield'. This type will then apply to all subsequent plotting and recording commands, unless it is overwritten explicitly with one of the method's input arguments.

This value can be overwritten by explicitly specifying a plot type when using the methods plot (see 9.4.3 Plotting Weights) or recordMovie (see 9.4.6 Recording a Movie).

Plot type 'heatmap' will plot a 2D weight matrix where the first dimension corresponds to the number of neurons in the pre-synaptic group (labeled nrPre in the image above), and the second dimension corresponds to the number of neurons in the post-synaptic group (labeled nrPost in the image above).

Plot type 'histogram' will plot a histogram of all weight values in the connection.

Plot type 'receptivefield' will plot the spatial receptive field of post-synaptic neurons (looking back on all connected pre-synaptic neurons). By default, the receptive field of all neurons will be shown. An additional argument to plot allows to specify a list of neurons for which to show the receptive field. For example, the receptive field in the above image (third panel) was generated with:

CM.plot('receptivefield',1,5); % plotType, frames, neurons

shown for the first frame and the fifth neuron in the post-synaptic group (which is located at (0,0,0)).

Plot type 'responsefield' will plot the spatial response field of pre-synaptic neurons (looking forward on all connected post-synaptic neurons). By default, the response field of all neurons will be shown. An additional argument to plot allows to specify a list of neurons for which to show the response field. For example, the response field in the above image (fourth panel) was generated with:

CM.plot('responsefield',1,59); % plotType, frames, neurons

shown for the first frame and the 59th neuron in the pre-synaptic group (which is located at (0,0,0)).

Since
v3.0

9.4.5 ConnectionMonitor Plotting Attributes

The method setPlottingAttributes(varargin) can be used to set default plotting attributes. These default settings will apply to all activity plots, unless their values are overwritten explicitly in the plot method (see 9.4.3 Plotting Weights).

The following command sets the value of variable propertyName1 to value value1:

>> CM.setPlottingAttributes('propertyName1',value1);

Additional variables can be flexibly appended; order or capitalization does not matter. A list of available attributes can be displayed via:

>> help ConnectionMonitor.setPlottingAttributes
CM.setPlottingAttributes(varargin) can be used to set default
settings that will apply to all activity plots.
This function provides control over additional attributes
that are not available as input arguments to CM.plot or
CM.plotFrame.
CM.setPlottingAttributes('propertyName1',value1,...) sets the
value of 'propertyName1' to value1.
Calling the function without input arguments will restore the
default settings.
BGCOLOR - Set background color for figure. Must be of
type ColorSpec (char such as 'w','b','k' or
a 3-element vector for RGB channels).
Default: 'w'.
BINWINDOWMS - The binning window (ms) in which the data
will be displayed. Default: 1000.
DISPFRAMENR - A boolean flag that indicates whether to
display the frame number. Default: true.
FPS - The frames per second for the plotting
loop. Default: 5.
HISTNUMBINS - Number of bins for histogram. Default: 20.
INTERACTIVEMODE - A boolean flag to set InteractiveMode on or
off. If it is off, key events/FPS/stepping
will take no effect (helpful if you want to
take over control yourself). Default: true.
Since
v3.0

9.4.6 Recording a Movie

Activity plots can be directly saved to AVI movie files via the following command:

>> CM.recordMovie;

This will generate a default ConnectionMonitor plot (see 9.4.3 Plotting Weights) and save the frames to an .avi binary using the MATLAB VideoWriter utility.

The following command will generate file called myMovie.avi that shows a heat map of the weight matrix, and display the first, second, and eighth frame (or snapshot) at a playback rate of 1 fps:

>> CM.recordMovie('myMovie.avi', 'heatmap', [1 2 8], 1);
created file "myMovie.avi"
See also
9.4.7 ConnectionMonitor Recording Attributes
Since
v3.0

9.4.7 ConnectionMonitor Recording Attributes

The method setRecordingAttributes(varargin) can be used to set default recording attributes. These default settings will apply to all recordings, unless their values are overwritten explicitly in the recordMovie method (see 9.4.6 Recording a Movie).

The following command sets the value of variable propertyName1 to value value1:

>> CM.setRecordingAttributes('propertyName1',value1);

Additional variables can be flexibly appended; order or capitalization does not matter. A list of available attributes can be displayed via:

>> help ConnectionMonitor.setRecordingAttributes
CM.setRecordingAttributes(varargin) can be used to set
default settings that will apply to all activity recordings.
This function provides control over additional attributes
that are not available as input arguments to CM.recordMovie.
CM.setRecordingAttributes('propertyName1',value1,...) sets
Calling the function without input arguments will restore the
default settings.
BGCOLOR - Set background color for figure. Must be of
type ColorSpec (char such as 'w','b','k' or
a 3-element vector for RGB channels). The
default is white.
FILENAME - File name where movie will be stored.
Currently the only supported file ending is
".avi".
FPS - The frames per second for the movie. The
default is 10.
WINSIZE - A 2-element vector specifying the window
size of the video as width x height in
pixels.Set to [0 0] in order to
automatically make the movie window fit to
the size of the plot window.
Since
v3.0

9.5 Reading Raw Data

Author
Michael Beyeler
Kexin Chen

Although the OAT provides a variety of functions to simplify the visualization and analysis of network activity or topology, there might be cases in which the user might like to have complete control over the process. Therefore, CARLsim also provides a means to directly read the simulation, spike, and weight file binaries generated during a simulation.

9.5.1 Simulation Reader

A SimulationReader can be used to read a simulation log file that is created by default by every CARLsim simulation, or by explicitly calling CARLsim::saveSimulation. This allows to directly access important properties of the simulation run or the spiking network, without the need of a NetworkMonitor.

The following public members (properties) are available:

>> properties SimulationReader
fileStr % path to simulation file
sim % struct containing viable simulation/network information
groups % struct containing all group info
syn_preIDs % pre-synaptic ID for every synapse in the network
syn_postIDs % post-synaptic ID for every synapse in the network
syn_weights % weight value for every synapse in the network
syn_maxWeights % max weight value for every synapse in the network
syn_plastic % type for every synapse in the network
syn_delays % delay value for every synapse in the network

The following code snippet points a SimulationReader to a simulation file results/sim_myNet.dat and populates the public member structs sim and groups with viable simulation/network information:

>> SimR = SimulationReader('results/sim_myNet.dat');

The sim struct can then be queried for values such as simulation time or execution time:

>> SimR.sim.simTimeSec % print simulation time (sec)
>> SimR.sim.exeTimeSec % print execution time (sec)
>> SimR.sim.nGroups % print number of groups in network
>> SimR.sim.nNeurons % print number of neurons in network
>> % etc.

The groups struct can then be queried for values such as the Grid3D dimensions or neuron IDs:

>> SimR.groups(1).sizeN % print number of neurons in first group
>> SimR.groups(1).startN % print ID of first neuron in first group
>> SimR.groups(1).grid3D % print Grid3D dimensions of first group
>> % etc.

By default, the deprecated syn_* properties will not be populated by the constructor call. In order to access these properties, the constructor needs to be called with an additional flag loadSynapseInfo:

>> SimR = SimulationReader('results/sim_myNet.dat',true);

Note that for this to work, the simulation must have been saved with CARLsim::saveSimulation input argument saveSynapseInfo set to true.

Note
Use of the syn_* properties above is deprecated. Use ConnectionMonitor or ConnectionReader to access synapse information instead.
Since
v3.0

9.5.2 Spike Reader

A SpikeReader can be used to read raw spike file data that was generated with the SpikeMonitor utility in CARLsim. This allows to directly access the spike data, be it in AER format or binned in suitable time windows, without the need of a GroupMonitor or NetworkMonitor.

The following methods are available:

>> methods SpikeReader
getError % returns the current error status (flag and message)
getGrid3D % returns the Grid3D dimensions of the group
getSimDurMs % returns the estimated simulation duration (ms)
readSpikes % reads spike files and returns data binned or in AER format

The following public members (properties) are available:

>> properties SpikeReader
fileStr % path to spike file
errorMode % current error mode
supportedErrorModes % list of supported error modes

The following code snippet points a SpikeReader object to a spike file results/spk_group1.dat (generated with the SpikeMonitor utility in CARLsim) and returns the spike data binned into 100 ms time windows:

>> SR = SpikeReader('results/spk_group1.dat');
>> spkData = SR.readSpikes(100); % binWindowMs

The variable spkData will return spike data in a 2D matrix, where the first dimension corresponds to the bin windows and the second dimension corresponds to the number of neurons in the group (1-indexed). For example, with a binning window of 100ms, spkData(1,1) would contain the number of spikes that the first neuron in the group emitted in the first 100ms (t = 0 .. 99ms) of the simulation.

Alternatively, spike data can be returned in AER format (as [times;neurIds]) if the binWindowMs input argument to readSpikes is set to -1:

>> SR = SpikeReader('results/spk_group1.dat');
>> spkData = SR.readSpikes(-1); % binWindowMs

The generation of a raster plot is then as easy as:

>> plot(spkData(1,:), spkData(2,:), '.k');
>> xlabel('time (ms)')
>> ylabel('neuron ID')

The SpikeReader can also be queried for an estimate about the total simulation duration via:

>> simDur = SR.getSimDurMs();

Note that this is only an estimate, based on the last spike time in the group. Other than that, a SpikeReader object does not know about any simulation procedures.

Since
v3.0

9.5.3 Connection Reader

A ConnectionReader can be used to read raw connection file data that was generated with the ConnectionMonitor utility in CARLsim. This allows to directly access the weight data, at specific times, without the need of a ConnectionMonitor.

The following methods are available:

>> methods ConnectionReader
getError % returns the current error status (flag and message)
getGrid3DPre % returns the Grid3D dimensions of the pre-synaptic group
getGrid3DPost % returns the Grid3D dimensions of the post-synaptic group
getNumNeuronsPre % returns the number of neurons in the pre-synaptic group
getNumNeuronsPost % returns the number of neurons in the post-synaptic group
getNumSnapshots % returns the number of snapshots in the connection file
readWeights % returns the weights of a connection at specific simulation times

The following public members (properties) are available:

>> properties ConnectionReader
fileStr % path to connection file
errorMode % current error mode
supportedErrorModes % list of supported error modes

The following code snippet points a ConnectionReader object to a connection file results/conn_group1_group2.dat (generated with the ConnectionMonitor utility in CARLsim) and returns the weight data for all recorded snapshots:

>> CR = ConnectionReader('results/conn_group1_group2.dat');
>> [allTimestamps, allWeights] = CR.readWeights();

The variable allTimestamps will contain a list of timestamps (ms) at which the corresponding weights were recorded. The variable allWeights will return the weight data in a 2D matrix, where the first dimension specifies the snapshot number and the second dimension corresponds to all synaptic weights for that specific snapshot. For example, allWeights(1,:) would contain all synaptic weights recorded during the first snapshot. The timestamp of the first snapshot can be retrieved via allTimestamps(1).

Plotting a histogram of all weights is then as easy as:

>> hist(allWeights(1,:));
>> xlabel('weight value')
>> ylabel('number of occurrences')

Alternatively, the weight vector can be reshaped as a 2D weight matrix according to the population dimensions and plotted as a heatmap:

>> imagesc( reshape(allWeights(1,:), CR.getNumNeuronsPost(), CR.getNumNeuronsPre()) );
>> xlabel('nrPre')
>> ylabel('nrPost')
Since
v3.0

9.5.4 Neuron Reader

A NeuronReader can be used to read the raw neuron state information

The following methods are available:

>> methods NeuronReader
getError % returns the current error status (flag and message)
getGrid3D % returns the Grid3D dimensions of the group
getSimDurMs % returns the estimated simulation duration (ms)
readValues % reads neuron monitor files and returns neuron state information

The following public members (properties) are available:

>> properties NeuronReader
fileStr % path to spike file
errorMode % current error mode
supportedErrorModes % list of supported error modes

The following code snippet points a NeuronReader object to a neuron monitor file results/n_group1.dat (generated with the NeuronMonitor utility in CARLsim) and returns the neuron state information in a MATLAB struct nValues:

nR = NeuronReader('results/ n_group1.dat');
nValues = nR.readValues();

Neuron state information, including the membrane potential (v), current (I), and the refactory variable (u), are stored as separate fileds in the nValues struct.

9.6 Migrating from CARLsim 2.2

Author
Michael Beyeler

Please note that the following scripts from CARLsim 2.2 (from former directory scripts/common/) are no longer available: