[](https://zenodo.org/badge/latestdoi/274122364)
DeepSlice is a python library which automatically aligns mouse histology with the allen brain atlas common coordinate framework (and now rat brain histology to the Waxholm rat brain atlas, though this is in beta).
The alignments are viewable, and refinable, using the [QuickNII](https://www.nitrc.org/projects/quicknii "QuickNII") software package.
DeepSlice requires no preprocessing and works on any stain, however we have found it performs best on brightfield images.
At present one limitation is that it only works on Coronally cut sections, we will release an update in the future for sagittal and horizontally cut histology.
DeepSlice automates the process of identifying exactly where in the brain a section lies, it can accomodate non-orthogonal cutting planes and will produce an image specific annotation for each section in your brain.
## Citation
If you use DeepSlice in your work please cite [Carey et al, 2023](https://www.nature.com/articles/s41467-023-41645-4). It may also be useful if you mention the version you use :)
## Workflow
DeepSlice is fully integrated with the <a href="https://quint-workflow.readthedocs.io/en/latest/QUINTintro.html" >QUINT workflow.</a> Quint helps you register, segment and quantify brain wide datasets! 🐭🧠🔬💻🤖
## Web Application
If you would like to use DeepSlice but don't need your own personal installation, check out [**DeepSlice Flask**](https://www.DeepSlice.com.au), a fully functional web application which will allow you to upload your dataset and download the aligned results. The web interface was developed by [Michael Pegios](https://github.com/ThermoDev/).
## [Installation: How to install DeepSlice](#installation)
## [Usage: How to align using DeepSlice](#basic-usage)
## [For a jupyter notebook example check out](examples/example_notebooks/DeepSlice_example.ipynb)
**Happy Aligning :)**
<br>
<a name='Installation'></a>
<h1> Installation </h1>
<!-- This h2 must be bold -->
<h2 style="font-weight: bold; text-decoration: underline"> From PIP </h2>
This is the easy and recommended way to install DeepSlice, simply:
```bash
pip install DeepSlice
```
And you're ready to go! 🚀 Check out the PyPi package [here](https://pypi.org/project/DeepSlice/)
<h2 style="font-weight: bold; text-decoration: underline"> From Source </h2>
**First** In order to easily install all the dependancies we recommend using [Anaconda](https://www.anaconda.com/products/individual "Anaconda Installation Files").
**Second** Once anaconda is installed, cd into your cloned DeepSlice directory, then cd into the 'conda_environments' directory, and use our premade environment files to setup your system.
```
cd DeepSlice/conda_environments
```
* **CPU Installation** For most users we recommend using the DS-CPU.yaml installation file. this will install all the dependencies required to run DeepSlice on your CPU.
Do this with the command:
conda env create -f DS-CPU.yml
* **GPU Installation** If you wish to run DeepSlice on a huge number of images, and have access to an nvidia GPU then please use the DS-GPU.yaml installation file.
conda env create -f DS-GPU.yml
**Finished :)** You are now ready to run DeepSlice. Just activate the environment using
```python
conda activate DS-CPU
```
or
```python
conda activate DS-GPU
```
If you run into any problems create a github issue and I will help you solve it.
<br>
<a name='BasicUsage'></a>
# Basic Usage
## On start
After cloning our repo and navigating into the directory open an ipython session and import our package.
```python
from DeepSlice import DSModel
```
Next, specify the species you would like to use and initiate the model.
```python
species = 'mouse' #available species are 'mouse' and 'rat'
Model = DSModel(species)
```
---
**Important**
* Sections in a folder must all be from the same brain
* DeepSlice uses all the sections you select to inform its prediction of section angle. Thus it is important that you do not include sections which lie outside of the Allen Brain Atlas. This include extremely rostral olfactory bulb and caudal medulla. **If you include these sections in your selected folder it will reduce the quality of all the predictions**.
* The sections do not need to be in any kind of order.
* The model downsamples images to 299x299, you do not need to worry about this but be aware that there is no benefit from using higher resolutions.
------
## Predictions
Now your model is ready to use, just direct it towards the folder containing the images you would like to align.
<br/> eg:
```bash
├── your_brain_folder
│ ├── brain_slice_1.png
│ ├── brain_slice_2.png
│ ├── brain_slice_3.png
```
In this parent directory there should be only one sub folder, in this example this is "your_brain_folder".
<br />To align these images using DeepSlice simply call
```python
folderpath = 'examples/example_brain/GLTa/'
#here you run the model on your folder
#try with and without ensemble to find the model which best works for you
#if you have section numbers included in the filename as _sXXX specify this :)
Model.predict(folderpath, ensemble=True, section_numbers=True)
#If you would like to normalise the angles (you should)
Model.propagate_angles()
#To reorder your sections according to the section numbers
Model.enforce_index_order()
#alternatively if you know the precise spacing (ie; 1, 2, 4, indicates that section 3 has been left out of the series) Then you can use
#Furthermore if you know the exact section thickness in microns this can be included instead of None
#if your sections are numbered rostral to caudal you will need to specify a negative section_thickness
Model.enforce_index_spacing(section_thickness = None)
#now we save which will produce a json file which can be placed in the same directory as your images and then opened with QuickNII.
Model.save_predictions(folderpath + 'MyResults')
```
## Acknowledgements
We are grateful to Ann Goodchild for her time-saving blunt assessments of many failed prototypes, for the motivation provided by Dr William Redmond, and especially to Veronica Downs, Freja Warner Van Dijk and Jayme McCutcheon, whose Novice alignments were instrumental to this work. We would like to thank Gergely Csúcs for providing his expertise and many atlasing tools. Work in the authors’ laboratories is supported by the National Health & Medical Research Council of Australia, the Hillcrest Foundation, and Macquarie University (SMcM), and from the European Union’s Horizon 2020 Framework Program for Research and Innovation under the Specific Grant Agreement No. 945539 (Human Brain Project SGA3) and the Research Council of Norway under Grant Agreement No. 269774 (INCF, JGB). We are grateful to Macquarie University for access to their HPC resources, essential for production of early DeepSlice prototypes.
Raw data
{
"_id": null,
"home_page": "https://github.com/PolarBean/DeepSlice",
"name": "DeepSlice",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "histology, brain, atlas, alignment",
"author": "DeepSlice Team",
"author_email": "harry.carey@medisin.uio.no",
"download_url": "https://files.pythonhosted.org/packages/91/bd/b0dd33e6b278007c4a50bbfeedcfc2e5d0e3a712cd86eb4cd448c7259af9/deepslice-1.2.4.tar.gz",
"platform": null,
"description": "\n\n[](https://zenodo.org/badge/latestdoi/274122364)\n\n\n![Alt](docs/images/DeepSlice_github_banner.png \"DeepSlice Banner\")\nDeepSlice is a python library which automatically aligns mouse histology with the allen brain atlas common coordinate framework (and now rat brain histology to the Waxholm rat brain atlas, though this is in beta).\nThe alignments are viewable, and refinable, using the [QuickNII](https://www.nitrc.org/projects/quicknii \"QuickNII\") software package.\nDeepSlice requires no preprocessing and works on any stain, however we have found it performs best on brightfield images.\nAt present one limitation is that it only works on Coronally cut sections, we will release an update in the future for sagittal and horizontally cut histology.\n \nDeepSlice automates the process of identifying exactly where in the brain a section lies, it can accomodate non-orthogonal cutting planes and will produce an image specific annotation for each section in your brain. \n## Citation\nIf you use DeepSlice in your work please cite [Carey et al, 2023](https://www.nature.com/articles/s41467-023-41645-4). It may also be useful if you mention the version you use :)\n\n## Workflow \nDeepSlice is fully integrated with the <a href=\"https://quint-workflow.readthedocs.io/en/latest/QUINTintro.html\" >QUINT workflow.</a> Quint helps you register, segment and quantify brain wide datasets! \ud83d\udc2d\ud83e\udde0\ud83d\udd2c\ud83d\udcbb\ud83e\udd16\n\n## Web Application\nIf you would like to use DeepSlice but don't need your own personal installation, check out [**DeepSlice Flask**](https://www.DeepSlice.com.au), a fully functional web application which will allow you to upload your dataset and download the aligned results. The web interface was developed by [Michael Pegios](https://github.com/ThermoDev/).\n## [Installation: How to install DeepSlice](#installation)\n\n## [Usage: How to align using DeepSlice](#basic-usage)\n## [For a jupyter notebook example check out](examples/example_notebooks/DeepSlice_example.ipynb)\n\n**Happy Aligning :)**\n\n\n<br>\n\n\n<a name='Installation'></a> \n<h1> Installation </h1>\n<!-- This h2 must be bold -->\n\n<h2 style=\"font-weight: bold; text-decoration: underline\"> From PIP </h2>\nThis is the easy and recommended way to install DeepSlice, simply:\n\n```bash\npip install DeepSlice\n```\nAnd you're ready to go! \ud83d\ude80 Check out the PyPi package [here](https://pypi.org/project/DeepSlice/)\n\n<h2 style=\"font-weight: bold; text-decoration: underline\"> From Source </h2>\n\n**First** In order to easily install all the dependancies we recommend using [Anaconda](https://www.anaconda.com/products/individual \"Anaconda Installation Files\"). \n\n\n**Second** Once anaconda is installed, cd into your cloned DeepSlice directory, then cd into the 'conda_environments' directory, and use our premade environment files to setup your system. \n```\ncd DeepSlice/conda_environments\n```\n* **CPU Installation** For most users we recommend using the DS-CPU.yaml installation file. this will install all the dependencies required to run DeepSlice on your CPU. \nDo this with the command: \n\n conda env create -f DS-CPU.yml\n\n\n* **GPU Installation** If you wish to run DeepSlice on a huge number of images, and have access to an nvidia GPU then please use the DS-GPU.yaml installation file.\n\n conda env create -f DS-GPU.yml\n\n**Finished :)** You are now ready to run DeepSlice. Just activate the environment using \n```python\nconda activate DS-CPU\n```\nor \n```python \nconda activate DS-GPU\n```\nIf you run into any problems create a github issue and I will help you solve it.\n\n<br>\n\n<a name='BasicUsage'></a> \n# Basic Usage \n## On start \nAfter cloning our repo and navigating into the directory open an ipython session and import our package. \n```python \nfrom DeepSlice import DSModel \n``` \nNext, specify the species you would like to use and initiate the model. \n```python \nspecies = 'mouse' #available species are 'mouse' and 'rat'\n\nModel = DSModel(species)\n``` \n\n---\n**Important**\n\n* Sections in a folder must all be from the same brain\n\n* DeepSlice uses all the sections you select to inform its prediction of section angle. Thus it is important that you do not include sections which lie outside of the Allen Brain Atlas. This include extremely rostral olfactory bulb and caudal medulla. **If you include these sections in your selected folder it will reduce the quality of all the predictions**.\n\n* The sections do not need to be in any kind of order. \n\n* The model downsamples images to 299x299, you do not need to worry about this but be aware that there is no benefit from using higher resolutions.\n\n------\n\n## Predictions\n\nNow your model is ready to use, just direct it towards the folder containing the images you would like to align. \n<br/> eg: \n```bash \n \n \u251c\u2500\u2500 your_brain_folder\n \u2502 \u251c\u2500\u2500 brain_slice_1.png \n \u2502 \u251c\u2500\u2500 brain_slice_2.png \n \u2502 \u251c\u2500\u2500 brain_slice_3.png\n``` \nIn this parent directory there should be only one sub folder, in this example this is \"your_brain_folder\". \n<br />To align these images using DeepSlice simply call \n```python \nfolderpath = 'examples/example_brain/GLTa/'\n#here you run the model on your folder\n#try with and without ensemble to find the model which best works for you\n#if you have section numbers included in the filename as _sXXX specify this :)\nModel.predict(folderpath, ensemble=True, section_numbers=True) \n#If you would like to normalise the angles (you should)\nModel.propagate_angles() \n#To reorder your sections according to the section numbers \nModel.enforce_index_order() \n#alternatively if you know the precise spacing (ie; 1, 2, 4, indicates that section 3 has been left out of the series) Then you can use \n#Furthermore if you know the exact section thickness in microns this can be included instead of None\n#if your sections are numbered rostral to caudal you will need to specify a negative section_thickness \nModel.enforce_index_spacing(section_thickness = None)\n#now we save which will produce a json file which can be placed in the same directory as your images and then opened with QuickNII. \nModel.save_predictions(folderpath + 'MyResults') \n\n\n\n```\n## Acknowledgements\nWe are grateful to Ann Goodchild for her time-saving blunt assessments of many failed prototypes, for the motivation provided by Dr William Redmond, and especially to Veronica Downs, Freja Warner Van Dijk and Jayme McCutcheon, whose Novice alignments were instrumental to this work. We would like to thank Gergely Cs\u00facs for providing his expertise and many atlasing tools. Work in the authors\u2019 laboratories is supported by the National Health & Medical Research Council of Australia, the Hillcrest Foundation, and Macquarie University (SMcM), and from the European Union\u2019s Horizon 2020 Framework Program for Research and Innovation under the Specific Grant Agreement No. 945539 (Human Brain Project SGA3) and the Research Council of Norway under Grant Agreement No. 269774 (INCF, JGB). We are grateful to Macquarie University for access to their HPC resources, essential for production of early DeepSlice prototypes.\n\n\n\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "A package to align histology to 3D brain atlases",
"version": "1.2.4",
"project_urls": {
"Download": "https://github.com/PolarBean/DeepSlice/archive/refs/tags/1.2.4.tar.gz",
"Homepage": "https://github.com/PolarBean/DeepSlice"
},
"split_keywords": [
"histology",
" brain",
" atlas",
" alignment"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a02b7e53cdbaf680e68e5a9751671e06dcdb1b29f381d68ba0ab364ea2ff25fb",
"md5": "7ec496c5a83aa5fdc72644ea9d3f9254",
"sha256": "61c4bf2819e4b977849b4a2555ad2c72fbe3f81295d6dcd78923bf3c99577ef7"
},
"downloads": -1,
"filename": "DeepSlice-1.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7ec496c5a83aa5fdc72644ea9d3f9254",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 24978,
"upload_time": "2024-06-06T14:35:45",
"upload_time_iso_8601": "2024-06-06T14:35:45.774147Z",
"url": "https://files.pythonhosted.org/packages/a0/2b/7e53cdbaf680e68e5a9751671e06dcdb1b29f381d68ba0ab364ea2ff25fb/DeepSlice-1.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "91bdb0dd33e6b278007c4a50bbfeedcfc2e5d0e3a712cd86eb4cd448c7259af9",
"md5": "02e22dac0e4ce341cacb0e5f34de66c6",
"sha256": "fc3a01878d3aa32871c09a3e3f3ed6311a990e1610f22bf33f33864a321e3d5d"
},
"downloads": -1,
"filename": "deepslice-1.2.4.tar.gz",
"has_sig": false,
"md5_digest": "02e22dac0e4ce341cacb0e5f34de66c6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20879,
"upload_time": "2024-06-06T14:35:47",
"upload_time_iso_8601": "2024-06-06T14:35:47.010065Z",
"url": "https://files.pythonhosted.org/packages/91/bd/b0dd33e6b278007c4a50bbfeedcfc2e5d0e3a712cd86eb4cd448c7259af9/deepslice-1.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-06 14:35:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PolarBean",
"github_project": "DeepSlice",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "deepslice"
}
JSON
