{"id":19252293,"url":"https://github.com/sccn/winpact","last_synced_at":"2025-04-21T13:30:52.324Z","repository":{"id":150759950,"uuid":"327716998","full_name":"sccn/winPACT","owner":"sccn","description":null,"archived":false,"fork":false,"pushed_at":"2021-01-15T19:40:47.000Z","size":696,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-01T13:38:10.967Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sccn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-07T20:24:02.000Z","updated_at":"2024-01-18T07:43:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"42afd33e-31ad-4cb4-b55e-d223327de61c","html_url":"https://github.com/sccn/winPACT","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sccn%2FwinPACT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sccn%2FwinPACT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sccn%2FwinPACT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sccn%2FwinPACT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sccn","download_url":"https://codeload.github.com/sccn/winPACT/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250064550,"owners_count":21368925,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T18:26:16.647Z","updated_at":"2025-04-21T13:30:52.318Z","avatar_url":"https://github.com/sccn.png","language":"MATLAB","funding_links":[],"categories":[],"sub_categories":[],"readme":"Introduction\n------------\n\nwinPACT() is a successor of [PACT\nplugin](https://sccn.ucsd.edu/wiki/PACT) for EEGLAB. Named after\napplying phase-amplitude coupling (PAC) using a sliding window so that\nit generates time-series of PAC measures. It supports Canolty and\ncolleagues' modulation index (MI), Özkurt and colleagues' normalized MI,\nand Tort and colleagues' Kullback-Leibler divergence. It comes with a\nPAC simulator based on Özkurt and Schnitzler (2011) and Kramer et al.\n(2008)\n\n### Caution\n\nThis application assumes users hopefully use \\\u003e 200 cycles of the center\nfrequency of the LFO (Tort et al., 2010). This means that if you want to\nanalyze amplitude coupling with 1-Hz phase, the sliding window size is\nhopefully \\\u003e 200 s! In the same way, 2 Hz for 100 s, 3 Hz for 66.6 s, 4\nHz for 50 s, etc. Using shorter window than this rule of thumb is not\nprohibited, but careful empirical test is needed. In the section below,\nI will show you how to perform it.\n\nOptimize parameters\n-------------------\n\nIn this (sliding) window PAC, the choice of window length is critical\nbecause a short window does not detect PAC well. As already mentioned,\nTort et al. (2011) mentioned that the number of cycles is hopefully \\\u003e\n200. However, as this is a very large number to blindly follow, you may\nwonder if there is a way to adjust the number of cycles with objective\ncriterion, such as sensitivity in SNR. In ECoG data, the targeted PAC is\nsometimes directly identifiable by eye. In such situation, having \\\u003e 200\ncycles maybe an overkill and you may end up with inappropriate side of\nthe trade off without knowing. This function allows you to test the\nlimit of SNR in detecting PAC with the specified window length. Some\nempirical evidence, obtained from using the PAC simulator and test\nfunctions implemented in this plugin, is shown at the bottom of this\npage.\n\nGenerate simulatd PAC data\n--------------------------\n\nIt adds +/-10% frequency jitter (by default; you can change it) to\nlow-frequency oscillation (LFO), and adds Hamming-windowed\nhigh-frequency oscillation (HFO) to the trough of the LFO with 1/4 pi\nradian phase jitter. Use can choose either pink (i.e., 1/f curve) or\nwhite (i.e., uniform distributed) noise with specified noise level. The\ngenerated simulation data are stored into EEG structure. Sampling rate\nis fixed to be 1000Hz. The type of data for each channels is as follows.\n\n`1ch: Simulated PAC data (LFO + HFO + Noise)`\n`2ch: LFO + Noise`\n`3ch: HFO + Noise`\n`4ch: Noise `\n\n![Simulate.png](images/Simulate.png)\n\nIn this example, 4x120000 (120 s) data will be generated, in which PAC\nwill be present between 300-420 s and 600-720 s. The SNR of the PAC part\nis -6dB.\n\nPrecompute PAC and data stored\n------------------------------\n\n-   The top box: According to amplitude modulation theory, it is\n    recommended that the LFO is low-pass filtered with the twice of the\n    target center frequency. In this simulation, the generated LFO is\n    centered at 3 Hz. Therefore, the band-pass filter of 1-6 Hz is\n    applied. Note that the values specified here refers to the pass-band\n    edge, in contrast to often-used cutoff frequency (-6dB). For the\n    difference of pass-band edge and cutoff frequency, see [this\n    page](https://sccn.ucsd.edu/wiki/Firfilt_FAQ#Q._What_are_passband.2C_stopband.2C_transition_band_width.2C_cutoff_frequency.2C_passband_ripple.2Fringing.2C_and_stopband_ripple.2Fattenuation.3F).\n-   The second box: the HFO should be band-pass filtered with at least\n    \\[HFO center freq\\] +/- \\[LFO center freq\\]. In the current example,\n    the LFO is only 3 Hz. The optimal bandwidth of 100 +/- 3 Hz cannot\n    be missed unless one designs inappropriately aggressive narrow band\n    filter.\n-   The third box: Next, (sliding) window width is determined. According\n    to Tort et al. (2010), \\\u003e 200 cycles of the center frequency of the\n    LFO is recommended.\n-   The fourth box: The number of surrogate data iteration should be\n    determined. Do not enter too large value here, otherwise your\n    computer may cause buffer overflow.\n-   The list box: You can choose a label of event if you want.\n-   The 'Load .xlsx' button: Alternatively, you can load Excel file that\n    has nx1 column vector of event onset latency (s).\n-   The edit box next to the 'Load .xlsx' button: Alternatively, you can\n    specify a number series with regular interval. The example here\n    shows '60-second sliding window sampled at 30, 60, 90, 120, ...,\n    1140, and 1170 s'. This means window overlaps 50%.\n-   As an option, you can save the output data into separate Excel files\n    for HFO, Modulation Index, uncorrecnormalized Modulation Index,\n    KLDivergence, amplitude distribution across phase bins (which has\n    dimensions of time + \\[(36 phase bins x number of channels) x time\\]\n    but the two dimensions inside the round bracket are collapsed), and\n    p-values (those that pass generalized family-wise error rate\n    correction is highlighted by x(-1)).\n\n![Precompute.png](images/Precompute.png)\n\nAfter calculation is done, data are stored under EEG.etc.winPACT. All\nthe items except for ampDistribAllChan has 1+\\[number of channels\\] x\n\\[time points\\]. \"1+\" represents time in second. The ampDistribAllChan\nhas time + \\[(36 phase bins x number of channels) x time\\] but the two\ndimensions inside the round bracket are collapsed.\n\nVisualize PAC\n-------------\n\nYou first choose the type of measure to plot, then enter the channel\nindex to plot. You can also use a slider to move the vertical dotted\nline to choose the data point to plot HFO amplitude distribution across\nphase bins (Note that two cycles of the phase bins are plotted). When I\nanalyzed simulated data with -6dB SNR, I obtained the following results.\nSubjectively, KLDivergence showed the clearest pattern as expected.\nAlthough I implemented generalized FWER correction, it tends to be\noverly conservative and does not show much significant results. This\ncould be explained by how the circular rotation is done on HFO in\ngenerating surrogate data (phase rotates, after all... probably more\nrotation does not mean more randomizing in this case, unfortunately).\n\n![Visualize.png](images/Visualize.png)\n\nNotes and Discussions\n---------------------\n\nI tried other SNR values, but after -6dB the results got rapidly worse.\nAlso, when I tested shorter windows, the results got worse.\n\nAppendix: Determining SNR limit for various window length\n---------------------------------------------------------\n\n### Background\n\nTort et al. (2011) mentioned that hopefully there are \\\u003e 200 cycles of\nLFO in the PAC window to assure reliable PAC detection. However, it is\nnot quantitatively tested yet.\n\n### Methods (04/11/2019 updated)\n\n1.  There were five conditions: Window lengths (60 s, 30 s, 15 s, 7.5 s,\n    and 3.75 s) which is equivalent to Cycle numbers (180, 90, 45, 22.5,\n    and 11.25)\n2.  Forty-window length of data were generated in the following way.\n3.  100-Hz HFO coupled with 3-Hz LFO was generated using the simulated\n    PAC generator of the current plugin.\n4.  One-hundred levels of pink noise, varying from -10 to 10 dB in SNR,\n    were generate and mixed with the synthesized PAC signal generated by\n    using the function proposed by Özkurt TE, Schnitzler A. (2011).\n5.  Data were prepared so that their first half was noise only, and the\n    second half was noise plus synthesized PAC.\n6.  PAC was quantified the three supported algorithms, namely Canolty's\n    Modulation Index, normalized Modulation Index, and KL Divergence.\n7.  After performing PAC quantification, two-sample t-test was performed\n    between noise only (20 windows) and noise plus PAC (20 windows).\n    Obtained t-scores were plotted, Also, the obtained uncorrected\n    p-values were corrected with FDR method within each condition and\n    measure.\n\n### Results\n\n![Canoltysmi60s.png](images/Canoltysmi60s.png)\n![Normmi60s.png](images/Normmi60s.png)\n![Kld60s.png](images/Kld60s.png)\n\n![Canoltysmi30s.png](images/Canoltysmi30s.png)\n![Normmi30s.png](images/Normmi30s.png)\n![Kld30s.png](images/Kld30s.png)\n\n![Canoltysmi15s.png](images/Canoltysmi15s.png)\n![Normmi15s.png](images/Normmi15s.png)\n![Kld15s.png](images/Kld15s.png)\n\n![Canoltysmi7_5s.png](images/Canoltysmi7_5s.png)\n![Normmi7_5s.png](images/Normmi7_5s.png)\n![Kld7_5s.png](images/Kld7_5s.png)\n\n![Canoltysmi3_75s.png](images/Canoltysmi3_75s.png)\n![Normmi3_75s.png](images/Normmi3_75s.png)\n![Kld3_75s.png](images/Kld3_75s.png)\n\n### Conclusion\n\nShortening the window length deteriorated the SNR limits. Using 22.5\ncycles still allowed PAC detection under -4dB SNR i.e., the signal power\nis only 40% of the noise power. Under the situation where the targeted\nPAC phenomenon is visually identifiable on raw ECoG signal, using 22.5\ncycles seems justifiable. Using 11.25 cycle should be avoided, the\nnormalized MI method failed to detect PAC.\n\nReferences\n----------\n\nCanolty RT, Ganguly K, Kennerley SW, Cadieu CF, Koepsell K, Wallis JD,\nCarmena JM. (2006). Proc Natl Acad Sci USA. 107:17356-17361.\n\nKramer MA, Tort AB, Kopell NJ. (2008). J Neurosci Methods. 170:352–7.\n\nÖzkurt TE, Schnitzler A. (2011). J Neurosci Methods. 201:438-443.\n\nTort AB, Komorowski R, Eichenbaum H, Kopell N. (2010). J Neurophysiol.\n104:1195-1210.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsccn%2Fwinpact","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsccn%2Fwinpact","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsccn%2Fwinpact/lists"}