Neurorecorder ToolNote: This manual applies to Neurorecorder 168+ with LWDAQ 10.6.11+.
Warning: The Neurorecorder assumes there are no spaces in any directory or file names.
[20-JUL-24] The Neurorecorder is a component of our LWDAQ Program. It downloads signals from our telemetry receivers and writes the signals to disk as NDF files. To play and analyze these recordings, we us a separate Neuroplayer tool. For a video tutorial on how to use the Neurorecorder and Neuroplayer, see Neuroarchiver Introduction.
When we select Neurorecorder in the Tool Menu, our LWDAQ process creates a Neurorecorder in a new and separate process. This Neurorecorder will continue recording even when we quit our original LWDAQ process. Each time we select Neurorecorder in the Tool Menu, we create a new and independent Neurorecorder. We can record simultaneously from any number of data receivers on the same computer, and process the recordings as they are written to disk using several Neuroplayers, without worrying about the failure of a player halting a recording.
To prepare for recording, we specify the internet protocol (IP) address of our telemetry receiver. If our receiver is connected to a LWDAQ Driver, we must also specify the driver socket to which the receiver is connected. If our receiver supports the pre-selection of telemetry channels for recording, we can list these channels in the Select field. We choose a directory for recording with PickDir. We specify how long we want each NDF archive to be, the default being one hour (3600 s).
To begin recording we press Start. The state label will change to "Start" with a red background. The Neurorecorder resets the data receiver at the beginning of the next computer clock second. It creates a new disk archive named after the UNIX time. It starts downloading telemetry signals and storing them in the archive. We can see the name of the archive next to the Archive label. During recording, the state label says "Record" and the background flashes yellow. A yellow background means the Neurorecorder is waiting for data from the data receiver. Press Receiver to see the telemetry signals as they arrive from the receiver. The Receiver Instrument will open, presenting plots of the signals and providing summaries of reception quality. The Receiver Panel consumes some of your computer's computational resources, so we recommend you close the Receiver when you are done looking at the signals.
Press Stop to stop recording. Press Resume to continue recording from the same data receiver to the same archive. So long as we press Resume within a few seconds, we can be confident no data will be lost. We refer to the files written by the Neurorecorder as archives. The archives are written in our NDF format. A Neuroplayer can read, display, and analyze an archive as it is being written by the Neurorecorder, or any time thereafter.
The Configure button opens the a Configuration Panel, which presents a complete list of the Neurorecorder configuration parameters. The parameters presented in the Neurorecorder window are all listed here again, as well as other parameters we doubt you will ever have to adjust. Press Save Configuration and the Neurorecorder will save its configuration parameters to a file in your LWDAQ/Tools/Data folder. When you next open the Neurorecorder, these parameters will once again be loaded into the tool. All Neurorecorders share the same settings file, so we cannot save and recall distinct settings for multiple data receivers. When you press Unsave Configuration, the Neurorecorder deletes any existing settings file.
[20-JUL-24] Follow our telemetry set-up instructions to get your data receiver and computer communicating with one another. As part of the set-up you will download and install the LWDAQ Software. To record signals to disk, select the Neurorecorder from the Tool menu. To play back and process existing archives, select the Neuroplayer in the Tool menu.
To configure the Neurorecorder, set ip_addr to the internet protocol (IP) address of your Animal Location Tracker, Telemetry Control Box, or LWDAQ Driver. If you are using a LWDAQ Driver, set driver_sckt to the socket on the driver into which you have plugged your data receiver. If your receiver supports pre-recording channel selection, enter the channels you wish to record, or use a "*" to record all available channels. Press PickDir in the Neurorecorder to select a directory for recording archives. Enter how often you want the Neurorecorder to create a new archive by entering the length in seconds in the Autocreate box. By default, this length is one hour. The Neurorecorder will close the current file when it reaches the requested length, and start a new file, and so on.
Press Start. The Neurorecorder state indicator turns red. The Neurorecorder attempts to make contact with the receiver. If successful, it reset the receiver and creates a new archive on disk. It printes several lines of text, giving the data receiver type, the features the receiver supports, and the name of the newly-created archive. The Neurorecorder starts downloading telemetry data and writing it to the archive. The state indicator turns white and starts flashing yellow.
The Neurorecorder is designed to run continuously. Leave it running during your entire experiment. To stop the recording press Stop. To resume recording without resetting the data receiver or creating a new archive, press Resume. To reset the receiver and start a new archive, press Start.
[20-JUL-24] The Neurorecorder stores transmitter messages in NDF (Neuroscience Data Format) files. It performs no processing upon the messages as it stores them to disk. What appears in the NDF file is exactly the same sequence of messages that the telemetry data receiver stored in its own memory. Thus we have the raw data on disk, and no information is lost in the storage process. An NDF file contains a header, metadata string, and a data block to which we can append data at any time without writing to the header or the data string. We define the NDF format in the Images section of the LWDAQ Manual. We describe how SCT messages are stored in the data section of NDF files in Reading NDF Files. The Neurorecorder manipulates NDF files with routines provided by LWDAQ. These routines are declared in LWDAQ's Utils.tcl script. You will find them described in the LWDAQ Command Reference. Their names begin with LWDAQ_ndf_.
All archives created by the Neurorecorder receive a name of the form Mx.ndf, where M is the prefix string specified in ndf_prefix and x is a ten-digit number giving the time of creation of the archive. By default, the prefix is itself the capital letter "M". If we recall correctly, we chose "M" because it is the first letter of the word "messages". If you want to use a prefix other than "M", change ndf_prefix in the Configuration panel. If you do change ndf_prefix, don't include any spaces in your prefix string.
The ten-digit number, x, specifies a standard Unix Time. It is the number of seconds since 00:00 on 1st January 1970, GMT. We can get the Unix time corresponding to our computer's clock and time zone using the Tcl command clock seconds. Open the LWDAQ console and type in this command to see for yourself. The Neuroplayer's Clock Pane uses the timestamps in archive file names to find intervals corresponding to specified absolute times.
The Neurorecorder stores data in NDF archives and the Neuroplayer reads the NDF archives to extract telemetry signals and calculate spectra. When the Neuroplayer reaches the end of an archive, it looks for a newer archive in the same directory and starts playing that one immediately afterwards. Thus if we are playing the archive that is being recorded, the Neuroplayer will play the fresh data from the expanding archive until the Neurorecorder starts a new archive, at which time the Neuroplayer will switch to the new archive automatically. If we are playing old archives, the Neuroplayer will still move from the end of one to the start of the next, even if the next is unrelated to the first. Thus we can go through a collection of archives that are from different experiments and different times, and apply processing to extract characteristics from all the archives.
The Neurorecorder provides a Header button that opens a text window and allows you to enter a comment or document describing the recordings. This header string will be added to the metadata of every archive created by the Neurorecorder.
When recording generates a warning or an error, these appear in the text window in blue and red respectively. If we set log_warnings to 1, the Neurorecorder will write all warnings and errors to a log file. The name of the log file is stored in log_file. By default, the log file is the /Tools/Data directory and is named Neurorecorder_log.txt. In the Configure Panel, we can type in a new log file name and so place the log file somewhere else. The warnings and error messages all include the current time as a suffix, which is the time the Neurorecorder discovered the problem.
[19-JUL-24] The data acquired by the Neurorecorder takes the form of a stream of data receiver messages, as we describe in the Receiver Instrument manual. The data contains values from one or more telemetry channel numbers. If we have several receivers sharing the same Faraday enclosure with many transmitters in the same enclosure, we might want to record from each receiver only those telemetry channels provided by sources near the receiver. The Neurorecorder supports isolation of telemetry channels with its pre-recording select string, available in its Select entry box. Pre-recording selection is supported by newer receivers such as the Animal Location Tracker (A3038) and Telemetry Control Box (A3042). We enter a list of channel numbers separated by spaces to select particular channels. We enter a wildcard "*" character to indicated all received channels should be recorded.
The Header button opens a text window into which you can enter a comment or paste a text document describing the contents of the archive you are recording. This comment will be written to the metadata of every archive created by the recorder.
The Neurorecorder's customization string allows us to override default values for parameters such as the coordinates of animal location tracker coils. We open the customization string editor with the Customize button in the Neurorecorder, edit the string, and save with the Save button. To override tracker coil positions, we enter them as a string of numbers enclosed in an alt tag, like this:
<alt>100 100 100 100 100 200 100 200 100 100 200 200 200 100 100 200 100 200 200 200 100 200 200 200 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1</alt>
In the above example, we have eight loop antennas with coaxial cables connected to the first eight detector modules of an A3038 animal location tracker. We are are not using the remaining eight detector modules. We give the x, y, and z coordinates of the eight antennas in centimeters. We choose our coordinate origin so all coordinates are positive. We use negative values for the coordinates of the remaining coils, which instructs the Neurotracker to ignore these coils in the calculation of power centroid. We enter the string as above, with the alt tags, and the Neurorecorder will use these coordinates in place of the default A3038 array locations. We can also specify tracker background powers with the alt_bg tag. We give one integer background power for each of the available detectors. For the A3038C we would enter sixteen values.
[22-JUL-24] Synchronization between telemetry data and a computer clock is hard to achieve when we must accommodate inaccuracy in our clocks, account for occasional network failures, and recover from mandatory operating system updates. In the paragraphs below, we attempt to explain how it is that the Neurorecorder guarantees agreement between telemetry timing and the computer clock, and to explain what will happen if you check the Neurorecorder's Synchronize box.
When we press Start, the Neurorecorder waits until the first moment of a new computer second and resets the telemetry data receiver. We say the receiver clock and the computer clock have been synchronized. The delay between the start of the new second and the moment the reset command reaches the data receiver is the synchronization delay. We cannot measure the synchronization delay directly. We can measure only the time it takes for a confirmation of the reset to return to the Neurorecorder, which we call the reset delay. The reset delay is longer than the synchronization delay. Here are reports of the time period for which the Neurorecorder waited for a new computer clock second to begin, and the reset delay it observed for an Octal Data Receiver (A3027, ODR).
Detected: Octal Data Receiver (A3027), applying driver socket, ignoring channel selection. Synchronization: Waiting period 773 ms, reset delay 53 ms. Created: Synchronized archive M1674839047.ndf at 27-Jan-2023 12:04:07. Detected: Octal Data Receiver (A3027), applying driver socket, ignoring channel selection. Synchronization: Waiting period 665 ms, reset delay 44 ms. Created: Synchronized archive M1674839058.ndf at 27-Jan-2023 12:04:18.
Here is a similar report from a Telemetry Control Box (A3042, TCB). The TCB is faster than the ODR at responding to commands.
Detected: Telemetry Control Box (A3042), applying channel selection, ignoring driver socket. Synchronization: Waiting period 906 ms, reset delay 26 ms. Created: Synchronized archive M1674840015.ndf at 27-Jan-2023 12:20:15. Detected: Telemetry Control Box (A3042), applying channel selection, ignoring driver socket. Synchronization: Waiting period 889 ms, reset delay 31 ms. Created: Synchronized archive M1674840026.ndf at 27-Jan-2023 12:20:26.
Immediately following synchronization, the computer and receiver clocks agree to better than 50 ms, with the receiver clock lagging behind the computer clock. After that, the two clocks will drift apart. All our telemetry data receivers are equipped with temperature-compensated ±1 ppm clocks. These drift by no more than ±0.1 s/dy. After three months of continuous recording, they will be wrong by not more than 10 s. Computer clocks, when left to run without correction, are less accurate. We have seen computer clocks drift by ±4 s/dy, and drifts of ±1 s/dy are common. If the computer is connected to the Internet, however, its operating system will correct its clock using an Internet reference clock. Over the course of a day, the computer clock will drift by ±1 s, but this drift will not accumulate. The corrected computer clock will be accurate to ±1 s over any time period.
In years past, most of the computers running our telemetry systems were isolated from the Internet and their clocks ran without correction. These days, the computers are almost always connected to the Internet as well as the local network that hosts our telemetry system. The Internet connection allows us to transfer archives off the computer. As an additional benefit, the computer clock can be corrected. If your computer is connected to the Internet, we recommend you take advantage of Internet time by configuring your operating system to correct its clock using one of the global reference clocks.
The Neurorecorder provides two strategies for maintaining synchronization between telemetry data and the data acquisition computer's clock. The default strategy is free-running in which the Synchronize box is un-checked. In the free-running strategy, the Neurorecorder will not re-synchronizes the receiver clock unless it encounters a severe communication failure. The free-running Neurorecorder synchronizes telemetry timing with the computer clock through its choice of archive names. It never resets the receiver clock. It never needs to interrupt the flow of data from the receiver. All telemetry data is written to disk. Every autocreate seconds, the Neurorecorder creates a new archive and names the archive after the current computer time. The Neurorecorder will not wait for the start of a new computer second before creating the file. If autocreate = 3600. The Neurorecorder will create a new archive when it has written 3600 s worth of telemetry data to the previous archive. The computer clock might run slow enough that we accumulate 3600.0 s of telemetry data in 3599.8 s of computer time. After five hours, we will see two consecutive archives with timestamps that differ by only 3599 s. Conversely, the computer clock may be running fast, and we will see archives separated by 3601 s.
The Neuroplayer uses archive timestamps to navigate through our recording libraries. The drift between the receiver and computer clocks within a single hour will be no more than ±0.2 s, even with an uncorrected computer clock. The chief source of disagreement between telemetry timing and the computer clock is the fact that the creation of a new archive can occur anywhere within a computer second. If this creation occurs at the start of a computer clock second, the telemetry timing and the computer clock are synchronous at the beginning of the archive. If the creation occurs at the end of a computer clock second, the telemetry timing will lag the computer clock by 1.0 s. With the the Neurorecorder free-running and recording one-hour archives, the telemetry timing will lag behind the computer clock by anything from 0.0 s to an extreme of 1.2 s. As a rule of thumb, we can assume the average lag in the telemetry timing is 0.5 s with standard deviation 0.3 s.
If we can tolerate the free-running lag between the telemetry timing and the computer clock, we should leave the Synchronize unchecked. Because the free-running Neurorecorder never resets the receiver, we never discard telemetry data. All samples are recorded. But if we need better synchronization, we must check the Synchronize box to enable the re-synchronization strategy. When each new archive is created, the Neurorecorder waits until the start of a new computer second to reset the receiver and begin a new archive. In this manner, the receiver and computer clocks are synchronized at the start of each archive. If the computer clock is being corrected, we can hope for it to drift no more than ±50 ms per hour with respect to the receiver clock thereafter.
In re-synchronizing the receiver, we lose the telemetry data that was accumulated while we were waiting for the new computer clock second to begin. With the two clocks running at almost the same speed, this loss will be almost a full second every time we create a new archive. Our hour-long archives will have timestamps separated by 3601 s instead of 3600 s. When we combine twenty-four such one-hour archives into one export file, we will produce a day-long recording that is twenty-four seconds shorter than a full day. For these reasons, the default strategy of the Neurorecorder is free-running rather than re-synchronizing. We should select re-synchronization only our need for ±50 ms agreement between telemetry timing and the computer clock is worth the complications that result from loss of one second of telemetry per hour.
An example of an experiment in which we need ±50 ms synchronization is when we are recording video with Animal Cage Cameras (ACC) and we want to relate telemetry and video events with a precision of ±100 ms. The ACC maintains synchronization with the computer clock to within ±50 ms. If we can maintain ±50 ms synchronization of telemetry timing and the computer clock, we can confirm the simultaneity of an event in telemetry and video to within ±100 ms. Re-synchronization of the receiver clock at the start of each one-hour archive guarantees that the telemetry will be synchronized with the computer clock to within ±50 ms, at a cost of losing one second of telemetry data per hour.
The NDF format contains a header, a metadata string, and a data block. Transmitter messages and clock messages are stored by the Neurorecorder in the data block. New data is appended to the data block without any alteration of existing data. The metadata string has a fixed space allocated to it in the file, but is itself of variable length, being a null-terminated string of characters. We can edit the metadata of an archive with the Metadata button in the Neuroplayer. At the top of the metadata there is a metadata header, which the Neurorecorder writes into the metadata when it creates the recording archive. The metadata header contains one or two comment fields, where one comment is a string delimited by an xml "c" tags, like this:
<c> Date Created: 17-Jun-2021 14:29:09. Creator: Neurorecorder 145, LWDAQ_10.2.10. </c> <payload>16</payload> <coordinates>0 0 0 12 0 24 12 0 12 12 12 24 24 0 24 12 24 24 36 0 36 12 36 24 48 0 48 12 48 24</coordinates>
The Neurorecorder always generates a header comment like the one shown above. It also writes the message payload and tracker coil locations to the metadata so that subsequent playback of archives recorded from various data receivers will be configured by the metadata automatically. The Neurorecorder will also add another header comment defined by the user to every file it creates. We press the Header button in the Neurorecorder and we get the Header Panel, in which we can create, edit, and save a header string. This string might describe the apparatus from which we are recording, so that every archive we create contains a record of where the archive came from, and what it contains. We don't have to include xml "c" tags around the text in the Header Window. When the Neurorecorder writes the header to the metadata, it adds the "c" itself.
Here we list changes in recent versions that will be most noticeable to the user. Earlier changes are here. The Neurorecorder source code is the file Neurorecorder.tcl bundled with the LWDAQ distribution.