Exporting Event Labels into MATLAB

When exporting AcqKnowledge files to MATLAB^® via “File > Save As…”, event marks are not exported with the data. To get event mark information into a MATLAB file, there are four options:

A. Use the AcqKnowledge Software API.

B. Create a channel or channels that carry event mark information.

C. Summarize the events to the journal and write a MATLAB script that will parse that text.

D. Use AcqKnowledge scripting to produce a program that will generate a file containing marker information.

Option A: Use the API

The BIOPAC File Format Application Programming Interface (ACKAPI) functions give software developers the ability to retrieve data from files in BIOPAC’s file format.

Option B: Create a Channel

1. Modify the measurements such that there is only one (either use “Display > Preferences…” to set the number of measurement rows and measurement columns both to 1, or set all but one of the measurement types to “None”).
2. In the measurement type pull-down menu for that one measurement, choose “Expression…”.
3. In the large edit box in the Measurement expression dialog box, enter a constant (e.g., “1”) and click “OK” to close the dialog box.
4. With the I-beam tool, make sure that the cursor is placed before the first event mark that you wish to export.
5. Choose “Analysis > Find Cycle” (alternatively type Ctrl+f in Windows or Command+f on a Mac).
   • Under the “Cycles/Peaks” tab, click the radio button corresponding to “events” under “Locate cycles from.” Use the pull-down menus such that both “Start event” and “End event” match each other exactly and also will match the event marks (or one of the set of event marks) to be exported. When the start and end events are the same, the “Match pairs of events only” checkbox may (and should) be unchecked.
   • Under the “Selection” tab, both edges should be established without offsets. That is, the edit boxes should contain only zeros; it does not matter whether the edges are relative to starting or ending events as the starting and ending event are identical if these instructions have been followed faithfully.
   • Under the “Output” tab check “Display measurement values as channels in graph” under the “Measurements” tab. The “Enabled output” should now say only “Measurements.” If any other output type is selected, choose the appropriate tab and disable the associated output.
6. Click “Find All Cycles.”
   • The result will be a channel that is zero everywhere but the locations of the event marks. At those locations the channel will have the value of the Expression measurement.
   • If there is more than one class of event (even if the “class” is defined by something as simple as the specific text in the event mark’s label), use the I-beam tool to move the cursor back to the beginning of the file, click the information button (white “i” in a blue circle) associated with the expression measurement, change the value of the expression (e.g., to “2”), and run Find Cycle again exactly as before except for the criteria used to define the “Start” and “End” events under the “Cycles/Peaks” tab.

When the data file is imported into MATLAB, this channel will contain the event mark information–any non-zero values indicate the sample point associated with an event mark, and the exact value (if there is more than one) will have the information about the specific event at that location.

A problem with option B is that there is a hard limit to the size of .mat file that can be exported by AcqKnowledge. Adding even one channel may put a file over that limit. A workaround could be to split up the task or split up the original file so that AcqKnowledge may create multiple files instead of just one large one, then all files can be imported into MATLAB and re-consolidated there.

Also, if the above steps are followed exactly and the data file contains more than one event mark at the same sample point, only the one corresponding to the criteria set up in the last run of Find Cycle will be represented.

Option C: Summarize Events to Journal

Option C is much simpler to implement than option B on the AcqKnowledge side but might require a significant amount of development effort on the MATLAB side.

In AcqKnowledge, choose “Display > Show > Event Palette…” (a toolbar button is also available for this at the far right edge of the events toolbar). Under “Actions” click “Summarize in Journal.” The journal will then have a list of lines such as:

1277.132 sec Skin Conductance Response CH1, GSR100C No label

• The first field, “1277.132 sec”, indicates the location (time) of the event mark.
• The second field, “Skin Conductance Response”, indicates the type of event mark.
• The third field “CH1, GSR100C” lists the channel the event mark is associated with and that channel’s label.
• The last field, “No label”, indicates the label (note that in this case the field should be taken literally as the event mark in this example did not have any text in its label).

If this option is to be pursued, the journal text should be copied and pasted into a text editor which can save as an ASCII file, or the journal should be saved directly (via the floppy disk icon at the top of the journal). There are various options for saving the journal directly, but saving in this way would probably make the MATLAB programming task more difficult than saving through a text editor. For instance, the native format for the journal (.jcq file) includes html coding that MATLAB would probably have to be programmed to step around.

Option D: Use Scripting

Option D would probably still entail writing a MATLAB script to parse the file created by AcqKnowledge‘s scripting language. The scripting language is not a standard feature of AcqKnowledge but rather a licensed add on. This option provides the greatest flexibility and capability for automation. That benefit comes at the cost of the scripting license and development time to generate the scripts in both languages. To determine whether this option is to be preferred (or is even feasible) one would have to consider the number of files to be processed, the complexity of the event mark information to be extracted, and perhaps most important of all, the programming skills of the users who will write the scripts in AcqKnowledge and MATLAB. If it can be foreseen that multiple experiments might make use of similar scripts, this option could truly be the best in the long term.