ClearMap 2: Getting started and installation

ClearMap 2 is a powerful tool for performing whole-brain analysis, but if you are new to Python, or unfamiliar with troubleshooting tools developed in Python, you will likely run into trouble getting it to work straight out of the box. This guide is created to help you get started, from setting up a new Linux workstation for running ClearMap, to going through how to modify the scripts so that you have a useful foundation for performing your own analysis in ClearMap.

First, if you are starting a new project performing whole-brain analysis with ClearMap, it’s worth reviewing a few publications first:

1. Mapping of Brain Activity by Automated Volume Analysis of Immediate Early Genes

2. Mapping the Fine-Scale Organization and Plasticity of the Brain Vasculature

3. The Allen Mouse Brain Common Coordinate Framework: A 3D Reference Atlas

The authors have also made great efforts to document both the clearing and analysis protocols, with information available at idisco.info and through existing documentation on ClearMap2.

---

Getting started with Ubuntu

The next few steps cover some important basics if you are setting up a new Linux workstation. Feel free to skip ahead if you are already up and running in Linux. In our hands, ClearMap 2 works well with both Ubuntu 18.04 and 20.04.

Installing Linux

Ubuntu desktop is available for download here. An easy way to install it on a new machine, either as a stand-alone or as a dual boot with Windows, is to create a bootable USB with Rufus. Simply install and run Rufus, then follow the steps to create the bootable USB with the downloaded ubuntu .iso file.

Using the terminal and enabling the firewall

Once installed, you should protect your machine by enabling the Linux firewall. Most things in Linux can be best performed using the Command Line Interface (CLI) via the Terminal. To enable the firewall:

1. Open a new Terminal window - Ctrl-Alt-T

2. In the terminal window that appears type:

     sudo ufw enable

Ensuring you have the correct GPU drivers

Some issues running ClearMap can be traced back to not having proper GPU drivers installed. There are some useful notes here on checking and installing correct drivers.

Remote access to your Linux workstation

It’s possible to set up remote access to your Linux workstation using Remote Desktop and SSH tunneling, but ClearMap’s visualizations are not compatible with this configuration. A good alternative is to use AnyDesk or TeamViewer, combined with 2-factor authentification.

---

Installing Anaconda and ClearMap 2

Install Anaconda

1. Download Anaconda for Linux

2. Open a Terminal window (Ctrl-Alt-T), and use the command below to install (*check the name of the install file you downloaded)

     bash ~/Downloads/Anaconda3-2021.05-Linux-x86_64.sh 

Install ClearMap 2

1. Download and unpack a zip file of the ClearMap 2 code from Github, or Clone to a folder using a Terminal window:

   git clone https://github.com/ChristophKirst/ClearMap2.git

2. Navigate to this directory in the Terminal. For example:

   cd Documents/Github/ClearMap2/ClearMap/

3. Create a ClearMap2 environment.
   For ClearMap2 to work, it’s important to install it in its own environment with the correct dependencies. You can create an environment with Anaconda using the .yml file provided in the ClearMap2 directory.
   In our hands, it was necessary to use ClearMap_stable.yml.

   conda env create --name ClearMapStable --file=ClearMap_stable.yml

4. Activate the environment.

   conda activate ClearMapStable

5. We also had to update spyder to successfully run clearmap. The commands below will install a stable version of spyder in the environment:

   pip uninstall spyder

   pip install spyder==3.3.6

---