Generative network modeling reveals a first quantitative definition of bilateral symmetry exhibited by a whole insect brain connectome

Code accompanying the publication: Generative network modeling reveals quantitative definitions of bilateral symmetry exhibited by a whole insect brain connectome

eLife

2023

Benjamin D. Pedigo, Mike Powell, Eric W. Bridgeford, Michael Winding, Carey E. Priebe, Joshua T. Vogelstein

Abstract

Comparing connectomes can help explain how neural connectivity is related to genetics, disease, development, or learning. However, making statistical inferences about the significance and nature of differences between two networks is an open problem, and such analysis has not been extensively applied to nanoscale connectomes. Here, we investigate this problem via a case study on the bilateral symmetry of a larval Drosophila brain connectome. We translate notions of “bilateral symmetry” to generative models of the network structure of the left and right hemispheres, allowing us to test and refine our understanding of symmetry. We find significant differences in connection probabilities both across the entire left and right networks and between specific cell types. By rescaling connection probabilities or removing certain edges based on weight, we also present adjusted definitions of bilateral symmetry exhibited by this connectome. This work shows how statistical inferences from networks can inform the study of connectomes, facilitating future comparisons of neural structures.

Repo structure

• .github: Files specifying how the repo behaves on GitHub.
• data: Directory to store the raw data.
• docs: Files to build the documentation website (in the form of a Jupyter Book), talks, and posters.
• overleaf: Link to an Overleaf document as a git submodule.
• pkg: A local Python package used for analysis in the Jupyter Notebooks/Python scripts.
• results: Place to store intermediate outputs, figures, and saved variables.
• sandbox: Junk scripts not part of the final paper/project.
• scripts: Python scripts used to do all analyses
• shell: Shell scripts used to run the entire project, copy results, etc.

Guide to using the repository

Getting the code and setting up an environment

Prerequisites: git, working knowledge of Python and command line tools.

Using Poetry

I recommend using Poetry to create and manage a reproducible environment for running the code for this project.

• If you don't have it already, install Poetry following their linked instructions.

• Navigate to a directory where you want to store the project, and clone this repo:

  git clone https://github.com/neurodata/bilateral-connectome
  

• (TEMPORARY) Clone the sister repository, giskard:

  git clone https://github.com/bdpedigo/giskard.git
  

  • Note: once the code is stable, this will be replaced by an install from PyPI

• Enter the newly cloned directory:

  cd bilateral-connectome
  

• Create a Poetry environment:

  • Note: this requires that you have a Python 3.9 installation on your machine. It is possible that the code for this project will run with other versions of Python, but I haven't tested it. To check if you have Python 3.9, you can do:

    which python3.9
    

    If the result says python3.9 not found then you'll need to get a 3.9 interpreter on your machine. Common ways to install an interpreter are via python.org, brew, or conda.
  • After you have ensured you have a Python 3.9 installation, do:

    poetry env use python3.9
    

  • For me, the output looks like

    Creating virtualenv bilateral-connectome in /Users/bpedigo/bilateral-test/bilateral-connectome/.venv
    Using virtualenv: /Users/bpedigo/bilateral-test/bilateral-connectome/.venv
    

• To activate the new environment, do

  source .venv/bin/activate
  

  • If you need to deactivate this environment, just type deactivate

Using pip

Coming soon

Getting the data

Coming soon

Running the code

• Make sure your virtual environment from the last section is active.
• Now you should be able to run any individual python files like normal, for example:

  python ./bilateral-connectome/scripts/er_unmatched_test.py
  

• Instead of running as a Python file, you can also easily convert a Python file to a notebook, execute it, and have it included in the documentation folder for rendering as a Jupyter Book. To do so, use the make_notebook.sh script and pass in the name of the python file (without the .py file extension):

  sh ./bilateral-connectome/shell/make_notebook er_unmatched_test
  

  If you'd like to build that individual notebook and then rebuild the documentation, just add the -b argument to the same script:

  sh ./bilateral-connectome/shell/make_notebook -b er_unmatched_test
  

• You can also build and run all notebooks which are essential to the final paper via the make_project.sh script:

  sh ./bilateral-connectome/shell/make_project.sh
  

Building the documentation Jupyter Book

The notebooks associated with this project are assembled into a Jupyter Book.

• To build the documentation, do:

  jb build ./bilateral-connectome/docs
  

• You can then view the locally built HTML by pasting the produced link into your browser. For me, the built index is stored at ./bilateral-connectome/docs/_build/html/index.html

Linking Overleaf and writing the paper

Coming soon

Questions about the code or paper

Please get in touch! You are welcome to make an issue or email me at bpedigo[ at ]jhu[ dot ]edu.