{"id":19252261,"url":"https://github.com/sccn/pact","last_synced_at":"2025-07-17T17:33:13.529Z","repository":{"id":150759805,"uuid":"225724991","full_name":"sccn/PACT","owner":"sccn","description":null,"archived":false,"fork":false,"pushed_at":"2025-01-31T17:19:00.000Z","size":2897,"stargazers_count":3,"open_issues_count":4,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-06-06T06:35:28.583Z","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,"zenodo":null}},"created_at":"2019-12-03T21:58:08.000Z","updated_at":"2025-01-31T17:19:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"914522c8-48e7-4844-ae44-5e30fbb71ee0","html_url":"https://github.com/sccn/PACT","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sccn/PACT","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sccn%2FPACT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sccn%2FPACT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sccn%2FPACT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sccn%2FPACT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sccn","download_url":"https://codeload.github.com/sccn/PACT/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sccn%2FPACT/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265636858,"owners_count":23802575,"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:10.106Z","updated_at":"2025-07-17T17:33:13.481Z","avatar_url":"https://github.com/sccn.png","language":"MATLAB","funding_links":[],"categories":[],"sub_categories":[],"readme":"What is PACT?\n-------------\n\nPACT is a plug-in for EEGLAB. PACT stands for (cross-frequency)\nPhase-Amplitude Coupling Toolbox. See the github repository at\n[\u003chttps://github.com/sccn/PACT\u003e](https://github.com/sccn/PACT) to submit\nbug reports or modify the codebase.\n\nWhat data does PACT take?\n-------------------------\n\nPACT was initially developed for analyzing electrocorticographic (ECoG) data. The\napplicability of using PACT on scalp-recorded EEG relies on the manner in which\nhighest-amplitude sampling (HAS) is utilized. For more information, please refer\nto the next section. The current version of PACT supports event-related data analysis.\n\nWhat is high-frequency oscillation (HFO) and highest-amplitude sampling (HAS)?\n-------------------------\n\nIn the field of epileptology, it is well-established that ECoG data reveals the\npresence of transient bursts with high amplitude, which are associated with\nepileptogenesis. These bursts are commonly referred to as high-frequency\noscillations (HFOs). Various algorithms have been developed to detect HFOs.\nHowever, some neurologists realized that HFO's sensitivity was limited. So they\nconsidered that pathological HFO may show characteristic coupling with low-frequency\nphase. Thus, they hypothesized that detecting HFOs then evaluating their PAC patterns\nshould improve sensitivity. This is the basic motivation of PACT that can quantify\nPAC of HFOs. Thus, the PACT first identifies potential HFO candidates by applying a\nstraightforward amplitude threshold. Afterward, PAC is computed using only the selected\ndata points. When HAS is set to 100%, it calculates the original Canolty's modulation\nindex (MI).\n\nCan we apply PACT on scalp-recorded EEG data (HAS)?\n-------------------------\n\nThe simple answer is yes, as long as you are knowledgeable about the process.\n\nThe more detailed answer is that it depends on how you process data. One key\ndifference between ECoG and scalp-recorded EEG is that the latter is prone to\ncontamination from artifacts such as blinks, eye movements, muscle potentials,\nand line noise at frequencies like 50Hz or 60Hz. Some of these artifacts have\na dominant power distribution in higher frequency ranges, including beta and gamma.\n\nTo effectively apply PACT to scalp-recorded EEG data, it is recommended to select\ndata with minimal artifacts. For instance, blinks often produce phase-amplitude\ncoupled artifacts. Users should be familiar with the basic qualities of signals\nand artifacts, and exercise caution when using PACT. Additionally, it is advised\nto systematically vary HAS values to observe how it affects the results.\n\nAlways remember that while selecting high-amplitudes is effective for identifying\nHFOs in ECoG, it also introduces potential bias towards different types of artifacts\nin scalp-recorded EEG data.\n\nIs there an example paper that applied PACT on scalp-recorded EEG?\n-------------------------\n\nMiyakoshi M, Nariai H, Rajaraman RR, Bernardo D, Shrey DW, Lopour BA, Sim MS, Staba RJ, Hussain SA. (2021).\nAutomated preprocessing and phase-amplitude coupling analysis of scalp EEG discriminates infantile spasms from controls during wakefulness.\nEpilepsy Res. 178:106809.\n\nIn this paper, HAS of 2% is used. The relevant description in the method section is cited below.\n\n\u003e Data points with gamma amplitude larger than the 98th percentile were marked as high amplitude samples (HAS)\n\nHowever, this does not mean 2% is the generally recommended value for all the applications.\nIt serves one of the potential anchor points which showed successful results. I recommend we stick to\nfamiliar values like 5% (0.05), 1% (0.01), etc. that are widely accepted values in the application\nof inferential statistics. As you parametrically change the HAS values from small to large values,\nyou might find non-linear responses. You should determine what you are sensing there, whether\nit is an artifact (blinks, saccades, etc.) or brain signals (genuine HFO-PAC in the EEG signals).\n\n\nWhat does PACT do?\n------------------\n\nIn preparatory exploration, you may run a brute-force computation of PAC\nfor all combinations of low-frequency oscillation (LFO) and\nhighest-amplitude sampling (HAS) center frequencies. This computation\nmay take a long time depending on the frequency resolution and bandwidth\nyou specify. To compute each PAC value for a channel\nfrequency-by-frequency combination, PACT performs the following steps:\n\n1\\. Band-pass filter the data to extract HFO and LFO signals.\n\n2\\. Hilbert transform the HFO signal to extract a time series of\ninstantaneous amplitudes.\n\n3\\. Hilbert transform the LFO signal to extract a time series of\ninstantaneous phases.\n\n4\\. (Highest-Amplitude Sampling, HAS): apply a threshold to select the\nN% highest HFO amplitudes. Obtain the HAS index from this.\n\n5\\. For LFO phase, apply HAS index.\n\n6\\. Combine HAS-indexed HFO and LFO indices into complex-valued phasors.\n\n7\\. Compute the Modulation Index (Canotly et al., 2006) for the\ncollection of HAS phasors constructed above.\n\n8\\. Generate a collection of surrogate data by circularly permuting the\nphase time-series relative to the amplitude series.\n\n9\\. Compute a surrogate set of Modulation Indices for which the null\nhypothesis should hold and determine a statistical threshold from their\ndistribution.\n\n10\\. Perform multiple comparison corrections based on the number of\nchannels for which you are estimating PAC significance.\n\nNote: To compute and perform statistics on the Mean Resultant Vector\nLength, PACT uses CircStat (Berens, 2009). To compute phase-sorted\namplitude statistics, PACT uses K-S and Chi-square tests.\n\nWhat do the PACT GUIs look like?\n--------------------------------\n\n![thumb\\|400px\\|Figure 1. PACT Seen from EEGLAB main\nGUI.](images/Demo01.jpg)\n\n\u003ci\u003e\u003cp style=\"text-align: center\"\u003eFigure 1. PACT Seen from EEGLAB main GUI.\u003c/p\u003e\u003c/i\u003e\n\n![thumb\\|400px\\|Figure 2. Main\nGUI.](images/Demo02.jpg)\n\n\u003ci\u003e\u003cp style=\"text-align: center\"\u003eFigure 2. Main GUI\u003c/p\u003e\u003c/i\u003e \n\nWhen successfully installed, the item\n'PACT' should appear under 'Tools' (Figure 1). Currently it has 12\nmenus.\n\n-   Compute PAC: This launches the main GUI (Figure 2). When press ok,\n    computation starts. When it done, statistics set up window pops up\n    (described later).\n    -   Phase freq range \\[lohz hihz\\]\n    -   Amp freq range \\[lohz hihz\\]\n    -   Highest amplitude sampling rate \\[%\\]\n    -   Sampling pool: This is for the experimental purpose. Always\n        choose 'Each channel'.\n    -   If handpicked, event type and win size \\[+/- ms\\]: If you want\n        to run the analysis using the data around event markers\n        generated by either VidEd or MoBILAB, use this.\n    -   Significance threshold \\[p\\]\n    -   Number of surrogation \\[N\\]: This determines how many data\n        points you want to generate surrogate data that represents for\n        distribution of null hypothesis.\n    -   Number of phase bins \\[N\\]: This affects sensitivity of circular\n        statistics. Don't use too extremely large value (e.g. \\\u003e100).\n\n\u003cimg src=\"images/Demo06.jpg\" alt=\"Figure 3. Detected HFOs (shown in\nred).\" width=\"600\" /\u003e\n\n\u003ci\u003e\u003cp style=\"text-align: center\"\u003eFigure 3. Detected HFOs (shown in red)\u003c/p\u003e\u003c/i\u003e \n\n-   Plot HFO-marked Raw data: This plot looks like Figure 3.\n-   Invert polarity: This is to invert EEG polarity by simply\n    multiplying -1 to all the data.\n\n\n\n**The function described in the following section is depricated (works only in Matlab 2013 or older)**\n\u003cimg src=\"images/Demo04.jpg\" alt=\"Figure 4. Manually marking HFOs. Left, using VisEd.\nRight, using customized MoBILAB plots.\" width=\"800\" /\u003e\n\n\u003ci\u003e\u003cp style=\"text-align: center\"\u003eFigure 4. Manually marking HFOs. Left, using VisEd. Right, using customized MoBILAB plots\u003c/p\u003e\u003c/i\u003e \n\n-   ~~Handpick HFO(VisEd): This plot looks like Figure 4 left. You can~~\n    ~~choose the marking point by mouse click. For detailed explanation~~\n    ~~how to use this VisEd, see VisEd help.~~\n-   ~~Handpick HFO(Mobilab): This plot looks like Figure 4 left.~~\n    ~~Similarly, you can choose the marking point by mouse click. Use~~\n    ~~whichever suit you.~~\n-   ~~Copy event markers: This is to copy event markers from dataset 1 to dataset 2.~~\n\n![thumb\\|400px\\|Figure 5. Statistics set\nup.](images/Demo03.jpg)\n\n\u003ci\u003e\u003cp style=\"text-align: center\"\u003eFigure 5. Statistics set up\u003c/p\u003e\u003c/i\u003e \n\n-   Set up statistics: This shows a GUI that look like Figure 5.\n-   Plot Modulation Index: This shows a plot that look like Figure 7/8\n    top right.\n-   Plot Angular hist (bar)\n-   Plot Angular hist (polar): This shows a plot that look like Figure\n    7/8 bottom left.\n-   Plot phase-sorted amp: This shows a plot that look like Figure 7/8\n    bottom left. Each bar represents mean amplitude of each phase bin.\n\n![thumb\\|400px\\|Figure 6. Scanning parameter space consists of LFO phase\nfrequencies and HAS rates.](images/Demo05.jpg)\n\n\u003ci\u003e\u003cp style=\"text-align: center\"\u003eFigure 6. Scanning parameter space consists of LFO phase frequencies and HAS rates\u003c/p\u003e\u003c/i\u003e \n\n-   Scan LFO freqs (very slow!): This pops up GUI like Figure 6. Start\n    with N = 10 or around, and HAS rate of 0.3-10. Color normalization\n    should be used when plotting Mean Resultant Vector Length.\n\nWhat plots does PACT output?\n----------------------------\n\n1\\. LFO-HAS parameter space scan results (combination of LFO phase\nfrequencies and HAS rates; the measure used may be either Mean Resultant\nVector Length or Modulation Index.\n\n2\\. Using Modulation Index with a confidence interval of 95% or 99%.\n\n3a. Angular histogram displayed in a polar plot using Mean Resultant\nVector Length.\n\n3b. Angular histogram in a rectangular plot with phase unwrapped on the\nx-axis.\n\n4\\. Bar graphs of LFO phase-sorted HFO-amplitudes.\n\n5\\. (When event-related PAC is selected) Time-domain phase-amplitude time\nseries. See below.\n\n\u003cimg src=\"images/PactERP.jpg\" alt=\"Time-domain event-related PAC\" width=\"400\" /\u003e\n\nNote that the number of phase bins in Figures 3a and 3b is determined by\nuser input and affects the results of the circular statistics.\n\nHow PACT can be used, and how its output can be interpreted: A demo example\n---------------------------------------------------------------------------\n\nThese plots show examples in which PACT was applied to\nelectrocorticographic data for which a neurologist judged the channel(\nCh) 1 signal to be pathological and the Ch2 signal to be normal.\n\nFirst, exploratory LFO frequency scans were performed (Figures 7 and 8,\ntop left; they are the same). We needed to run PACT several times,\nadjusting parameters; the result that showed the difference most clearly\nis plotted here. Mean Resultant Vector Length was chosen as the\ndependent variable, since it is naturally normalized from 0 to 1 and is\ntherefore convenient for comparisons across channels. This plot shows\ntwo noticeable clusters of interest that showed differences between Ch1\nand Ch2:.One is (LFO 0.5 Hz, HAS 3%,) the other (LFO 1.5 Hz, HAS 1.5%).\nWe decided to run analysis for both combinations of parameters.\nStatistical significance level was set to 1% with Bonferroni-Holm\ncorrection (Note: here, since we have only 2 items to compare, B-H is\nthe same as Bonferroni).\n\n![](images/PACT05Hz.jpg)\n\n\u003ci\u003e\u003cp style=\"text-align: center\"\u003eFigure 7. LFO 0.5Hz, HAS 3%, p \u003c 0.01, CI 95%. Top left, LFO-HAS parameter space scan results. Top right, Modulation Index. Bottom left, Mean Resultant Vector Length. Bottom right, phase-sorted HFO amplitudes\u003c/p\u003e\u003c/i\u003e \n\nFigure 7 shows the result of choosing parameters (LFO0.5 Hz, HAS 3%). The Modulation Index\nfor Ch1 is larger than that for Ch2. Only the Ch1 value reached\nstatistical significance (Figure 7, top right; a horizontal bar in the\ngraph shows the 95% confidence interval). By Mean Resultant Vector\nlength, both channel signals exhibited showed phase concentrations,\nthough their preferred phases were different -- almost opposite (Figure\n7, bottom left). Phase-sorted HFO amplitude also indicated that Ch1 has\na preferred phase, and the Ch1 amplitude distribution over phase bins\ndeviates significantly from uniform, whereas Ch2 does not show this\neffect (Figure 7, bottom right). Note also the large difference in\namplitude scales.\n\n![](PACT15Hz.jpg) \u003ci\u003e\u003cp style=\"text-align: center\"\u003eFigure 8. LFO 1.5Hz, HAS 1.5%, p \u003c 0.01, CI 95%. Top right, Modulation Index. Bottom left, Mean Resultant Vector Length. Bottom right, Phase-sorted HFO amplitude. Note that the Ch1 Modulation Index is much larger than the confidence interval compared to Figure 7\u003c/p\u003e\u003c/i\u003e \n\nFigure 8 shows the result of\nchoosing the parameters (LFO 1.5 Hz, HAS 1.5%). Modulation Index, Mean\nResultant Vector length, and Phase-sorted HFO amplitude all showed\nsimilar properties to the results shown in Figure 7. However, note that\nthe Ch1 Modulation Index is much larger than its confidence interval\nlevel; probably this combination of parameters better fits the\npathological pattern in this channel signal.\n\nDownload Link\n-------------\n\n\u003chttp://sccn.ucsd.edu/wiki/Plugin_list_process\u003e\n\nCaution and Limitation\n----------------------\n\nThe 'Handpick HFO' menu does not work with newer Matlab versions, which\nno longer support the *graphics.cursorbar* object. To use this function,\nuse Matlab 2013 or older as a workaround.\n\nScanning Phase-frequency vs. HFO-frequency (07/24/2019 updated)\n---------------------------------------------------------------\n\nIn calculating phase-amplitude coupling, a typical problem is how to\ndetermine the target frequencies in both phase and amplitude. To perform\nit simply, in ver.0.30 I implemented a function to generate\nphase-amplitude frequency-by-frequency grid plot. If you need to reduce\nthe number of channel, do so by using EEGLAB GUI beforehand. Otherwise,\nthis frequency scan process does not need any preprocessing by PACT, it\ndoes the job itself. One extra parameter you have to choose is highest\namplitude sampling (HAS) rate, which specifies the right-tail cutoff for\nthe amplitude distribution for each channel. Note that this is only\npicking up the highest amplitude after high-frequency band-pass filter,\nso if there is artifact with high-frequency (or broadband), HAS will\npick it up. In this case, you would want to clean the data using EEGLAB\nfunction before performing this analysis.\n\nIn the example below, one can easily find that Ch21 showed the strongest\nPAC between 3-Hz phase and 80-Hz HFO amplitude, followed by Ch16. Ch18\nalso showed some PAC, but it coupled with 1.7 Hz instead of 3 Hz so this\ncould be something different. If one chooses mean vector length to show\ninstead of Canolty's modulation index (MI), it allows to evaluate the\nsame measure without the effect of HFO amplitude. The calculated values\nare stored under EEG.pacScan.\n\n![200px](images/PactUpdate1crop.jpg)\n\n![600px](images/PactUpdate2.jpg)\n\n### How to obtain mean HFO gamma amplitude\n\n1.  In the plot above, confirm that the peak PAC value is observed at\n    Ch21, phase 3.2-Hz, ampltiude 80-Hz.\n2.  Type 'EEG.pacScan' in the command line. Among the variables, find\n    'meanHfoAmp' This is mean HFO amplitude in microVolt. If you are not\n    sure about dimensions, see 'dataDimensions'. We know our channel and\n    freq-freq window of interest, which are 21, 3.2 Hz, 80 Hz,\n    respectively. Based on these parameters of interest, we obtain\n    indices for these parameters: 21 for the channel order, 7 for the\n    phase freq (see 'phaseFreqEdge'--3.2Hz is between the 7th and 8th\n    edges, so we select 7), and 1 for the HFO freq.\n3.  We enter EEG.pacScan.meanHfoAmp(21,7,1) in the command window. It\n    returned '35.0391' which mean the mean HFO amplitude during the\n    selected HFO frames was 35.0391 microVolt.\n\n![600px](images/PactUpdate3.jpg)\n\nBug report, request, comment\n----------------------------\n\nPlease post bugs and suggestions to the EEGLAB mailing list.\n\nReference\n---------\n\n\u003chttp://www.ncbi.nlm.nih.gov/pubmed/24110429\u003e Makoto Miyakoshi, Arnaud\nDelorme, Tim Mullen, Katsuaki Kojima, Scott Makeig, Eishi Asano.\n*Automated detection of cross-frequency coupling in the\nelectrocorticogram for clinical inspection.* Conf Proc IEEE Eng Med Biol\nSoc.2013.3282-3285.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsccn%2Fpact","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsccn%2Fpact","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsccn%2Fpact/lists"}