initial commit of optional hemispheres

[PolarBean]

closes #644

This adds a hemispheres_available option to the wrapup. There are two cases when hemispheres are not available.

1. Theyre not provided by the atlas developers.
2. The object has no hemispheres (like a kidney).

This is increasingly blocking atlases, from being merged. Many atlases that are already integrated have no hemisphere information but to get around this are labelled symmetrical which is suboptimal.

some notes about this PR

• If hemispheres_available is set to False then atlas.hemispheres will return None.
• The metadata field is accessed via .get and returns True if unavailable so the API behaviour is unchanged for existing atlases and will not require immediate repackaging.
• Before we merge this we should check that this is not a catastrophic issue for the other BrainGlobe tools which are referenced in the associated issue.

[Copilot]

Pull request overview

Adds an explicit hemispheres_available flag to atlas packaging + manifests, enabling atlases to declare that hemisphere information is unavailable (rather than forcing symmetric=True as a workaround). This integrates the new flag through generation, download behavior, runtime accessors, and validation/tests.

Changes:

• Introduces hemispheres_available into generated metadata/manifests and the metadata template, while keeping legacy manifests valid.
• Updates atlas packaging and wrapup logic to skip hemisphere stack creation/writing when hemispheres are unavailable.
• Updates runtime API behavior so Atlas.hemispheres returns None (and hemisphere_from_coords warns/returns None) when hemispheres are unavailable; updates download logic to avoid fetching hemisphere metadata in that case.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/atlasgen/test_validation.py	Adds coverage to ensure legacy manifests missing hemispheres_available still validate.
tests/atlasgen/test_metadata_utils.py	Extends metadata generation tests to include/validate hemispheres_available.
tests/atlasgen/test_atlas_packaging_data.py	Verifies packaging skips hemisphere generation when unavailable and does not force symmetric.
tests/atlasapi/test_core_atlas.py	Adds runtime behavior tests for default availability and unavailable-hemisphere behavior/warnings.
tests/atlasapi/test_bg_atlas.py	Ensures download does not request hemisphere metadata when unavailable.
brainglobe_atlasapi/descriptors.py	Extends METADATA_TEMPLATE with hemispheres_available.
brainglobe_atlasapi/core.py	Makes Atlas.hemispheres return None when hemispheres are unavailable; warns/returns None in hemisphere_from_coords.
brainglobe_atlasapi/bg_atlas.py	Skips downloading hemisphere metadata when hemispheres_available is false.
brainglobe_atlasapi/atlas_generation/wrapup.py	Gates hemisphere writing/loading on hemispheres_available and writes the new flag into the manifest.
brainglobe_atlasapi/atlas_generation/validate_atlases.py	Treats hemispheres_available as optional to support legacy manifests.
brainglobe_atlasapi/atlas_generation/metadata_utils.py	Adds hemispheres_available to generated manifest metadata.
brainglobe_atlasapi/atlas_generation/atlas_packaging_data.py	Adds hemispheres_available to packaging data and prevents hemisphere stack generation/loading when unavailable.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

brainglobe_atlasapi/core.py:376

• This method now returns None when hemisphere information is unavailable, but the function signature is still annotated as returning Union[int, str]. Please update the return type annotation to include None so the public API type contract matches the behavior described in the docstring.

        Returns
        -------

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

brainglobe_atlasapi/atlas_generation/metadata_utils.py:36

• hemispheres_available was inserted in the middle of generate_metadata_dict’s positional parameters, which breaks any existing positional callers (e.g. code passing resolution positionally will now be bound to hemispheres_available). To keep backward compatibility, add the new parameter at the end (callers can still pass it by keyword).

    symmetric: bool,
    hemispheres_available: bool = True,
    resolution: Tuple[int, int, int] | Tuple[float, float, float],
    orientation: str,

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud