Unexpected behavior with event reader for neuralynx files

[eduardosand]

Describe the bug
When loading in a neuralynx file that had several starts and stops in recording (therefore missing data), the events in Events.nev and global start are relative to the most recent starting recording as opposed to the first sample of the file. Then when using event_reader.rescale_event_timestamp(timestamps), inappropriate timestamps are returned as a result.

To Reproduce

event_reader = NeuralynxRawIO(dirname=stems[0], include_filenames=event_path)
event_reader.parse_header()
ph_reader = NeuralynxRawIO(dirname=stems[0], include_filenames=ph_path)
ph_reader.parse_header()
global_start = ph_reader.global_t_start
global_start_ev = event_reader.global_t_start
print(global_start == global_start_ev) #Returns False if the recording itself had many stops and missing data
event_timestamps, _, event_labels = event_reader.get_event_timestamps()
event_times = event_reader.rescale_event_timestamp(event_timestamps)
event_times_manual = event_timestamps*10**-6 - global_start
print(event_times==event_times_manual) # prints False if the recording has many stops and it's not reflected as an event

Expected behaviour
I expect the rescale event timestamp method on event reader to return the timestamp in seconds relative to the first sample of the entire fire. Instead, the timestamps are returned relative to the most recent 'starting recording' event which doesn't always pop up in the event_reader events, despite in showing up when I open the file in other contexts. Essentially, the global_start for events.nev doesn't match the global start for photo.ncs or other .ncs files that were recorded simultaneously.

Environment:

• OS: Windows, and tested on Linux
• Python version: 3.11.3
• Neo version: 0.13.4

Additional context
I'm only writing this so that others who are analyzing neuralynx data are aware of this potential issue. For now, I recommend avoiding the use of event_reader.rescale_event_timestamp(event_timestamps) and loading in a recording from the dataset to get global_start if needed. It'll take slightly longer but worth it. After getting global_start from a file, you can manually convert the event_timestamps with

rescaled_event_timestamps = event_timestamps*10**-6 - global_start

[zm711]

Thanks @eduardosand. This has been a big struggle with neuralynx (and other ios) that have pauses and skips. Maybe @samuelgarcia or @PeterNSteinmetz have opinions on this since they know this IO much more than I do.

[PeterNSteinmetz]

@eduardosand Can you try it using the keep_original_times=True argument in the constructor?

If that doesn't work, it would be useful to have a set of test files to see exactly what is happening.

I notice that the two constructor calls appear to have different include_filenames. Without the keep_original_times, the first time in the file(s) provided is subtracted from all times being returned.

[eduardosand]

Yes, so that's what I mean. From the same dataset, but from different files (events.nev and photo.ncs(or any other file)), the global_t_start are different. The event labels then, rescaled or not, are in this case about 9000 seconds off, I think because of the start and stop. The global_t_start are correct in the other signals in this dataset to the photo.ncs, but not events.nev. Event reader doesn't show starting and stopping recording, but I saw it when looking at the events.nev file in a text editor.

I know the event label times are inappropriate because I'm using ephy_viewer to comb through my photodiode signal to separate out different tasks in the same file and noticed the event labels were offset by 9000, but relative to each other are correct (event 1 and event 2 are roughly 1000 seconds apart, the labels were correct when recording).

Here are two files that should demonstrate the mismatch, but I found this in a few more cases.
https://drive.google.com/drive/folders/17JAKAyIKZUhpi08s0Ztg_L-HM4nGvVeA?usp=sharing

With keep_original_times, the first time is 0, but the events are still in machine time. Then when rescaling the event times, they don't change. I need them in seconds from start of recording, so unfortunately, this doesn't work.

[PeterNSteinmetz]

@eduardosand Those files are in a protected DropBox. I just requested access so you should see that.

Please also note that the timestamps between two instances of NeuralynxRawIO will not agree unless both use the keep_original_timestamps=True option. For this RawIO, timestamps are in microseconds until the rescale_ method is called, then they should be in seconds and in floating point format.

When keep_original_timestamps=True, the global_t_start should always be 0.

In any case, once I have access to the test files, I will have a further look.

[eduardosand]

@PeterNSteinmetz So I noticed that in general the global_t_start agrees across NeuralynxRawIO if they're streams (.ncs files), but occasionally the global_t_start of a .nev file is the one that disagrees(hence the issue here), when using keep_original_times=False.

Might be a bug, but after using keep_original_timestamps=True, and running

event_timestamps, _, event_labels = event_reader.get_event_timestamps()
event_times = event_reader.rescale_event_timestamp(event_timestamps)
print(event_timestamps == event_times)

I found that this printed out true, suggesting rescale_event_timestamp didn't rescale my times. My understanding of the rescale_event_timestamp method, is it does the computation I suggested in the original post, namely
rescaled_event_timestamps = event_timestamps*10**-6 - global_start

But, since global_start would be 0 if keep_original_times=True, then rescaling doesn't change anything. As a result, the event_times fail to be meaningful.

I granted you access to the files.

[PeterNSteinmetz]

@eduardosand Please see the code gist at https://gist.github.com/PeterNSteinmetz/0472b4a7fd75749922a5c76d2b0d4c6f. It should run without a failed assertion for your test files.

I believe the trouble you are experiencing may be related to not having specified a event_channel_index in the get_event_timestamps method call which then defaults to 0. If this does not resolve your issue, can you please add some assertions to the code snippet which are failing and which illustrate the problem you are seeing?

This has unearthed another bug, which I think is unrelated to you issue. Thus can we have your permission to use this .nev file in the testing data repository? Is it human subjects data by any chance? If so, do we need to anonymize it in some way.

[PeterNSteinmetz]

@eduardosand On further thought, I wonder if the apparent discrepancy may be due to the use of ephyviewer when looking at the signal in photo1_0012.ncs. I believe it may ignore the gaps and breaks in recording and present all samples as one contiguous time block, even when that is not the case.

There are 4942 segments in this file and apparently some very large gaps. Also see the strict_gap_mode setting which is True by default. Though I think even with that set false you will still have more than one segment with large gaps and that may cause this apparent discrepancy.

[eduardosand]

@PeterNSteinmetz Thanks for looking into this. I actually process the data into a numpy array ahead of using ephyviewer. I deal with gaps by interpolating across them (in between segments I compute the difference between the timestamp of the last sample of the first segment and the first sample of the first segment). That's actually part of the reason I noticed this discrepancy. I have it print out when there are large sections without samples and noticed that if I took that time to be 0, then the events labels did have the correct time, suggesting that that time was being mistaken as global_t_start. I understand that in general the global_t_starts won't match (in cases where this issue doesn't pop up it seems like the difference is less than a millisecond) but here the difference is on the order of 9000 seconds.

[PeterNSteinmetz]

@eduardosand That seems like a good way to handle the issue of multiple segments. If you try the strict_gap_mode=False flag it might reduce the number of segments you are dealing with.

So what you are noticing may be related to what I noted in Issue #1598 . Could you add some assertions to the gist I linked above that show exactly what you are concerned about? That will help me determine if this is the same issue and then try and resolve it.

I understand you have a workaround presently, is that correct?