Recording backend ascii - Write data to plain text files¶
Description¶
The ascii recording backend writes collected data persistently to a plain text ASCII file. It can be used for small to medium sized simulations, where the ease of a simple data format outweighs the benefits of high-performance output operations.
This backend will open one file per recording device per thread on each MPI process. This can cause a high load on the file system in large simulations. This backend can become prohibitively inefficient, particularly on machines with distributed filesystems. In case you experience such scaling problems, the recording backend for SIONlib may be a possible alternative.
Filenames of data files are determined according to the following pattern:
data_path/data_prefix(label|model_name)-node_id-vp.file_extension
The properties data_path
and data_prefix
are global kernel
properties. They can, for example, be set during repetitive simulation
protocols to separate the data originating from individual runs. The
label
replaces the model name component if it is set to a non-empty
string. node_id
and vp
denote the zero-padded global ID and virtual
process of the recorder writing the file. The filename ends in a dot
and the file_extension
.
The life of a file starts with the call to Prepare
and ends with
the call to Cleanup
. Data that is produced during successive calls
to Run
in between a pair of Prepare
and Cleanup
calls will
be written to the same file, while the call to Run
will flush all
data to the file, so it is available for immediate inspection.
If the file name already exists when creating a new recording, the
call to Prepare
will fail with a FileExists
error. To overwrite
the old file, the kernel property overwrite_files
can be set to
True
using the corresponding kernel attribute. An alternative way
for avoiding name clashes is to set the kernel attributes
data_path
or data_prefix
, to write to a different file.
Data format¶
Any file written by the ascii recording backend starts with an informational header. The first header line contains the NEST version, with which the file was created, followed by the version of the recording backend in the second. The third line describes the data by means of the field names for the different columns. All lines of the header start with a # character.
The first field of each record written is the node ID of the neuron the event originated from, i.e., the source of the event. This is followed by the time of the measurement, the recorded floating point values and the recorded integer values.
The format of the time field depends on the value of the property
time_in_steps
. If set to false (which is the default), time is
written as a single floating point number representing the simulation
time in ms. If time_in_steps
is true, the time of the event is
written as a pair of values consisting of the integer simulation time
step in units of the simulation resolution and the negative floating
point offset in ms from the next integer grid point.
Note
The number of decimal places for all decimal numbers written can be
controlled using the recorder property precision
.
Parameter summary¶
- file_extension
A string (default: “dat”) that specifies the file name extension, without leading dot. The generic default was chosen, because the exact type of data cannot be known a priori.
- filenames
A list of the filenames where data is recorded to. This list has one entry per local thread and is a read-only property.
- label
A string (default: “”) that replaces the model name component in the filename if it is set.
- precision
An integer (default: 3) that controls the number of decimal places used to write decimal numbers to the output file.
- time_in_steps
A Boolean (default: false) specifying whether to write time in steps, i.e., in integer multiples of the simulation resolution plus a floating point number for the negative offset from the next grid point in ms, or just the simulation time in ms. This property cannot be set after Simulate has been called.