This function will add markers to the NIRS data. The data must be the format generated using import_nirs and markers must be in the COBI .mrk file with the exact same name and location as the original .nir file. The returned data will have the markers added as a new column. If there are duplicate markers (i.e. more than one marker sent within a 500ms window), the function will either allow duplicates or remove them, depending on the parameters set.
Arguments
- nirsData
(DATAFRAME) A dataframe containing NIRS data in a long format that has been imported using the
import_nirsfunction.- allowDuplicates
(LOGICAL: optional) If TRUE, the function will allow multiple markers to be attached to the same data point in the data. This will cause extra rows in the output (see details). Default is FALSE.
- removeDuplicates
(LOGICAL: optional) If TRUE, the function will remove duplicate markers that are attached to the exact same timepoint in the data, retaining only the first marker value for that particular data point. Default is FALSE.
Details
This function will add markers to the NIRS data. The data must be the format generated using import_nirs and markers must be in the COBI .mrk file with the exact same name and location as the original .nir file. The returned data will have the markers added as a new column.
How are markers added to the NIRS data?
In real time, the markers are often sent in-between the data acquisition points. However, the COBI marker (.mrk) file specifies which data point the marker should be attached to using a row value, which is the equivalent of the dataRow value in the NIRS data generated by import_nirs. This function will add the markers to the NIRS data by linking the value specified in the .mrk file to the dataRow value in the nirsData.
Dealing with duplicate markers:
I have found that when sending markers via a serial port connection, there is the possibility of sending duplicate markers. This happens if they are sent in quick succession, faster than the sampling rate of the fNIRS data acquisition. The result is more than one marker attached to the same data point in the original .mrk file - (You can see this by opening the .mrk file in a text editor and looking at the 3rd column for duplicate values).
Often, duplicates are not useful. However, it is also possible that the markers are sent at the same time intentionally, for example, marking the end of a trial and the start of the next trial. In this case, you may want to keep the duplicate markers.
The allowDuplicates and removeDuplicates parameters allow you to choose how to handle duplicate markers.
Examples
if (FALSE) {
# import the NIRS data
nirsData <- import_nirs("path/to/nirs/file.nir")
# The location of the marker file will be read
# from the fileName column of the nirsData dataframe.
nirsData <- add_markers(nirsData)
# Now let's assume there are duplicate values in the marker file.
# This could be problematic if it is unintentional.
# Equally, it could be completely fine for you if you are aware of this or did it intentionally.
# If you run the function normally, it will return a message
# to let you know that there are duplicates.
# We have 2 options: allow the duplicates or remove them.
# If we allow them, the output will have extra rows.
# These will be exact duplicates of the rows that have the same dataRow value (i.e. the same timepoint) but with the additional markers.
# You might want this, and it might cause no issues with your analysis.
# To allow duplicates, set allowDuplicates = TRUE.
nirsData <- add_markers(nirsData, allowDuplicates = TRUE)
# If we remove the duplicates, we will retain only the first marker value for that particular datapoint.
# This is will mean that only one of the markers will be linked to this exact datapoint.
# This might be useful if you are only interested in the first marker that was sent, or if you sent additional markers accidentally.
# The output will have the same number of rows as the input.
#To remove duplicates, set removeDuplicates = TRUE.
nirsData <- add_markers(nirsData, removeDuplicates = TRUE)
}