linumpy.reference.allen#

Methods to download data from the Allen Institute.

Attributes#

AVAILABLE_RESOLUTIONS

Functions#

numpy_to_sitk_image(volume, spacing[, cast_dtype])

Convert numpy array (Z, Y, X) to SimpleITK image format.

download_template(resolution[, cache, cache_dir])

Download a 3D average mouse brain.

download_template_ras_aligned(resolution[, cache, ...])

Download a 3D average mouse brain and align it to RAS+ orientation.

register_3d_rigid_to_allen(moving_image, moving_spacing)

Perform 3D rigid registration of a brain volume to the Allen atlas.

Module Contents#

linumpy.reference.allen.AVAILABLE_RESOLUTIONS = [10, 25, 50, 100][source]#
linumpy.reference.allen.numpy_to_sitk_image(volume, spacing, cast_dtype=None)[source]#

Convert numpy array (Z, Y, X) to SimpleITK image format.

Parameters:

  • volume (np.ndarray) – 3D volume with shape (Z, Y, X) matching the project-wide convention (axis 0 = Z/depth, axis 1 = Y/row, axis 2 = X/column).

  • spacing (tuple) – Voxel spacing in mm as (res_z, res_y, res_x).

  • cast_dtype (numpy dtype or None) – If provided, cast the volume to this dtype before creating the SITK image (useful for registration where float32 is expected). If None, preserve the input numpy dtype.

Returns:

SimpleITK image with proper spacing and orientation

Return type:

sitk.Image

linumpy.reference.allen.download_template(resolution, cache=True, cache_dir='.data/')[source]#

Download a 3D average mouse brain.

Parameters:

  • resolution (int) – Allen template resolution in micron. Must be 10, 25, 50 or 100.

  • cache (bool) – Keep the downloaded volume in cache

  • cache_dir (str) – Cache directory

Return type:

Allen average mouse brain.

linumpy.reference.allen.download_template_ras_aligned(resolution, cache=True, cache_dir='.data/')[source]#

Download a 3D average mouse brain and align it to RAS+ orientation.

The Allen CCF v3 template is stored in PIR orientation (SITK axes (X, Y, Z) = (AP, DV, ML) with +X = Posterior, +Y = Inferior, +Z = Right). Converting to RAS+ (+X = Right, +Y = Anterior, +Z = Superior) requires PermuteAxes((2, 0, 1)) followed by flipping both the Y and Z axes (I → S and P → A).

Parameters:

  • resolution (int) – Allen template resolution in micron. Must be 10, 25, 50 or 100.

  • cache (bool) – Keep the downloaded volume in cache

  • cache_dir (str) – Cache directory

Return type:

Allen average mouse brain in RAS+ orientation.

linumpy.reference.allen.register_3d_rigid_to_allen(moving_image, moving_spacing, allen_resolution=100, metric='MI', max_iterations=1000, verbose=False, progress_callback=None, initial_rotation_deg=(0.0, 0.0, 0.0))[source]#

Perform 3D rigid registration of a brain volume to the Allen atlas.

Parameters:

  • moving_image (np.ndarray) – 3D brain volume to register (shape: Z, Y, X)

  • moving_spacing (tuple) – Voxel spacing in mm (res_z, res_y, res_x)

  • allen_resolution (int) – Allen template resolution in micron (default: 100)

  • metric (str) – Similarity metric: ‘MI’ (mutual information), ‘MSE’, ‘CC’ (correlation), or ‘AntsCC’ (ANTS correlation)

  • max_iterations (int) – Maximum number of iterations

  • verbose (bool) – Print registration progress

  • progress_callback (callable, optional) – Callback function called on each iteration with the registration method. Function signature: callback(registration_method)

  • initial_rotation_deg (tuple, optional) – Initial rotation in degrees (rx, ry, rz) applied before optimization.

Returns:

  • transform (sitk.Euler3DTransform) – Rigid transform to align moving_image to Allen atlas

  • stop_condition (str) – Optimizer stopping condition

  • error (float) – Final registration metric value

Return type:

tuple