brainstem-python-api-tools 2.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

brainstem_api_tools/brainstem_api_client.py

@@ -1,6 +1,10 @@
+import gzip
+import hashlib
+import json
 import os
 import stat
 import time
+import warnings
 import webbrowser
 from enum import Enum
 from pathlib import Path
@@ -18,68 +22,134 @@ from urllib3.util.retry import Retry
 
 _MODEL_TO_APP: dict = {
     # stem
+    "breeding": "stem",
+    "cohort": "stem",
+    "cohortsubject": "stem",
+    "collection": "stem",
+    "collectionsession": "stem",
+    "epoch": "stem",
     "project": "stem",
-    "subject": "stem",
+    "projectgroupmembershipinvitation": "stem",
+    "projectmembershipinvitation": "stem",
     "session": "stem",
-    "collection": "stem",
-    "cohort": "stem",
-    "breeding": "stem",
-    "project_membership_invitation": "stem",
-    "project_group_membership_invitation": "stem",
+    "sessiondatastorage": "stem",
+    "specimen": "stem",
+    "specimenset": "stem",
+    "subject": "stem",
     # modules
-    "procedure": "modules",
     "behavior": "modules",
+    "consumablestock": "modules",
     "dataacquisition": "modules",
-    "manipulation": "modules",
+    "dataacquisitioninterface": "modules",
+    "dataacquisitionprocedure": "modules",
+    "dataacquisitiontemplate": "modules",
+    "episodepersonnel": "modules",
     "equipment": "modules",
-    "consumablestock": "modules",
+    "experimentalinterface": "modules",
+    "experimentalinterfacetemplate": "modules",
+    "manipulation": "modules",
+    "manipulationinterface": "modules",
+    "manipulationtemplate": "modules",
+    "materialusage": "modules",
+    "materialusagetemplate": "modules",
+    "procedure": "modules",
+    "procedureepisode": "modules",
+    "procedureepisodetemplate": "modules",
     "procedurelog": "modules",
+    "proceduretemplate": "modules",
+    "specimenlog": "modules",
+    "specimenprocedure": "modules",
+    "specimenproceduretemplate": "modules",
     "subjectlog": "modules",
     # personal_attributes
     "behavioralassay": "personal_attributes",
+    "behavioralassaygroupmembershipinvitation": "personal_attributes",
+    "behavioralassaymembershipinvitation": "personal_attributes",
     "datastorage": "personal_attributes",
+    "datastoragegroupmembershipinvitation": "personal_attributes",
+    "datastoragemembershipinvitation": "personal_attributes",
     "inventory": "personal_attributes",
+    "inventorygroupmembershipinvitation": "personal_attributes",
+    "inventorymembershipinvitation": "personal_attributes",
     "license": "personal_attributes",
+    "licensegroupmembershipinvitation": "personal_attributes",
+    "licensemembershipinvitation": "personal_attributes",
     "protocol": "personal_attributes",
+    "protocolgroupmembershipinvitation": "personal_attributes",
+    "protocolmembershipinvitation": "personal_attributes",
     "setup": "personal_attributes",
+    "setupgroupmembershipinvitation": "personal_attributes",
+    "setupmembershipinvitation": "personal_attributes",
     # resources
     "consumable": "resources",
+    "consumableapproval": "resources",
     "hardwaredevice": "resources",
+    "hardwaredeviceapproval": "resources",
     "supplier": "resources",
+    "supplierapproval": "resources",
     # taxonomies
+    "anatomicalreference": "taxonomies",
+    "anatomicalregion": "taxonomies",
     "behavioralcategory": "taxonomies",
+    "behavioralcategoryapproval": "taxonomies",
     "behavioralparadigm": "taxonomies",
-    "brainregion": "taxonomies",
+    "behavioralparadigmapproval": "taxonomies",
+    "coordinatetransform": "taxonomies",
     "regulatoryauthority": "taxonomies",
+    "regulatoryauthorityapproval": "taxonomies",
     "setuptype": "taxonomies",
+    "setuptypeapproval": "taxonomies",
     "species": "taxonomies",
+    "speciesapproval": "taxonomies",
     "strain": "taxonomies",
     "strainapproval": "taxonomies",
     # dissemination
     "journal": "dissemination",
     "journalapproval": "dissemination",
     "publication": "dissemination",
+    "publicationapproval": "dissemination",
     # users
+    "admingroup": "users",
     "group": "users",
-    "group_membership_invitation": "users",
-    "group_membership_request": "users",
+    "groupmembershipinvitation": "users",
+    "groupmembershiprequest": "users",
     "laboratory": "users",
+    "pendinginvitation": "users",
     "user": "users",
 }
 
 _TOKEN_FILE = Path.home() / ".config" / "brainstem" / "token"
 
+# Deprecated model names, resolved to the server's current name with a warning:
+# the underscored names earlier versions of this client used (they never matched
+# a server route), and "brainregion", renamed "anatomicalregion".
+_MODEL_ALIASES: dict = {
+    "brainregion": "anatomicalregion",
+    "project_membership_invitation": "projectmembershipinvitation",
+    "project_group_membership_invitation": "projectgroupmembershipinvitation",
+    "group_membership_invitation": "groupmembershipinvitation",
+    "group_membership_request": "groupmembershiprequest",
+}
+
 # Derived from _MODEL_TO_APP so there is exactly one source of truth.
-ModelType = Enum("ModelType", {k: k for k in _MODEL_TO_APP})  # type: ignore[misc]
+ModelType = Enum(  # type: ignore[misc]
+    "ModelType", {k: k for k in [*_MODEL_TO_APP, *_MODEL_ALIASES]}
+)
 
 _VALID_PORTALS = {"private", "public", "super"}
 
 
 def _resolve_model(model) -> str:
-    """Accept a plain string or a ModelType member and return the string value."""
+    """Accept a plain string or a ModelType member and return the server's resource name."""
     if isinstance(model, ModelType):
-        return model.value
+        model = model.value
     model = str(model)
+    if model in _MODEL_ALIASES:
+        warnings.warn(
+            f"Model name '{model}' is deprecated; use '{_MODEL_ALIASES[model]}'.",
+            FutureWarning, stacklevel=3,
+        )
+        return _MODEL_ALIASES[model]
     if model not in _MODEL_TO_APP:
         raise ValueError(
             f"Unknown model '{model}'. Valid models are: "
@@ -115,6 +185,10 @@ class AuthenticationError(Exception):
     pass
 
 
+class ExportError(Exception):
+    """A project export could not be produced or downloaded."""
+
+
 # ---------------------------------------------------------------------------
 # Client
 # ---------------------------------------------------------------------------
@@ -123,14 +197,34 @@ class BrainstemClient:
 
     BASE_URL = "https://www.brainstem.org/"
     DEFAULT_TIMEOUT: int = 30  # seconds; applied to all HTTP calls
+    MAX_PAGE_SIZE: int = 500   # the API returns at most this many records per page
 
     def __init__(
         self,
         token: str = None,
         headless: bool = False,
         url: str = None,
+        anonymous: bool = False,
     ) -> None:
+        """Create a client.
+
+        Parameters
+        ----------
+        token     : API token. Defaults to ``$BRAINSTEM_API_TOKEN``, then the
+                    cached token, then the browser device authorization flow.
+        headless  : Print the verification URL and code instead of opening a browser.
+        url       : Base URL of the server. Defaults to ``$BRAINSTEM_API_URL``,
+                    then ``https://www.brainstem.org/``.
+        anonymous : Send no token and never start a login. Only the public
+                    portal (``portal='public'``) is readable.
+        """
+        if url is None:
+            url = os.environ.get("BRAINSTEM_API_URL")
+        if token is None:
+            token = os.environ.get("BRAINSTEM_API_TOKEN")
+
         base = (url.rstrip("/") + "/") if url else self.BASE_URL
+        self._base_url = base
         self._address = base + "api/"
         self._session = requests.Session()
 
@@ -139,6 +233,10 @@ class BrainstemClient:
         self._session.mount("https://", HTTPAdapter(max_retries=_retry))
         self._session.mount("http://", HTTPAdapter(max_retries=_retry))
 
+        if anonymous:
+            self._token = None
+            return
+
         if token:
             self._token = token
         else:
@@ -209,8 +307,18 @@ class BrainstemClient:
                 json={"device_code": device_code},
                 timeout=10,
             )
-            poll.raise_for_status()
-            result = poll.json()
+            # The server answers 400 (invalid_device_code) or 500 (token_error)
+            # with a JSON "error" key; report those as authentication failures
+            # rather than bare HTTP errors.
+            try:
+                result = poll.json()
+            except ValueError:
+                result = {}
+            if not poll.ok:
+                error = result.get("error") if isinstance(result, dict) else None
+                if error:
+                    raise AuthenticationError(f"Authorization failed: {error}")
+                poll.raise_for_status()
 
             if result.get("status") == "success":
                 return result["token"]
@@ -260,11 +368,20 @@ class BrainstemClient:
                    Supports ``.icontains``, ``.startswith``, ``.endswith``,
                    ``.gt``, ``.gte``, ``.lt``, ``.lte``.
         sort     : List of fields to sort by. Prefix with ``'-'`` for descending.
-        include  : Related models to embed, e.g. ``['dataacquisition', 'behaviors']``.
-        limit    : Max records per page (API maximum: 100).
-        offset   : Number of records to skip (for pagination).
+        include  : Related fields to sideload, e.g. ``['dataacquisition', 'behaviors']``.
+                   Their records are returned as extra lists next to the main
+                   one, and only records you may read are included. See ``save``
+                   before writing back a list field read this way.
+        limit    : Records per page, 1 to 500 (default 100). Sent to the API as
+                   ``per_page``. With *load_all*, a larger value is reduced to
+                   500, which returns the same records in more pages.
+        offset   : Number of records to skip. The API pages with ``page`` and
+                   ``per_page``, so *offset* must be a multiple of the page size
+                   (*limit*, or 100 if *limit* is not set); it is sent as
+                   ``page = offset // page_size + 1``.
         load_all : When ``True``, automatically follow pagination and return a
-                   combined ``dict`` with all records merged under the model key.
+                   combined ``dict`` with all records merged under the model key,
+                   starting at the page selected by *offset*.
                    When ``False`` (default), returns the raw ``Response``.
         """
         model = _resolve_model(model)
@@ -280,54 +397,88 @@ class BrainstemClient:
                 params.setdefault("sort[]", []).append(field)
             for rel in (include or []):
                 params.setdefault("include[]", []).append(f"{rel}.*")
-            if limit is not None:
-                params["limit"] = limit
-            if offset is not None:
-                params["offset"] = offset
-
-        if not load_all:
-            return self._session.get(url, params=params, timeout=self.DEFAULT_TIMEOUT)
 
-        if id is not None:
+        if load_all and id is not None:
             raise ValueError("load_all=True cannot be used together with id.")
 
-        # --- auto-paginate and merge all pages ---
-        page_size = limit or 100
-        params["limit"] = page_size
-        params.setdefault("offset", offset or 0)
+        # The API paginates with page/per_page (it also accepts limit/offset
+        # as aliases under the same multiple-of-page-size rule); translate
+        # limit/offset here so the request is explicit and validated early.
+        page_size = 100 if limit is None else limit
+        if load_all:
+            page_size = min(page_size, self.MAX_PAGE_SIZE)
+        if not id and not 1 <= page_size <= self.MAX_PAGE_SIZE:
+            raise ValueError(
+                f"limit ({limit}) must be between 1 and {self.MAX_PAGE_SIZE}, "
+                "the API's maximum page size."
+            )
+        if not id and offset and offset % page_size:
+            raise ValueError(
+                f"offset ({offset}) must be a multiple of limit (the page size, "
+                f"{page_size}): the API pages with page/per_page."
+            )
+        start_page = (offset or 0) // page_size + 1
+
+        if load_all:
+            return self._load_all_pages(url, params, page_size, start_page=start_page)
+
+        if not id and (limit is not None or offset is not None):
+            params["per_page"] = page_size
+            params["page"] = start_page
+        return self._session.get(url, params=params, timeout=self.DEFAULT_TIMEOUT)
+
+    def _get_json(self, url: str, params: dict = None) -> dict:
+        """GET *url* and return the decoded JSON, raising on HTTP errors."""
+        resp = self._session.get(url, params=params, timeout=self.DEFAULT_TIMEOUT)
+        if resp.status_code == 401:
+            raise AuthenticationError(
+                "API token is invalid or expired. Run `brainstem login` to re-authenticate."
+            )
+        resp.raise_for_status()
+        return resp.json()
+
+    def _load_all_pages(self, url: str, params: dict,
+                        page_size: int = 100, start_page: int = 1) -> dict:
+        """Follow pagination and merge every page into a single dict.
 
+        All list-valued keys are concatenated across pages: the primary
+        records as well as any sideloaded related records (de-duplicated by
+        ``id``). Non-list keys are taken from the first page.
+        """
+        params = dict(params, per_page=page_size)
+        page = start_page
         combined: dict = {}
-        records_key: str = None
+        seen_ids: dict = {}
 
         while True:
-            resp = self._session.get(url, params=params, timeout=self.DEFAULT_TIMEOUT)
-            if resp.status_code == 401:
-                raise AuthenticationError(
-                    "API token is invalid or expired. Run `brainstem login` to re-authenticate."
-                )
-            resp.raise_for_status()
-            data = resp.json()
+            data = self._get_json(url, dict(params, page=page))
+            lists = {k: v for k, v in data.items() if isinstance(v, list)}
 
-            if records_key is None:
-                # Detect the list key (e.g. 'sessions', 'projects')
-                records_key = next(
-                    (k for k, v in data.items() if isinstance(v, list)), None
-                )
-                if records_key is None:
+            if not combined:
+                if not lists:
                     raise ValueError(
                         "load_all=True requires a paginated list response, but the API "
                         "returned no list-valued key. Use load_all=False for single-object endpoints."
                     )
-                combined = {k: v for k, v in data.items() if k != records_key}
-                combined[records_key] = []
-
-            combined[records_key].extend(data.get(records_key, []))
-            total = data.get("count", len(combined[records_key]))
-
-            if len(combined[records_key]) >= total:
+                combined = {k: v for k, v in data.items() if k not in lists}
+
+            for key, records in lists.items():
+                bucket = combined.setdefault(key, [])
+                ids = seen_ids.setdefault(key, set())
+                for record in records:
+                    rid = record.get("id") if isinstance(record, dict) else None
+                    if rid is not None:
+                        if rid in ids:
+                            continue
+                        ids.add(rid)
+                    bucket.append(record)
+
+            total_pages = (data.get("meta") or {}).get("total_pages")
+            if total_pages is None and "count" in data:
+                total_pages = -(-data["count"] // page_size)  # ceil division
+            if total_pages is None or page >= total_pages or not any(lists.values()):
                 break
-
-            params["offset"] = params.get("offset", 0) + page_size
+            page += 1
 
         return combined
 
@@ -342,6 +493,14 @@ class BrainstemClient:
         When *id* is provided the record is **updated** (PATCH).
         When *id* is omitted a **new record** is created (POST).
 
+        .. warning::
+           Sending a list field (``projects``, ``subjects``, ``behaviors``, ...)
+           replaces the whole list. A list read with ``include`` (including the
+           convenience loaders' default includes) holds only the records you may
+           read, so writing it back drops links to records you cannot see. Read
+           the record without ``include`` first, e.g.
+           ``client.load('session', id=uid).json()``, and change that list.
+
         Parameters
         ----------
         model   : Model name string or ``ModelType`` member, e.g. ``'session'``.
@@ -382,6 +541,159 @@ class BrainstemClient:
         url = self._build_url(portal, app, model, id)
         return self._session.delete(url, timeout=self.DEFAULT_TIMEOUT)
 
+    # ------------------------------------------------------------------
+    # Export
+    # ------------------------------------------------------------------
+
+    EXPORT_TIMEOUT: int = 90  # seconds; the server builds the whole export per request
+
+    def export_project(self, project_id: str, background: bool = False,
+                       poll_interval: float = 5.0, timeout: float = 3600) -> dict:
+        """Export a project as the server's versioned JSON export.
+
+        Returns the same payload as the JSON download on the BrainSTEM website
+        (format documented in the server's ``docs/project-export-format.md``)::
+
+            {
+              "export_info": {"format_version", "exported_at", "scope",
+                              "project_id", "project_ids", "session_id",
+                              "lab_resources", "restricted", "record_count",
+                              "counts"},
+              "records": {"stem.project": [...], "stem.subject": [...], ...}
+            }
+
+        Each record has the shape ``{"model", "pk", "fields"}``. Exporting
+        requires read access to the project.
+
+        Parameters
+        ----------
+        project_id    : UUID of the project to export.
+        background    : When ``True``, queue the export as a server-side job,
+                        wait for it to finish and download the result. Use this
+                        for large projects, which can exceed the server's
+                        30-second request limit. The server also emails you
+                        when the job finishes.
+        poll_interval : Seconds between job status checks (background only).
+        timeout       : Maximum seconds to wait for the job (background only).
+        """
+        return self._export("project", project_id, background, poll_interval, timeout)
+
+    def export_session(self, session_id: str, background: bool = False,
+                       poll_interval: float = 5.0, timeout: float = 3600) -> dict:
+        """Export one session and everything it touches: the content of one NWB file.
+
+        Returns the same format as ``export_project`` (``export_info.scope`` is
+        ``"session"``), holding the session with its data acquisitions,
+        manipulations, behaviors and epochs; the subjects and specimen sets
+        linked to it with their full procedure and log history; the session's
+        projects; and the lab resources, catalog entries and users these
+        reference. Only records you can read are included, in any of the
+        session's projects.
+
+        A subject's procedure history is complete, including procedures after
+        the session, so filter by date where that matters. Exporting requires
+        read access to one of the session's projects.
+
+        Parameters are the same as for ``export_project``, with
+        ``session_id`` the UUID of the session to export.
+        """
+        return self._export("session", session_id, background, poll_interval, timeout)
+
+    def _export(self, model: str, record_id: str, background: bool,
+                poll_interval: float, timeout: float) -> dict:
+        """Run a direct or background export of a project or session record."""
+        if not record_id:
+            raise ValueError(f"'{model}_id' is required to export a {model}.")
+        url = self._build_url("private", "stem", model, record_id, "export/")
+
+        if not background:
+            # Bypass the session's automatic retries: a timed-out export would be
+            # rebuilt up to three more times, each counting against the export rate limit.
+            resp = requests.get(url, headers=self._session.headers, timeout=self.EXPORT_TIMEOUT)
+            if resp.status_code in (503, 504):
+                raise ExportError(
+                    "The export did not finish within the server's request time limit. "
+                    f"Use export_{model}(..., background=True) for large exports."
+                )
+            self._check_export_response(resp, model)
+            return resp.json()
+
+        resp = self._session.post(url, timeout=self.DEFAULT_TIMEOUT)
+        self._check_export_response(resp, model)
+        job = resp.json()["export_job"]
+        job_url = self._build_url("private", "stem", model, record_id,
+                                  f"export-jobs/{job['id']}/")
+
+        deadline = time.monotonic() + timeout
+        while job["status"] in ("pending", "running"):
+            if time.monotonic() > deadline:
+                raise ExportError(
+                    f"Export job {job['id']} did not finish within {timeout} seconds "
+                    f"(status: {job['status']}, {job.get('progress_percent', 0)}%)."
+                )
+            time.sleep(poll_interval)
+            job = self._get_json(job_url)["export_job"]
+
+        if job["status"] != "completed":
+            raise ExportError(job.get("error_message") or f"Export job ended as '{job['status']}'.")
+
+        resp = self._session.get(self._base_url + job["download_url"].lstrip("/"),
+                                 timeout=self.EXPORT_TIMEOUT)
+        self._check_export_response(resp, model)
+        content = resp.content
+        if content[:2] == b"\x1f\x8b":  # gzip magic number
+            expected = job.get("file_sha256")
+            if expected and hashlib.sha256(content).hexdigest() != expected:
+                raise ExportError(f"Export job {job['id']}: downloaded file failed its checksum.")
+            content = gzip.decompress(content)
+        return json.loads(content)
+
+    def _check_export_response(self, resp: Response, model: str) -> None:
+        """Turn export endpoint errors into clear exceptions."""
+        if resp.ok:
+            return
+        if resp.status_code == 401:
+            raise AuthenticationError(
+                "API token is invalid or expired. Run `brainstem login` to re-authenticate."
+            )
+        is_json = "json" in resp.headers.get("Content-Type", "")
+        if resp.status_code == 404:
+            if not is_json:
+                raise ExportError(f"This BrainSTEM server does not support {model} export yet.")
+            # The API answers 404, not 403, when the record exists but you cannot read it.
+            raise ExportError(f"The {model} was not found, or you do not have read access to it.")
+        if resp.status_code == 403:
+            raise ExportError(f"You do not have permission to export this {model}.")
+        if resp.status_code in (400, 409, 410, 429) and is_json:
+            raise ExportError(resp.json().get("detail", resp.reason))
+        resp.raise_for_status()
+
+    # ------------------------------------------------------------------
+    # Agent reference
+    # ------------------------------------------------------------------
+
+    def agent_reference(self, page: str = "index.md") -> str:
+        """Return one page of the server's agent reference as text.
+
+        The server describes its own API and data model at ``/reference/`` (Markdown
+        pages such as ``rules.md``, ``resources/session.md`` or
+        ``guides/query-planning.md``, and JSON documents under ``data/``). It is
+        public, so this works with an anonymous client too.
+
+        Parameters
+        ----------
+        page : Page path relative to the reference root. Defaults to the index.
+        """
+        url = self._base_url + "reference/" + page.lstrip("/")
+        resp = self._session.get(url, timeout=self.DEFAULT_TIMEOUT)
+        if resp.status_code == 404:
+            raise ValueError(
+                f"No agent reference page '{page}' on this server. The page does not exist, "
+                "or the server predates the agent reference."
+            )
+        resp.raise_for_status()
+        return resp.text
+
     def __enter__(self):
         return self
 
@@ -431,13 +743,13 @@ class BrainstemClient:
         name     : Filter by project name (case-insensitive contains).
         sessions : Filter by session UUID.
         subjects : Filter by subject UUID.
-        tags     : Filter by tag.
+        tags     : Filter by tag name (sent as ``filter{tags.name}``; records return tags as names).
         """
         return self._convenience_load(
             "project",
             default_include=["sessions", "subjects", "collections", "cohorts"],
-            filter_map={"name": "name.icontains", "sessions": "sessions.id",
-                        "subjects": "subjects.id", "tags": "tags"},
+            filter_map={"name": "name.icontains", "sessions": "sessions",
+                        "subjects": "subjects", "tags": "tags.name"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
             name=name, sessions=sessions, subjects=subjects, tags=tags,
@@ -457,13 +769,13 @@ class BrainstemClient:
         projects : Filter by project UUID.
         strain   : Filter by strain UUID.
         sex      : Filter by sex (``'M'``, ``'F'``, or ``'U'``).
-        tags     : Filter by tag.
+        tags     : Filter by tag name (sent as ``filter{tags.name}``; records return tags as names).
         """
         return self._convenience_load(
             "subject",
             default_include=["procedures", "subjectlogs"],
-            filter_map={"name": "name.icontains", "projects": "projects.id",
-                        "strain": "strain.id", "sex": "sex", "tags": "tags"},
+            filter_map={"name": "name.icontains", "projects": "projects",
+                        "strain": "strain", "sex": "sex", "tags": "tags.name"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
             name=name, projects=projects, strain=strain, sex=sex, tags=tags,
@@ -482,13 +794,13 @@ class BrainstemClient:
         name        : Filter by session name (case-insensitive contains).
         projects    : Filter by project UUID.
         datastorage : Filter by data storage UUID.
-        tags        : Filter by tag.
+        tags        : Filter by tag name (sent as ``filter{tags.name}``; records return tags as names).
         """
         return self._convenience_load(
             "session",
             default_include=["dataacquisition", "behaviors", "manipulations", "epochs"],
-            filter_map={"name": "name.icontains", "projects": "projects.id",
-                        "datastorage": "datastorage.id", "tags": "tags"},
+            filter_map={"name": "name.icontains", "projects": "projects",
+                        "datastorage": "datastorage", "tags": "tags.name"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
             name=name, projects=projects, datastorage=datastorage, tags=tags,
@@ -504,12 +816,12 @@ class BrainstemClient:
         Parameters
         ----------
         name : Filter by collection name (case-insensitive contains).
-        tags : Filter by tag.
+        tags : Filter by tag name (sent as ``filter{tags.name}``; records return tags as names).
         """
         return self._convenience_load(
             "collection",
             default_include=["sessions"],
-            filter_map={"name": "name.icontains", "tags": "tags"},
+            filter_map={"name": "name.icontains", "tags": "tags.name"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
             name=name, tags=tags,
@@ -525,19 +837,19 @@ class BrainstemClient:
         Parameters
         ----------
         name : Filter by cohort name (case-insensitive contains).
-        tags : Filter by tag.
+        tags : Filter by tag name (sent as ``filter{tags.name}``; records return tags as names).
         """
         return self._convenience_load(
             "cohort",
             default_include=["subjects"],
-            filter_map={"name": "name.icontains", "tags": "tags"},
+            filter_map={"name": "name.icontains", "tags": "tags.name"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
             name=name, tags=tags,
         )
 
     def load_behavior(self, portal="private", id: str = None,
-                      session: str = None, tags: str = None,
+                      session: str = None,
                       filters: dict = None, sort: list = None,
                       include: list = None, limit: int = None,
                       offset: int = None, load_all: bool = False):
@@ -546,19 +858,18 @@ class BrainstemClient:
         Parameters
         ----------
         session : Filter by session UUID.
-        tags    : Filter by tag.
         """
         return self._convenience_load(
             "behavior",
             default_include=[],
-            filter_map={"session": "session.id", "tags": "tags"},
+            filter_map={"session": "session"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            session=session, tags=tags,
+            session=session,
         )
 
     def load_dataacquisition(self, portal="private", id: str = None,
-                             session: str = None, tags: str = None,
+                             session: str = None,
                              filters: dict = None, sort: list = None,
                              include: list = None, limit: int = None,
                              offset: int = None, load_all: bool = False):
@@ -567,19 +878,18 @@ class BrainstemClient:
         Parameters
         ----------
         session : Filter by session UUID.
-        tags    : Filter by tag.
         """
         return self._convenience_load(
             "dataacquisition",
             default_include=[],
-            filter_map={"session": "session.id", "tags": "tags"},
+            filter_map={"session": "session"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            session=session, tags=tags,
+            session=session,
         )
 
     def load_manipulation(self, portal="private", id: str = None,
-                          session: str = None, tags: str = None,
+                          session: str = None,
                           filters: dict = None, sort: list = None,
                           include: list = None, limit: int = None,
                           offset: int = None, load_all: bool = False):
@@ -588,19 +898,18 @@ class BrainstemClient:
         Parameters
         ----------
         session : Filter by session UUID.
-        tags    : Filter by tag.
         """
         return self._convenience_load(
             "manipulation",
             default_include=[],
-            filter_map={"session": "session.id", "tags": "tags"},
+            filter_map={"session": "session"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            session=session, tags=tags,
+            session=session,
         )
 
     def load_procedure(self, portal="private", id: str = None,
-                       subject: str = None, tags: str = None,
+                       subject: str = None,
                        filters: dict = None, sort: list = None,
                        include: list = None, limit: int = None,
                        offset: int = None, load_all: bool = False):
@@ -609,19 +918,18 @@ class BrainstemClient:
         Parameters
         ----------
         subject : Filter by subject UUID.
-        tags    : Filter by tag.
         """
         return self._convenience_load(
             "procedure",
             default_include=[],
-            filter_map={"subject": "subject.id", "tags": "tags"},
+            filter_map={"subject": "subject"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            subject=subject, tags=tags,
+            subject=subject,
         )
 
     def load_procedurelog(self, portal="private", id: str = None,
-                          procedure: str = None, tags: str = None,
+                          procedure: str = None,
                           filters: dict = None, sort: list = None,
                           include: list = None, limit: int = None,
                           offset: int = None, load_all: bool = False):
@@ -630,19 +938,18 @@ class BrainstemClient:
         Parameters
         ----------
         procedure : Filter by procedure UUID.
-        tags      : Filter by tag.
         """
         return self._convenience_load(
             "procedurelog",
             default_include=[],
-            filter_map={"procedure": "procedure.id", "tags": "tags"},
+            filter_map={"procedure": "procedure"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            procedure=procedure, tags=tags,
+            procedure=procedure,
         )
 
     def load_subjectlog(self, portal="private", id: str = None,
-                        subject: str = None, tags: str = None,
+                        subject: str = None,
                         filters: dict = None, sort: list = None,
                         include: list = None, limit: int = None,
                         offset: int = None, load_all: bool = False):
@@ -651,19 +958,18 @@ class BrainstemClient:
         Parameters
         ----------
         subject : Filter by subject UUID.
-        tags    : Filter by tag.
         """
         return self._convenience_load(
             "subjectlog",
             default_include=[],
-            filter_map={"subject": "subject.id", "tags": "tags"},
+            filter_map={"subject": "subject"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            subject=subject, tags=tags,
+            subject=subject,
         )
 
     def load_equipment(self, portal="private", id: str = None,
-                       name: str = None, setup: str = None, tags: str = None,
+                       name: str = None, setup: str = None,
                        filters: dict = None, sort: list = None,
                        include: list = None, limit: int = None,
                        offset: int = None, load_all: bool = False):
@@ -673,19 +979,18 @@ class BrainstemClient:
         ----------
         name  : Filter by equipment name (case-insensitive contains).
         setup : Filter by setup UUID.
-        tags  : Filter by tag.
         """
         return self._convenience_load(
             "equipment",
             default_include=[],
-            filter_map={"name": "name.icontains", "setup": "setup.id", "tags": "tags"},
+            filter_map={"name": "name.icontains", "setup": "setup"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            name=name, setup=setup, tags=tags,
+            name=name, setup=setup,
         )
 
     def load_consumablestock(self, portal="private", id: str = None,
-                             tags: str = None,
+                             inventory: str = None,
                              filters: dict = None, sort: list = None,
                              include: list = None, limit: int = None,
                              offset: int = None, load_all: bool = False):
@@ -693,19 +998,19 @@ class BrainstemClient:
 
         Parameters
         ----------
-        tags : Filter by tag.
+        inventory : Filter by inventory UUID.
         """
         return self._convenience_load(
             "consumablestock",
             default_include=[],
-            filter_map={"tags": "tags"},
+            filter_map={"inventory": "inventory"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            tags=tags,
+            inventory=inventory,
         )
 
     def load_behavioralassay(self, portal="private", id: str = None,
-                             name: str = None, tags: str = None,
+                             name: str = None,
                              filters: dict = None, sort: list = None,
                              include: list = None, limit: int = None,
                              offset: int = None, load_all: bool = False):
@@ -714,19 +1019,18 @@ class BrainstemClient:
         Parameters
         ----------
         name : Filter by name (case-insensitive contains).
-        tags : Filter by tag.
         """
         return self._convenience_load(
             "behavioralassay",
             default_include=[],
-            filter_map={"name": "name.icontains", "tags": "tags"},
+            filter_map={"name": "name.icontains"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            name=name, tags=tags,
+            name=name,
         )
 
     def load_datastorage(self, portal="private", id: str = None,
-                         name: str = None, tags: str = None,
+                         name: str = None,
                          filters: dict = None, sort: list = None,
                          include: list = None, limit: int = None,
                          offset: int = None, load_all: bool = False):
@@ -735,19 +1039,18 @@ class BrainstemClient:
         Parameters
         ----------
         name : Filter by name (case-insensitive contains).
-        tags : Filter by tag.
         """
         return self._convenience_load(
             "datastorage",
             default_include=[],
-            filter_map={"name": "name.icontains", "tags": "tags"},
+            filter_map={"name": "name.icontains"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            name=name, tags=tags,
+            name=name,
         )
 
     def load_setup(self, portal="private", id: str = None,
-                   name: str = None, tags: str = None,
+                   name: str = None,
                    filters: dict = None, sort: list = None,
                    include: list = None, limit: int = None,
                    offset: int = None, load_all: bool = False):
@@ -756,19 +1059,18 @@ class BrainstemClient:
         Parameters
         ----------
         name : Filter by name (case-insensitive contains).
-        tags : Filter by tag.
         """
         return self._convenience_load(
             "setup",
             default_include=[],
-            filter_map={"name": "name.icontains", "tags": "tags"},
+            filter_map={"name": "name.icontains"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            name=name, tags=tags,
+            name=name,
         )
 
     def load_hardwaredevice(self, portal="private", id: str = None,
-                            name: str = None, tags: str = None,
+                            name: str = None,
                             filters: dict = None, sort: list = None,
                             include: list = None, limit: int = None,
                             offset: int = None, load_all: bool = False):
@@ -777,83 +1079,128 @@ class BrainstemClient:
         Parameters
         ----------
         name : Filter by name (case-insensitive contains).
-        tags : Filter by tag.
         """
         return self._convenience_load(
             "hardwaredevice",
             default_include=[],
-            filter_map={"name": "name.icontains", "tags": "tags"},
+            filter_map={"name": "name.icontains"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            name=name, tags=tags,
+            name=name,
         )
 
     def load_brainregion(self, portal="private", id: str = None,
-                         name: str = None, tags: str = None,
+                         name: str = None,
                          filters: dict = None, sort: list = None,
                          include: list = None, limit: int = None,
                          offset: int = None, load_all: bool = False):
-        """Load brain region record(s).
+        """Deprecated: use ``load_anatomicalregion``, which this calls.
+
+        Brain regions are ``anatomicalregion`` records; the response holds them
+        under ``anatomical_regions``.
 
         Parameters
         ----------
         name : Filter by name (case-insensitive contains).
-        tags : Filter by tag.
+        """
+        warnings.warn(
+            "load_brainregion() is deprecated; use load_anatomicalregion().",
+            FutureWarning, stacklevel=2,
+        )
+        return self.load_anatomicalregion(
+            portal=portal, id=id, name=name, filters=filters, sort=sort,
+            include=include, limit=limit, offset=offset, load_all=load_all,
+        )
+
+    def load_anatomicalregion(self, portal="private", id: str = None,
+                              name: str = None, acronym: str = None,
+                              reference: str = None,
+                              filters: dict = None, sort: list = None,
+                              include: list = None, limit: int = None,
+                              offset: int = None, load_all: bool = False):
+        """Load anatomical (brain) region record(s).
+
+        Parameters
+        ----------
+        name      : Filter by name (case-insensitive contains).
+        acronym   : Filter by acronym (case-insensitive exact match), e.g. ``'CA1'``.
+        reference : Filter by anatomical reference (atlas) UUID.
         """
         return self._convenience_load(
-            "brainregion",
+            "anatomicalregion",
             default_include=[],
-            filter_map={"name": "name.icontains", "tags": "tags"},
+            filter_map={"name": "name.icontains", "acronym": "acronym.iexact",
+                        "reference": "reference"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            name=name, tags=tags,
+            name=name, acronym=acronym, reference=reference,
         )
 
+    def load_anatomicalregion_descendants(self, id: str, portal="private") -> Response:
+        """Load every region below anatomical region *id* in its atlas.
+
+        Returns the raw ``Response``; its JSON is
+        ``{"anatomical_regions": [{"id", "name", "acronym", "parent_acronym",
+        "is_obsolete", "depth"}, ...]}``, ordered by depth (1 = direct child).
+        Atlases without a hierarchy return an empty list.
+        """
+        if not id:
+            raise ValueError("'id' is required to load the descendants of a region.")
+        url = self._build_url(_resolve_portal(portal), "taxonomies", "anatomicalregion",
+                              id, "descendants/")
+        return self._session.get(url, timeout=self.DEFAULT_TIMEOUT)
+
     def load_species(self, portal="private", id: str = None,
-                     name: str = None, tags: str = None,
+                     name: str = None,
                      filters: dict = None, sort: list = None,
                      include: list = None, limit: int = None,
-                     offset: int = None, load_all: bool = False):
+                     offset: int = None, load_all: bool = False,
+                     popular_name: str = None):
         """Load species record(s).
 
         Parameters
         ----------
-        name : Filter by name (case-insensitive contains).
-        tags : Filter by tag.
+        name         : Filter by scientific name (case-insensitive contains).
+        popular_name : Filter by common name (case-insensitive contains), e.g.
+                       ``'mouse'``. Needs a server with the specimen release.
         """
         return self._convenience_load(
             "species",
             default_include=[],
-            filter_map={"name": "name.icontains", "tags": "tags"},
+            filter_map={"name": "name.icontains",
+                        "popular_name": "popular_name.icontains"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            name=name, tags=tags,
+            name=name, popular_name=popular_name,
         )
 
     def load_strain(self, portal="private", id: str = None,
-                    name: str = None, species: str = None, tags: str = None,
+                    name: str = None, species: str = None,
                     filters: dict = None, sort: list = None,
                     include: list = None, limit: int = None,
-                    offset: int = None, load_all: bool = False):
+                    offset: int = None, load_all: bool = False,
+                    popular_name: str = None):
         """Load strain record(s).
 
         Parameters
         ----------
-        name    : Filter by name (case-insensitive contains).
-        species : Filter by species UUID.
-        tags    : Filter by tag.
+        name         : Filter by name (case-insensitive contains).
+        species      : Filter by species UUID.
+        popular_name : Filter by common name (case-insensitive contains).
+                       Needs a server with the specimen release.
         """
         return self._convenience_load(
             "strain",
             default_include=[],
-            filter_map={"name": "name.icontains", "species": "species.id", "tags": "tags"},
+            filter_map={"name": "name.icontains", "species": "species",
+                        "popular_name": "popular_name.icontains"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            name=name, species=species, tags=tags,
+            name=name, species=species, popular_name=popular_name,
         )
 
     def load_publication(self, portal="private", id: str = None,
-                         name: str = None, tags: str = None,
+                         name: str = None,
                          filters: dict = None, sort: list = None,
                          include: list = None, limit: int = None,
                          offset: int = None, load_all: bool = False):
@@ -862,19 +1209,18 @@ class BrainstemClient:
         Parameters
         ----------
         name : Filter by name (case-insensitive contains).
-        tags : Filter by tag.
         """
         return self._convenience_load(
             "publication",
             default_include=[],
-            filter_map={"name": "name.icontains", "tags": "tags"},
+            filter_map={"name": "name.icontains"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            name=name, tags=tags,
+            name=name,
         )
 
     def load_laboratory(self, portal="private", id: str = None,
-                        name: str = None, tags: str = None,
+                        name: str = None,
                         filters: dict = None, sort: list = None,
                         include: list = None, limit: int = None,
                         offset: int = None, load_all: bool = False):
@@ -883,13 +1229,12 @@ class BrainstemClient:
         Parameters
         ----------
         name : Filter by name (case-insensitive contains).
-        tags : Filter by tag.
         """
         return self._convenience_load(
             "laboratory",
             default_include=[],
-            filter_map={"name": "name.icontains", "tags": "tags"},
+            filter_map={"name": "name.icontains"},
             portal=portal, id=id, filters=filters, sort=sort, include=include,
             limit=limit, offset=offset, load_all=load_all,
-            name=name, tags=tags,
+            name=name,
         )