ClearMap and TubeMap

New!

We are finalizing the website pages for the upcoming TubeMap pipeline, for vascular reconstructions. Detailed instructions will be made available here shortly. In the meantime, you can visit the GitHub repository to download the beta version of ClearMap 2, and read the TubeMap handbook pdf to prepare your experiments for brain vascular reconstructions. You can also head to the OSF data repository to download tutorial example datasets.

If you are interested in testing early versions of TubeMap, please write us to get updates, or check out @nicolasrenier on Twitter!

Introduction

ClearMap is the software implementation of our analysis workflow for 3D datasets obtained with iDISCO+. ClearMap is a Python code that interfaces with various open-source softwares to streamline and automate the following tasks:

  • 3D object detection: as of today, 2 detections modes are available. The Spotdetection mode is a high speed detection of spherical objects, such as cell nuclei. The Ilastik mode interfaces with the learning filters trained with Ilastik.
  • 3D registration of the brain scan and detected objects onto a reference brain. The reference can be annotated to provide an automatic region segmentation of the detected points. To do the 3D registration of the data, ClearMap interfaces with Elastix.
  • Statistics: ClearMap can generate voxel based statistics on the results of the detection and registration, such as average maps, standard deviation maps and p-values maps. ClearMap also performs simple statistics based on the region segmentation.

Download and installation

Required configuration

ClearMap is written in Python 2.7, and although might run on any environment (for instance MacOs), it has only been tested on Ubuntu 14 through 16.04LTS. Recommended hardware specs for the analysis of light sheet scans are:

  • 32Gb of RAM at least (128Gb recommended)
  • SSD drives recommended (1Tb at least)
  • Multicore Intel Xeon processor (6 cores recommended)

Download

You can download ClearMap from Git Hub. You can get the code with the following command:

$ git clone https://github.com/ChristophKirst/ClearMap.git

Installation

ClearMap necessitate a few libraries and additional softwares to run. Here is a list of everything you’ll need:

  • To do the alignement, you should download Elastix
  • If you wish to use the machine learning filters, download Ilastik. This is an optional download, only if you wish to use this more complete object detection framework for complex objects.

If you’re starting from a fresh Ubuntu 16.04LTS install, for instance, here are the steps to complete the installation. Open a terminal window and type the following instructions:

 Installation tools:

$ sudo apt-get update
$ sudo apt-get install git
$ sudo apt-get install python-pip
$ sudo -H pip install –upgrade pip

Download ClearMap:

$ git clone https://github.com/ChristophKirst/ClearMap.git

Install Spyder:

$ sudo apt-get install spyder

Install the necessary libraries:

$ sudo apt-get install python-opencv
$ sudo apt-get install cython
$ sudo apt-get install python-tifffile
$ sudo apt-get install python-h5py
$ sudo apt-get install python-natsort
$ sudo -H pip install scikit-image

We use Spyder to run the code. Set the working environment to the ClearMap folder.

Configuration

Open the file “ClearMap/Settings.py“ to set the paths of installations for Ilastik and Elastix:

>>> IlastikPath = ‘/yourpath/ilastik’;
>>> ElastixPath = ‘/yourpath/elastix’;

Note that Ilastik is optional. If you haven’t installed it, you can set the path to None.

Documentation

You can browse the online documentation or download a pdf version.

Additional files for mouse brains

We prepared a package containing the necessary files to work with mouse brains. This package includes:

  • The autofluorescence average mouse brain for registration, at a 25µm resolution. This was generated by Serial 2-photon Tomography by the lab of Pavel Osten, and is registered to the Allen Brain Atlas annotation.
  • The Allen Brain Institute Atlas annotation at 25µm.
  • The companion region identity parsing table.
  • A companion RGB version of the annotation file for figures and presentations purposes.
  • The registration parameter files for Elastix

Please cite and acknowledge the involved labs or institutions when using those ressources.

Download the ClearMap ressources for the Mouse brain (48Mb, zip archive).

Data for training

Datasets for training purposes have been posted online on the website of the Open Science Framework.