res = editcxdata( filename, data [, verbose, editSpikewave] ), where:
filename: A string containing the pathname for the Maestro (or Cntrlx) data file to be processed. This can be an absolute path or a path relative to the current working directory.
data: A Matlab structure array that must, at a minimum, have the fields mark1, mark2, cut, marks, tags, discard, and sortedSpikes -- as defined for the output structure created by readcxdata(). Any of these fields may be a null/empty matrix, indicating the absence of data. [Note: Some use the marked flag in the readcxdata() output structure as an "ignore data file" indication. Since the flag is 1 if the marks field is not empty and 0 otherwise, one can indirectly control the state of the flag by changing the content of the marks field with editcxdata(). Better yet, use the new (as of Sep 2010) discard field, an explicit discard flag.] In addition, this structure may optionally include the field spikewave, a 1xN double array containing the uncompressed 25KHz spike waveform (12-bit raw ADC samples, in [-2048 .. 2047]). If present, its contents are compressed and packaged into data records, replacing the spike waveform records that were originally in the file. This is the one exception in which editcxdata() may be used to alter actual data stored in a Maestro data file. NOTE that editcxdata() does not let the user change the length of the spike waveform, only the samples themselves. The spike waveform data in the file is replaced only if the following conditions are met: (1) the editSpikewave guard flag is set; (2) the spikewave field is present in this structure and is not empty. If the conditions are met, but the array length N does not match the number of samples in the waveform data read from the file, the function aborts.
verbose: If nonzero, detailed progress messages are written to the Matlab console window. Defaults to 0. This is typically used only for debugging purposes.
editSpikewave: If nonzero, this guard flag enables editing of the 25KHz spike waveform stored in the data file. Default value is 0, so this flag must be explicitly included in the invocation of editcxdata() in order to modify the spike waveform.
res: 0 if successful, -1 if an error occurs. In the latter case, an error message is written to the Matlab console window.
This function is a companion to readcxdata(). It may be used to clear, edit or augment JM/X/MWork-generated analysis results appended to the data file without altering the original recorded data. For example, some lab members have preferred to write their own scripts to do saccade cutting, spike sorting, and other preliminary analytic tasks that could be done in JMWork. Such scripts can use editcxdata() to append the results of the analysis to the data file. Like readcxdata(), it is a compiled MEX function written in C for optimum performance.
By design, the input argument data is intended to mirror the format of the output structure returned by readcxdata(). Typically, a user will first read in the data file by invoking A=readcxdata(fName), then modify some or all of the abovementioned fields in the structure array A, and finally call editcxdata(fName,A) to modify the data file itself. The MEX function makes two passes through the original data file. On the first pass, it simply reads through the data file a record at at time and constructs the set of existing action codes contained therein. This set of action codes is updated in accordance with the contents of the mark1, mark2, cut, marks, tags, and discard fields in the data argument (all other JM/X/MWork actions are left unchanged). On the second pass, it again reads the file one record at a time, streaming all raw data records as is into a temporary file created in the same directory. The data records are followed by the necessary action records (if any), followed possibly by sorted spike train records that store the contents of the sortedSpikes field. Once the temporary file has been successfully written and closed, the original data file is deleted and the temporary file is given the same name as the original file.
The function does not allow one to alter the data records contained in the file -- with one important exception. If the spikewave field is included in the data argument, its contents will replace the original spike waveform data stored in the file (under the conditions described above). This feature was added to permit preprocessing of the spike waveform to remove stimulus artifacts prior to submitting a Maestro data file to JM/X/MWork for spike sorting. Use with care! It is recommended that users save a copy of the original data file prior to changing the spike waveform contents.
The function does not support the JMWork-specific action codes that add or remove spikes in a sorted-spike train channel. Running a data file through editcxdata() will remove these actions from the file regardless of what is in the field data.sortedSpikes. Be aware of this limitation if you use both JMWork and editcxdata() in your analysis workflow.
Prior to a bug fix dated 22 Feb 2010, repeated use of readcxdata()/editcxdata() on a given data file could introduce jitter in the spike times saved in the "sorted-spike train" channels. This was due to a truncation error that occurred when converting back and forth between the external (absolute spike times in milliseconds) and internal representations (inter-spike intervals in integral number of 10-µs ticks) of the spike time data.