# CCF_translator
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.
## 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 age, for instance post natal day 9.
## Installation
CCF_translator can be installed by running
```
pip install CCF-translator
```
## Currently supported spaces
the name in CCF_translator aims to copy the name of atlases in the brainglobe_atlasapi when possible.
| Framework Name | name in api | supported age range
| -------------- | ----------- | -----------
| Allen mouse CCFv3 | allen_mouse | 56
| Demba developmental mouse | demba_dev_mouse| 4-56
| Gubra lightsheet mouse | perens_lsfm_mouse| 56
| Gubra MRI mouse | perens_mri_mouse| 56
| Gubra STPT mouse | perens_stpt_mouse| 56
| Princeton lighsheet mouse | princeton_mouse| 56
## 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.
```python
import numpy as np
import CCF_translator
points = np.array([(286,250,267), (414,247,452)])
pset = 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**
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.
```python
from brainglobe_atlasapi.bg_atlas import BrainGlobeAtlas
import CCF_translator
voxel_size_micron = 10
space_name = r"allen_mouse"
atlas = BrainGlobeAtlas("{space_name}_{voxel_size_micron}um")
source_age = 56
target_age= 32
CCFT_vol = 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](https://www.biorxiv.org/content/10.1101/2024.06.14.598876v1). If you use CCF_translator, please cite that paper.
Raw data
{
"_id": null,
"home_page": "https://github.com/Neural-Systems-at-UIO/CCF_translator",
"name": "CCF-translator",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "neuroinformatics, brain, atlas, brainglobe, neuroscience",
"author": null,
"author_email": "harry.carey@medisin.uio.no",
"download_url": "https://files.pythonhosted.org/packages/94/ed/5ecbbe469d12191a05a094a78cd6b2482947b4a11954f61bc1926b9d557a/ccf_translator-0.22.tar.gz",
"platform": null,
"description": "# CCF_translator\n\n\nA tool for translating between common coordinate frameworks using deformation matrices. \nA 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. \n\nCCF_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. \n\n\n## Use Cases\nOne 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 age, for instance post natal day 9.\n\n## Installation\nCCF_translator can be installed by running \n```\npip install CCF-translator\n```\n## Currently supported spaces\nthe name in CCF_translator aims to copy the name of atlases in the brainglobe_atlasapi when possible. \n| Framework Name | name in api | supported age range\n| -------------- | ----------- | ----------- \n| Allen mouse CCFv3 | allen_mouse | 56\n| Demba developmental mouse | demba_dev_mouse| 4-56\n| Gubra lightsheet mouse | perens_lsfm_mouse| 56\n| Gubra MRI mouse | perens_mri_mouse| 56\n| Gubra STPT mouse | perens_stpt_mouse| 56\n| Princeton lighsheet mouse | princeton_mouse| 56\n## Usage\n**Transforming points**\nTo take a coordinate in one volume and find the equivalent coordinate in a second volume is quite simple in CCF_translator. \n```python\nimport numpy as np\nimport CCF_translator\n\npoints = np.array([(286,250,267), (414,247,452)])\npset = CCF_translator.PointSet(points, 'demba_dev_mouse', voxel_size_micron=20, age_PND=56)\npset.transform(target_age=56, target_space='allen_mouse')\nprint(f\"new points are {pset.values}\")\n\n```\n```\nnew points are [[267 250 286] [452 247 414]]\n ```\n**Transforming volumes**\n\nTo run the volume examples you will want to install brainglobe-atlasapi using the following\n```\npip install brainglobe-atlasapi\n```\n\nTransforming 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. \n```python\nfrom brainglobe_atlasapi.bg_atlas import BrainGlobeAtlas\nimport CCF_translator\n\n\nvoxel_size_micron = 10\nspace_name = r\"allen_mouse\"\natlas = BrainGlobeAtlas(\"{space_name}_{voxel_size_micron}um\")\nsource_age = 56\ntarget_age= 32\n\nCCFT_vol = CCF_translator.Volume(\n values = atlas.reference,\n space = 'allen_mouse',\n voxel_size_micron=voxel_size_micron,\n segmentation_file=False,\n age_PND = source_age\n)\n\nCCFT_vol.transform(target_age, 'demba_dev_mouse')\nCCFT_vol.save(rf\"demo_data/P{target_age}_template_{voxel_size_micron}um.nii.gz\")\n```\n## Contributing\nIf 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. \n\n## Citation\nCCF_translator was first described in [DeMBA: a developmental atlas for navigating the mouse brain in space and time](https://www.biorxiv.org/content/10.1101/2024.06.14.598876v1). If you use CCF_translator, please cite that paper.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "a package to translate data between common coordinate templates",
"version": "0.22",
"project_urls": {
"Homepage": "https://github.com/Neural-Systems-at-UIO/CCF_translator"
},
"split_keywords": [
"neuroinformatics",
" brain",
" atlas",
" brainglobe",
" neuroscience"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "68f42328b8e876c9f73d7e344ad8cedb64e81f0eefa8e5f602b43e5c4c017755",
"md5": "7b4af1a77278159d53ae1de7e5c6d7da",
"sha256": "9c74638c50fd1eb04a4536134efd2a8d93bbf53fda770d69868ecfef4c36c962"
},
"downloads": -1,
"filename": "CCF_translator-0.22-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b4af1a77278159d53ae1de7e5c6d7da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 24508,
"upload_time": "2024-10-14T12:13:22",
"upload_time_iso_8601": "2024-10-14T12:13:22.178478Z",
"url": "https://files.pythonhosted.org/packages/68/f4/2328b8e876c9f73d7e344ad8cedb64e81f0eefa8e5f602b43e5c4c017755/CCF_translator-0.22-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "94ed5ecbbe469d12191a05a094a78cd6b2482947b4a11954f61bc1926b9d557a",
"md5": "6fa89cb26b552fdca9f4b0c82d5e0a51",
"sha256": "f55acfab54c48fca9422063b5a9caf7cc83fae15a0ef08b7437e0f61696798d8"
},
"downloads": -1,
"filename": "ccf_translator-0.22.tar.gz",
"has_sig": false,
"md5_digest": "6fa89cb26b552fdca9f4b0c82d5e0a51",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23679,
"upload_time": "2024-10-14T12:13:23",
"upload_time_iso_8601": "2024-10-14T12:13:23.701436Z",
"url": "https://files.pythonhosted.org/packages/94/ed/5ecbbe469d12191a05a094a78cd6b2482947b4a11954f61bc1926b9d557a/ccf_translator-0.22.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-14 12:13:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Neural-Systems-at-UIO",
"github_project": "CCF_translator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ccf-translator"
}
JSON
