Atlas to low resolution image registration

Low resolution mouse brain image to allen mouse brain atlas registration

This script is intended to be used at the command line and will save the initial, intermediate, final registration results for aligning a single 3D slice (.npz) or multiple consecutive slices ([.npz,…]) to the Allen Mouse Brain Atlas. This script performs step 1 of 3 in the registration pipeline.

step1_atlas_registration.main()

Command line arguments

datasetstr

The name of the dataset to be registered. This will be included in the names of the majority of the output files.

orientationchar

The portion of the brain captured by this dataset (W - whole, L - left hemisphere, R - right hemisphere)

-low_pathsstr or list of str

1 or more file paths pointing to the location(s) of the low resolution mouse brain images (.npz) in Anterior to Posterior order

-outdirstr

The path to the directory where all outputs will be stored

-atlas_pathslist of 3 str

The paths pointing to the 3 Allen mouse brain atlases used for registration. In order, these files are named (1) ara_nissl_50.vtk, (2) average_template_50.vtk, and (3) annotation_50.vtk

-to_flipint or list of int

A list of the indeces of the slices from ‘-low’ that need to flipped so that they are all the same orientation

-devicestr

The device for torch computation (Options: ‘cpu’, ‘cuda:0’, ‘cuda:1’, ‘mps’)

-Astr

The 4x4 affine matrix used to estimate an initial guess for the registration algorithm. Should be of the form [[x,x,x,x],[x,x,x,x],[x,x,x,x],[x,x,x,x]]; If not supplied, a sensible default will be produced based on orientation to reproduce previous work with the Yang lab’s MORF project

-AJlist of str

A list of 4x4 affine matrices used to estimate an initial guess for each slice to be used in the registration algorithm. Should be a list of the same length as the number of slices and each element must be of the form [[x,x,x,x],[x,x,x,x],[x,x,x,x],[x,x,x,x]]; If not supplied, a sensible default will be produced based on orientation to reproduce previous work with the Yang lab’s MORF project

-dsliceint

Default - 500; The thickness of the slab(s) within the dataset, in units of um

-n_iterint

Default - 40000; The number of iterations to run the EMLDDMM optimization algorithm

-e_pathstr

The location of the custom Python library ‘emlddmm’, which can be cloned from GitHub at https://github.com/twardlab/emlddmm

-d_pathstr

The location of the custom Python library ‘donglab_workflows’, which be cloned from GitHub at https://github.com/twardlab/donglab_workflows

-save_fig0bool

Default - False; If present, save histogram of voxel values in outdir

-save_fig1bool

Default - False; If present, save figure showing MIP of every slice in outdir

-save_fig2bool

Default - False; If present, save figure showing where data is missing from low-res images in outdir

-save_fig3bool

Default - False; If present, save figure displaying the trapezoid function in outdir

-save_fig4bool

Default - False; If present, save figure displaying a map of the edges of the atlas in outdir

-save_fig5bool

Default - False; If present, save figure displaying the inner product which allows us to perform gradient descent in outdir

-save_fig6bool

Default - False; If present, save figure displaying the 12x12 matrices gid and gJid in outdir

–normalizeDatabool

Default - True; If True, normalize input data to [0,1]

–zeroMeanbool

Default - True; If True, use the zero mean convention when loading all input data

–largerRGBfigbool

Default - False; If True, Include 8 panels for each orientation in the figRGB outputs during regstration, otherwise include 5 panels

raises Exception:

if any of the files provided to the ‘-low’ argument cannot be accessed

raises Exception:

if the number of arguments passed to ‘AJ’ does not equal the number of arguments passed to ‘low’

raises Exception:

if the provided atlases don’t have a .vtk, .nii, or .tif file extension

raises ValueError:

if the argument ‘A’ is not of the correct form

raises ValueError:

if any elements from the list argument ‘AJ’ are not of the correct form