christianjans / mesonet

A python toolbox for locating and exporting brain regions from mouse brain images.

Instructions for Chan Lab members

Welcome to the Chan Lab MesoNet repository! This repository is built off of the MesoNet repository. Included are some added scripts and functions for data analysis. All Chan Lab scripts can be found in the mesonet/chan_lab/ directory.

To begin, start by installing MesoNet. The recommended install is using the Anaconda (conda) environment to install DeepLabCut and the other requirements for MesoNet.

If pupillometry is also required, download the MATLAB code available at: https://github.com/christianjans/pupillometry_matlab.

Often, the results of the pupillometry code are analyzed in conjunction with the processed mesoscale images. If this is the case, follow the instructions in the pupillometry code to produce cleaned pupil size data for the desired dataset. Then, come back to this repository and check out its features.

Once installation of this repository is complete, MesoNet can be used with the scripts in the mesonet/chan_lab/ directory. See the Chan Lab scripts for more details.

MesoNet

MesoNet is a comprehensive Python toolbox for automated registration and segmentation of mesoscale mouse brain images. You can use it to:

• Automatically identify cortical landmarks
• Register a brain atlas to your mesoscale calcium activity data (or vice versa)
• Segment brain data based on a brain atlas
• Use one of our machine learning models (or train your own) to segment brain regions without using any landmarks!

Read the MesoNet article in Nature Communications.

We developed atlas-to-brain and brain-to-atlas approaches to make the software flexible, easy to use and robust.

We offer an easy to use GUI, as well as a powerful command line interface (CLI) allowing you to integrate the toolbox with your own neural imaging workflow.

We also extend our pipeline to make use of functional sensory maps and spontaneous cortical activity motifs.

We provided six end-to-end automated pipelines to allow users to quickly output results from input images.

MesoNet is built primarily on the U-net machine learning model (Ronneberger, Fischer, and Brox, 2015), as adapted in zhixuhao's unet repository, as well as DeepLabCut, keras, and opencv.

Installation

1. For DeepLabCut functionality (necessary for identifying brain atlas landmarks!), install and set up a DeepLabCut environment. We recommend using their supplied Anaconda environments.
2. Activate the DeepLabCut environment (as described above, usually activate DEEPLABCUT on Windows or conda activate DEEPLABCUT on Linux/Mac.
3. Clone this git repository: git clone https://github.com/christianjans/MesoNet.git

• NOTE: If you are on Windows, please clone the repository to a location on C:// as the git repository search function does not currently support other drives.

5. Enter the git repository folder using cd mesonet, then run python setup.py install to install additional dependencies for MesoNet (installation via pip coming soon!)
6. Run bash get_default_models.sh to download pre-trained DeepLabCut, U-Net, and VoxelMorph models from OSF for use on your data.

Usage

Follow our tutorial on the wiki.

Supported platforms

MesoNet has been tested on Windows 8.1, Windows 10, and Linux (Ubuntu 16.04 and Arch 5.7); it should also work on older versions of Windows and on MacOS, but these platforms have not been tested. It works with or without a GPU, but a GPU is strongly recommended for faster training and processing. MesoNet can be used with or without a GUI, and can be run on headless platforms such as Google Colab.

Contributors

Dongsheng Xiao designed the processing pipeline, collected data, trained the DeepLabCut, U-Net and VoxelMorph models provided with MesoNet, and developed the brain atlas alignment approach. Brandon Forys wrote the code of GUI and CLI. They are in the Murphy Lab in UBC’s Department of Psychiatry.

Citing

If you use our software, please cite the original research article:

Xiao, D., Forys, B.J., Vanni, M.P. et al. MesoNet allows automated scaling and segmentation of mouse mesoscale cortical maps using machine learning. Nat Commun 12, 5992 (2021). https://doi.org/10.1038/s41467-021-26255-2

BibTex:

@article{2021,
  doi = {10.1038/s41467-021-26255-2},
  url = {https://doi.org/10.1038/s41467-021-26255-2},
  year = {2021},
  month = oct,
  publisher = {Springer Science and Business Media {LLC}},
  volume = {12},
  number = {1},
  author = {Dongsheng Xiao and Brandon J. Forys and Matthieu P. Vanni and Timothy H. Murphy},
  title = {{MesoNet} allows automated scaling and segmentation of mouse mesoscale cortical maps using machine learning}
}

This work is licensed under a Creative Commons Attribution 4.0 International License.