Skip to content

Latest commit

 

History

History
117 lines (79 loc) · 7.74 KB

README.md

File metadata and controls

117 lines (79 loc) · 7.74 KB
Raw

License CI codecov Ruff Code style: black pre-commit

brainglobe-template-builder

Build unbiased anatomical templates from individual images

Overview

brainglobe-template-builder provides a streamlined process to create unbiased anatomical reference images, or templates, from multiple high-resolution brain images. While primarily designed for brain imaging, its versatility extends to any organ with available 3D digital images, especially those produced by 3D volumetric microscopy like serial two-photon tomography (STPT) and light-sheet microscopy (LSM).

brainglobe-template-builder aims to:

Warning

  • Early development phase. Stay tuned
  • Interface may undergo changes.

Installation

Pre-requisites

  • A Unix-like operating system (Linux or MacOS)

  • A bash shell (if you are using MacOS, where zsh is the default, you may need to install bash via Homebrew).

  • A working installation of Advanced Normalisation Tools (ANTs). We recommend following these instructions to compile ANTs from source and to follow all recommended post-installation steps.

  • The scripts from the optimised ANTs template construction pipeline, which should be available in your PATH. According to the instructions in that repository's README, you should do the following:

    git clone --recursive https://github.com/CoBrALab/optimized_antsMultivariateTemplateConstruction.git
cd optimized_antsMultivariateTemplateConstruction
echo "export PATH=$(pwd):\$PATH" >> $HOME/.bashrc
echo "export PATH=$(pwd)/minc-toolkit-extras:\$PATH" >> $HOME/.bashrc
source $HOME/.bashrc  # or restart your terminal

    If you are on MacOS, you may need to replace $HOME/.bashrc with $HOME/.bash_profile.

Create a conda environment

We recommend installing brainglobe-template-builder within a conda or mamba environment. Instructions assume conda usage, but mamba/micromamba are interchangeable.

conda env create -n template-builder -f environment.yaml
conda activate template-builder

We have called the environment "template-builder", but you can choose any name you like.

This environment contains all dependencies for running the optimised ANTs template construction pipeline, but if you want to use the pre- and post-processing funcitonalities of brainglobe-template-builder, you will need to also pip install the package in editable mode (see below).

Install brainglobe-template-builder with pip

To install the latest development version of brainglobe-template-builder, first clone the repository:

git clone https://github.com/brainglobe/brainglobe-template-builder
cd brainglobe-template-builder

Then, install the package in editable mode with the following command:

pip install -e .[dev]

Background

On templates and atlases

In brain imaging, a template serves as a standard reference for brain anatomy, often used interchangeably with the term reference image. By aligning multiple brain images to a common template, researchers can standardize their data, facilitating easier data-sharing, cross-study comparisons, and meta-analyses.

An atlas elevates this concept by annotating a template with regions of interest, often called labels or parcellations. With an atlas, researchers can pinpoint specific brain regions and extract quantitative data from them.

The entire process, from registration to data extraction, hinges on the quality of the template image. A high-quality template can significantly improve registration accuracy and the precision of atlas label annotations.

The aim of brainglobe-template-builder is to assist researchers in constructing such high-quality templates.

Single-subject vs population templates

Templates can be derived in two primary ways. A single-subject template is based on the brain of one individual. While this approach is simpler and may be suitable for some applications, it risks being unrepresentative, as the chosen individual might have unique anatomical features. On the other hand, population templates are constructed by aligning and averaging brain images from multiple subjects. This method captures the anatomical variability present in a population and reduces biases inherent in relying on a single subject. Population templates have become the standard in human MRI studies and are increasingly being adopted for animal brain studies.

Template construction with ANTs

brainglobe-template-builder leverages the power of ANTs (Advanced Normalisation Tools), a widely used software suite for image registration and segmentation.

ANTs includes a template construction piepline - implemented in the antsMultivariateTemplateConstruction2.sh script - that iteratively aligns and averages multiple images to produce an unbiased population template (see this issue for details).

An optimsed implementation of the above pipeline, developed by the CoBra lab, lies at the core of the brainglobe-template-builder's functionality.

Seeking help or contributing

We are always happy to help users of our tools, and welcome any contributions. If you would like to get in contact with us for any reason, please see the contact page of our website.

License

⚖️ BSD 3-Clause

Package blueprint

This package layout and configuration (including pre-commit hooks and GitHub actions) have been copied from the python-cookiecutter template.