Add documentation suite, license, and preprint citation

.gitignore

@@ -0,0 +1,93 @@
+# MATLAB
+*.asv
+*.m~
+*.mex*
+*.autosave
+
+# Results and Data directories (too large for git)
+Results/
+Dataset/
+*.mat
+*.nii
+*.nii.gz
+
+# Brainstorm database
+brainstorm_db/
+*brainstorm*/
+protocols/
+
+# FreeSurfer outputs
+subjects/
+fsaverage/
+
+# Temporary files
+*.tmp
+*.temp
+*.log
+*.swp
+*~
+.DS_Store
+Thumbs.db
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+*.egg-info/
+dist/
+build/
+
+# R
+.Rhistory
+.RData
+.Rproj.user
+
+# IDE
+.vscode/
+.idea/
+*.sublime-*
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Desktop.ini
+
+# Documentation builds
+_build/
+site/
+
+# Backup files
+*.bak
+*.backup
+
+# Large data files
+*.fif
+*.sqd
+*.con
+*.raw
+*.eve
+*.cov
+*.trans
+
+# Specific to this project - keep these patterns
+# But allow small example/test data if needed
+!example_data.mat
+
+# Logs and reports
+*.pdf
+*.png
+*.jpg
+*.jpeg
+*.svg
+# But keep documentation images
+!docs/*.png
+!docs/*.jpg
+!docs/*.svg

CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+All notable changes to the AD_PAC project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive documentation suite
+  - Main README.md with project overview
+  - CITATION.md with preprint reference
+  - REQUIREMENTS.md with detailed dependency information
+  - QUICKSTART.md for rapid onboarding
+  - CONTRIBUTING.md with contribution guidelines
+  - Module-specific READMEs for each pipeline stage
+- LICENSE file (MIT License)
+- .gitignore for keeping repository clean
+- CHANGELOG.md for tracking changes
+
+### Changed
+- Initial documentation release
+
+### Deprecated
+- None
+
+### Removed
+- None
+
+### Fixed
+- None
+
+### Security
+- None
+
+## [1.0.0] - 2026-02-16
+
+### Added
+- Initial release of AD_PAC pipeline
+- Head modeling pipeline (anatomyTransform, buildHeadModels, processBSFiles, removeElec)
+- Preprocessing pipeline (preprocessing, interpolate_bad_channels, detect_bad_trials, plot_data)
+- Source reconstruction pipeline (sourceReconstruction_p, lcmv_meg, and helper functions)
+- PAC analysis pipeline (seedRoitoCortex, er_pac, er_pac_3, test_pac)
+- Statistical analysis pipeline (prepareTable, powerAnalysis, clusterBasedModel, linearMixedEffectsModel)
+- Python scripts for visualization (Fig_creator.py, cluster_based_perm.py)
+- Supporting data files (roi_name.mat, dk_labels.mat, cm17.mat, mask.mat)
+
+## Release Notes
+
+### Version 1.0.0 (2026-02-16)
+
+First public release of the AD_PAC pipeline. This version includes:
+
+**Features:**
+- Complete pipeline from raw MEG data to statistical analysis
+- Support for CTF MEG systems (275 channels)
+- Integration with FieldTrip, Brainstorm, and FreeSurfer
+- Cluster-based permutation testing
+- Linear mixed-effects modeling
+- Comprehensive documentation
+
+**Data:**
+- Compatible with data from OSF repository: https://osf.io/pd4h9/overview
+- Supports Desikan-Killiany cortical parcellation
+- Analyzes theta/alpha - low-gamma PAC
+
+**Requirements:**
+- MATLAB R2018b or later
+- FieldTrip toolbox
+- Brainstorm toolbox
+- FreeSurfer 6.0 or later
+
+**Known Limitations:**
+- Currently optimized for CTF MEG systems
+- Requires substantial computational resources
+- FreeSurfer preprocessing can take 6-24 hours per subject
+
+**Citation:**
+If you use this release, please cite:
+- Preprint: https://www.medrxiv.org/content/10.64898/2026.02.06.26345635v1
+
+---
+
+## Future Plans
+
+### Planned for Version 1.1.0
+- [ ] Support for additional MEG systems (Neuromag, KIT)
+- [ ] GPU acceleration for PAC computation
+- [ ] Additional PAC metrics (MI, MVL, GLM)
+- [ ] Automated quality control metrics
+- [ ] Example dataset for testing
+
+### Planned for Version 1.2.0
+- [ ] Web-based visualization interface
+- [ ] Batch processing utilities
+- [ ] Docker container for easier deployment
+- [ ] Integration with BIDS standard
+
+### Long-term Goals
+- [ ] Real-time PAC analysis capabilities
+- [ ] Machine learning classification features
+- [ ] Support for combined MEG/EEG analysis
+- [ ] Cloud computing integration
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.
+
+## Versioning
+
+We use [Semantic Versioning](https://semver.org/):
+- MAJOR version for incompatible API changes
+- MINOR version for new functionality in a backwards compatible manner
+- PATCH version for backwards compatible bug fixes
+
+## License
+
+This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.

CITATION.md

@@ -0,0 +1,105 @@
+# Citation
+
+## Primary Citation
+
+If you use this code or methodology in your research, please cite our preprint:
+
+**Preprint Paper:**
+- **URL**: [https://www.medrxiv.org/content/10.64898/2026.02.06.26345635v1](https://www.medrxiv.org/content/10.64898/2026.02.06.26345635v1)
+- **DOI**: 10.64898/2026.02.06.26345635
+
+### BibTeX Entry
+
+```bibtex
+@article{AD_PAC_2026,
+  title={Phase-Amplitude Coupling Analysis in Alzheimer's Disease},
+  author={[Authors to be filled from paper]},
+  journal={medRxiv},
+  year={2026},
+  doi={10.64898/2026.02.06.26345635},
+  url={https://www.medrxiv.org/content/10.64898/2026.02.06.26345635v1}
+}
+```
+
+## Additional Citations
+
+### PAC Method
+
+The PAC estimation code is based on the method developed by:
+
+Pellegrini, F., Delgado Saa, J., & Haufe, S. (2023). Identifying good practices for detecting inter-frequency coupling in resting-state EEG: A simulation study. *NeuroImage*, 277, 120233.
+
+```bibtex
+@article{pellegrini2023identifying,
+  title={Identifying good practices for detecting inter-frequency coupling in resting-state EEG: A simulation study},
+  author={Pellegrini, Franziska and Delgado Saa, Josefina and Haufe, Stefan},
+  journal={NeuroImage},
+  volume={277},
+  pages={120233},
+  year={2023},
+  publisher={Elsevier}
+}
+```
+
+**Code Repository**: [https://github.com/fpellegrini/PAC](https://github.com/fpellegrini/PAC)
+
+### Required Toolboxes
+
+If you use the toolboxes employed in this pipeline, please also cite:
+
+#### FieldTrip
+
+Oostenveld, R., Fries, P., Maris, E., & Schoffelen, J. M. (2011). FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data. *Computational Intelligence and Neuroscience*, 2011.
+
+```bibtex
+@article{oostenveld2011fieldtrip,
+  title={FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data},
+  author={Oostenveld, Robert and Fries, Pascal and Maris, Eric and Schoffelen, Jan-Mathijs},
+  journal={Computational Intelligence and Neuroscience},
+  volume={2011},
+  year={2011},
+  publisher={Hindawi}
+}
+```
+
+#### Brainstorm
+
+Tadel, F., Baillet, S., Mosher, J. C., Pantazis, D., & Leahy, R. M. (2011). Brainstorm: a user-friendly application for MEG/EEG analysis. *Computational Intelligence and Neuroscience*, 2011.
+
+```bibtex
+@article{tadel2011brainstorm,
+  title={Brainstorm: a user-friendly application for MEG/EEG analysis},
+  author={Tadel, Fran{\c{c}}ois and Baillet, Sylvain and Mosher, John C and Pantazis, Dimitrios and Leahy, Richard M},
+  journal={Computational Intelligence and Neuroscience},
+  volume={2011},
+  year={2011},
+  publisher={Hindawi}
+}
+```
+
+#### FreeSurfer
+
+Dale, A. M., Fischl, B., & Sereno, M. I. (1999). Cortical surface-based analysis: I. Segmentation and surface reconstruction. *NeuroImage*, 9(2), 179-194.
+
+```bibtex
+@article{dale1999cortical,
+  title={Cortical surface-based analysis: I. Segmentation and surface reconstruction},
+  author={Dale, Anders M and Fischl, Bruce and Sereno, Martin I},
+  journal={NeuroImage},
+  volume={9},
+  number={2},
+  pages={179--194},
+  year={1999},
+  publisher={Elsevier}
+}
+```
+
+## Data Availability
+
+The MEG and MRI data used in this study are available at:
+- **OSF Repository**: [https://osf.io/pd4h9/overview](https://osf.io/pd4h9/overview)
+
+## Software Availability
+
+The source code for this project is available at:
+- **GitHub Repository**: [https://github.com/braindatalab/AD_PAC](https://github.com/braindatalab/AD_PAC)