Anatomical region API endpoint

The shared atlas of brain regions that procedures and recordings point to.

Table of contents

1. Endpoints
2. Fields
3. List
4. Add
5. Detail
6. Change
7. Delete
8. Custom actions
9. Data model

Endpoints

• Private portal: https://www.brainstem.org/api/private/taxonomies/anatomicalregion/ (needs a token; one record: append <id>/)
• Public portal: https://www.brainstem.org/api/public/taxonomies/anatomicalregion/ (read-only, public projects, no token)
• Response keys: anatomical_region (detail, create, update), anatomical_regions (list)
• Permissions: see the permissions page
• Uniqueness: reference, region_id unique together
• Uniqueness: reference, acronym, name unique together

Fields

[required] fields must be sent on create; [read-only] fields are returned but cannot be set. A nestable relation can be traversed in filters (filter{field.other}) and sideloaded with include[]=field.*; other relations can only be compared with ids (filter{field}=<id>). See the query syntax.

Field	Description
id	UUID string [read-only]
name	string [required]; max 200 characters
description	string; max 2000 characters; nullable
acronym	string [required]; max 15 characters
atlas	string
reference	anatomicalreference id [required]
region_id	number; nullable
parent_acronym	string; max 15 characters
graph_order	number; nullable
is_obsolete	boolean. Retired by the source atlas or ontology; kept for historical records.
replaced_by	anatomicalregion id; nullable. Successor term named by the source ontology, when one exists.
ontology_url	string [read-only]

List

• Allowed portals: private, public
• Request method: GET
• URL: https://www.brainstem.org/api/private/taxonomies/anatomicalregion/
• Responses: 200 OK; 401 Not authenticated; 403 Not allowed

Use example (Python API tool)

resp = client.load('anatomicalregion', load_all=True)
records = resp['anatomical_regions']

Use example (MATLAB API tool)

resp = client.load('anatomicalregion', 'load_all', true);
records = resp.anatomical_regions;

Response example

{
    "anatomical_regions": [
        {
            "id": "<id>",
            "name": "Anatomical region 1",
            "description": "",
            "acronym": "",
            "atlas": "",
            "reference": "<anatomicalreference-id>",
            "region_id": 1,
            "parent_acronym": "",
            "graph_order": 1,
            "is_obsolete": true,
            "replaced_by": "<anatomicalregion-id>",
            "ontology_url": ""
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 100,
        "total_results": 1,
        "total_pages": 1
    }
}

Add

• Allowed portals: private
• Request method: POST
• URL: https://www.brainstem.org/api/private/taxonomies/anatomicalregion/
• Data: JSON object with at least the required fields
• Responses: 201 Created; 400 Bad request (validation errors per field); 403 Not allowed

Use example (Python API tool)

resp = client.save('anatomicalregion', data={"name": "Anatomical region 1", "acronym": "<acronym>", "reference": "<anatomicalreference-id>"})
record = resp.json()['anatomical_region']

Use example (MATLAB API tool)

created = client.save(struct('name', 'Anatomical region 1', 'acronym', '<acronym>', 'reference', '<anatomicalreference-id>'), 'anatomicalregion');
record = created.anatomical_region;

Detail

• Allowed portals: private, public
• Request method: GET
• URL: https://www.brainstem.org/api/private/taxonomies/anatomicalregion/<id>/
• Responses: 200 OK; 403 Not allowed; 404 Not found

Use example (Python API tool)

resp = client.load('anatomicalregion', id='<id>')
record = resp.json()['anatomical_region']

Use example (MATLAB API tool)

out = client.load('anatomicalregion', 'id', '<id>');
record = out.anatomical_region;

Response example

{
    "anatomical_region": {
        "id": "<id>",
        "name": "Anatomical region 1",
        "description": "",
        "acronym": "",
        "atlas": "",
        "reference": "<anatomicalreference-id>",
        "region_id": 1,
        "parent_acronym": "",
        "graph_order": 1,
        "is_obsolete": true,
        "replaced_by": "<anatomicalregion-id>",
        "ontology_url": ""
    }
}

Change

• Allowed portals: private
• Request method: PATCH
• URL: https://www.brainstem.org/api/private/taxonomies/anatomicalregion/<id>/
• Data: JSON object with the fields to change. Lists (projects, tags, …) and JSON payloads (details, coordinates) are replaced as a whole: read the record first and send the full list or object.
• Responses: 200 OK; 400 Bad request; 403 Not allowed; 404 Not found

Use example (Python API tool)

resp = client.save('anatomicalregion', id='<id>', data={"name": "Anatomical region 1 (renamed)"})

Use example (MATLAB API tool)

client.save(struct('id', '<id>', 'name', 'Anatomical region 1 (renamed)'), 'anatomicalregion', 'method', 'patch');

Delete

• Allowed portals: private
• Request method: DELETE
• URL: https://www.brainstem.org/api/private/taxonomies/anatomicalregion/<id>/
• Responses: 204 Deleted; 400 Still referenced by other records; 403 Not allowed; 404 Not found

Use example (Python API tool)

resp = client.delete('anatomicalregion', id='<id>')

Use example (MATLAB API tool)

client.delete('<id>', 'anatomicalregion');

Custom actions

Action	Request
descendants	GET /api/private/taxonomies/anatomicalregion/<id>/descendants/

descendants returns the regions below a region in its atlas hierarchy.

Data model

The fields are described for the web forms on the Anatomical region data model page.