[Feature] pairwise phase consistency

[TRuikes]

Hi!
In our lab we are using 'pairwise phase consistency' as a metric to measure spike-LFP interactions. The conventional method 'Phase Locking Value' can give faulty output if there are few spikes, and PPC improves on this. (function as implemented by authors. In short you compute the phase of an lfp during spike times (spike_triggered_phase) and then compute the angular distance between each pair of phases.

The output for the function phase_analysis.spike_triggered_phase can be directly fed into this function. While PPC can also be used to compute synchony between two EEG/LFP signals, I think there are allready other (better) measures for this and we can leave it at this simple implementation for now.

It can be a nice addition, let me know if you want to add this and if so what you would like me to change/add. In addition I suggest a tutorial on 'spike-field' functionality of elephant, briefly describing basic LFP processing steps (filtering, hilbert transform) and possible metrics/functions (spike_triggered_phase, sta.spike_field_coherence, sta.spike_triggered_average (<-that's PLV)).

[pep8speaks]

Hello @TRuikes! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

• In the file elephant/phase_analysis.py:

Line 194:1: W293 blank line contains whitespace

Comment last updated at 2023-09-25 09:45:53 UTC

[coveralls]

coverage: 86.606% (-0.4%) from 86.983% when pulling a1ff672 on TRuikes:master into c3eb21f on NeuralEnsemble:master.

[dizcza]

Hi Thijs,
we're currently advancing phase statistics (see #385), and we do have PPC on the to-do list, thanks for bringing this!
We're also porting the documentation to the new BibTex citation documentation format, so I've updated your docs & reference in TRuikes#1. You can merge my PR here. I still don't see you in the authors list of Elephant!

The tests are missing. If you're lazy to write them, I can come up with something, though I'm not an expert in this field.

[TRuikes]

Allright, thanks for the quick response! I'll think of some tests (wasn't too lazy, just didn't want spend time before knowing if you were going to use it ;) ) and add myself to authors.

The authors made impoved versions of PPC (this one they call 'ppc0' and then there are two more, I think). Long story short, when computing PPC between pairs, they dont want to draw samples from the same trial (their full reasoning written here, due to spiking properties of a neuron). To compute this I'd have to give information on trial nr per phase. I think I'll add an optional keyword trial_ids whith same dimensions as phases with a number per trial. Then another keyword to select ppc0 or ppc1.

I'm going to work on this next week again (monday), so I'll push something around then.

[dizcza]

I think we don't need to multiply by 2. The matrix dot_prod is completely filled, so each pair 'i','j' is computed twice.

Yes, you're right, I didn't think of that.

Regarding your previous comment about ppc1, if you think that it could take much time or you're unsure how to implement this additional feature that potentially (!) improves the estimate, it's better to come up with another pull request that addresses the improvement after this PR is merged.

[dizcza]

Let me know when it's ready for review.

[TRuikes]

It's ready for review! I'm allready testing it on a (large) dataset and will let you know if something comes up.

[TRuikes]

If I'm supposed to do something please let me know

[dizcza]

I created a PR again TRuikes#2

There was a todo "handle nans". Nans can occur iff the sum is zero and n_trials=1. In such cases, nans are the valid output.

Once the PR is merged, I merge this.

[Moritz-Alexander-Kern]

Hi @TRuikes ,
thank you for your persistent and steady work on this project to contribute to elephant.

Since I am taking over this PR, I am unfortunately not familiar with all the details.
Looking at the previous comment, this PR already received an approving review.
From my perspective the next steps are the following: (please correct me if wrong)

• merge PR Fixed many small things about PPC0 TRuikes/elephant#2 (you are the only one with permissions to merge this PR on your fork)
• finish the review process (1 pending review, this might entail further changes)
• resolve possible conflicts with master (ask me, I am happy to do so)
• merge this PR

If there is anything blocking progress on this project, that I could help to solve, please let me know, I am happy to do my part.

Update

• merged current master into INM-6:pull/ppc0, see Fixed many small things about PPC0 TRuikes/elephant#2 .

[TRuikes]

Hi @Moritz-Alexander-Kern , happy to help.
I've merged the PR. Since I created the code I have extended it with 'ppc1' (same metric but excluded pairs from the same trials).
Should I add it to this PR/script? It is a minor extension from the existing code, but possibly you prefer to wrap this up first.

I talked to @rjurkus about this briefly, he mentioned there might be a need for more tests. I'm also happy to work on those, but that will be after september.

[Moritz-Alexander-Kern]

Hi @TRuikes ,
To keep the whole thing neatly organized, it seems to make sense to merge this as one PR.
So I suggest to continue on this after september, otherwise we would have to scatter the PPC1extension and additional tests across multiple PRs.
Nice work so far, looking forward to continue working on this with you.