siibra 1.0a8__py3-none-any.whl → 1.0a11__py3-none-any.whl

siibra/VERSION

@@ -1 +1 @@
-1.0a08
+1.0a11

siibra/commons.py

@@ -18,11 +18,12 @@ import os
 import re
 from enum import Enum
 from nibabel import Nifti1Image
+from nilearn.image import resample_to_img
 import logging
 from tqdm import tqdm
 import numpy as np
 import pandas as pd
-from typing import Generic, Iterable, Iterator, List, TypeVar, Union, Dict
+from typing import Generic, Iterable, Iterator, List, TypeVar, Union, Dict, Generator, Tuple
 from skimage.filters import gaussian
 from dataclasses import dataclass
 from hashlib import md5
@@ -102,9 +103,11 @@ class InstanceTable(Generic[T], Iterable):
         self._dataframe_cached = None
 
     def add(self, key: str, value: T) -> None:
-        """Add a key/value pair to the registry.
+        """
+        Add a key/value pair to the registry.
 
-        Args:
+        Parameters
+        ----------
             key (string): Unique name or key of the object
             value (object): The registered object
         """
@@ -153,10 +156,13 @@ class InstanceTable(Generic[T], Iterable):
         the first in sorted order is returned. If the specification does not match,
         a RuntimeError is raised.
 
-        Args:
-            spec [int or str]: Index or string specification of an object
+        Parameters
+        ----------
+        spec: int, str
+            Index or string specification of an object
 
-        Returns:
+        Returns
+        -------
             Matched object
         """
         if spec is None:
@@ -508,34 +514,69 @@ def compare_arrays(arr1: np.ndarray, affine1: np.ndarray, arr2: np.ndarray, affi
     )
 
 
-def resample_array_to_array(
-    source_data: np.ndarray,
-    source_affine: np.ndarray,
-    target_data: np.ndarray,
-    target_affine: np.ndarray
-) -> np.ndarray:
+def resample_img_to_img(
+    source_img: Nifti1Image,
+    target_img: Nifti1Image,
+    interpolation: str = ""
+) -> Nifti1Image:
     """
-    Returns the source data resampled to match the target data
-    according to their affines.
+    Resamples to source image to match the target image according to target's
+    affine. (A wrapper of `nilearn.image.resample_to_img`.)
+
+    Parameters
+    ----------
+    source_img : Nifti1Image
+    target_img : Nifti1Image
+    interpolation : str, Default: "nearest" if the source image is a mask otherwise "linear".
+        Can be 'continuous', 'linear', or 'nearest'. Indicates the resample method.
+
+    Returns
+    -------
+    Nifti1Image
     """
-    from nibabel import Nifti1Image
-    from nilearn.image import resample_to_img
-    interp = "nearest" if issubclass(source_data.dtype.type, np.integer) \
-        else 'linear'
+    interpolation = "nearest" if np.array_equal(np.unique(source_img.dataobj), [0, 1]) else "linear"
     resampled_img = resample_to_img(
-        Nifti1Image(source_data, source_affine),
-        Nifti1Image(target_data, target_affine),
-        interpolation=interp
+        source_img=source_img,
+        target_img=target_img,
+        interpolation=interpolation
     )
-    return np.asanyarray(resampled_img.dataobj)
+    return resampled_img
 
 
-def connected_components(imgdata: np.ndarray):
+def connected_components(
+    imgdata: np.ndarray,
+    background: int = 0,
+    connectivity: int = 2,
+    threshold: float = 0.0,
+) -> Generator[Tuple[int, np.ndarray], None, None]:
     """
-    Provide an iterator over connected components in the array
+    Provide an iterator over connected components in the array. If the image
+    data is float (such as probability maps), it will convert to a mask and
+    then find the connected components.
+
+    Note
+    ----
+    `Uses skimage.measure.label()` to determine foreground compenents.
+
+    Parameters
+    ----------
+    imgdata : np.ndarray
+    background_value : int, Default: 0
+    connectivity : int, Default: 2
+    threshold: float, Default: 0.0
+        The threshold used to create mask from probability maps, i.e, anything
+        below set to 0 and rest to 1.
+
+    Yields
+    ------
+    Generator[Tuple[int, np.ndarray], None, None]
+        tuple of integer label of the component and component as an nd.array in
+        the shape of the original image.
     """
     from skimage import measure
-    components = measure.label(imgdata, connectivity=2, background=0)
+
+    mask = (imgdata > threshold).astype('uint8')
+    components = measure.label(mask, connectivity=connectivity, background=background)
     component_labels = np.unique(components)
     return (
         (label, (components == label).astype('uint8'))
@@ -630,11 +671,15 @@ def MI(arr1, arr2, nbins=100, normalized=True):
     """
     Compute the mutual information between two 3D arrays, which need to have the same shape.
 
-    Parameters:
-    arr1 : First 3D array
-    arr2 : Second 3D array
-    nbins : number of bins to use for computing the joint histogram (applies to intensity range)
-    normalized : Boolean, default:True
+    Parameters
+    ----------
+    arr1: np.ndarray
+        First 3D array
+    arr2: np.ndarray
+        Second 3D array
+    nbins: int
+        number of bins to use for computing the joint histogram (applies to intensity range)
+    normalized: Boolean. Default: True
         if True, the normalized MI of arrays X and Y will be returned,
         leading to a range of values between 0 and 1. Normalization is
         achieved by NMI = 2*MI(X,Y) / (H(X) + H(Y)), where  H(x) is the entropy of X

siibra/configuration/factory.py

@@ -27,12 +27,12 @@ from ..core import atlas, parcellation, space, region
 from ..locations import point, pointset
 from ..retrieval import datasets, repositories
 from ..volumes import volume, sparsemap, parcellationmap
-from ..volumes.providers import provider, gifti, neuroglancer, nifti
+from ..volumes.providers.provider import VolumeProvider
 
 from os import path
 import json
 import numpy as np
-from typing import List, Type, Dict, Callable
+from typing import List, Dict, Callable
 import pandas as pd
 from io import BytesIO
 from functools import wraps
@@ -102,7 +102,7 @@ class Factory:
         for i, vspec in enumerate(volume_specs):
             if space_id:
                 if 'space' in vspec:
-                    logger.warning(f"Replacing space spec {vspec['space']} in volume spec with {space_id}")
+                    assert vspec['space']["@id"] == space_id, "Space spec {vspec['space']} in volume field must be the same with space field in the configuration."
                 vspec['space'] = {"@id": space_id}
             if names and vspec.get('name') is None:  # only use provided name if the volume has no specific name
                 vspec['name'] = names[i]
@@ -256,18 +256,9 @@ class Factory:
     @build_type("siibra/volume/v0.0.1")
     def build_volume(cls, spec):
         providers: List[volume.VolumeProvider] = []
-        provider_types: List[Type[volume.VolumeProvider]] = [
-            neuroglancer.NeuroglancerProvider,
-            neuroglancer.NeuroglancerMesh,
-            neuroglancer.NeuroglancerSurfaceMesh,
-            nifti.NiftiProvider,
-            nifti.ZipContainedNiftiProvider,
-            gifti.GiftiMesh,
-            gifti.GiftiSurfaceLabeling
-        ]
 
         for srctype, provider_spec in spec.get("providers", {}).items():
-            for ProviderType in provider_types:
+            for ProviderType in VolumeProvider._SUBCLASSES:
                 if srctype == ProviderType.srctype:
                     providers.append(ProviderType(provider_spec))
                     break
@@ -276,7 +267,7 @@ class Factory:
                     logger.warning(f"No provider defined for volume Source type {srctype}")
                     cls._warnings_issued.append(srctype)
 
-        assert all([isinstance(p, provider.VolumeProvider) for p in providers])
+        assert all([isinstance(p, VolumeProvider) for p in providers])
         result = volume.Volume(
             space_spec=spec.get("space", {}),
             providers=providers,
@@ -294,7 +285,7 @@ class Factory:
         assert "filename" in spec
         basename = path.splitext(path.basename(spec['filename']))[0]
         name = basename.replace('-', ' ').replace('_', ' ').replace('continuous', 'statistical')
-        identifier = f"{spec['@type'].replace('/','-')}_{basename}"
+        identifier = f"{spec['@type'].replace('/', '-')}_{basename}"
         volumes = cls.extract_volumes(spec, space_id=spec["space"].get("@id"), name_prefix=basename)
 
         if spec.get("sparsemap", {}).get("is_sparsemap"):
@@ -365,6 +356,7 @@ class Factory:
             tsvfile=spec['file'],
             anchor=cls.extract_anchor(spec),
             datasets=cls.extract_datasets(spec),
+            id=spec.get("@id", None)
         )
 
     @classmethod
@@ -375,6 +367,7 @@ class Factory:
             layerfiles=spec['layerfiles'],
             anchor=cls.extract_anchor(spec),
             datasets=cls.extract_datasets(spec),
+            id=spec.get("@id", None)
         )
 
     @classmethod
@@ -385,6 +378,7 @@ class Factory:
             tsvfile=spec['file'],
             anchor=cls.extract_anchor(spec),
             datasets=cls.extract_datasets(spec),
+            id=spec.get("@id", None)
         )
 
     @classmethod
@@ -396,6 +390,7 @@ class Factory:
             url=spec['file'],
             anchor=cls.extract_anchor(spec),
             datasets=cls.extract_datasets(spec),
+            id=spec.get("@id", None)
         )
 
     @classmethod
@@ -408,6 +403,7 @@ class Factory:
             "space_spec": vol._space_spec,
             "providers": vol._providers.values(),
             "datasets": cls.extract_datasets(spec),
+            "id": spec.get("@id", None)
         }
         modality = spec.get('modality', "")
         if modality == "cell body staining":
@@ -425,6 +421,7 @@ class Factory:
             "space_spec": vol._space_spec,
             "providers": vol._providers.values(),
             "datasets": cls.extract_datasets(spec),
+            "id": spec.get("@id", None)
         }
         modality = spec.get('modality', "")
         if modality == "cell body staining":
@@ -495,7 +492,8 @@ class Factory:
                 "filename": filename,
                 "subject": fkey if files_indexed_by == "subject" else "average",
                 "feature": fkey if files_indexed_by == "feature" else None,
-                "connector": repo_connector or base_url + filename
+                "connector": repo_connector or base_url + filename,
+                "id": spec.get("@id", None)
             })
             conn_by_file.append(conn_cls(**kwargs))
         return conn_by_file
@@ -528,7 +526,8 @@ class Factory:
         for fkey, filename in files.items():
             kwargs.update({
                 "filename": filename,
-                "subject": fkey
+                "subject": fkey,
+                "id": spec.get("@id", None)
             })
             timeseries_by_file.append(timeseries_cls(**kwargs))
         return timeseries_by_file

siibra/core/atlas.py

@@ -64,9 +64,20 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
             matchfunc=_parcellation.Parcellation.match,
         )
 
-    def get_parcellation(self, parcellation=None):
-        """Returns a valid parcellation object defined by the atlas.
-        If no specification is provided, the default is returned."""
+    def get_parcellation(self, parcellation=None) -> "_parcellation.Parcellation":
+        """
+        Returns a valid parcellation object defined by the atlas. If no
+        specification is provided, the default is returned.
+
+        Parameters
+        ----------
+        parcellation: str, Parcellation
+            specification of a parcellation or a parcellation object
+
+        Returns
+        -------
+            Parcellation
+        """
 
         if parcellation is None:
             parcellation_obj = self.parcellations[self._parcellation_ids[0]]
@@ -80,12 +91,19 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
 
         return self.parcellations[parcellation]
 
-    def get_space(self, space=None):
-        """Returns a valid reference space object defined by the atlas.
-        If no specification is provided, the default is returned.
+    def get_space(self, space=None) -> "_space.Space":
+        """
+        Returns a valid reference space object defined by the atlas. If no
+        specification is provided, the default is returned.
+
+        Parameters
+        ----------
+        space: str, Space
+            specification of a space or a space object
 
-        Parameters:
-            space: Space, or string specification of a space
+        Returns
+        -------
+            Space
         """
         if space is None:
             space_obj = self.spaces[self._space_ids[0]]
@@ -105,12 +123,13 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
         parcellation: _parcellation.Parcellation = None,
         maptype: MapType = MapType.LABELLED,
     ):
-        """Returns a parcellation map in the given space.
+        """
+        Returns a parcellation map in the given space.
 
         Parameters
         ----------
 
-        space : Space
+        space: Space
             The requested reference space. If None, the default is used.
         parcellation: Parcellation
             The requested parcellation. If None, the default is used.
@@ -160,13 +179,18 @@ class Atlas(concept.AtlasConcept, configuration_folder="atlases"):
     def get_voi(self, space: _space.Space, point1: tuple, point2: tuple):
         """Get a volume of interest spanned by two points in the given reference space.
 
-        Args:
-            space (Space or str): The target reference space, or a string specification of the space
-            point1 (Tuple): A 3D coordinate given in this reference space
-            point2 (Tuple): Another 3D coordinate given in this reference space
+        Parameters
+        ----------
+        space: Space, str
+            The target reference space, or a string specification of the space
+        point1: Tuple
+            A 3D coordinate given in this reference space
+        point2: Tuple
+            Another 3D coordinate given in this reference space
 
-        Returns:
-            Bounding Box
+        Returns
+        -------
+            BoundingBox
         """
         return self.get_template(space).get_boundingbox(point1, point2)