The Neuroarchiver Tool is a program written in TCL/TK. It is a tool available in the LWDAQ Software. It is works with the LWDAQ Software's Recorder Instrument and data acquisition hardware such as the Data Receiver (A3018) and collections of Subcutaneous Transmitters (A3013). The Neuroarchiver acquires raw data continuously from the hardware and saves the data to disk. Independently from its data-storage activities, the Neuroarchiver reads raw data from disk, extracts signals from the raw data, displays the signals on the screen, and applies user-defined analysis to the signals.
The Neuroarchiver makes heavy use of disk files. The recorder portion of the Neuroarchiver acquires data and stores it to disk immediately, without any analysis. The player portion of the Neuroarchiver reads data from disk and analyses it. Both the recorder and player can run simultaneously, so that the player can be reading data as it becomes available on disk.
To run the Neuroarchiver, download and install the LWDAQ Software for your Linux, Windows, or MacOS computer. Run the program and select the Neuroarchiver from the Tool menu. Before you proceed, however, we recommend you open the Recorder Instrument in the Instrument menu, and learn to use it with the help of the Recorder Instrument Manual. Before you acquire data with the Neuroarchiver from your own hardware, you must set up the Recorder Instrument to be the source of data. You are welcome to use the Recorder Instrument's default settings, which will acquire raw data from our demonstration hardware.
In the figure above, the recorder portion of the Neuroarchiver is downloading data in half-second intervals and storing them to an archive file called M1225927145.ndf. Every 1000 seconds the recorder will produce a new archive file. The archive files are in the NDF (Neuroscience Data Format) we describe here. The player portion of the Neuroarchiver is reading the same archive and displaying the signals from channels 5 and 3. The signal versus time is in the left plot and the aplitude versus frequency is in the right plot. The player state is "Play" with a green background. The green background means that the player is at this very moment analyzing its most recently-read block of messages. If the background is yellow, that means the player is waiting from data to be added to its archive. When the yellow background appears behind the recorder state, the recorder is waiting for data from the Recorder Instrument, which is in turn waiting for data from the data acquisition hardware.
Here is how you start recording and simultaneous play-back with the Neuroarchiver.
Look at your data recorder. It should have an EMPTY light. This light should be flashing regularly. If it is not flashing regularly, then your Neuroarchiver is not recording data as fast as the data is being generated by the data recorder. Turn off the player's transform display and press Reset again. If the red light still does not flash regularly, try turning off the signal display. If the red light still does not flash regularly, you must be using a computer with clock speed less than 330 MHz, or your network connection is too slow to transport the data as it is created.
Once you get the recording and play-back working, you can try out various values of recording interval and play-back interval. For the most stable operation with up-to date signal display, the recording interval should be half the play-back interval. In stable operation, the player is waiting for the recorder to save data to disk. When the data is available, the player displays it. While it waits, the player state indicator is yellow.
The data processed by the Neuroarchiver takes the form of a list of data recorder messages, as we describe here. In general, the data will contain values from one or more channels. The Neuroarchiver selects which channels to display, transform, and store to disk using its channels parameter.
In its simplest form, channels is a list of channel numbers, each between 0 and 255. In its more complex form, channels is a list of channels, each with a nominal sampling frequency and scatter extent. For a description of sampling frequency and scatter extent, see our description of the Recorder Analysis. You specify each channel with three numbers separated by colons. The first number is the channel number, the second is the sampling frequency in samples per second, and the third is the scatter extent in data-recorder clock ticks. Thus "5:512:8" means channel 5 with sampling frequency 512 SPS and scatter extent 8.
The sampling frequency and scatter extent are used by the Neuroarchiver when it reconstructs an incoming message stream. The Neuroarchiver uses its clocks_per_second and ticks_per_clock parameter to convert samples per second into a sample period in units of data recorder clock ticks. The Neuroarchiver can then go through a channel's messages and identify places where messages are missing, and eliminate bad messages that occur in the message stream at random times.
You can turn on and of the reconstruction of incoming message streams using the Reconstruct check box. When you un-check this box, the Neuroarchiver takes the message streams as they are, without adding substitute messages or eliminating bad messages.
If you don't specify the scatter extent, the Neuroarchiver uses its default value, in default_scatter. If you don't specify the sampling frequency, the Neuroarachiver uses default_frequency. You can change these values in the Neuroarchiver's configuration window, which you open with the Config button. With "5:512:8 2:256", we select two channels, numbers 5 and 2. Channel 5 has frequency 512 SPS and scatter 8. Channel 2 has frequency 256 SPS and scatter 8.
The Neuroarchiver uses the Recorder Instrument Manual to obtain live data. First you set up the Recorder Instrument to read out streams of messages from a data-recording device, then you open the Neuroarchiver to store the live data. The Neuroarchiver does not display new data until after it has been stored to disk, so display and analysis are not part of data acquisition.
To capture live data, open the Recorder Instrument and configure it to read your data out of your data recorder. The Neuroarchiver will simply call the Recorder Instrument's data acquisition procedure when it captures new live data. You don't have to leave the Recorder Panel open after you set it up for data Recording, but you can leave it open if you like. By default, the Neuroarchiver turns off the Recorder Instrument's plotting and analysis of the incoming data. But you can turn on the plotting and analysis by setting enable_recorder_analysis to 1 in the Neuroarchiver's Configuration Panel, which you can open with the Configure button. With the plots turned off, you will see the raw data displayed as gray-scale pixels in the Recorder Instrument.
The only thing that passes from the Recorder Instrument to the Neuroarchiver is the raw data acquired from the data acquisition hardware. The Recorder Instrument has a data acquisition parameter called daq_num_clocks. When you instruct the Recorder Instrument to acquire new data, it acquires a block of messages with exactly this number of clocks. The Recorder Instrument makes sure that first message in the block is always a clock message. The Neuroarchiver calculates daq_num_clocks from record_interval, which has units of seconds. In the example shown above, the recording time interval is 0.5 s, and is shown in the menu-button to the right of the recorder controls.
The Neuroarchiver performs all its signal processing, plotting, and analysis when it reads data from disk. You can turn on signal reconstruction, fourier transformation, and user-defined analysis with checkboxes in the player section of the Neuroarchiver Panel.
The Neuroarchiver Script is the TCL/TK program that defines the Neuroarchiver process. The name of the file is Neuroarchiver.tcl, and you will find it in the Tools directory of your LWDAQ distribution. We have added extensive comments to the script. We intend these comments to act as an introduction to TCLTK and LWDAQ programming.
