Glossary

  • Pipeline - Refers to the entire process of aligning a number of files, this includes all directories and files that are being created.

Setting up the registration environment (at MICe only)

When you are at the Mouse Imaging Centre, you should set your shell environment to one of the quarantines. Here is how you can do this, and why you should do this.

How to run MICe-build-model

MICe-build-model is run by executing a single script called, not surprisingly, MICe-build-model. There's a large set of options which control how MICe-build-model runs; anyone wanting all the gory choices should take a look at:

MICe-build-model.pl -help

Described in the rest of this page are the most common options and general usage patterns.

Setting up

At its most basic MICe-build-model needs just two or more input MINC files, the name of the pipeline, and it's ready to go. In most situations, however, an initial model used for rigid body alignment and masking of areas of interest is highly recommended. See creating initial models for how to create one of these models if you don't already have it.

General settings

During a registration process there are hundreds of processes being executed, many of which can be run in parallel. For this reason, the MICe-build-model script gives you the option to run the pipeline on one machine, but also to use a sun grid engine (sge) in order to exploit the parallel nature of the registration process.

Option

Argument

Description

-spawn

(none)

run the processes (jobs) sequentially on your machine (default).

-sge

(none)

use the sun grid engine (SGE) to run the processes.

Step #1 - 6 Parameter Registration

The first part of running MICe-build-model is the rigid body alignment. There are a few choices to be made here: whether or not to use an initial model (and if so, which one), and which strategy to employ for bringing the images into the same space. The choice of initial model is specified by:

Option

Argument

Description

-bootstrap-model

empty directory

Use this option when you do not have an initial model. The directory specified will be created if it does not exist already. Make sure to specify an absolute (not relative) path.

-init-model

basename of initial model

Use this option when you have an initial model. See examples below for how to specify the initial model.

-pipeline-name

prefix for pipeline folders

A registration pipeline will create a number of directories. This option is used to give a distinguishing name to that set of folders. For instance if you have a set of MRI brains images from a project called sonic-hedgehog, you could use mri-brains-sonic-hedgehog for the -pipeline-name option.

For example, to run without an initial model using four mice you'd use the following command:

MICe-build-model.pl -pipeline-name simple_pipeline -no-lsq6-large-rotations -bootstrap-model /path/to/new/directory/ mouse1.mnc mouse2.mnc mouse3.mnc mouse4.mnc

The mouse1.mnc ... mouse4.mnc would, of course, be replaced by the actual filenames of your images. The -pipeline-name option takes a string giving the name of the pipeline, which will be used when creating the necessary output directories and files. It'll create the pipeline in the directory from which you launched the command; if you want the data to be written elsewhere, an optional -pipeline-base /path/to/output can be specified.

Using an initial model would result in the equivalent command being:

MICe-build-model.pl -pipeline-name simple_pipeline -init-model /path/to/init/model/basename mouse1.mnc mouse2.mnc mouse3.mnc mouse4.mnc

When you are at MICe

There is a default argument for the -init-model option that you can use when you are at MICe and want to register a set of brain-in-the-box images. This means that you do not have to specify this option yourself in that case.

After the choice of whether to use an initial model you are now faced with three options for how to perform the linear registration:

Option

Argument

Description

-lsq6-large-rotations

(none)

This is the default - it uses a fairly time consuming process, but allows for the largest variance in rotations between the input images. Recommended for the scanning of fixed samples in particular, where ensuring equivalent positioning across scans is difficult or impossible.

-no-lsq6-large-rotations

(none)

Much faster, but more likely to incorrectly handle images with large rotations. Recommended for in-vivo brain scans or similar acquisitions where the initial positioning of the animals is fairly consistent.

-lsq6-identity

(none)

An add-on option for -no-lsq6-large-rotations, it assumes that the position in world space between all the scans is similar. If it is not similar (i.e. data from different scanners, etc.) then a centre of gravity estimation needs to be performed first, which is done with ...

-no-lsq6-identity

(none)

... does not assume equivalent position in world space, and performs centre of gravity estimation first. This is the default. Remember that these two options are ignored when -lsq6-large-rotations is in use

-lsq6-kernels                

e.g. 1.0_blur, 0.5_blur, 0.3_blur

Comma separated list of kernels (default depends on other -lsq6 choices). Altering the choice of kernels can sometimes improve registration.

-registration-accuracy       

(none)

Performs a registration accuracy test on the pipeline. Locates brain images that are 2, 3, and 4 standard deviations away from the average brain in terms of intensities and number of deformations.This information is useful in determining the cause of failure when registration cannot be completed.

Two illustrate this usage with three examples, we use the following invocation for specimen scanning:

MICe-build-model.pl -pipeline-name specimens -init-model /specimen/model/basename \
  mouse1.mnc mouse2.mnc mouse3.mnc mouse4.mnc

Whereas for in-vivo brain scans from our scanner, where we scan multiple mice in the same bore and thus have different world coordinates for each of them, we'd use:

MICe-build-model.pl -pipeline-name in-vivo1 -init-model /invivo/model/basename \
  -no-lsq6-large-rotations \
  mouse1.mnc mouse2.mnc mouse3.mnc mouse4.mnc

And for in-vivo brain scans from most other sites where world coordinates ought to be similar the invocation would be:

MICe-build-model.pl -pipeline-name in-vivo2 -init-model /invivo/model/basename \
  -no-lsq6-large-rotations -lsq6-identity \
  mouse1.mnc mouse2.mnc mouse3.mnc mouse4.mnc

Step #2 - 12 Parameter Pairwise Registration

After the rigid body alignment, a full affine alignment stage can be run, where each file is aligned to each of the other file using 12 parameters (3 translations, 3 rotations, 3 scales, and 3 shears). In the end, an average affine transformation is created from the individual pairwise registrations. This stage is run by adding the -lsq12 flag to the parameters to MICe-build.model.pl.

In the case of the bootstrap mode, this is how to continue:

MICe-build-model.pl -pipeline-name simple_pipeline -no-lsq6-large-rotations -bootstrap-model /path/to/new/directory/ mouse1.mnc mouse2.mnc mouse3.mnc mouse4.mnc -lsq12

and when using the initial mode:

MICe-build-model.pl -pipeline-name simple_pipeline -init-model /path/to/init/model/basename mouse1.mnc mouse2.mnc mouse3.mnc mouse4.mnc -lsq12

Step #3 - Non-linear Registration

Option

Argument

Description

-nlin-partial

none

Run only the first two non-linear fitting steps. This is much faster than running all of the steps. If errors arise while running the first two, corrections may be made before proceeding, thereby saving the user a significant amount of time. 

-nlin-stats

none

Create volumes for analysis of deformation fields. Jacobians, scaled jacobians, and magnitudes are deposited into folders.

-stiffness

number

Less stiffness allows greater flexibility when performing deformations of brain images. Specify stiffness as a number; the default is 0.98.

-similarity

number

Specify similarity as a number; the default is 0.8.

-weight

number

This is the amount by which the deformation is underestimated. Specify weight as a number; the default is 0.8.

-nlin-protocol

file

File containing the nonlinear fitting protocol; see n-lin-protocol.

  • No labels