{"id":20956512,"url":"https://github.com/bluebrain/atlas-annotation","last_synced_at":"2025-08-03T14:08:25.233Z","repository":{"id":37930874,"uuid":"417128872","full_name":"BlueBrain/atlas-annotation","owner":"BlueBrain","description":"Align and improve brain annotation atlases","archived":false,"fork":false,"pushed_at":"2022-11-28T13:57:36.000Z","size":346,"stargazers_count":4,"open_issues_count":7,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-19T21:45:54.391Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://atlas-annotation.rtfd.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BlueBrain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-10-14T12:51:35.000Z","updated_at":"2023-11-01T12:44:25.000Z","dependencies_parsed_at":"2022-08-29T16:51:34.779Z","dependency_job_id":null,"html_url":"https://github.com/BlueBrain/atlas-annotation","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2Fatlas-annotation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2Fatlas-annotation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2Fatlas-annotation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2Fatlas-annotation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BlueBrain","download_url":"https://codeload.github.com/BlueBrain/atlas-annotation/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076977,"owners_count":22010630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T01:26:24.734Z","updated_at":"2025-05-14T05:31:55.693Z","avatar_url":"https://github.com/BlueBrain.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Atlas Annotation\n\n\u003cimg src=\"docs/images/Atlas-Annotation-banner.jpg\"/\u003e\n\nOver the years the Allen Brain institute has constantly improved and updated\ntheir brain region annotation atlases. Unfortunately the old annotation atlases\nare not always aligned with the new ones. For example, the CCFv2 annotations\nand the Nissl volume are not compatible with the CCFv3 annotation and the\ncorresponding average brain volume. This package proposes a number of methods\nfor deforming the Nissl volume and the CCFv2 annotations in order to re-align\nthem to CCFv3.\n\n* [Installation](#installation)\n    * [Python Version and Environment](#python-version-and-environment)\n    * [Install \"Atlas Annotation\"](#install-atlas-annotation)\n* [Data](#data)\n    * [Remote Storage Access](#remote-storage-access)\n    * [Get the Data](#get-the-data)\n* [Examples](#examples)\n* [Notebooks, Widgets, and Experiments](#notebooks-widgets-and-experiments)\n* [Funding \u0026 Acknowledgment](#funding--acknowledgment)\n\n## Installation\n### Python Version and Environment\nThe currently supported python versions are `3.7`, `3.8`, and `3.9`.\n\nIf you are part of the Blue Brain Project and are working on the BB5 you can\nfind the correct python version in the archive modules:\n- `python3.7`: `archive/2020-02` - `archive/2020-12`\n- `python3.8`: `archive/2021-01` - `archive/2021-12`\n- `python3.9`: `archive/2022-01` - `unstable`.\n  Here's an example of a set of commands that will set up your environment on the BB5:\n\n```shell\nmodule purge\nmodule load archive/2020-12\nmodule load python\npython -m venv venv\n. ./venv/bin/activate\npython --version\n```\n\nWe also recommend that you make sure that `pip` is up-to-date and that the\npackages `wheel` and `setuptools` are installed:\n```shell\npip install --upgrade pip wheel setuptools\n```\n\n### Install \"Atlas Annotation\"\nIn order to access the data and the example scripts a local clone of this\nrepository is required. Run these commands to get it:\n```shell\ngit clone https://github.com/BlueBrain/atlas-annotation\ncd atlas-annotation\n```\n\nThe \"Atlas Interpolation\" package can now be installed directly from the clone\nwe just created:\n```shell\npip install '.[data, interactive]'\n```\n\n## Data\nThe data for this project is managed by the [DVC tool](https://dvc.org/) and all\nrelated files are located in the `data` directory. The DVC tool has already been\ninstalled together with the \"Atlas Interpolation\" package. Every time you need\nto run a DVC command (`dvc ...`) make sure to change to the `data` directory\nfirst (`cd data`).\n\n### Remote Storage Access\nWe have already prepared all the data, but it is located on a remote storage\nthat is only accessible to people within the Blue Brain Project who have\naccess permissions to project `proj101`. If you're unsure you can test your\npermissions with the following command:\n```shell\nssh bbpv1.bbp.epfl.ch \\\n\"ls /gpfs/bbp.cscs.ch/data/project/proj101/dvc_remotes\"\n```\nPossible outcomes:\n```shell\n# Access OK\natlas_annotation\natlas_interpolation\n\n# Access denied\nls: cannot open directory [...]: Permission denied\n```\nDepending on whether you have access to the remote storage in the following\nsections you will either pull the data from the remote (`dvc pull`) or download\nthe input data manually and re-run the data processing pipelines to reproduce\nthe output data (`dvc repro`).\n\nIf you work on the BB5 and have access to the remote storage then run the\nfollowing command to short-circuit the remote access (because the remote is\nlocated on the BB5 itself):\n```shell\ncd data\ndvc remote add --local gpfs_proj101 \\\n  /gpfs/bbp.cscs.ch/data/project/proj101/dvc_remotes/atlas_annotation\ncd ..\n```\n\n### Get the Data\nThe purpose of the \"Atlas Annotation\" package is to align brain volumes and\nthe corresponding atlases. This section explains how to get these data.\n\nIf you have access to the remote storage (see above) then all data can be\nreadily pulled from it:\n```shell\ncd data\ndvc pull\ncd ..\n```\n\nIn the case where you don't have access to the remote storage, the data need\nto be downloaded from the original sources and the pre-processing needs to\nbe run. Note that the pre-processing may take a long time (around an hour).\nRun the following commands to start this process:\n```shell\ncd data\ndvc repro\ncd ..\n```\n\nIn some cases you might not need all data. Then it is possible to download\nunprepared data that you need by running specific DVC stages. Refer to the\n[`data/README.md`](data/README.md) file for the description of different data\nfiles.\n\n## Examples\nHere are some examples of the functionalities that one can find in the\n`atlannot` package.\n\n### Registration\nOne can compute the registration between a fixed and a moving image. \nThose images can be of any type (for example Atlas Annotations or simply\nintensity images). The inputs can be 2D or 3D, the only constraint is that they\nhave to be of the same shape.\n\nThe main use-case of `atlannot` is the registration of brain volumes from one\ncoordinate framework to another. It is then needed to allow some flexibility in\nterms of inputs type to accept any data such as regions annotations, intensity\nimages. \n\n```python\nimport numpy as np\n\nfrom atlannot.ants import register, transform\n\nfixed = np.random.rand(20, 20)   # replace by a real image\nmoving = np.random.rand(20, 20)  # replace by a real image\n# Computation of the displacement field from moving image to fixed image.\nnii_data = register(fixed.astype(np.float32), moving.astype(np.float32)) \n# Apply the displacement to moving image.\nwarped = transform(moving.astype(np.float32), nii_data)\n```\n\n### Image Manipulation\n`atlannot` has also a lot of utility functions to manipulate images in order\nto make some pre-processing/post-processing on images.\n\nA concrete example could be to combine a region annotation and an intensity\nimage together and use the final result as an input to the registration.\nTo merge information from both images, one could superpose regions borders of\nthe annotation on top of the intensity image.\n\n```python\nimport numpy as np\nfrom atlannot.utils import edge_laplacian_thin, merge\n\nintensity_img = np.random.rand(20, 20) # Load intensity image here\n\n# Create fake annotation image\nannotation_img = np.zeros((20, 20))    # Load annotation image here\nannotation_img[5:15, 5:15] = 1         # Load annotation image here\n\n# Compute the borders of the annotation image\nborders = edge_laplacian_thin(annotation_img)\n\n# Merge intensity image and annotation image\nmerge_img = merge(intensity_img, borders)\n```\n\nSee here other manipulation one can do on any kind of images:\n```python\nimport numpy as np\nfrom atlannot.utils import (\n  add_middle_line, \n  edge_laplacian_thick, \n  edge_laplacian_thin, \n  edge_sobel, \n  image_convolution,\n  split_halfs,\n)\n\n# Instantiate an image \nimg = np.random.rand(20, 20)  # Please replace by a real image\n\n# Apply some convolution to the image\nkernel = [[-1, -1, -1], [-1, 8, -1], [-1, -1, -1]]\nimg1 = image_convolution(img, kernel=kernel)\nimg2 = edge_laplacian_thick(img)\nimg3 = edge_sobel(img)\nimg4 = edge_laplacian_thick(img)\n\n# Add a middle line, can choose the axis, the tickness, ...\nimg5 = add_middle_line(img, axis=0, thickness=2)\n\n# Split the image into two \nhalf_imgs = split_halfs(img2, axis=0)[0]\n```\n\n### Utilities\nThe `atlannot` contains other utilities:\n- Atlas utilities:\n  - Merge atlases to harmonize the scripts\n  - Unfurl regions if the regions are structured in tree\n  - Compute misalignments\n  - Remapping the labels\n- Notebook utilities:\n  - Volume Viewer to see volume in every directions\n  - Add colored legend to atlas images\n\n### Concrete examples\nYou can find numerous examples of the usage of `atlannot` package in the\nscripts located in the [`experiments`](experiments) directory. \n```shell\ngit clone https://github.com/BlueBrain/atlas-annotation#egg=atlannot\ncd atlas-annotation/experiments\n```\n\nTo execute the scripts in this `experiments` folder, please first follow the\ndata preparation instructions found in the [data](#data) section. \n\nNext, one needs also to install additional packages for interactive use.\n```shell\npip install git+https://github.com/BlueBrain/atlas-annotation#egg=atlannot[interactive]\n```\n\nOnce the cloning, the installation and the download of data is done, you can \nuse any script, for example:\n```shell\npython ants2d_atlas_fine.py\n```\n\n## Notebooks, Widgets, and Experiments\nThe additional functionality related to notebooks, widgets, and experiment\nscripts is not activated by default. In order to use it you need to specify\nan additional `interactive` option upon installing this package. This can\nbe done as follows:\n```shell\npip install git+https://github.com/BlueBrain/atlas-annotation#egg=atlannot[interactive]\n```\n\nFurthermore, you will need JupyterLab or Jupyter Notebook installed in your\nvirtual environment, as well as the corresponding `ipywidgets` plugin. Follow\nthe following online instructions in order to do so:\n- How to install JupyterLab/Jupyter Notebook: https://jupyter.org\n- How to install the `ipywidgets` plugin:\n  https://ipywidgets.readthedocs.io/en/latest/user_install.html\n\n## Funding \u0026 Acknowledgment\nThe development of this software was supported by funding to the Blue Brain\nProject, a research center of the École polytechnique fédérale de Lausanne\n(EPFL), from the Swiss government’s ETH Board of the Swiss Federal Institutes\nof Technology.\n\nCopyright (c) 2021-2022 Blue Brain Project/EPFL\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluebrain%2Fatlas-annotation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluebrain%2Fatlas-annotation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluebrain%2Fatlas-annotation/lists"}