brainglobe-ccf-translator

CCF translator (brainglobe-ccf-translator) is a tool for translating between common coordinate frameworks using deformation matrices. A longstanding problem in NeuroInformatics has been the inability to easily translate data between common coordinate frameworks. CCF translator aims to solve this. By connecting each new space to an existing one, we can construct a graph of deformations. This means that data can be translated as long as there is a route from one space to another, even if that route passes through multiple other spaces. Now, when new templates for new modalities, strains, or ages are released, users will not be subdivided into unrelated spaces. As long as they are connected to a space which exists in our network, they will be fully connected to all other spaces.

CCF translator can also interpolate between spaces and create a new intermediate space. This is primarily useful for development, where, for instance, the midpoint between day 5 and day 7 can be taken and used as a postnatal day 6 reference. It could also be useful for making references of disease progression.

Diagram: a graph of all the available spaces and how they are connected. the spaces are nodes with the space name written on top of them, the edges show which spaces are connected to which other spaces.

graph TD
    allen_mouse_P56 --- demba_dev_mouse_P56
    allen_mouse_P56 --- perens_multimodal_lsfm_P56
    allen_mouse_P56 --- perens_stereotaxic_mri_mouse_P56
    allen_mouse_P56 --- princeton_mouse_P56
    demba_dev_mouse_P14 --- demba_dev_mouse_P21
    demba_dev_mouse_P14 --- demba_dev_mouse_P7
    demba_dev_mouse_P21 --- demba_dev_mouse_P28
    demba_dev_mouse_P28 --- demba_dev_mouse_P56
    demba_dev_mouse_P4 --- demba_dev_mouse_P7
    dorr_mouse_mri_P84 --- perens_stereotaxic_mri_mouse_P56

Use Cases

One way you can use CCF translator is to view data from one space, in another space. For instance the allen connectivity dataset shows projections from viral tracing studies in the adult brain. We can take any of these projection datasets and view them in the developing brain, for instance post natal day 9.

Installation

CCF translator can be installed by running

pip install brainglobe-ccf-translator

Or by cloning this repository and running

pip install -e .

while in the root of the repository.

Currently supported spaces

the name in CCF translator usually copies the name of the atlas in the brainglobe atlasapi.

We also support brainglobe atlas api names which are in existing coordinate frameworks. For instance you can specify osten_mouse and CCF translator will autoconvert this to allen_mouse.

Usage

Transforming points To take a coordinate in one volume and find the equivalent coordinate in a second volume is quite simple in CCF translator.

import numpy as np
import brainglobe_ccf_translator

points = np.array([(286,250,267), (414,247,452)])
pset = brainglobe_ccf_translator.PointSet(points, 'demba_dev_mouse', voxel_size_micron=20, age_PND=56)
pset.transform(target_age=56, target_space='allen_mouse')
print(f"new points are {pset.values}")

new points are [[267 250 286] [452 247 414]]

Transforming volumes by default we downsample the deformation fields to match the resolution of your volume. This is much faster and uses less memory but is slightly less accurate. For a more accurate result set downsample=False in Volume.transform and VolumeSeries.interpolate_series.

All of our transforms assume you retrieved the atlas from the brianglobe-atlasapi. To run the volume examples you will want to install brainglobe-atlasapi using the following

pip install brainglobe-atlasapi

Transforming a volume is equally simple, here we get the volume from the brainglobe api, but you can load it however you like. In the Demba space the valid ages are from 4 to 56, and all of these are valid targets for transformation.

from brainglobe_atlasapi.bg_atlas import BrainGlobeAtlas
import brainglobe_ccf_translator

voxel_size_micron = 10
space_name = r"allen_mouse"
atlas = BrainGlobeAtlas(f"{space_name}_{voxel_size_micron}um")
source_age = 56
target_age= 32

ccft_vol = brainglobe_ccf_translator.Volume(
    values = atlas.reference,
    space = 'allen_mouse',
    voxel_size_micron=voxel_size_micron,
    segmentation_file=False,
    age_PND = source_age
)

ccft_vol.transform(target_age, 'demba_dev_mouse')
ccft_vol.save(rf"demo_data/P{target_age}_template_{voxel_size_micron}um.nii.gz")

Contributing

If you would like to add a new space or connect an existing one, please create a deformation matrix and/or describe the required reorientation, flipping, cropping, and padding of the axis between this space and one that already exists in the network, and then open an issue in this repository. Ideally, choose a space which covers all the areas which are covered in your space. While the Allen CCFv3 is very popular, it is missing the anterior olfactory bulb and the caudal portion of the cerebellum and brain stem, so it is not the optimal choice.

Citation

CCF translator was first described in DeMBA: a developmental atlas for navigating the mouse brain in space and time. If you use CCF translator, please cite that paper.