HyPyP Cookbook Sprint #5
Description
Title
HyPyP Cookbook Sprint: a community-driven onboarding kit (docs, tutorials, examples, and small feature fixes)
Leaders
- Rémy Ramadour // remy.ramadour.hsj@ssss.gouv.qc.ca // Discord: @ramdam79
- Patrice Fortin // patrice.fortin.hsj@ssss.gouv.qc.ca // Discord: @osokin
Collaborators
- Vincent Chamberland
- Nadine Mohamed
- Mariem Hafsia
- Saskia Helbling
- Anne Monnier
- Anaïs Rourre
Project Description
HyPyP is an open-source Python toolbox for hyperscanning and interpersonal brain/physiology synchrony analyses. The goal of this BrainHack project is to build a community-driven onboarding kit that makes HyPyP easier to learn, run, and extend—especially for newcomers.
Concretely, we will produce a Cookbook: a small set of well-documented, reproducible tutorials (notebooks), improved documentation, and contributor-friendly entry points (“good first issues”). This will help students, researchers, and engineers quickly go from “I installed HyPyP” to “I can run a complete synchrony workflow and understand what I’m doing,” while also making it easier for new contributors to participate.
As part of the Cookbook effort, we will also identify the main bottlenecks and roadblocks that create friction for newcomers (installation issues, unclear steps, common pitfalls) and either remove them when feasible or document clear solutions (troubleshooting/FAQ).
This is a high-impact, low-friction community effort: in only a few days, we can significantly reduce the barrier to entry for hyperscanning analyses and improve reproducibility. The project is designed to be inclusive: contributors can help through writing, reviewing, coding, testing, visualization, or pedagogy, at beginner/intermediate/advanced levels.
Bonus: if time allows, we’ll implement a small “quality-of-life” improvement (e.g., clearer API wrapper, tests, example dataset, or minor feature fix) so the event yields both documentation and code improvements.
Participants will:
- clone the repo, install dependencies, and run a “hello world” notebook,
- pick a task (tutorial writing, doc improvement, tests/CI, visualization, small feature),
- submit contributions via PRs using templates and “good first issues” labels.
We will provide a clear README, a beginner-friendly checklist, and a live coordination channel during the event.
Link to project repository/sources
https://github.com/ppsp-team/HyPyPCookbook
Goals for Brainhack Montreal
Milestone 1 — “Onboarding Kit” baseline (Day 1)
Deliverables
- A refreshed Quickstart in README: install, minimal example, expected output.
- A Cookbook skeleton: folder structure + table of contents.
- At least 5 “good first issues” ready to pick.
- A first pass “Friction log” (list of newcomer bottlenecks/roadblocks + proposed fixes or documentation links).
Beginner-friendly tasks
- Rewrite/install troubleshooting (macOS/Windows/Linux, conda/poetry/pip).
- Add a glossary page: key concepts + links.
- Report friction points while onboarding (what broke / what was unclear) and propose wording fixes.
Intermediate tasks
- Add a minimal simulated dataset and a script/notebook that runs end-to-end.
- Add CI smoke test: “import + run minimal pipeline”.
Milestone 2 — Tutorials that run end-to-end (Day 2)
Deliverables
- 2–3 runnable notebooks with expected outputs saved (figures/tables):
- Hello synchrony (simulated signals → compute synchrony metrics)
- EEG hyperscanning minimal (MNE preprocessing → HyPyP metrics)
- Stats & surrogates (permutation/surrogate testing + interpretation)
- Optional: a short notebook section or mini-notebook for common group stats (t-test / ANOVA) on synchrony outputs.
Beginner tasks
- Improve narrative: explanations, figures, “what to check if results look wrong”.
- Add docstrings / examples to 2–3 public functions.
Intermediate tasks
- Add unit tests for one tutorial pipeline (golden outputs / shape checks).
- Add a “common pitfalls” page (filtering, alignment, edge effects, leakage).
- Turn top friction items into fixes or documented solutions (FAQ / troubleshooting entries).
Advanced tasks
- Identify and fix one small “paper cut” in the API (naming, defaults, error messages).
- Optional: add a small feature/wrapper improving usability, with tests + docs.
Milestone 3 — Integration & demo-ready output (Day 3)
Deliverables
- A single BrainHack Demo Notebook that runs in <10 minutes.
- A short “How to contribute” page + contributor credit instructions.
- A short report: what was improved, what remains, next steps.
- A consolidated “Friction log” summary (top bottlenecks + resolutions / workarounds).
Quality bar
- Everything runs from a clean environment (fresh install) using the Quickstart.
- PRs merged, issues triaged, next milestones listed for after the event.
Skills
Beginner (no coding required)
- Technical writing / pedagogy: rewriting documentation, improving clarity, adding step-by-step explanations.
- Example tasks: improve the Quickstart, write a glossary, add a “common pitfalls” page.
- User testing / QA: installing HyPyP from scratch and reporting friction points.
- Example tasks: test installation on macOS/Windows/Linux, write an install checklist, propose fixes.
- Scientific curation: collecting references and mapping “concepts → HyPyP functions”.
- Example tasks: create a “recommended readings” page with short annotations.
Intermediate (Python)
- Jupyter notebooks & reproducibility: writing runnable tutorials with expected outputs (figures/tables).
- Example tasks: build “Hello synchrony” and “Stats & surrogates” notebooks.
- EEG basics / data handling: working with MNE objects, basic preprocessing, aligning multi-person recordings.
- Example tasks: minimal MNE → HyPyP pipeline notebook.
- Tooling: environments, dependency management, documentation structure.
- Example tasks: improve install instructions, add a minimal example dataset for tutorials.
Advanced (engineering / methods)
- Software engineering: unit tests, CI, refactoring, typing, code review.
- Example tasks: add tests for core functions, set up GitHub Actions smoke tests.
- Signal processing & statistics: surrogates/permutation tests, circular stats, leakage control.
- Example tasks: validate a tutorial pipeline statistically; document interpretation guidelines.
- Small feature fixes (optional): minor API/UX improvements that remove “paper cuts”.
- Example tasks: clearer error messages, input validation, small wrapper functions with tests.
Bonus (non-coding but very valuable)
- Visualization & communication: figures, diagrams, short demo slides.
- Project coordination: issue triage, labels, PR templates, maintaining a project board.
Tech stack
Core language & ecosystem
- Python 3.x
- HyPyP (main target project): hyperscanning / interpersonal synchrony toolbox
Scientific computing
- NumPy / SciPy: core numerical operations
- MNE-Python (for EEG-focused tutorials): data structures, basic preprocessing, examples
- Matplotlib (and/or existing HyPyP plotting utilities): figures for tutorials and demos
- (Optional, if already in HyPyP deps/workflow) Pandas for tidy tutorial outputs
Documentation & tutorials
- Jupyter Notebooks: executable tutorials (“Cookbook”)
- Markdown: README, Quickstart, glossary, troubleshooting, contributor docs
- (Optional, depending on current repo tooling) MkDocs or Sphinx for structured docs
Engineering & collaboration
- Git + GitHub: issues, pull requests, review workflow
- GitHub Actions (CI): smoke tests (import + run minimal pipeline), unit tests
- pytest: unit tests
- pre-commit (optional): formatting/lint checks
Onboarding documentation / Expectations
We will use a dedicated BrainHack branch for the sprint work, and provide clear contribution guidelines.
Planned onboarding assets (in the HyPyP repo):
- CONTRIBUTING.md (on the BrainHack branch):
- how to set up the environment
- how to run tests / notebooks
- coding style expectations (lightweight)
- how to open a PR, review process, and how we credit contributions
- BrainHack Sprint README section (or docs/brainhack.md):
- project goals and day-by-day plan
- “pick a task” menu (beginner → advanced)
- links to “good first issues”
- Issue labels + templates: good first issue, documentation, tutorial, tests, help wanted
How to join and start contributing (during the event)
- Join the project communication channel (link will be shared in the README).
- Clone the repo and check out the BrainHack branch.
- Run the Quickstart notebook/script to validate your setup.
- Pick an issue (or propose one), then open a PR early (even as draft) for feedback.
What will participants learn?
Beginner outcomes (no coding required)
- How hyperscanning / interpersonal synchrony projects are typically structured (data → preprocessing → synchrony metrics → stats → interpretation).
- How to read and improve open-source scientific documentation effectively (Quickstart, troubleshooting, glossary).
- How to contribute to a research software project via GitHub issues and pull requests (even for non-code contributions).
Intermediate outcomes (Python + notebooks)
- How to run a complete, reproducible HyPyP pipeline using notebooks.
- How to work with typical hyperscanning data structures (multi-person time series, alignment, basic preprocessing).
- How to generate clear figures and “expected outputs” that make analyses easier to verify and teach.
Advanced outcomes (engineering + methods)
- How to add unit tests and CI checks to scientific Python codebases without slowing research iteration.
- Best practices for reproducibility in computational neuroscience (minimal datasets, deterministic outputs, versioned tutorials).
- Deeper understanding of synchrony statistics (surrogates/permutations, circular measures, leakage pitfalls) and how to document interpretation.
Bonus outcomes (for everyone)
- Practical experience in collaborative open science: task breakdown, review, crediting contributions, and producing demo-ready outputs in a short sprint.
Data to use
We will provide a small dataset on Day 1 of the event to support reproducible tutorials and testing. The dataset will be shared via the project repository (or a linked public folder) and will be accompanied by a minimal “expected outputs” notebook so contributors can validate their setup quickly.
Credit to collaborators
We will credit contributions openly and consistently:
- All contributions will happen via GitHub issues and pull requests, so each contributor’s work is traceable.
- We will maintain a Contributors section in the project documentation (README or a dedicated page) listing names and contribution types (docs, tutorials, code, testing, review, coordination).
- Where appropriate, we will use the all-contributors format (or an equivalent simple table) to acknowledge non-code contributions equally (documentation, QA, design, project management).
- Contributors who actively participate during the event will be acknowledged in the final BrainHack wrap-up materials (demo/report), by name.
Image
Type
documentation
Project Maturity Status
1 - basic structure
Topic
other
Tools
MNE
Programming language
Python
Modalities
EEG
Git skills
1_commit_push
Anything else?
No response
Things to do after the project is submitted and ready to review.
- Short summary of your project pitch to present during the hackathon.