How brainglobe/brainglobe-atlasapi works
Main components
• CLI Layer
– brainglobe_atlasapi/cli.py (entry point for console commands)
– list_atlases.py, show_atlases, update_atlases
• Core API Layer
– bg_atlas.py (BrainGlobeAtlas class)
– core.py, descriptors.py, config.py, utils.py, structure_class.py, structure_tree_util.py
• Atlas Generation Pipeline
– brainglobe_atlasapi/atlas_generation package
• atlas_scripts (per-atlas packaging scripts)
• annotation_utils.py, mesh_utils.py, metadata_utils.py, volume_utils.py, stacks.py, validate_atlases.py, wrapup.py
• pre_packaging subfolder (special preprocessing steps)
• Data & Storage
– Local cache directory (~/.brainglobe/<atlas_name>_vX.X) containing
• reference images (.npy or nifti)
• annotation images
• meshes (.obj)
• metadata (CSV, JSON)
– External remote repositories (e.g. Allen SDK, S3 or HTTP endpoints)
• Testing & QA
– tests/ (pytest suites covering atlasapi and atlas_generation)
– CI workflows (.github/workflows/test_and_deploy.yml)
– pre-commit, black, isort, codecov
• Documentation & Examples
– README.md, tutorials/Atlas API usage.ipynb
Relationships and interactions
• User → CLI Layer (command‐line “brainglobe-atlasapi”)
→ CLI Layer calls Core API functions (show_atlases, update_atlases)
→ Core API uses config and utilities to fetch, cache, and serve atlas data
• User → Python API (import BrainGlobeAtlas)
→ Core API factory returns Atlas object
→ Atlas object lazily loads reference, annotation, hemispheres, mesh, metadata
• Core API ↔ Local Data Cache (read/write files)
• Core API ↔ External Data Sources (download raw atlas data)
• Atlas Generation Pipeline (offline use by developers)
→ atlas_scripts read raw data from public URLs
→ pipeline utilities (annotation_utils, mesh_utils, etc.) process volumes & meshes
→ wrapup packages outputs into standard folder structure
• Testing harness exercises both API and pipeline modules
Architectural patterns & design principles
• Layered architecture: Presentation (CLI/tutorials), Domain (Core API), Infrastructure (data I/O), Pipeline (atlas generation)
• Modular plugin-style extensibility: each atlas has its own script in atlas_generation/atlas_scripts
• Separation of concerns: parsing, mesh creation, volume operations, metadata handling each in dedicated utility modules
• Lazy loading and caching: Atlas objects only load data on access
Call out key technologies & frameworks
• Python 3.8+
• PyPI packaging (pyproject.toml, MANIFEST.in)
• pytest for tests
• GitHub Actions for CI/CD
• pre-commit hooks (black, isort)
• External libs: numpy, nibabel, allensdk (optional), pandas
Final checklist
• Separation of at least these zones: User Interfaces, Core API, Atlas Generation Pipeline, Data Storage, External Services, Testing/CI