Skip to article frontmatterSkip to article content

How to contribute

This is an overview of our workflow:

We create computational notebooks and upload them to our GitHub repository. These notebooks get automatically built into this website, where they can be discussed. Once the story becomes clearer, we start writing up the paper in Overleaf.

Follow the steps below to start contributing to this project.

1. Join the community

Join the Discord, to chat about the project and read announcements. If you have a question, use our Q&A forum on GitHub. Participation in the community is subject to our Code of Conduct.

You can check out where others are located in the world, and add yourself, on this map 🗺.

We will be organizing regular online meetings to talk about progress. They will be announced on Discord.

Meetup in Paris (optional), July 8th

We also come together in person, where possible, to work on the project in ‘hackathon’ fashion. Note though that being able to attend one of such meetups is by no means a requirement to join the project.

A first hackathon is organized in Paris on Friday July 8th – the day before the start of the 2022 FENS conference. Concrete details to follow (though it will likely be at the UPMC campus, from roughly 14h to 22h CET).

2. Learn about the subject

Watch the two videos of Dan Goodman’s tutorial on spiking neural network (SNN) models.

Topics covered in the videos

  • Video 1

    • Spiking neuron models (LIF and more)
    • Intro to the sound localization problem
    • The classic delay line / coincidence detection model of sound localization
      • The notebook explained in this part — from 32:40 on — uses a package (Brian) that we do not use here. This part is still relevant insofar that the introduced concepts are used in the next video and in our project.

  • Video 2

    • Learning in neural networks, and surrogate gradient descent for SNNs.
    • Training an SNN for sound localization using PyTorch.

The slides, and links for learning more, are available at the tutorial website.

Then, read for a brief introduction to the auditory system and sound localization, and for links to previous modelling work in sound localization.

3. Pick a research question

Visit to find inspiration for something you’d like to try out or investigate.

Edit that page and add your name to an item, or add a new item:

How to edit the Questions page ✏

On the page, via the GitHub logo at the top, click “suggest edit” (or go there directly using this link). Sign up / log in to GitHub if needed, and edit the markdown text there to add your name / research question.

If you are not already a member of our GitHub organization, GitHub will warn you that “You’re making changes in a project you don’t have write access to.” Make your edit anyway and click the green “Propose changes” button. This will make a Pull Request to our project. We will merge it, and add you as a member to our GitHub organization.

If you are already a member, you can simply choose “Commit directly to the main branch”.

It is hard to say beforehand where research will lead you, so feel free to edit this at any time.

4. Work in a notebook

The contains a basic analysis pipeline.

Overview of the Starting notebook
  • A simple sound localization task is defined, and input/output data for it are generated.
    • The task: given a pure tone that arrives with a delay in one ear, calculate the interaural phase difference (IPD).
  • An SNN model is defined, and trained on this data, using surrogate gradient descent.
  • The model’s performance is analyzed, and its learned weights are visualized.

This notebook is a good starting point for your own experiments. Duplicate the Starting notebook and work on your experiment in this copy. You can do this using either Google Colab or a local setup:

How to work with Google Colab ☁

NOTE: the Colab rocket icon button mentioned below is not currently working, you need to download a copy of the notebook and drop it into Colab for the moment.

On the page, via the rocket icon at the top, click “Colab” (or go there directly via this link).

For an intro to the Colab interface and its keyboard shortcuts, see here.

To save your changes, use one of the “Save a copy …” options in the File menu. (You can choose either your personal GitHub / GitHub Gists, or your Google Drive).

When you have something ready to share, ‘Download’ the notebook as an .ipynb file via the File menu. See the next step for how to share this file and have it appear on this website.

How to work locally 💻

Below are detailed instructions to get set up locally.
If you are already familiar with such instructions however, the summary is:

  1. Install conda if it is not already installed.
    • The recommended installer is miniforge : it is lean, and is generally faster than installers like Miniconda, as it only uses the conda-forge channel by default.
  2. Download the repository.
  3. Run, in the repo root:
    $ conda env create -f environment.yml
$ conda activate spikeloc
$ jupyter notebook
  4. Make a copy of research/Starting-Notebook.ipynb and work in that copy.

Besides duplicating the starting notebook, you could also do one of the following:

Other ways to work
  • Duplicate another notebook than the ‘Starting’ one, if you want to build on someone else’s work.
  • Start from scratch in a new notebook.
  • If no code is needed, write a simple markdown file. (‘’ is an example of this).
  • If you prefer scripts to Jupyter Notebooks, upload 1) the script (.py file), 2) the generated plots (image files), and 3) a .md file that describes the analysis and includes the plots (preferably placed in a subdirectory).

5. Share your work

When you have finished some work to share:

Step 1: Rename your notebook file to something reflective of its contents.

How the filename and title are used on the website
  • The notebook’s filename (e.g. Learning-delays.ipynb) is used to create the URL for your notebook (e.g: https://comob-project.github.io/snn-sound-localization/research/Learning-delays.html).
    • Use dashes and underscores rather than spaces: spaces get converted to noisy %20s in URLs.
    • Avoid changing the filename after the notebook has been integrated in the website: that would break existing links to it. It would also lose the on-page comments (discussed in step 6. Check out others’ work) attached to the page.
    • Filenames are also used to cross-reference pages within this website: for example, the markdown “[](research/Starting-Notebook)” gets rendered as .
  • The notebook’s title (the markdown header in the first cell, e.g. # Learning delays) is used in the table of contents (the menu on the left here on the website).

Step 2: Upload the notebook file to our GitHub repository

How to upload to GitHub
  • To do so, you need to be a member of our GitHub organization, which you should be after following step 3. Pick a research question.
  • Go to the research/ directory on GitHub, and drag and drop your notebook onto the page (or use the “Add file” button). Choose “Commit directly to the main branch” and click “Commit changes”.
    • This same procedure can also be used to update a file that is already on the website: simply upload a file with the same name as the existing one.
    • (If you git cloned the repository earlier, you can of course also just push your notebook, to main).

After your commit, the website will be automatically rebuilt. Your notebook should appear on the website in a short while.

6. Check out others’ work

All our notebooks and research notes appear under the ‘Research’ rubric to the left.

7. Help write the paper

The paper is being edited in the same repository using MyST markdown.

COMOB Sound Localization Project
Code of Conduct
Paper
Organising the paper