From c931260644163c34193c8a3049604ef41fc02021 Mon Sep 17 00:00:00 2001 From: Mike Gevaert Date: Wed, 14 May 2025 13:43:47 +0200 Subject: [PATCH 1/6] initial atlas doc --- docs/API.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/API.md b/docs/API.md index 474b5f28..d4dece1f 100644 --- a/docs/API.md +++ b/docs/API.md @@ -212,6 +212,48 @@ GET /reconstruction-morphology?within_brain_region_hierarchy_id=3f41b5b5-4b62-40 In other words, the name of the hierarchy, and the id which will be recursively included. This can happen in either by the `descendants` (the default) or by `ascendants`. +# Brain Atlas: + +A BrainAtlas is an volumetric concept describing the locatations of brain regions in space. +It is composed of an `annotation` (also known as `parecellation`) of a voxels, storred in an NRRD file. +Each of the voxels is assigned an ID, which corresponds to `annotation_value` in the hierarchy. +In addition, there is metadata assocated with an atlas: + + # the volume of each region + # meshes of regions + +The following endpoints exist: + +`GET brain-atlas` + +Returns all the atlases that exist + +`GET brain-atlas/$UUID` + +Returns metadata about the atlas: + +``` +{ + "creation_date": "2025-05-09T13:32:18.034672Z", + "id": $UUID, + "name": "human_v0.1.1", + "species_id": $UUID, + "hierarchy_id: $UUID, + "update_date": "2025-05-09T13:32:18.034672Z" +} +``` + + +`GET brain-atlas/$UUID/regions` + +[{ + "brain_region_id: $UUID, + "volume": 33 +}] +The volume is in um^3. +Note: It returns only the leaf-nodes, and is meant to be used with the associated hierarchy. +By only storing the leaf nodes, it composes with the different views by clibing the tree, and summing all the children along the way. + # Authorization: Current model is to have `Entity`s (ex: `EModel`, `ReconstructionMorphology`, etc) be either public, or private to a project. As such, results returned will be gated by this, based on the logged in user. From 77763d10f5727a33db44f8427c0e64697c612c8e Mon Sep 17 00:00:00 2001 From: Mike Gevaert Date: Thu, 15 May 2025 11:07:49 +0200 Subject: [PATCH 2/6] review --- docs/API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/API.md b/docs/API.md index d4dece1f..7dd98d6a 100644 --- a/docs/API.md +++ b/docs/API.md @@ -215,7 +215,7 @@ This can happen in either by the `descendants` (the default) or by `ascendants`. # Brain Atlas: A BrainAtlas is an volumetric concept describing the locatations of brain regions in space. -It is composed of an `annotation` (also known as `parecellation`) of a voxels, storred in an NRRD file. +It is composed of an `annotation` (also known as `parecellation`) of voxels, storred in an NRRD file. Each of the voxels is assigned an ID, which corresponds to `annotation_value` in the hierarchy. In addition, there is metadata assocated with an atlas: From e6dddf9b04fe401a87091fd9463c03cea7289db2 Mon Sep 17 00:00:00 2001 From: Mike Gevaert Date: Fri, 23 May 2025 15:26:54 +0200 Subject: [PATCH 3/6] update docs to reflect implementation --- docs/API.md | 48 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 35 insertions(+), 13 deletions(-) diff --git a/docs/API.md b/docs/API.md index 7dd98d6a..d009d2d2 100644 --- a/docs/API.md +++ b/docs/API.md @@ -234,25 +234,47 @@ Returns metadata about the atlas: ``` { - "creation_date": "2025-05-09T13:32:18.034672Z", - "id": $UUID, - "name": "human_v0.1.1", - "species_id": $UUID, - "hierarchy_id: $UUID, - "update_date": "2025-05-09T13:32:18.034672Z" -} + "creation_date": ..., + "hierarchy_id": $UUID, + "id": str(brain_atlas.id), + "name": "test brain atlas", + "species": { + "creation_date": ..., + "id": species_id, + "name": "Test Species", + "taxonomy_id": "12345", + "update_date": ..., + }, + "update_date": ANY, + } ``` `GET brain-atlas/$UUID/regions` + [ + { + "brain_atlas_id": $UUID, + "brain_region_id": $UUID, + "creation_date": ..., + "id": $UUID, + "leaf_region": False, + "update_date": ..., + "volume": -1_000_000.0, # this is negative, since it's a leaf region; + }, + { + "brain_atlas_id": $UUID, + "brain_region_id": $UUID, + "creation_date": ..., + "id": $UUID, + "leaf_region": False, + "update_date": ..., + "volume": 123456789.0, + }, + .... + ] -[{ - "brain_region_id: $UUID, - "volume": 33 -}] The volume is in um^3. -Note: It returns only the leaf-nodes, and is meant to be used with the associated hierarchy. -By only storing the leaf nodes, it composes with the different views by clibing the tree, and summing all the children along the way. +By only storing the volume for leaf nodes, it composes with the different views by clibing the tree, and summing all the children along the way. # Authorization: Current model is to have `Entity`s (ex: `EModel`, `ReconstructionMorphology`, etc) be either public, or private to a project. From cb759d0d75bb78feb69f8b1e73e06e9fe5730d92 Mon Sep 17 00:00:00 2001 From: jdcourcol Date: Tue, 27 May 2025 11:24:05 +0000 Subject: [PATCH 4/6] small typos --- docs/API.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/API.md b/docs/API.md index d009d2d2..6fad2fd4 100644 --- a/docs/API.md +++ b/docs/API.md @@ -215,7 +215,7 @@ This can happen in either by the `descendants` (the default) or by `ascendants`. # Brain Atlas: A BrainAtlas is an volumetric concept describing the locatations of brain regions in space. -It is composed of an `annotation` (also known as `parecellation`) of voxels, storred in an NRRD file. +It is composed of an `annotation` (also known as `parcellation`) of voxels, storred in an NRRD file. Each of the voxels is assigned an ID, which corresponds to `annotation_value` in the hierarchy. In addition, there is metadata assocated with an atlas: @@ -274,7 +274,7 @@ Returns metadata about the atlas: ] The volume is in um^3. -By only storing the volume for leaf nodes, it composes with the different views by clibing the tree, and summing all the children along the way. +By only storing the volume for leaf nodes, it composes with the different views by climbing the tree, and summing all the children along the way. # Authorization: Current model is to have `Entity`s (ex: `EModel`, `ReconstructionMorphology`, etc) be either public, or private to a project. From 497106a264bf38d0aa972d1888ad76a7fcc34a8d Mon Sep 17 00:00:00 2001 From: Mike Gevaert Date: Tue, 27 May 2025 13:26:35 +0200 Subject: [PATCH 5/6] fix --- docs/API.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/API.md b/docs/API.md index 6fad2fd4..a6417bdf 100644 --- a/docs/API.md +++ b/docs/API.md @@ -236,7 +236,7 @@ Returns metadata about the atlas: { "creation_date": ..., "hierarchy_id": $UUID, - "id": str(brain_atlas.id), + "id": brain_atlas.id, "name": "test brain atlas", "species": { "creation_date": ..., @@ -245,7 +245,7 @@ Returns metadata about the atlas: "taxonomy_id": "12345", "update_date": ..., }, - "update_date": ANY, + "update_date": ..., } ``` @@ -259,7 +259,7 @@ Returns metadata about the atlas: "id": $UUID, "leaf_region": False, "update_date": ..., - "volume": -1_000_000.0, # this is negative, since it's a leaf region; + "volume": null, # this is null, since it's a leaf region; }, { "brain_atlas_id": $UUID, From d20c6590762f30c145ab3b1af6edde9223960cad Mon Sep 17 00:00:00 2001 From: Mike Gevaert Date: Tue, 27 May 2025 13:46:38 +0200 Subject: [PATCH 6/6] fix property name --- docs/API.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/API.md b/docs/API.md index a6417bdf..d1cb5dea 100644 --- a/docs/API.md +++ b/docs/API.md @@ -257,7 +257,7 @@ Returns metadata about the atlas: "brain_region_id": $UUID, "creation_date": ..., "id": $UUID, - "leaf_region": False, + "is_leaf_region": False, "update_date": ..., "volume": null, # this is null, since it's a leaf region; }, @@ -266,7 +266,7 @@ Returns metadata about the atlas: "brain_region_id": $UUID, "creation_date": ..., "id": $UUID, - "leaf_region": False, + "is_leaf_region": False, "update_date": ..., "volume": 123456789.0, },