RecordingDevice

Command: RecordingDevice


Description


Recording devices are used to measure properties of or signals emitted
by network nodes e.g. using a multimeter voltmeter or a spike detector.

Recording devices can collect data in memory display it on the terminal
output or write it to file in any combination. The output format can be
controlled by device parameters as discussed below.

Recording devices can be subdivided into two groups: collectors and samplers.
- Collectors collect events sent to them; the spike detector is the archetypical
example. Nodes are connected to collectors and the collector then collects all
spikes emitted by the nodes connected to it and records them.
- Samplers actively interrogate their targets at given time intervals (default: 1ms)
and record the data they obtain. This means that the sampler must be connected
to the node (not the node to the sampler) and that the node must support the
particular type of sampling; see device specific documentation for details.

Recording devices share the start stop and origin parameters global to
devices. Start and stop have the following meaning for stimulating devices
(origin is just a global offset):
- Collectors collect all events with timestamps T that fulfill
start < T <= stop.
Note that events with timestamp T == start are NOT recorded.
- Sampling devices sample at times t = nh with
start < t <= stop
(t-start) mod interval == 0

Parameters

The following parameters are shared with all devices:
/start - Actication time relative to origin.
/stop - Inactivation time relative to origin.
/origin - Reference time for start and stop.

The following parameter is only relevant for sampling devices:
/interval - Sampling interval in ms (default: 1ms).

The following parameters control where output is sent/data collected:
/record_to - An array containing any combination of /file /memory /screen
indicating whether to write to file record in memory or write
to the console window. An empty array turns all recording of
individual events off only an event count is kept. You can also pass
strings (file) (memory) (screen) mainly for compatibility with
Python.

The name of the output file is
data_path/data_prefix(label|model_name)-gid-vp.file_extension

See /label and /file_extension for how to change the name. /data_prefix
is changed in the root node. If you change any part of the name
an open file will be closed and a new file opened.

To close the file pass a /record_to array without /file or pass
/to_file false. If you later turn recording to file on again the
file will be overwritten unless you have changed data_prefix label
or file_extension.

/to_file - If true turn on recording to file. Similar to /record_to [/file] but
does not affect settings for recording to memory and screen.
/to_screen - If true turn on recording to screen. Similar to /record_to [/screen] but
does not affect settings for recording to memory and file.
/to_memory - If true turn on recording to memory Similar to /record_to [/memory] but
does not affect settings for recording to file and screen.

/filenames - Array containing the filenames where data is recorded to. This array has one
entry per local thread and is only available if /to_file is set to true or
if /record_to contains /to_file.

/label - String specifying an arbitrary label for the device. It is used instead of
model_name in the output file name.
/file_extension - String specifying the file name extension without leading dot. The
default depends on the specific device.
/close_after_simulate - Close output stream before Simulate returns. If set to false any output
streams will remain open when Simulate returns. (Default: false).
/flush_after_simulate - Flush output stream before Simulate returns. If set to false any output
streams will be in an undefined state when Simulate returns. (Default: true).
/flush_records - Flush output stream whenever new data has been written to the stream. This
may impede performance (Default: false).
/close_on_reset - Close output file stream upon ResetNetwork. Upon the next call to Simulate
the file is reopened overwriting its contents. If set to false the file
will remain open after ResetNetwork so you can record continuously. NB:
the file is always closed upon ResetKernel. (Default: true).

The following parameters control how output is formatted:
/withtime - boolean value which specifies whether the network time should be
recorded (default: true).
/withgid - boolean value which specifies whether the global id of the observed node(s)
should be recorded (default: false).
/withweight - boolean value which specifies whether the weight of the event should be
recorded (default: false).
/time_in_steps - boolean value which specifies whether to print time in steps i.e. multiples
of the resolution rather than in ms. If combined with /precise_times each
time is printed as a pair of an integer step number and a double offset < 0.
/precise_times - boolean value which specifies whether offsets describing the precise timing
of a spike within a time step should be taken into account when computing
the spike time. This is only useful when recording from neurons that can
emit spikes off-grid (see module precise). Times are given in milliseconds.
If /time_in_steps is true times are given as steps and negative offset.
/scientific - if set to true doubles are written in scientific format otherwise in
fixed format; affects file output only not screen output (default: false)
/precision - number of digits to use in output of doubles to file (default: 3)
/binary - if set to true data is written in binary mode to files instead of ASCII.
This setting affects file output only not screen output (default: false)
/fbuffer_size - the size of the buffer to use for writing to files. The default size is
determined by the implementation of the C++ standard library. To obtain an
unbuffered file stream use a buffer size of 0.

Data recorded in memory is available through the following parameter:
/n_events - Number of events collected or sampled. n_events can be set to 0 but
no other value. Setting n_events to 0 will delete all spikes recorded
in memory. n_events will count events even when not recording to memory.
/events - Dictionary with elements /senders (sender GID only if /withgid or /withpath
are true) /times (spike times in ms or steps depending on /time_in_steps;
only if /withtime is true) and /offsets (only if /time_in_steps
/precise_times and /withtime are true). All data stored in memory
is erased when /n_events is set to 0.

Remarks

- Recording devices can only reliably record data generated during the previous
min_delay interval. This means that in order to ensure consistent results
you should always set a stop time for a recording device that is at least
one min_delay before the end of the simulation time.
- By default devices record to memory. If you want to record to file it may
be a good idea to turn off recording to memory to avoid that you computer's
memory fills up with gigabytes of data: << /to_file true /to_memory false >>.
- Events are not necessarily recorded in chronological order.
- The device will not open an existing file since that would erase the existing
data in the file. If you want existing files to be overwritten automatically
you must set /overwrite_files in the root node.

File
nestkernel/recording_device.h