Skip to content

Latest commit

 

History

History
604 lines (388 loc) · 19.6 KB

installation.rst

File metadata and controls

604 lines (388 loc) · 19.6 KB
Raw

Installing and running MIRACL

We provide instructions on how to install and run MIRACL using either of the following methods:

Important

Docker is our recommended method for running MIRACL on local machines and servers. We recommend Singularity to run MIRACL in a cluster environment (e.g. Compute Canada).

Attention

Support for installing MIRACL locally (i.e. on your host system directly without using Docker or Singularity) will be phased out in future versions of the software

Docker

We provide a build script to automatically create a Docker image for you that can be run using Docker Compose. This method does not require a manual installation of MIRACL and works on Linux, macOS and Windows (using WSL 2).

Tip

This is our recommended method for running MIRACL on local machines and servers

Docker is well suited if you want to run MIRACL on a local machine or local server. If you need to run MIRACL on a cluster, see our instructions for installing Singularity. If you don't have Docker installed on your computer, do that first. Make sure your installation includes Docker Compose as it is required to run the build script we provide. Note that Docker Compose is included as part of the Docker Desktop installation by default.

Getting started

First, it is important to understand how the container is built. There is a base image in the docker folder that installs Python and dependencies. Then the Dockerfile in the base of the repository builds the mgoubran/miracl image from that base. When the build happens, it cats the version.txt file in the repository to save a versioned base, but then the build uses the tag revised-base-latest that is always the latest base. The base container is built from this folder and pushed manually, while the main container is built and pushed automatically via the CircleCI Recipe. Thus, if you want to update the base, you will need to see the README.md in that folder and push new images.

Build MIRACL from scratch

This will build a Docker image of MIRACL based on its latest version using our default naming scheme. For custom names and specific versions see below for our Additional build options section.

Clone the MIRACL repo to your machine:

$ git clone https://www.github.com/mgoubran/MIRACL
$ cd MIRACL

Build the latest MIRACL image using the build script we provide:

$ ./build.sh

Error

Make sure that the script can be executed. If it can't and you are the owner of the file, use chmod u+x build.sh to make it executable. Prefix with sudo if you are not the owner of the file or change permissions for g and/or o.

Once the image has successfully been built, run the container using Docker Compose:

$ docker compose up -d

The container is now running and ready to be used.

Using the container

Interactively shell inside:

$ docker exec -it miracl bash

Files that are saved while using MIRACL should be saved to volumes mounted into the container in order to make them persistent. To mount volumes, just add them to the docker-compose.yml in the base directory under volumes.

Danger

Do not delete the volume that is already mounted which mounts your .Xauthority! This is important for X11 to work correctly.

Example:

volumes:
      - '/home/mgoubran/.Xauthority:/home/mgoubran/.Xauthority'
      - '/home/mgoubran/mydata:/home/mgoubran/mydata'

Stopping the container

Exit your container and navigate to your MIRACL folder. Use Docker Compose to stop the container:

$ docker compose down

Additional build options

Image and container naming

Naming is done automatically when using our build script which includes a default naming scheme. By default, the image is named mgoubran/miracl:latest and the container is tagged with miracl.

You can easily change the defaults if your usecase requires it by running our build script with the following options:

$ ./build -i <image_name> -c <container_name>

Options:

-i, Specify image name (default: mgroubran/miracl)
-c, Specify container name (default: miracl)

Example:

$ ./build -i josmann/miracl -c miracl_dev_version

Tip

Use ./build -h to show additional options

MIRACL versions

By default, Docker images will be built using the latest version of MIRACL. If you need to build a Docker image based on a specific version of MIRACL, do the following:

  1. Clone the MIRACL repository and navigate to the MIRACL folder:
$ git clone https://www.github.com/mgoubran/MIRACL
$ cd MIRACL
  1. Cloning the repository will download all tags/versions. List them with:
$ git tag -l

Example output:

v1.1.1
v2.2.1
v2.2.2
v2.2.3
v2.2.4
v2.2.5
  1. Decide which tag/version of MIRACL you want to use and check it out as a new branch:
$ git checkout tags/<tag_name> -b <branch_name>

Example:

$ git checkout tags/v2.2.4 -b miracl_v2.2.4
  1. If you are reverting to a version of MIRACL >= 2.2.4, you can build the image for your chosen version by running the build script with the -t flag:
$ ./build.sh -t

Note

If you want to build an image for a version of MIRACL <= 2.2.4 either follow the build instructions of the particular version or download the latest build script using e.g. wget https://raw.githubusercontent.com/AICONSlab/MIRACL/master/build.sh (overwrites current build script if present) and run it with the -t flag.

  1. From here you can follow our instructions for building MIRACL from scratch starting with docker compose up -d. Our script will automatically detect the version of the branch you checked out and tag the image accordingly.

Singularity

Unlike Docker, Singularity is well suited to run in a cluster environment (like Sherlock at Stanford or Compute Canada). We provide the latest version of MIRACL as a Singularity container that can be conveniently pulled from cloud storage.

Tip

This is our recommended method for running MIRACL in a SLURM cluster environment such as Compute Canada or Sherlock @ Stanford

Download container

First, log in to the cluster:

$ ssh -Y <username>@<cluster>

<cluster> could be sherlock.stanford.edu or cedar.computecanada.ca for example

Once logged in, change the directory to your scratch space and pull (download) the Singularity container:

$ cd $SCRATCH
$ singularity pull miracl_latest.sif library://aiconslab/miracl/miracl:latest

Attention

singularity pull requires Singularity version 3.0.0 or higher. Please refer to our Troubleshooting section <../troubleshooting/troubleshooting_singularity> ("Can I build a Singularity container from the latest MIRACL image on Docker Hub") if you are using an older version of Singularity.

Interaction

To shell into the container use:

$ singularity shell miracl_latest.sif bash

Use the -B flag to bind a data directory to the container:

$ singularity shell -B /data:/data miracl_latest.sif bash

For running functions on clusters please check our Singularity tutorials for Compute Canada and Sherlock

Local

Warning

Support for this installation method will be discontinued in future versions of MIRACL. We recommend to use Docker or Singularity instead.

Steps to setup/run MIRACL on a Linux/macOS machine:

$ git clone https://github.com/mgoubran/MIRACL.git miracl

Tip

Alternatively, you can download the zip file containg the repo and uncompress it

Next, change directories into the newly created miracl folder:

$ cd miracl

Create your virtual MIRACL environment and activate it:

Attention

To setup a virtual environment you need Anaconda for Python 2.7. It can be downloaded from their official website

$ conda create --name miracl python=3.7.4 pip
$ conda activate miracl

Install dependencies:

$ pip install -e .

ANTS & c3d

Next, download the depends folder from our Dropbox link and place it either inside the linux_depends or mac_depends folder:

$ mv ~/Downloads/depends.zip miracl/.
$ cd miracl
$ unzip depends.zip
$ rm depends.zip

This folder contains compiled versions of ANTS and c3d for Linux or Mac OS. Before continuing, make sure to change the permissions.

This can be done by running:

$ chmod -R 755 <path/to/depends>/*

In order to run the pipeline, some symbolic links must be added to access certain commands. Inside the miracl folder, run:

$ sudo ln -s <path/to/depends>/ants/antsRegistrationMIRACL.sh /usr/bin/ants_miracl_clar && chmod +x /usr/bin/ants_miracl_clar
$ sudo ln -s <path/to/depends>/ants/antsRegistrationMIRACL_MRI.sh /usr/bin/ants_miracl_mr && chmod +x /usr/bin/ants_miracl_mr

Make sure <path/to/depends> is replaced with the directory path that leads to the depends directory.

Allen atlas

Place the atlases folder (which got downloaded together with the depends folder) inside the miracl folder:

$ mv ~/Downloads/atlases.zip miracl/.
$ cd miracl
$ unzip atlases.zip
$ rm atlases.zip

This folder contains the Allen Atlas data needed for registration and connectivity analysis.

Fiji & FSL

Install Fiji & FSL

First, download Fiji/ImageJ from their offical website.

Then do:

$ cd depends
$ wget https://downloads.imagej.net/fiji/latest/fiji-linux64.zip
$ unzip fiji-linux64.zip
$ rm fiji-linux64.zip

Next, install additional plugins by going to Help -> Update and clicking on the Manage update sites button.

Choose the following update sites:

Download FSL and install it:

$ wget https://fsl.fmrib.ox.ac.uk/fsldownloads/fslinstaller.py
$ sudo python fslinstaller.py

Visualization

For the visualization of nifti files and labels we recommend ITKSNAP or the nifti plugin for Fiji/ImageJ.

Diffusion Data

If you have diffusion MRI data download and install MRtrix3:

$ sudo apt-get install git g++ python python-numpy libeigen3-dev zlib1g-dev libqt4-opengl-dev libgl1-mesa-dev libfftw3-dev libtiff5-dev
$ git clone https://github.com/MRtrix3/mrtrix3.git
$ cd mrtrix3
$ ./configure
$ ./build
$ ./set_path

Deactivate

To end a MIRACL session, deactivate your virtual environment:

$ conda deactivate

Update MIRACL

To update MIRACL, navigate into your MIRACL base folder (e.g. $ cd miracl) and run:

$ git pull

You should be good to go!

Windows

Warning

Support for installing MIRACL locally in the WSL will be discontinued in future versions of MIRACL. We recommend to use Docker or Singularity instead.

To install MIRACL on your Windows system, Windows Subsystem for Linux (WSL) must be installed. WSL2 is preferred. From there, the usual steps to install MIRACL on a Linux based system will be used with a few tweaks.

Hint

Follow the below steps if you want to install MIRACL in your WSL instance locally. If you prefer to use Docker to run MIRACL on Windows follow our installation instructions for Docker instead.

Installing WSL 2 on Windows

The Windows Subsystem for Linux (WSL) creates an environment that allows users to run versions of Linux without having to set up a virtual machine or a different computer.

To install WSL, users can follow the instructions from Microsoft. More comprehensive instructions can be found here. Upgrading from WSL 1 to WSL 2 is recommended, due to WSL 2's benefits.

Install the Ubuntu distribution (Ubuntu 22.04) from the Microsoft Store

Note

You may ignore this step if you have a preferred Linux distribution that is already installed in your WSL2

A Linux distribution (distro), like Ubuntu, is an operating system based on the Linux kernel.

Now that WSL (either 1 or 2) is installed, the Ubuntu 22.04 distro can be installed. To install Ubuntu, open the Windows Store app, search for "Ubuntu 22.04", and select the Get button. You could also use this link.

Install Python and pip

The Ubuntu distro should have Python 3 installed. To ensure that this is the case, update all packages installed in the WSL:

$ sudo apt update
$ sudo apt -y upgrade

We can see which version of Python 3 is installed by typing:

$ python3 -V

The output in the terminal window will show the version number.

pip is required to install software packages in Python. It can be installed by running the following command:

$ sudo apt install -y python3-pip

You could also use Anaconda to install the packages but we found that installing and using pip was more straightforward.

Install MIRACL using local installation instructions

To actually install MIRACL, follow the local installation instructions for Linux and macOS.

Installing Xming

To use MIRACL's graphical user interface (GUI), Xming must be installed. Xming is a display server for Windows computers, that is available for use by anyone. It can be downloaded from SourceForge.

Before running MIRACL's GUI, run Xming. In the terminal window where MIRACL's GUI will be run, input the following command:

$ export DISPLAY=$DISPLAY:localhost:0

Running MIRACL with WSL 2

Now that everything is installed, MIRACL can be run via the WSL. To run:

  1. Open WSL via terminal
  2. Navigate to the folder where you would like to run MIRACL from
  3. Activate the environment containing miracl:
$ source activate miracl
$ miraclGUI

Jupyter notebook