siibra 1.0.1a2__tar.gz → 1.0.1a5__tar.gz

{siibra-1.0.1a2/siibra.egg-info → siibra-1.0.1a5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: siibra
-Version: 1.0.1a2
+Version: 1.0.1a5
 Summary: siibra - Software interfaces for interacting with brain atlases
 Home-page: https://github.com/FZJ-INM1-BDA/siibra-python
 Author: Big Data Analytics Group, Forschungszentrum Juelich, Institute of Neuroscience and Medicine (INM-1)
@@ -33,6 +33,7 @@ Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: license-file
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -43,18 +44,16 @@ Dynamic: summary
 siibra - Software interface for interacting with brain atlases
 ==============================================================
 
-Copyright 2018-2024, Forschungszentrum Jülich GmbH
+Copyright 2018-2025, Forschungszentrum Jülich GmbH
 
 *Authors: Big Data Analytics Group, Institute of Neuroscience and
 Medicine (INM-1), Forschungszentrum Jülich GmbH*
 
 .. intro-start
 
-``siibra`` is a Python client to a brain atlas framework that integrates brain parcellations and reference spaces at different spatial scales, and connects them with a broad range of multimodal regional data features. 
+``siibra-python`` is a Python client to a brain atlas framework that integrates brain parcellations and reference spaces at different spatial scales, and connects them with a broad range of multimodal regional data features. 
 It aims to facilitate programmatic and reproducible incorporation of brain parcellations and brain region features from different sources into neuroscience workflows.
 
-    **Note:** ``siibra-python`` *is still in development. While care is taken that it works reliably, its API is not yet stable and you may still encounter bugs when using it.*
-
 ``siibra`` provides structured access to parcellation schemes in different brain reference spaces, including volumetric reference templates at  macroscopic and microscopic resolutions as well as surface representations. 
 It supports both discretely labelled and statistical (probabilistic) parcellation maps, which can be used to assign brain regions to spatial locations and image signals, to retrieve region-specific neuroscience datasets from multiple online repositories, and to sample information from high-resolution image data. 
 The datasets anchored to brain regions address features of molecular, cellular and architecture as well as connectivity, and are complemented with live queries to external repositories as well as dynamic extraction from "big" image volumes such as the 20 micrometer BigBrain model.
@@ -84,10 +83,26 @@ Installation
 
 ``siibra`` is available on pypi. 
 To install the latest released version, simply run ``pip install siibra``. 
+The installation typically takes about 2 minutes on a standard computer where Python is already installed.
 In order to work with the latest version from github, use ``pip install git+https://github.com/FZJ-INM1-BDA/siibra-python.git@main``.
 
-There is also an image based on jupyter:scipy-notebook, which already includes ``siibra``.
-
+``siibra-python`` should be installable on recent versions of Windows, Linux and Mac OS in a recent Python 3 environment.
+We run continuous integration tests for versions 3.7 - 3.12 on recent Ubuntu images. 
+
+The library requires a couple of open source packages, namely:
+```
+anytree >= 2.12.1
+nibabel >= 5.3.2
+appdirs >= 1.4.4
+scikit-image >= 0.25.0
+requests >= 2.32.3
+neuroglancer-scripts >= 1.2.0
+nilearn >= 0.11.0
+filelock >= 3.16.1
+ebrains-drive >= 0.6.0
+```
+
+You can also install a docker image with all dependencies included:
 .. code-block:: sh
 
   docker run -dit \
@@ -97,19 +112,20 @@ There is also an image based on jupyter:scipy-notebook, which already includes `
         docker-registry.ebrains.eu/siibra/siibra-python:latest
 
 
+
 Documentation & Help
 ====================
 
 ``siibra-python``\ ’s documentation is hosted on https://siibra-python.readthedocs.io.
 The documentation includes a catalogue of documented code examples that walk you through the different concepts and functionalities.
+These examples use real data and include both the code and the produced expected outputs.
+They can be accessed at https://siibra-python.readthedocs.io/en/latest/examples.html, and are
+automatically tested and updated whenever a new version of ``siibra-python`` is published.
 As a new user, it is recommended to go through these examples - they are easy and will quickly provide you with the right code snippets that get you started.
-Furthermore, a set of jupyter notebooks demonstrating more extensive example use cases are maintained in the `siibra-tutorials <https://github.com/FZJ-INM1-BDA/siibra-tutorials>`__ repository.
-We are working on a full API documentation of the library. You find the current status on readthedocs, but be aware that it is not yet complete and as up-to-date as the code examples.
+The documentation on readthedocs further includes introductory explanations and an API reference.
 
 If you run into issues, please open a ticket on `EBRAINS support <https://ebrains.eu/support/>`__ or file bugs and
 feature requests on `github <https://github.com/FZJ-INM1-BDA/siibra-python/issues>`__.
-Please keep in mind that ``siibra-python`` is still in development.
-While care is taken to make everything work reliably, the API of the library is not yet stable, and the software is not yet fully tested.
 
 .. getting-started-end
 

{siibra-1.0.1a2 → siibra-1.0.1a5}/README.rst

@@ -4,18 +4,16 @@
 siibra - Software interface for interacting with brain atlases
 ==============================================================
 
-Copyright 2018-2024, Forschungszentrum Jülich GmbH
+Copyright 2018-2025, Forschungszentrum Jülich GmbH
 
 *Authors: Big Data Analytics Group, Institute of Neuroscience and
 Medicine (INM-1), Forschungszentrum Jülich GmbH*
 
 .. intro-start
 
-``siibra`` is a Python client to a brain atlas framework that integrates brain parcellations and reference spaces at different spatial scales, and connects them with a broad range of multimodal regional data features. 
+``siibra-python`` is a Python client to a brain atlas framework that integrates brain parcellations and reference spaces at different spatial scales, and connects them with a broad range of multimodal regional data features. 
 It aims to facilitate programmatic and reproducible incorporation of brain parcellations and brain region features from different sources into neuroscience workflows.
 
-    **Note:** ``siibra-python`` *is still in development. While care is taken that it works reliably, its API is not yet stable and you may still encounter bugs when using it.*
-
 ``siibra`` provides structured access to parcellation schemes in different brain reference spaces, including volumetric reference templates at  macroscopic and microscopic resolutions as well as surface representations. 
 It supports both discretely labelled and statistical (probabilistic) parcellation maps, which can be used to assign brain regions to spatial locations and image signals, to retrieve region-specific neuroscience datasets from multiple online repositories, and to sample information from high-resolution image data. 
 The datasets anchored to brain regions address features of molecular, cellular and architecture as well as connectivity, and are complemented with live queries to external repositories as well as dynamic extraction from "big" image volumes such as the 20 micrometer BigBrain model.
@@ -45,10 +43,26 @@ Installation
 
 ``siibra`` is available on pypi. 
 To install the latest released version, simply run ``pip install siibra``. 
+The installation typically takes about 2 minutes on a standard computer where Python is already installed.
 In order to work with the latest version from github, use ``pip install git+https://github.com/FZJ-INM1-BDA/siibra-python.git@main``.
 
-There is also an image based on jupyter:scipy-notebook, which already includes ``siibra``.
-
+``siibra-python`` should be installable on recent versions of Windows, Linux and Mac OS in a recent Python 3 environment.
+We run continuous integration tests for versions 3.7 - 3.12 on recent Ubuntu images. 
+
+The library requires a couple of open source packages, namely:
+```
+anytree >= 2.12.1
+nibabel >= 5.3.2
+appdirs >= 1.4.4
+scikit-image >= 0.25.0
+requests >= 2.32.3
+neuroglancer-scripts >= 1.2.0
+nilearn >= 0.11.0
+filelock >= 3.16.1
+ebrains-drive >= 0.6.0
+```
+
+You can also install a docker image with all dependencies included:
 .. code-block:: sh
 
   docker run -dit \
@@ -58,19 +72,20 @@ There is also an image based on jupyter:scipy-notebook, which already includes `
         docker-registry.ebrains.eu/siibra/siibra-python:latest
 
 
+
 Documentation & Help
 ====================
 
 ``siibra-python``\ ’s documentation is hosted on https://siibra-python.readthedocs.io.
 The documentation includes a catalogue of documented code examples that walk you through the different concepts and functionalities.
+These examples use real data and include both the code and the produced expected outputs.
+They can be accessed at https://siibra-python.readthedocs.io/en/latest/examples.html, and are
+automatically tested and updated whenever a new version of ``siibra-python`` is published.
 As a new user, it is recommended to go through these examples - they are easy and will quickly provide you with the right code snippets that get you started.
-Furthermore, a set of jupyter notebooks demonstrating more extensive example use cases are maintained in the `siibra-tutorials <https://github.com/FZJ-INM1-BDA/siibra-tutorials>`__ repository.
-We are working on a full API documentation of the library. You find the current status on readthedocs, but be aware that it is not yet complete and as up-to-date as the code examples.
+The documentation on readthedocs further includes introductory explanations and an API reference.
 
 If you run into issues, please open a ticket on `EBRAINS support <https://ebrains.eu/support/>`__ or file bugs and
 feature requests on `github <https://github.com/FZJ-INM1-BDA/siibra-python/issues>`__.
-Please keep in mind that ``siibra-python`` is still in development.
-While care is taken to make everything work reliably, the API of the library is not yet stable, and the software is not yet fully tested.
 
 .. getting-started-end
 

siibra-1.0.1a5/siibra/VERSION

@@ -0,0 +1 @@
+1.0.1-alpha.5

{siibra-1.0.1a2 → siibra-1.0.1a5}/siibra/commons.py

@@ -534,13 +534,21 @@ def resample_img_to_img(
     -------
     Nifti1Image
     """
+    from nilearn._version import version as nilearn_version
+    from packaging.version import Version
+
     interpolation = "nearest" if np.array_equal(np.unique(source_img.dataobj), [0, 1]) else "linear"
-    resampled_img = resample_to_img(
+    kwargs = dict(
         source_img=source_img,
         target_img=target_img,
         interpolation=interpolation,
         force_resample=True,  # False is intended for testing. see nilearn docs
     )
+    if Version(nilearn_version) >= Version("0.11.0"):
+        # because nilearn>=0.11.0 don't support "copy_header" and python <= 3.8
+        kwargs["copy_header"] = True  # use new default in nilearn >= 0.11.0
+
+    resampled_img = resample_to_img(**kwargs)
     return resampled_img
 
 
@@ -725,6 +733,7 @@ class Species(Enum):
     MACACA_MULATTA = 5
     MACACA_FUSCATA = 6
     CHLOROCEBUS_AETHIOPS_SABAEUS = 7
+    CALLITHRIX_JACCHUS = 8
 
     UNSPECIFIED_SPECIES = 999
 

{siibra-1.0.1a2 → siibra-1.0.1a5}/siibra/configuration/configuration.py

@@ -185,5 +185,4 @@ class Configuration:
 
 
 if SIIBRA_USE_CONFIGURATION:
-    logger.warning(f"config.SIIBRA_USE_CONFIGURATION defined, use configuration at {SIIBRA_USE_CONFIGURATION}")
     Configuration.use_configuration(SIIBRA_USE_CONFIGURATION)

{siibra-1.0.1a2 → siibra-1.0.1a5}/siibra/configuration/factory.py

@@ -487,6 +487,10 @@ class Factory:
             return volume_of_interest.LSFMVolumeOfInterest(
                 modality="Light Sheet Fluorescence Microscopy", **kwargs
             )
+        elif modality == "morphometry":
+            return volume_of_interest.MorphometryVolumeOfInterest(
+                modality="Morphometry", **kwargs
+            )
         else:
             raise ValueError(
                 f"No method for building image section feature type {modality}."

{siibra-1.0.1a2 → siibra-1.0.1a5}/siibra/core/assignment.py

@@ -26,12 +26,12 @@ T = TypeVar("T")
 
 class Qualification(Enum):
     EXACT = 1
-    OVERLAPS = 2
-    CONTAINED = 3
-    CONTAINS = 4
-    APPROXIMATE = 5
-    HOMOLOGOUS = 6
-    OTHER_VERSION = 7
+    APPROXIMATE = 2
+    OTHER_VERSION = 3
+    CONTAINED = 4
+    CONTAINS = 5
+    OVERLAPS = 6
+    HOMOLOGOUS = 7
 
     @property
     def verb(self):
@@ -67,6 +67,17 @@ class Qualification(Enum):
         assert self in inverses, f"{str(self)} inverses cannot be found."
         return inverses[self]
 
+    def __lt__(self, other: "Qualification"):
+        """
+        This is used to sort feature query results. Since it is very difficult
+        to determine a well-ordering principle and it is difficult to sort
+        without one, the enum values are used for sorting. This means
+        not all comparisons have logical basis but they are well-defined,
+        making it reproducible but also clearly distinguishes important
+        comparisons.
+        """
+        return self.value < other.value
+
     def __str__(self):
         return f"{self.__class__.__name__}={self.name.lower()}"
 
@@ -108,4 +119,4 @@ class AnatomicalAssignment(Generic[T]):
     def __lt__(self, other: 'AnatomicalAssignment'):
         if not isinstance(other, AnatomicalAssignment):
             raise ValueError(f"Cannot compare AnatomicalAssignment with instances of '{type(other)}'")
-        return self.qualification.value < other.qualification.value
+        return self.qualification < other.qualification

{siibra-1.0.1a2 → siibra-1.0.1a5}/siibra/explorer/url.py

@@ -136,7 +136,7 @@ def encode_url(
 
     try:
         result_props = region.spatial_props(space, maptype="labelled")
-        if len(result_props.components) == 0:
+        if len(result_props) == 0:
             return return_url + nav_string.format(encoded_nav=encoded_position or "0.0.0", **zoom_kwargs)
     except Exception as e:
         print(f"Cannot get_spatial_props {str(e)}")
@@ -144,7 +144,7 @@ def encode_url(
             raise e
         return return_url + nav_string.format(encoded_nav=encoded_position or "0.0.0", **zoom_kwargs)
 
-    centroid = result_props.components[0].centroid
+    centroid = result_props[0].centroid
 
     encoded_centroid = separator.join(
         [encode_number(math.floor(val * 1e6)) for val in centroid]

{siibra-1.0.1a2 → siibra-1.0.1a5}/siibra/features/anchor.py

@@ -176,9 +176,7 @@ class AnatomicalAnchor:
                 assignments.append(region.assign(concept))
             self._assignments[concept] = sorted(a for a in assignments if a is not None)
 
-        self._last_matched_concept = concept \
-            if len(self._assignments[concept]) > 0 \
-            else None
+        self._last_matched_concept = concept if len(self._assignments[concept]) > 0 else None
         return self._assignments[concept]
 
     def matches(self, concept: Union[BrainStructure, Space]) -> bool:

{siibra-1.0.1a2 → siibra-1.0.1a5}/siibra/features/connectivity/regional_connectivity.py

@@ -104,6 +104,7 @@ class RegionalConnectivity(Feature, Compoundable):
         self._matrix = None
         self._subject = subject
         self._feature = feature
+        self._matrix_std = None  # only used for compound feature
 
     @property
     def subject(self):
@@ -170,6 +171,9 @@ class RegionalConnectivity(Feature, Compoundable):
         merged._matrix = elements[0]._arraylike_to_dataframe(
             np.stack(all_arrays).mean(0)
         )
+        merged._matrix_std = elements[0]._arraylike_to_dataframe(
+            np.stack(all_arrays).std(0)
+        )
         return merged
 
     def _plot_matrix(
@@ -258,10 +262,14 @@ class RegionalConnectivity(Feature, Compoundable):
             non-symmetric matrices. ('column' or 'row')
         """
         matrix = self.data
+        assert isinstance(matrix, pd.DataFrame)
+        matrix_std = self._matrix_std
         if direction.lower() not in ['column', 'row']:
             raise ValueError("Direction can only be 'column' or 'row'")
         if direction.lower() == 'row':
             matrix = matrix.transpose()
+            if matrix_std is not None:
+                matrix_std = matrix_std.transpose()
 
         def matches(r1, r2):
             if isinstance(r1, tuple):
@@ -270,32 +278,38 @@ class RegionalConnectivity(Feature, Compoundable):
                 assert isinstance(r1, _region.Region)
                 return r1.matches(r2)
 
-        regions = [r for r in matrix.index if matches(r, region)]
-        if len(regions) == 0:
+        # decode region spec
+        region_candidates = [r for r in matrix.index if matches(r, region)]
+        if len(region_candidates) == 0:
             raise ValueError(f"Invalid region specification: {region}")
-        elif len(regions) > 1:
-            raise ValueError(f"Region specification {region} matched more than one profile: {regions}")
-        else:
-            name = self.modality
-            series = matrix[regions[0]]
-            last_index = len(series) - 1 if max_rows is None \
-                else min(max_rows, len(series) - 1)
-            return Tabular(
-                description=self.description,
-                modality=f"{self.modality} {self.cohort}",
-                anchor=_anchor.AnatomicalAnchor(
-                    species=list(self.anchor.species)[0],
-                    region=regions[0]
-                ),
-                data=(
-                    series[:last_index]
-                    .to_frame(name=name)
-                    .query(f'`{name}` > {min_connectivity}')
-                    .sort_values(by=name, ascending=False)
-                    .rename_axis('Target regions')
-                ),
-                datasets=self.datasets
-            )
+        if len(region_candidates) > 1:
+            raise ValueError(f"Region specification {region} matched more than one profile: {region_candidates}")
+        region = region_candidates[0]
+
+        # create DataFrame
+        data = matrix[region].to_frame('mean')
+        if matrix_std is not None:
+            data = pd.concat([data, matrix_std[region].rename('std')], axis=1)
+
+        last_index = len(data) if max_rows is None else min(max_rows, len(data))
+
+        data = (
+            data
+            .query(f'`mean` > {min_connectivity}')
+            .sort_values(by="mean", ascending=False)
+            .rename_axis('Target regions')
+        )[:last_index]
+
+        return Tabular(
+            description=self.description,
+            modality=f"{self.modality} {self.cohort}",
+            anchor=_anchor.AnatomicalAnchor(
+                species=list(self.anchor.species)[0],
+                region=region
+            ),
+            data=data,
+            datasets=self.datasets
+        )
 
     def plot(
         self,
@@ -336,8 +350,8 @@ class RegionalConnectivity(Feature, Compoundable):
         profile = self.get_profile(regions, min_connectivity, max_rows, direction)
         kwargs["kind"] = kwargs.get("kind", "barh")
         if backend == "matplotlib":
-            kwargs["logx"] = kwargs.get("logx", logscale)
-            return profile.data.plot(*args, backend=backend, **kwargs)
+            kwargs["logy"] = kwargs.get("logy", logscale)
+            return profile.plot(*args, backend=backend, **kwargs)
         elif backend == "plotly":
             kwargs.update({
                 "color": kwargs.get("color", profile.data.columns[0]),

{siibra-1.0.1a2 → siibra-1.0.1a5}/siibra/features/feature.py

@@ -232,7 +232,10 @@ class Feature:
         from ..configuration.configuration import Configuration
         conf = Configuration()
         Configuration.register_cleanup(cls._clean_instances)
-        assert cls._configuration_folder in conf.folders
+        if cls._configuration_folder not in conf.folders:
+            logger.debug(f"{cls._configuration_folder} is not in current configuration")
+            return []
+
         cls._preconfigured_instances = [
             o for o in conf.build_objects(cls._configuration_folder)
             if isinstance(o, cls)
@@ -580,7 +583,10 @@ class Feature:
         # with the query concept.
         live_instances = feature_type._livequery(concept, **kwargs)
 
-        results = list(dict.fromkeys(preconfigured_instances + live_instances))
+        results = sorted(
+            dict.fromkeys(preconfigured_instances + live_instances),  # to remove duplicates
+            key=lambda f: min(f.last_match_result) if f.last_match_result else False,  # to order according to assignmnent ranking
+        )
         return CompoundFeature._compound(results, concept)
 
     @classmethod

{siibra-1.0.1a2 → siibra-1.0.1a5}/siibra/features/image/__init__.py

@@ -21,7 +21,8 @@ from .volume_of_interest import (
     MRIVolumeOfInterest,
     XPCTVolumeOfInterest,
     LSFMVolumeOfInterest,
-    DTIVolumeOfInterest
+    DTIVolumeOfInterest,
+    MorphometryVolumeOfInterest,
 )
 from .sections import (
     CellbodyStainedSection,

{siibra-1.0.1a2 → siibra-1.0.1a5}/siibra/features/image/volume_of_interest.py

@@ -78,3 +78,12 @@ class LSFMVolumeOfInterest(
 ):
     def __init__(self, modality, **kwargs):
         image.Image.__init__(self, **kwargs, modality=modality)
+
+
+class MorphometryVolumeOfInterest(
+    image.Image,
+    configuration_folder="features/images/vois/morphometry",
+    category="macrostructural"
+):
+    def __init__(self, modality, **kwargs):
+        image.Image.__init__(self, **kwargs, modality=modality)

{siibra-1.0.1a2 → siibra-1.0.1a5}/siibra/features/tabular/gene_expression.py

@@ -225,6 +225,7 @@ class GeneExpressions(
             datasets=datasets
         )
         self.unit = "expression level"
+        self._genes = list(set(genes))
 
     def plot(self, *args, backend="matplotlib", **kwargs):
         """
@@ -239,18 +240,34 @@ class GeneExpressions(
             Keyword arguments are passed on to the plot command.
         """
         wrapwidth = kwargs.pop("textwrap") if "textwrap" in kwargs else 40
-        kwargs["title"] = kwargs.pop("title", None) \
-            or "\n".join(wrap(f"{self.modality} measured in {self.anchor._regionspec or self.anchor.location}", wrapwidth))
-        kwargs["kind"] = "box"
+        kwargs["title"] = kwargs.pop(
+            "title",
+            "\n".join(wrap(
+                f"{self.modality}\n{self.anchor._regionspec or self.anchor.location}",
+                wrapwidth
+            ))
+        )
+        kwargs["kind"] = kwargs.get("kind", "box")
         if backend == "matplotlib":
-            for arg in ['yerr', 'y', 'ylabel', 'xlabel', 'width']:
-                assert arg not in kwargs
-            default_kwargs = {
-                "grid": True, "legend": False, 'by': "gene",
-                'column': ['level'], 'showfliers': False, 'ax': None,
-                'ylabel': 'expression level'
-            }
-            return self.data.plot(*args, **{**default_kwargs, **kwargs}, backend=backend)
+            if kwargs["kind"] == "box":
+                from matplotlib.pyplot import tight_layout
+
+                title = kwargs.pop("title")
+                default_kwargs = {
+                    "grid": True,
+                    'by': "gene",
+                    'column': ['level'],
+                    'showfliers': False,
+                    'ylabel': 'expression level',
+                    'xlabel': 'gene',
+                    'color': 'dimgray',
+                    'rot': 90 if len(self._genes) > 1 else 0,
+                }
+                ax, *_ = self.data.plot(*args, backend=backend, **{**default_kwargs, **kwargs})
+                ax.set_title(title)
+                tight_layout()
+                return ax
+            return self.data.plot(*args, backend=backend, **kwargs)
         elif backend == "plotly":
             kwargs["title"] = kwargs["title"].replace('\n', "<br>")
             return self.data.plot(y='level', x='gene', backend=backend, **kwargs)