{"id":20956427,"url":"https://github.com/bluebrain/deep-atlas","last_synced_at":"2026-03-14T03:37:34.087Z","repository":{"id":37464589,"uuid":"414882740","full_name":"BlueBrain/Deep-Atlas","owner":"BlueBrain","description":null,"archived":false,"fork":false,"pushed_at":"2024-01-08T12:11:50.000Z","size":2088,"stargazers_count":5,"open_issues_count":22,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T13:22:31.760Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-10-08T07:08:02.000Z","updated_at":"2024-04-20T10:47:49.000Z","dependencies_parsed_at":"2023-12-12T15:29:40.522Z","dependency_job_id":"5d5afce3-8aff-4e78-9c99-ec3a30cbaa0f","html_url":"https://github.com/BlueBrain/Deep-Atlas","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2FDeep-Atlas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2FDeep-Atlas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2FDeep-Atlas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2FDeep-Atlas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BlueBrain","download_url":"https://codeload.github.com/BlueBrain/Deep-Atlas/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:25:54.334Z","updated_at":"2026-03-14T03:37:34.031Z","avatar_url":"https://github.com/BlueBrain.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Deep Atlas\nDeep Atlas is a suite of tools created by the Blue Brain Project to manipulate\nbrain atlas images. \n\n## Full pipeline\nSee below a simplified sketch of the entire pipeline.\n\u003cimg alt=\"Atlas Download Tools Banner\" src=\"images/pipeline.svg\" width=\"900\"/\u003e\n\nNote that a lot of details are omitted and the user is encouraged to read\nthe `--help` of relevant scripts.\n\nAll the scripts are lying in the `pipeline/` directory.\n\n```bash\npipeline/\n├── download_gene.py\n├── full_pipeline.py\n├── gene_to_nissl.py\n├── interpolate_gene.py\n├── nissl_to_ccfv3.py\n```\n\nTo run the entire pipeline one needs to use `full_pipeline.py`. However,\nit is also possible to run different stages of the pipeline separately.\n\n### `full_pipeline.py`\n\nSee below the `--help` of the `full_pipeline.py` script.\n\n```bash\nusage: full_pipeline.py [-h] --nissl-path NISSL_PATH --ccfv2-path CCFV2_PATH --experiment-id EXPERIMENT_ID --output-dir OUTPUT_DIR [--ccfv3-path CCFV3_PATH] [--coordinate-sys {ccfv2,ccfv3}] [--downsample-img DOWNSAMPLE_IMG]\n                        [--interpolator-name {linear,rife,cain,maskflownet,raftnet}] [--interpolator-checkpoint INTERPOLATOR_CHECKPOINT] [-e] [-f]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --nissl-path NISSL_PATH\n                        Path to Nissl Volume. (default: None)\n  --ccfv2-path CCFV2_PATH\n                        Path to CCFv2 Volume. (default: None)\n  --experiment-id EXPERIMENT_ID\n                        Experiment ID from Allen Brain to use. (default: None)\n  --output-dir OUTPUT_DIR\n                        Path to directory where to save the results. (default: None)\n  --ccfv3-path CCFV3_PATH\n                        Path to CCFv3 Volume. (default: None)\n  --coordinate-sys {ccfv2,ccfv3}\n                        Downsampling coefficient for the image download. (default: ccfv2)\n  --downsample-img DOWNSAMPLE_IMG\n                        Downsampling coefficient for the image download. (default: 0)\n  --interpolator-name {linear,rife,cain,maskflownet,raftnet}\n                        Name of the interpolator model. (default: rife)\n  --interpolator-checkpoint INTERPOLATOR_CHECKPOINT\n                        Path of the interpolator checkpoints. (default: None)\n  -e, --expression      If True, download and apply deformation to threshold images too. (default: False)\n  -f, --force           If True, force to recompute every steps. (default: False)\n```\n\nThe user is supposed to provide the following inputs (positional arguments)\n\n* `nissl_path` - path to a Nissl volume\n* `ccfv2_path` - path to an annotation volume in the CCFv2 reference space\n* `ccfv3_path` - path to an annotation volume in the CCFv3 reference space\n  (needed only if the `coordinate system` chosen is `CCFv3`)\n* `experiment_id` - unique identifier of the ISH experiment\n* `output_dir` - directory where to save the results\n\n\nNote that there are multiple optional arguments. For example, one\ncan decide what coordinate system to use - `ccfv2` or `ccfv3`. By providing\nthe flag `--expression` preprocessed expression images are going to be\nincluded. Finally, one can also pass stage specific parameters \n(e.g. `--interpolator-name` for the interpolation stage).\n\nConcerning the interpolation part, machine learning models are used to make \nthose predictions (except if the interpolator chosen is `linear`). It is then\nneeded to download the model and to specify to path through the \n`--interpolator-checkpoint` variable. To download the models, please follow the\ninstructions specified in the atlinter documentation \n[here](https://github.com/BlueBrain/atlas-interpolation#data).\n\n\n## Docker\nWe provide a docker file that allows you to run the `pipeline` on a docker container. \nTo build the docker image run the following command:\n\n```bash\ndocker build -f docker/Dockerfile -t deep-atlas-pipeline .\n```\nTo run the container use the following command:\n```bash\ndocker run --rm -it deep-atlas-pipeline\n```\n### Specify user and group ids\n\nBy default, the user within the docker container is `guest`, its id is 1000, and its group is 999. \\\nFiles created by this user within the container might not be accessible to the user running \nthe container, if their ids do not match. \\\nIf one wants to configure a specific user, one needs to adapt the `docker/Dockerfile` file, \nchanging the following lines with the users .\n```bash\nARG DEAL_USER_IDS\nARG DEAL_GROUP_ID=${DEAL_GROUP_ID:-999}\n```\nThe list of users has a comma separated list of users with the format `\u003cusername\u003e/\u003cuserid\u003e`. \\\nOnly one group id should be provided. The default user group is therefore recommended.\n\nAlternatively, one can define the environment variable and add this info \nto the CLI command of `docker build`\n```bash\nexport DEAL_USER_IDS=\"$(whoami)/$(id -u)\"\nexport DEAL_GROUP_ID=$(id -g)\ndocker build -f docker/Dockerfile -t deep-atlas-pipeline \\\n--build-arg DEAL_USER_IDS --build-arg DEAL_GROUP_ID .\n```\n\nTo specify the user to use when running the container, use the following command:\n```bash\ndocker run --rm -it -u \u003cusername\u003e  deep-atlas-pipeline\n```\n\n## Singularity for BB5\nDocker is not supported in BB5 and [singularity](https://docs.sylabs.io/guides/3.5/user-guide/introduction.html) will be used instead.\n1) ssh into BB5. \n\n`ssh bbpv1` or `ssh bbpv1.epfl.ch`.\n\n2) Allocate an interactive session using Slurm. Note that you have to use a `projectID` that you have permissions for.\n```bash\nsalloc \\\n--nodes 1 \\\n--account proj\u003cX\u003e \\\n--partition interactive \\\n--constraint volta \\\n--time 1:00:00 \\\n--ntasks-per-node 36\n```\nor with a shorter notation\n```bash\nsalloc -N 1 -A proj\u003cX\u003e -p interactive -C volta -t 1:00:00 --ntasks-per-node 36\n```\n3) Load the singularity module.\n```bash\nmodule load unstable singularityce\n```\n4) Pull the docker image from GitLab.\n```bash\nsingularity pull --docker-login --no-https docker://bbpgitlab.epfl.ch:5050/ml/deep-atlas:cuda10.2\n```\nA new file named `deep-atlas_cuda10.2.sif` will be created. This is your singularity image.\n\n5) Run the singularity container:\n```bash\nsingularity exec --cleanenv --nv --containall --bind $TMPDIR:/tmp,/gpfs/bbp.cscs.ch/project,$HOME:/home deep-atlas_cuda10.2.sif bash\n```\nThere is no write access inside the singularity container. Results have to be written, for instance, to the `/home` directory that is linked to the `$HOME` of BB5 or to `GPFS` mounted at `/gpfs`. (see the option `--bind` above)\n\n## Dependencies\nThe full pipeline depends on multiple other projects.\n- [Atlas Download Tools](#atlas-download-tools) — Search, download, and prepare\n  atlas data.\n- [Atlas Alignment](#atlas-alignment) — Perform multimodal image registration\n  and alignment.\n- [Atlas Annotation](#atlas-annotation) — Image registration for region\n  annotation atlases.\n- [Atlas Interpolation](#atlas-interpolation) — Slice interpolation for atlases.\n\nEach of the projects is described in more detail below.\n\n### Atlas Download Tools\n\u003cimg alt=\"Atlas Download Tools Banner\" src=\"images/Atlas-Download-Tools-banner.jpg\" width=\"600\"/\u003e\n\nUseful links:\n[GitHub repo](https://github.com/BlueBrain/Atlas-Download-Tools),\n[Docs](https://atlas-download-tools.readthedocs.io).\n\n**Search, download, and prepare atlas data.**\n\nAmong different sources of data, Allen Brain Institute hosts a rich database of\ngene expression images, Nissl volumes, and annotation atlases. The\nAtlas-Download-Tools library can help you to download single section images and\nentire datasets, as well as the corresponding metadata. It can further\npre-process the image data to place it in the standard reference space.\n\n\n### Atlas Alignment\n\u003cimg alt=\"Atlas Alignment Banner\" src=\"images/Atlas_Alignment_banner.jpg\" width=\"600\"/\u003e\n\nUseful links:\n[GitHub repo](https://github.com/BlueBrain/atlas-alignment),\n[Docs](https://atlas-alignment.readthedocs.io).\n\n**Multimodal registration and alignment toolbox.**\n\nAtlas Alignment is a toolbox to perform multimodal image registration. It\nincludes both traditional and supervised deep learning models. This project\noriginated from the Blue Brain Project efforts on aligning mouse brain atlases\nobtained with ISH gene expression and Nissl stains.\n\n### Atlas Annotation\n\u003cimg alt=\"Atlas Annotation Banner\" src=\"images/Atlas-Annotation-banner.jpg\" width=\"600\"/\u003e\n\nUseful links:\n[GitHub repo](https://github.com/BlueBrain/atlas-annotation),\n[Docs](https://atlas-annotation.readthedocs.io).\n\n**Align and improve brain annotation atlases.**\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### Atlas Interpolation\n\u003cimg alt=\"Atlas Interpolation Banner\" src=\"images/Atlas-Interpolation.jpg\" width=\"600\"/\u003e\n\nUseful links:\n[GitHub repo](https://github.com/BlueBrain/atlas-interpolation),\n[Docs](https://atlas-interpolation.readthedocs.io).\n\n**Interpolate missing section images in gene expression volumes.**\n\nThe Allen Brain Institute hosts a rich database of mouse brain imagery. It\ncontains a large number of gene expression datasets obtained\nthrough the in situ hybridization (ISH) staining. While for a given gene\na number of datasets corresponding to different specimen can be found, each of\nthese datasets only contains sparse section images that do not form a\ncontinuous volume. This package explores techniques that allow to interpolate\nthe missing slices and thus reconstruct whole gene expression volumes.\n\n\n# Funding \u0026 Acknowledgment\nThe development of this software was supported by funding to the Blue Brain Project, a research center of the École polytechnique fédérale de Lausanne (EPFL), from the Swiss government's ETH Board of the Swiss Federal Institutes of Technology.\n \nCopyright © 2021-2022 Blue Brain Project/EPFL\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluebrain%2Fdeep-atlas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluebrain%2Fdeep-atlas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluebrain%2Fdeep-atlas/lists"}