diff --git a/README.md b/README.md index 49af894..df9eb1c 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ pip install pygpla ### From source ```bash -git clone https://github.com/CMC-lab/PyGPLA.git +git clone https://github.com/CMC-unit/PyGPLA.git cd PyGPLA pip install -e . ``` diff --git a/docs/contributing.md b/docs/contributing.md index a8a47b2..92671ee 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -43,7 +43,7 @@ If it’s a larger change, opening an issue first is usually better than startin ### Clone + environment ```bash -git clone https://github.com/CMC-lab/PyGPLA.git +git clone https://github.com/CMC-unit/PyGPLA.git cd PyGPLA python -m venv .venv source .venv/bin/activate diff --git a/docs/installation.md b/docs/installation.md index 408ce16..ec6df78 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -42,7 +42,7 @@ pip install pygpla ### From source ```bash -git clone https://github.com/CMC-lab/PyGPLA.git +git clone https://github.com/CMC-unit/PyGPLA.git cd PyGPLA pip install -e . ``` diff --git a/paper/package_organization_revised.md b/paper/package_organization_revised.md new file mode 100644 index 0000000..ea3846f --- /dev/null +++ b/paper/package_organization_revised.md @@ -0,0 +1,7 @@ +# Package organization + +PyGPLA follows a function-oriented, layered design that mirrors the GPLA workflow, from preparation of the input data to statistical assessment. The main entry point is the high-level `pygpla.api.gpla` function, which coordinates preprocessing, coupling estimation, singular-value decomposition, and optional significance testing in one call. This keeps the default workflow compact while preserving access to lower-level components for advanced analyses, methodological modifications, and extensions. + +Core numerical routines are separated by responsibility. The `pygpla.preprocessing` module handles trial concatenation, temporal and unit selection, spike-count filtering, optional LFP normalization, and the invocation of optional whitening. The `pygpla.core` package implements whitening, coupling-matrix construction, and singular-value decomposition, including post-processing operations such as phase alignment, spike-vector normalization, and unwhitening-aware handling of LFP vectors. Statistical procedures are collected in `pygpla.stats`, which provides surrogate-based testing using multiple spike-jittering schemes [e.g., @grun2009data] and an analytical test based on the Marchenko--Pastur random-matrix-theory threshold [@safaviUnivariateMultivariateCoupling2021]. + +To support reproducibility and method validation, PyGPLA includes dedicated simulation utilities in `pygpla.simulations`. These include homogeneous and inhomogeneous Poisson generators, phase-locked spike simulations, and a transient-coupling simulator that generates paired spike and LFP signals. The repository additionally provides a figure-reproduction and visualization script and an automated test suite for validating individual numerical components and end-to-end behavior. Finally, the configuration dataclasses in `pygpla.config` provide structured parameter containers for preprocessing, whitening, and statistical testing. diff --git a/paper/package_organization_revised.tex b/paper/package_organization_revised.tex new file mode 100644 index 0000000..ac15ef7 --- /dev/null +++ b/paper/package_organization_revised.tex @@ -0,0 +1,30 @@ +\subsection{Package organization} + +PyGPLA follows a function-oriented, layered design that mirrors the GPLA workflow, +from preparation of the input data to statistical assessment. The main entry point is +the high-level \texttt{pygpla.api.gpla} function, which coordinates preprocessing, +coupling estimation, singular-value decomposition, and optional significance testing +in one call. This keeps the default workflow compact while preserving access to +lower-level components for advanced analyses, methodological modifications, and +extensions. + +Core numerical routines are separated by responsibility. The +\texttt{pygpla.preprocessing} module handles trial concatenation, temporal and unit +selection, spike-count filtering, optional LFP normalization, and the invocation of +optional whitening. The \texttt{pygpla.core} package implements whitening, +coupling-matrix construction, and singular-value decomposition, including +post-processing operations such as phase alignment, spike-vector normalization, and +unwhitening-aware handling of LFP vectors. Statistical procedures are collected in +\texttt{pygpla.stats}, which provides surrogate-based testing using multiple +spike-jittering schemes \citep[e.g., multiple jittering schemes; also, see][]{grun2009data} +and an analytical test based on the Marchenko--Pastur random matrix theory threshold +\citep{safaviUnivariateMultivariateCoupling2021}. + +To support reproducibility and method validation, PyGPLA includes dedicated simulation +utilities in \texttt{pygpla.simulations}. These include homogeneous and inhomogeneous +Poisson generators, phase-locked spike simulations, and a transient-coupling simulator +that generates paired spike and LFP signals. The repository additionally provides a +figure-reproduction and visualization script and an automated test suite for validating +individual numerical components and end-to-end behavior. Finally, the configuration +dataclasses in \texttt{pygpla.config} provide structured parameter containers for +preprocessing, whitening, and statistical testing. diff --git a/paper/paper.md b/paper/paper.md index 2041b41..459cf0d 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -36,7 +36,7 @@ affiliations: date: "22 March 2026" bibliography: paper.bib -repository: "https://github.com/CMC-lab/PyGPLA" +repository: "https://github.com/CMC-unit/PyGPLA" crossref: true url: "https://pygpla.readthedocs.io/en/latest/" @@ -46,7 +46,6 @@ url: "https://pygpla.readthedocs.io/en/latest/" PyGPLA is a Python implementation of Generalized Phase Locking Analysis (GPLA) for multivariate analysis of coupling between spikes and local field potentials (LFPs) [@safavi2023uncovering]. For a given frequency, GPLA constructs a complex coupling matrix $\hat{C}(f) \in \mathbb{C}^{N_c \times N_u}$ between LFP channels ($N_c$) and spike units ($N_u$), then applies singular value decomposition (SVD) to reduce the dimensionality of data. The leading singular value summarizes population-level coupling strength, while the corresponding singular vectors describe dominant LFP and spike coupling modes. PyGPLA accepts a user-provided frequency-specific analytic LFP signal or phase representation and provides data selection, optional whitening and normalization, coupling-matrix construction, SVD-based decomposition, and statistical significance testing [@safavi2021univariate]. - ## Statement of need Neural recordings are becoming increasingly high-dimensional and multimodal, demanding more sophisticated analysis tools. Simultaneous analysis of spiking activity and LFPs is among the most informative multi-modal approaches in systems neuroscience, providing insight into the multi-scale mechanisms underlying cognitive functions such as attention and memory [@buzsaki2012origin; @einevoll2013modelling; @herreras2016local]. LFP oscillatory activity partly reflects subthreshold processes shared by neuronal ensembles, and the synchronization between this activity and spiking is hypothesized to coordinate neural populations during cognitive processes [@buzsaki2012origin; @hagen2016hybrid]. @@ -100,11 +99,29 @@ The GPLA methodology has been evaluated in published simulations, biophysical ne ## AI usage disclosure -Generative AI tools were used only to assist with drafting documentation and -refactoring code for style. All AI-assisted output was reviewed, tested, and -validated by the authors, who take full responsibility for the correctness of the -software and the content of this paper. The scientific method, algorithmic design, -and numerical implementation of GPLA were carried out by the authors. +Over the course of PyGPLA’s development, the authors used OpenAI GPT-family +models through ChatGPT and OpenAI Codex, including models from the GPT-5 +family. This assistance occurred over an extended period during which the +available models were updated; consequently, exact model snapshots and version +identifiers were not recorded for every interaction. + +The models were used to assist with porting selected MATLAB scripts to Python, +refactoring code, drafting and restructuring documentation, and conducting +language editing and grammatical review of the manuscript. AI-generated outputs +were treated as preliminary suggestions rather than authoritative +implementations. + +All AI-assisted code and text were reviewed and edited by the authors. +Translated code was reviewed against the original MATLAB implementation and +the published mathematical description of GPLA. Its behavior was evaluated +through tests, reproducible simulations, and manual inspection. As an +additional human-led validation step, the authors reproduced Figure 2 from the +original GPLA publication using PyGPLA and compared the resulting coupling +patterns with the published results, providing a further check of the ported +implementation. The authors made the scientific, architectural, and +methodological decisions and take full responsibility for the accuracy, +originality, licensing, and integrity of the software, documentation, and +paper. ## Acknowledgments diff --git a/pyproject.toml b/pyproject.toml index ddbaf37..c835dab 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -47,8 +47,8 @@ figures = [ ] [project.urls] -Repository = "https://github.com/CMC-lab/PyGPLA" -Documentation = "https://github.com/CMC-lab/PyGPLA#readme" +Repository = "https://github.com/CMC-unit/PyGPLA" +Documentation = "https://github.com/CMC-unit/PyGPLA#readme" [tool.hatch.version] path = "src/pygpla/_version.py"