Fix bwm notebook: brainglobe atlas download (correct GIN version, validate tarball)

[bendichter]

Problem

bwm_usage_notebook.ipynb fails on Colab at the BrainGlobeAtlas("allen_mouse_25um") cell with:

ReadError: Atlas download was interrupted or corrupted ... not a gzip file / truncated header

(reported in #176).

Root cause

brainglobe-atlasapi==2.3.1 — the latest release, and what the notebook pins — downloads atlases from GIN (gin.g-node.org/brainglobe/atlases), where allen_mouse_25um is version 1.2. brainglobe has since stood up a separate S3 catalog (OME-Zarr, atlas-rc2/) with renumbered versions where the same atlas is 3.0; no released atlasapi uses that bucket yet.

The previous workaround (added in #160) pre-seeded brainglobe's version cache from the S3 catalog, so on Colab — where atlasapi's live GIN manifest fetch gets a 403 and falls back to that cache — atlasapi read version 3.0 and requested allen_mouse_25um_v3.0.tar.gz from GIN, where it doesn't exist. GIN returned an HTML 404/403 page, and atlasapi's downloader (which never checks the HTTP status) saved it as the "tarball" → not a gzip file.

So updating the package can't help — 2.3.1 is already newest and is GIN-based. The bug is the version the workaround injected.

Fix

Rewrite the workaround in the affected cell to:

1. Seed GIN's version (1.2), not the S3 catalog's 3.0, and overwrite any stale cache (the old code skipped writing if a file already existed, leaving a wrong 3.0 across re-runs).
2. Download the tarball ourselves and validate gzip magic bytes before unpacking into ~/.brainglobe, so a 403/404 HTML page can never masquerade as a corrupt atlas. BrainGlobeAtlas() then loads the already-unpacked atlas locally and never hits its (status-blind) downloader.

If a Colab IP is ever fully blocked by GIN (not just the manifest endpoint), the cell now fails with an explicit message instead of the cryptic ReadError.

Verification

End-to-end against brainglobe-atlasapi==2.3.1 with a clean ~/.brainglobe:

Downloading allen_mouse_25um v1.2 from GIN...
Atlas ready at .../.brainglobe/allen_mouse_25um_v1.2
RESOLUTION: (25.0, 25.0, 25.0)
REFERENCE shape/dtype: (528, 320, 456) uint16
LOCAL VERSION: (1, 2)
SUCCESS

atlas.resolution and atlas.reference (the only attributes the figure cell uses) load correctly. Only cell 34's workaround changed; the notebook still validates as nbformat v4.

Fixes #176

🤖 Generated with Claude Code

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[github-actions]

Index page preview

A preview of the generated index.html has been deployed for this PR:

View preview

Last updated: commit c3d196d2cc2c67ddb3e9beab7d8dca7069e180e2

[yarikoptic]

PR lengthy description talks (only?!) about some version seeding etc but diff seems just unicode character replacements -- do not correspond to each other or relevant change is too burried???

[bendichter]

I'm working on fixing this at the source. I think the issue is that the Colab IP is blocked by the archive storage source