Contributing

After building an initial draft of your experiment code and you wish to start testing it, collect all the files relative to your experiment into one directory, name your directory as the name of your experiment. The contribution will be submitted for review through github. If you already have a github account sign in to it, if not create a github account.

  • Fork the current repository to your account

  • On the created fork, create a new branch named with the feature you are developping or change you are making

  • Add the directory containing the files of your experiment under the experiments/psychopy or experiments/psychtoolbox according to which framework you are using.

  • Create a pull request from your branch to the main branch of the source repository (Not your fork, but the original repo)

  • Add any comments you want the reviewer to know of

  • A reviewer will review your code and either approve or ask for changes

  • If changes are needed, make the changes and push your new code to the same branch, your PR (Pull Request) will then get automatically updated

  • Consider adding a page describing your experiment to the docssource3-experimentdesignexperiments

  • Once your branch is merged to the main branch (meaning your experiment is approved), your code will be available in the MEG lab Stimulus computer

Building your processing pipeline

Do the same steps as before to fork the repository and create a new branch named as experiment_name-analysis Submit an initial notebook under docs/source/5-pipeline/notebooks or simply code file for your pipeline under pipelineexperiment_name

Contributing to this repository Overview

Your contribution, mistake correction, code contributions are very welcome. Contributions are made through pull reqests, please do the following steps:

  • Fork the current repository to your account

  • Create a new branch named with the feature you are developping or change you are making

  • Make the change on that branch

  • Create a pull request from this branch to the main brach

  • Ensure that all automated checks have passed

    • Many times the sphinx documentation build fails due to error in the syntax of your .rst files. To access the logfile, on your Pull Request, click the failing docs/readthedocs.org:neurowaves check to access the logfile and correct all Warnings/Errors.

  • Wait until your pull request is approved, or commented on

  • Address all comments until the PR is approved

  • Once the PR is merged to the main branch, delete your branch

Contributing to the documentation

Use the Sphinx-documentation cheat-sheet below to correctly syntax, explore and use capabilities of Sphinx-documentation.

Sphinx header templates

If you’d like to contribute to this documentation, please follow the heading-adornment conventions below:

Level

Overline & Underline

Underline only

Character

Document title

=============

N/A

=

Top-level section

-------------

N/A

-

Sub-section

N/A

^^^^^^^^

^

Sub-sub-section

N/A

""""""""

"

Fourth-level

N/A

~~~~~~~~

~

Fifth-level

N/A

++++++++

+

Adding a toctree within a page

To add a toctree with the content of your page, copy the following code at the beginning of your page contents:

.. contents::
   :local:
   :depth: 2

This will render as:

Making a Checklist

You can add simple task checklists to any page using the checklist directive.

Note

Checklists are clickable in HTML builds. In PDF/LaTeX they render as static boxes (□ / ☒). If your project includes the optional checklist.js, checkbox state is remembered per browser.

Prerequisites

  • The custom extension is enabled in conf.py (for example):

    extensions = [
    # ... other extensions ...
    'checklist',   # or '_checklist' if that’s your package name
]

Basic usage

Write one task per line inside the directive. Use [ ] for unchecked and [x] for checked.

.. checklist::

   - [ ] Write the introduction
   - [x] Add figures
   - [ ] Final proofreading

Result (HTML) “”————-“”

  • ☐ Write the introduction

  • ☑ Add figures

  • ☐ Final proofreading

Tips

  • Start each task with - [ ] or - [x] exactly (lowercase x).

  • Each task is plain text (no nested markup).

  • For sub-tasks, add another checklist block under a bullet or subsection.

Example with sections
Project TODOs
--------------

**Docs**

.. checklist::

   - [ ] API reference pass
   - [x] Tutorial outline

**Release**

.. checklist::

   - [ ] Changelog
   - [ ] Tag and publish

Setting up MATLAB Kernel for Jupyter

To run MATLAB code within Jupyter Notebooks, you need to set up the MATLAB kernel in your environment.

Prerequisites

  • Ensure you have MATLAB R2025b installed (required for Python 3.12+ compatibility).

  • Your conda environment should be using Python 3.12.

Installation Steps

  1. Activate your environment:

    conda activate neurowaves-lab-documentation

  2. Install Jupyter and the MATLAB Kernel:

    conda install notebook jupyter_client
pip install matlab_kernel

  3. Install the MATLAB Engine for Python: Navigate to your MATLAB installation folder (e.g., C:\Program Files\MATLAB\R2025b\extern\engines\python) and install the engine:

    cd "C:\Program Files\MATLAB\R2025b\extern\engines\python"
python -m pip install .

Using the Kernels

Two kernels will be available in Jupyter:

  • Matlab: Starts a new, independent MATLAB session for the notebook.

  • Matlab (Connection): Connects to an already running MATLAB instance, allowing you to share the workspace.

To use the Connection kernel:

  1. In your standalone MATLAB Command Window, run:

    matlab.engine.shareEngine

  2. In Jupyter, select the Matlab (Connection) kernel. You can now access variables from your standalone MATLAB session using commands like who or simply typing the variable name.

Thank you for your contribution!

Calendar Synchronisation Technical Setup

The MEG Lab uses a synchronization workflow to mirror bookings from the Corelabs (Booked) portal to a Google Calendar. This allows researchers to use Google Calendar features like “Appointment Schedules” to manage participant bookings while automatically respecting the lab’s availability.

Infrastructure Overview

The synchronization consists of three main components:

  1. Python Script: scripts/sync-gcal.py fetches the lab’s ICS feed, parses events, and upserts them into Google Calendar via the Google Calendar API.

  2. Google Cloud Project: A service account with “Editor” access to the specific Lab Google Calendar.

  3. GitHub Actions: A workflow .github/workflows/sync-gcal.yml that runs every 5 minutes on a self-hosted Windows workstation.

Google Cloud Platform Setup

To maintain or update the synchronization, you need access to the Google Cloud Project:

  1. Service Account: Create a service account in the GCP Console.

  2. API Key: Generate a JSON key for the service account and store it securely.

  3. Calendar Access: Share the target Google Calendar with the service account’s email (found in the JSON key) with Make changes to events permissions.

GitHub Repository Secrets

The following secrets must be configured in the GitHub repository (Settings > Secrets and variables > Actions):

  • GOOGLE_SA_JSON: The entire content of the service account JSON key file.

  • GOOGLE_CALENDAR_ID: The ID of the target Google Calendar.

  • BOOKED_ICS_URL: The private iCal subscription URL from Corelabs.

  • LOCAL_CONDA_PATH: (Optional) Path to the conda executable on the self-hosted runner.

  • LOCAL_CONDA_ENV_PATH: (Optional) Path to the conda environment to use (e.g., C:\Users\hz3752\anaconda3\envs\neurowaves-lab-documentation).

Self-Hosted Runner Configuration

The workflow is designed to run on a Windows runner (specifically the MEG workstation) to avoid dependencies on cloud-hosted runners and to leverage local environments.

Windows-specific tips: - The workflow uses pwsh (PowerShell Core) for robust command execution. - Environmental variables like CONDA_EXE and CONDA_ENV_PATH are used to invoke the correct Python environment without requiring a full conda init in every run, which prevents path recursion limits. - The service account JSON is dynamically created on the runner during each run using the GOOGLE_SA_JSON secret and deleted afterward.

Thank you for your contribution!