Merge branch 'main' into doc_v1_test_1umservice

AhmetNSimsek · AhmetNSimsek · commit d53f71c59bf0 · 2026-03-06T09:49:37.000+01:00
diff --git a/.github/ISSUE_TEMPLATE/blank-issue.md b/.github/ISSUE_TEMPLATE/blank-issue.md
@@ -0,0 +1,10 @@
+---
+name: Blank issue
+about: Create a new issue without a template
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,22 @@
+---
+name: Bug report
+about: Please fill in the following information to the best of your ability.
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is. If there is an error message, please include it as well.
+
+**To Reproduce**
+python version: 
+siibra-python version: 
+
+```python
+# Short code snippet on how to reproduce the bug if possible. (insert your code below here)
+```
+
+**Additional context**
+Add any other context (or screenshot) about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: user feedback
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
diff --git a/.github/workflows/_run_examples.yaml b/.github/workflows/_run_examples.yaml
@@ -16,6 +16,10 @@ on:
         required: false
         type: string
         default: "INFO_WO_PROGRESS_BARS"
+      test_file:
+        required: false
+        type: string
+        default: "examples/test_examples.py, examples/test_tutorials.py"
 
 jobs:
   test_examples:
@@ -46,4 +50,4 @@ jobs:
       env:
         SIIBRA_LOG_LEVEL: ${{ inputs.siibra_log_level }}
       shell: bash
-      run: pytest -rx --durations=5 examples/test_examples.py
+      run: pytest -rx --durations=5 ${{ inputs.test_file }}
diff --git a/.github/workflows/siibra-testing.yml b/.github/workflows/siibra-testing.yml
@@ -103,12 +103,16 @@ jobs:
       test_folder: ${{ matrix.test_folder }}
     strategy:
       matrix:
-        test_folder: ["e2e/core", "e2e/volumes", "e2e/retrieval", "e2e/locations", "e2e/features/activity_timeseries", "e2e/features/connectivity", "e2e/features/image", "e2e/features/external", "e2e/features/molecular", "e2e/features/test_get.py e2e/features/test_plot.py e2e/features/test_generic.py"]
+        test_folder: ["e2e/core", "e2e/volumes", "e2e/retrieval", "e2e/locations", "e2e/features/activity_timeseries", "e2e/features/connectivity", "e2e/features/image", "e2e/features/external", "e2e/features/molecular", "e2e/features/test_get.py", "e2e/features/test_plot.py", "e2e/features/test_generic.py"]
 
   test-examples:
     needs: 'use-custom-cfg'
     uses: ./.github/workflows/_run_examples.yaml
     with:
       os: ubuntu-latest
       python-version: "3.8"
-      use-cfg: ${{ needs.use-custom-cfg.outputs.USE_REF }}
+      use-cfg: ${{ needs.use-custom-cfg.outputs.USE_REF }}
+      test_file: ${{ matrix.test_file }}
+    strategy:
+      matrix:
+        test_file: [examples/test_examples.py, examples/test_tutorials.py]
diff --git a/CITATION.cff b/CITATION.cff
@@ -15,9 +15,9 @@ license: Apache-2.0
 
 repository-code: https://github.com/FZJ-INM1-BDA/siibra-python
 
-version: v1.0.1-alpha.10
+version: v1.0.1-alpha.13
 
-date-released: 2025-08-25
+date-released: 2026-02-06
 
 doi: 10.5281/zenodo.7885728
 
diff --git a/e2e/features/image/test_image.py b/e2e/features/image/test_image.py
@@ -24,7 +24,7 @@ def test_images_datasets_names():
     all_ds_names = {ds.name for f in all_image_features for ds in f.datasets}
     end = time.time()
     duration = start - end
-    assert len(all_ds_names) == 10, "expected 10 distinct names"  # this must be updated if new datasets are added
+    assert len(all_ds_names) == 12, "expected 12 distinct names"  # this must be updated if new datasets are added
     assert duration < 1, "Expected getting dataset names to be less than 1s"
 
 
diff --git a/e2e/features/test_get.py b/e2e/features/test_get.py
@@ -38,7 +38,6 @@ def test_feature_unique(Cls: siibra.features.Feature):
 
 selected_ids = [
     "lq0::EbrainsDataFeature::p:minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290::r:Area hOc1 (V1, 17, CalcS) left::https://nexus.humanbrainproject.org/v0/data/minds/core/dataset/v1.0.0/3ff328fa-f48f-474b-bd81-b5ee7ca230b6",
-    # "cf0::BigBrainIntensityProfile::p:minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290::r:Area hOc1 (V1, 17, CalcS) left::acc39db40e08a9ce23d05bf75a4ce172::0d023118e0b9923a11628642e6170d00",  # 1574 BigBrain Intensity Profile features
     "cf0::BigBrainIntensityProfile::p:minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290::r:Area hOc1 (V1, 17, CalcS) left::acc39db40e08a9ce23d05bf75a4ce172::560a3ae060014a2076210c84e31b5412",  # 1236 BigBrain Intensity Profile features
     "lq0::BigBrainIntensityProfile::p:minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290::r:Area hOc1 (V1, 17, CalcS) left::acc39db40e08a9ce23d05bf75a4ce172--4b4e7dea27709f3367dd468f9c9a96ed",  # BigBrain Intensity Profile: (4.848050117492676, -55.64030075073242, 1.999250054359436)
     "cf0::CellDensityProfile::p:minds/core/parcellationatlas/v1.0.0/94c1125b-b87e-45e4-901c-00daee7f2579-290::r:Area hOc1 (V1, 17, CalcS)::f2cd6b97-e42d-41af-a01b-5caf2d692e28::599f219267d5bdc3c5c04ddf31f36748",  # 10 Cell Density Profile features
diff --git a/examples/02_maps_and_templates/004_access_bigbrain.py b/examples/02_maps_and_templates/004_access_bigbrain.py
@@ -53,7 +53,7 @@
     point2="-26.557mm, 6.277mm, 50.631mm",
     space=space
 )
-bigbrain_chunk = bigbrain_template.fetch(voi=voi, resolution_mm=0.02)
+bigbrain_chunk = bigbrain_template.fetch(voi=voi)
 plotting.view_img(bigbrain_chunk, bg_img=None, cmap='gray')
 
 # %%
@@ -70,10 +70,10 @@
 # %%
 # Next we select a parcellation which provides a map for BigBrain, and extract
 # labels for the same volume of interest. We choose the cortical layer maps by `Wagstyl et al<https://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.3000678>`.
-# Note that by specifying "-1" as a resolution, `siibra` will fetch the highest
-# possible resolution.
+# Note that `siibra` will fetch the highest possible resolution if not specified
+# limited by the download size which can be updated with `max_bytes`
 layermap = siibra.get_map(space='bigbrain', parcellation='layers')
-mask = layermap.fetch(fragment='left hemisphere', resolution_mm=-1, voi=voi)
+mask = layermap.fetch(fragment='left hemisphere', voi=voi)
 mask
 
 # %%
@@ -122,5 +122,5 @@
 
 # this is quite large, so we shrink it
 voi = hoc5_bbox.zoom(0.1)
-crop = section1402.fetch(voi=voi, resolution_mm=-1)
+crop = section1402.fetch(voi=voi)
 plotting.plot_img(crop, bg_img=None, cmap="gray", display_mode="y")
diff --git a/examples/test_examples.py b/examples/test_examples.py
@@ -9,7 +9,9 @@
 
 def get_examples():
     for example in pathlib.Path("./examples").resolve().rglob("*.py"):
-        if example.name == "test_examples.py":
+        if example.name in ["test_examples.py", "test_tutorials.py"]:
+            continue
+        if example.parent.name == "tutorials":  # computationally expensive, hence, a second test is performed to do them in parallel.
             continue
         yield pytest.param(example, id=example.name)
 
diff --git a/examples/test_tutorials.py b/examples/test_tutorials.py
@@ -0,0 +1,27 @@
+import pathlib
+import subprocess
+import pytest
+import sys
+from e2e.features.molecular.test_genes import xfail_if_allen_api_unavailable
+
+python_version = sys.version_info
+
+
+def get_examples():
+    for example in pathlib.Path("./examples").resolve().rglob("*.py"):
+        if example.name in ["test_examples.py", "test_tutorials.py"]:
+            continue
+        if example.parent.name != "tutorials":  # computationally expensive, hence, a second test is performed to do them in parallel.
+            continue
+        yield pytest.param(example, id=example.name)
+
+
+@pytest.mark.parametrize("example", get_examples())
+@xfail_if_allen_api_unavailable
+def test_script_execution(example: pathlib.Path):
+    result = subprocess.run(
+        ["python", example.as_posix()], capture_output=True, text=True
+    )
+    assert (
+        result.returncode == 0
+    ), f"Example {example.name} failed with:\n{result.stderr}"
diff --git a/examples/tutorials/2025-paper-fig5.py b/examples/tutorials/2025-paper-fig5.py
@@ -112,7 +112,7 @@
 
 # Fetch the region of interest from the section, and plot it.
 fig = plt.figure(figsize=(6, 5))
-roi_img = patch.section.fetch(voi=roi, resolution_mm=-1)
+roi_img = patch.section.fetch(voi=roi)
 display = plotting.plot_img(
     roi_img, display_mode="y", cmap='gray', annotate=False, figure=fig
 )
diff --git a/siibra/VERSION b/siibra/VERSION
@@ -1 +1 @@
-1.0.1-alpha.10
+1.0.1-alpha.13
diff --git a/siibra/retrieval/repositories.py b/siibra/retrieval/repositories.py
@@ -527,7 +527,7 @@ def __init__(self, dataset_id):
             self._files.extend(newfiles)
             logger.debug(f"{len(newfiles)} of {self.maxentries} objects returned.")
 
-            if len(newfiles) == self.maxentries:
+            if len(newfiles) > 0:
                 # there might be more files
                 marker = newfiles[-1]["name"]
             else:
diff --git a/siibra/volumes/parcellationmap.py b/siibra/volumes/parcellationmap.py
@@ -418,7 +418,7 @@ def fetch(
             Note that supplying 'region' will result in retrieving the map index of that region
             automatically.
         **fetch_kwargs
-            - resolution_mm: resolution in millimeters
+            - resolution_mm: resolution in millimeters as float or a tuple of floats
             - format: the format of the volume, like "mesh" or "nii"
             - voi: a BoundingBox of interest
 
diff --git a/siibra/volumes/providers/neuroglancer.py b/siibra/volumes/providers/neuroglancer.py
@@ -91,7 +91,7 @@ def _url(self) -> Union[str, Dict[str, str]]:
     def fetch(
         self,
         fragment: str = None,
-        resolution_mm: float = -1,
+        resolution_mm: Union[float, Tuple[float, float, float]] = None,
         voi: _boundingbox.BoundingBox = None,
         max_bytes: float = SIIBRA_MAX_FETCH_SIZE_BYTES,
         **kwargs,
@@ -105,11 +105,11 @@ def fetch(
             The name of a fragment volume to fetch, if any. For example,
             some volumes are split into left and right hemisphere fragments.
             See :func:`~siibra.volumes.Volume.fragments`
-        resolution_mm: float, default: -1 (i.e, the highest possible given max_bytes)
+        resolution_mm: float, default: None (i.e, the highest possible given max_bytes)
             Desired resolution in millimeters.
         voi: BoundingBox
             optional specification of a volume of interest to fetch.
-        max_bytes: float: Default: NeuroglancerVolume.MAX_BYTES
+        max_bytes: float: Default: NeuroglancerVolume.MAX_BYTES, 0.2GiB
             Maximum allowable size (in bytes) for downloading the image. siibra
             will attempt to find the highest resolution image with a size less
             than this value.
@@ -210,7 +210,7 @@ def get_boundingbox(self, **fetch_kwargs) -> "_boundingbox.BoundingBox":
 
     def _merge_fragments(
         self,
-        resolution_mm: float = -1,
+        resolution_mm: Union[float, Tuple[float, float, float]] = -1,
         voi: _boundingbox.BoundingBox = None,
         max_bytes: float = SIIBRA_MAX_FETCH_SIZE_BYTES,
     ) -> nib.Nifti1Image:
@@ -355,7 +355,7 @@ def affine(self):
 
     def fetch(
         self,
-        resolution_mm: float = -1,
+        resolution_mm: Union[float, Tuple[float, float, float]] = -1,
         voi: _boundingbox.BoundingBox = None,
         max_bytes: float = MAX_BYTES,
         **kwargs
@@ -373,47 +373,54 @@ def is_float(self):
 
     def _select_scale(
         self,
-        resolution_mm: float,
+        resolution_mm: Union[None, float, Tuple[float, float, float]],
         max_bytes: float = MAX_BYTES,
         bbox: _boundingbox.BoundingBox = None
     ) -> 'NeuroglancerScale':
-        if resolution_mm is None:
-            suitable = self.scales
-        elif resolution_mm < 0:
-            suitable = [self.scales[0]]
-        else:
-            suitable = sorted(s for s in self.scales if s.resolves(resolution_mm))
+        """
+        Select the best possible scale for a given resolution and max_bytes constraint.
+
+        If a specific resolution is requested, the smallest resolution <= max
+        requested resolution is chosen.
+
+        Parameters
+        ----------
+        resolution_mm (float/tuple): Requested resolution in mm. If negative, the highest resolution will be used.
+        max_bytes (float): Maximum allowable memory bandwidth for the fetched image.
 
-        if len(suitable) > 0:
-            scale = suitable[-1]
+        Returns
+        _______
+            NeuroglancerScale: The best resolution scale available.
+        """
+        if resolution_mm is None or (isinstance(resolution_mm, (int, float)) and resolution_mm < 0):
+            chosen_scale = min(self.scales)
         else:
-            scale = self.scales[0]
-            xyz_res = ['{:.6f}'.format(r).rstrip('0') for r in scale.res_mm]
-            if all(r.startswith(str(resolution_mm)) for r in xyz_res):
-                logger.info(f"Closest resolution to requested is {', '.join(xyz_res)} mm.")
-            else:
-                logger.warning(
-                    f"Requested resolution {resolution_mm} is not available. "
-                    f"Falling back to the highest possible resolution of "
-                    f"{', '.join(xyz_res)} mm."
+            suitable_scales = sorted([s for s in self.scales if s.resolves(resolution_mm)])
+            if not suitable_scales:
+                raise ValueError(
+                    f"Requested resolution {resolution_mm} is not feasible. Available resolutions: {[s.res_mm for s in self.scales]}"
                 )
+            chosen_scale = max(suitable_scales)  # `max` for choosing the closest resolution
+            if not all('{:.6f}'.format(r).startswith(str(resolution_mm)) for r in chosen_scale.res_mm):
+                logger.info(f"Closest resolution to requested is {chosen_scale.res_mm}")
 
+        # Further reduce resolution to fit into max_bytes if needed.
         scale_changed = False
-        while scale._estimate_nbytes(bbox) > max_bytes:
-            scale = scale.next()
-            scale_changed = True
-            if scale is None:
+        while chosen_scale is not None and chosen_scale._estimate_nbytes(bbox) > max_bytes:
+            next_scale = chosen_scale.next()
+            if not next_scale:
                 raise RuntimeError(
-                    f"Fetching bounding box {bbox} is infeasible "
-                    f"relative to the limit of {max_bytes / 1024**3}GiB."
+                    f"Infeasible resolution within {max_bytes / 1024**3} GiB."
                 )
+            chosen_scale = next_scale
+            scale_changed = True
+
         if scale_changed:
             logger.warning(
-                f"Resolution was reduced to {scale.res_mm} to provide a "
-                f"feasible volume size of {max_bytes / 1024**3} GiB. Set `max_bytes` to"
-                f" fetch in the resolution requested."
+                f"Changed resolution from {resolution_mm or self.scales[0].res_mm} to {chosen_scale.res_mm} to have download size below {max_bytes} bytes ({max_bytes / 1024**3} GiB). Increase `max_bytes` to allow higher-resolution downloads."
             )
-        return scale
+
+        return chosen_scale
 
 
 class NeuroglancerScale:
@@ -434,11 +441,15 @@ def __init__(self, volume: NeuroglancerVolume, scaleinfo: dict):
     def res_mm(self):
         return self.res_nm / 1e6
 
-    def resolves(self, resolution_mm):
+    def resolves(self, resolution_mm: Union[float, Tuple[float, float, float]]):
         """Test whether the resolution of this scale is sufficient to provide the given resolution."""
+        if isinstance(resolution_mm, tuple):
+            return all(self.res_nm / 1e6 <= resolution_mm)
+        if resolution_mm < 0:  # preserve legacy behaviour
+            return True
         return all(r / 1e6 <= resolution_mm for r in self.res_nm)
 
-    def __lt__(self, other):
+    def __lt__(self, other: "NeuroglancerScale"):
         """Sort scales by resolution."""
         return all(self.res_nm[i] < other.res_nm[i] for i in range(3))
 
diff --git a/siibra/volumes/volume.py b/siibra/volumes/volume.py
@@ -450,6 +450,10 @@ def fetch(self, format: str = None, **kwargs):
                 - supported format types, see SUPPORTED_FORMATS. This includes
                 'nii', 'zip/nii', 'neuroglancer/precomputed', 'gii-mesh',
                 'neuroglancer/precompmesh', 'gii-label'
+        **kwargs
+            - resolution_mm: resolution in millimeters as float or a tuple of floats
+            - format: the format of the volume, like "mesh" or "nii"
+            - voi: a BoundingBox of interest
 
         Returns
         -------
