Paper edit suggestions

[libertyh]

Thanks for providing this tool. I have a few suggestions for edits to the paper itself. Some of these suggestions are made perhaps because I myself don't typically use a photodiode to synchronize data (we use audio + a match filter instead), but I think overall this will be helpful for those contemplating using this type of setup and knowing that such a tool is available.

1. In the "Statement of Need" section, you mention that for your EMU recordings, "a photodiode placed on the monitor of the laptop was used to detect task-related luminance changes. The photodiode recordings were then digitized by the same clinical recording system which was used for the electrophysiology recordings." I'm not familiar with exactly how this is typically done. Do you mean that the photodiode itself is used as an additional channel in the preamplifier/headbox? Just adding a short sentence about how this is used with your system would be helpful.

2. If this is not appropriate for JOSS papers, feel free to ignore, but I felt the paper could have a brief statement of what general algorithm was used for event detection. On page 3, the authors say "This package has robust photodiode event-determination and photodiode to time-stamp alignment algorithms that are validated with both real and simulated photodiode data", and then go on to describe the possible differences in experimental setups. I think it would be helpful to add that this detects square-wave like deflections based on their width and a z-score threshold (or some other general description of the process). This helps me to know what the limitations might be and why some events may not be detected adequately.

3. Related to point 2, in Figure 3, the first row, third column says "no event found", but is this a false negative? Is this because of a short jump in the voltage that should have been ignored? I see in the legend this is discussed somewhat. Perhaps also a report on the total number of events expected and events detected could give the user an idea of the sensitivity/specificity of detection based on the parameters chosen.

[alexrockhill]

I'll incorporate the suggestions into the paper, thanks!

We had a redundant setup at first with audio as well and I think the fidelity is better (i.e. not having corrupted events) but for timing related to screen events I think the latency and uncertainty with the photodiode is better (for button or other events the audio is probably the same). Even with state-of-the-art setups and refresh rates, I noticed, especially working in vision research, that the monitor could hang a frame or more up to 5-10% of the time especially with older monitors and computers.

I was thinking of adding an audio match for the next release though because that is definitely widely used too.

[alexrockhill]

To answer your question about how we record the data, yes, the photodiode is plugged into the headstage/pre-amp through a gain modifier and bipolar referenced. You could try one channel with a common reference and you might be able to get away with it but we were having corrupted events even with the bipolar setup, although as you can see in the example recording the baseline noise was low, it was just there was a fair amount of drift and a lot of artifacts.

[alexrockhill]

Also for point 2 and 3 and why there was no event found for 98 (and this is related to example 2) the algorithm requires a square wave with a stretch of data greater than the zscore, and then an offset without any reonset. In this case, the algorithm rejected what could be considered an event because of the reonset. Example 2, that I just mentioned, shows getting the offset events, which would be complicated and I thought unideal if for every onset event you didn't have a corresponding offset event that was clean.

[libertyh]

To answer your question about how we record the data, yes, the photodiode is plugged into the headstage/pre-amp through a gain modifier and bipolar referenced. You could try one channel with a common reference and you might be able to get away with it but we were having corrupted events even with the bipolar setup, although as you can see in the example recording the baseline noise was low, it was just there was a fair amount of drift and a lot of artifacts.

Thanks! That helps -- if you want this to be adopted mostly by SEEG/ECoG people I could see this being a helpful detail, but I know photodiode event detection is widely used in other fields, so I'm also not sure whether this level of detail would be needed in the paper. Maybe it can go in the docs or somewhere instead, if anywhere.

[libertyh]

Also for point 2 and 3 and why there was no event found for 98 (and this is related to example 2) the algorithm requires a square wave with a stretch of data greater than the zscore, and then an offset without any reonset. In this case, the algorithm rejected what could be considered an event because of the reonset. Example 2, that I just mentioned, shows getting the offset events, which would be complicated and I thought unideal if for every onset event you didn't have a corresponding offset event that was clean.

That's a good point. I think like a lot of things then, it requires the user to look through the data to determine what works best for their particular application, and how many of those events they'd want to remove vs. retain.

[alexrockhill]

To answer your question about how we record the data, yes, the photodiode is plugged into the headstage/pre-amp through a gain modifier and bipolar referenced. You could try one channel with a common reference and you might be able to get away with it but we were having corrupted events even with the bipolar setup, although as you can see in the example recording the baseline noise was low, it was just there was a fair amount of drift and a lot of artifacts.

Thanks! That helps -- if you want this to be adopted mostly by SEEG/ECoG people I could see this being a helpful detail, but I know photodiode event detection is widely used in other fields, so I'm also not sure whether this level of detail would be needed in the paper. Maybe it can go in the docs or somewhere instead, if anywhere.

We were trying to strike a balance between being a tool for SEEG/ECoG researchers that meets all their needs particularly because that's where the motivation is coming from, but also anyone in electrophysiology or for whoever else uses a photodiode, there shouldn't be any reason why it wouldn't work in other situations.

[alexrockhill]

Also for point 2 and 3 and why there was no event found for 98 (and this is related to example 2) the algorithm requires a square wave with a stretch of data greater than the zscore, and then an offset without any reonset. In this case, the algorithm rejected what could be considered an event because of the reonset. Example 2, that I just mentioned, shows getting the offset events, which would be complicated and I thought unideal if for every onset event you didn't have a corresponding offset event that was clean.

That's a good point. I think like a lot of things then, it requires the user to look through the data to determine what works best for their particular application, and how many of those events they'd want to remove vs. retain.

Yeah events like those could be added back but I think this was some of the most corrupted photodiode data I've seen (shown in the example) and it still only lost ~3% of trials with the strictest time lag constraints (the 37 and 43 ms differences could easily have been kept). I think for most situations that's an acceptable loss and if you're having artifacts in the photodiode on a trial, that might be during the trial and so it might be a good trial to exclude just to be safe anyway.

The example data was collected with a photodiode fixed to the screen with adhesive and plastic supports but on a laptop on the participant's lap who moves around sometimes so I think that is pretty much the worst situation for photodiode artifact.

[alexrockhill]

I thought about what you said Liberty and I thought it could be helpful to add the ability to recover events that still look good. Here's the example I wrote https://alexrockhill.github.io/pd-parser/dev/auto_examples/plot_recover_events.html#sphx-glr-auto-examples-plot-recover-events-py.

Note that it's interactive (just pass/fail input for onset but you have to find the event manually for offset) so you have to run it to see that part.

[alexrockhill]

@libertyh, I added audio parsing capability as well and it was also very accurate. Thanks for bringing this up, I think it's a bit outside the name pd-parser but I think it's really useful and relies on the same core algorithms so hopefully people will still think to use pd-parser for audio. Here's the example: https://alexrockhill.github.io/pd-parser/dev/auto_examples/plot_find_audio_events.html#sphx-glr-auto-examples-plot-find-audio-events-py