siibra 0.4a33__py3-none-any.whl → 0.4a46__py3-none-any.whl

siibra/core/space.py

@@ -45,24 +45,25 @@ class Space(AtlasConcept, configuration_folder="spaces"):
 
         Parameters
         ----------
-        identifier : str
-            Unique identifier of the space
-        name : str
-            Human-readable name of the space
-        species: str or Species
-            Specification of the species
-        volumes: list of template volumes
-        shortname: str
-            Shortform of human-readable name (optional)
-        description: str
-            Textual description of the parcellation
-        modality  :  str or None
-            Specification of the modality representing this reference space
-        publications: list
-            List of ssociated publications, each a dictionary with "doi" and/or "citation" fields
-        ebrains_ids : dict
-            Identifiers of EBRAINS entities corresponding to this Parcellation.
-            Key: EBRAINS KG schema, value: EBRAINS KG @id
+            identifier : str
+                Unique identifier of the space
+            name : str
+                Human-readable name of the space
+            species: str or Species
+                Specification of the species
+            volumes: list[Volume]
+                list of template volumes
+            shortname: str, optional
+                Shortform of human-readable name
+            description: str, optional
+                Textual description of the parcellation
+            modality  :  str or None
+                Specification of the modality representing this reference space
+            publications: list
+                List of associated publications, each a dictionary with "doi" and/or "citation" fields
+            ebrains_ids : dict
+                Identifiers of EBRAINS entities corresponding to this Parcellation.
+                Key: EBRAINS KG schema, value: EBRAINS KG @id
         """
 
         AtlasConcept.__init__(
@@ -86,19 +87,20 @@ class Space(AtlasConcept, configuration_folder="spaces"):
 
         Parameters
         ----------
-        variant: str (optional)
-            Some templates are provided in different variants, e.g.
-            freesurfer is available as either white matter, pial or
-            inflated surface for left and right hemispheres (6 variants).
-            This field could be used to request a specific variant.
-            Per default, the first found variant is returned.
-        format: str (optional)
-            Volumes are typically available in multiple formats.
-            Use this to select a specific one, if needed.
-
-        Yields
-        ------
-        A VolumeSrc object representing the reference template, or None if not available.
+            variant: str, optional
+                Some templates are provided in different variants, e.g.
+                freesurfer is available as either white matter, pial or
+                inflated surface for left and right hemispheres (6 variants).
+                This field could be used to request a specific variant.
+                Per default, the first found variant is returned.
+            format: str, optional
+                Volumes are typically available in multiple formats.
+                Use this to select a specific one, if needed.
+
+        Returns
+        -------
+            Volume
+                representing the reference template, or None if not available.
         """
         tests = []
         if variant is not None:
@@ -131,10 +133,10 @@ class Space(AtlasConcept, configuration_folder="spaces"):
         """
         Get a volume of interest specification from this space.
 
-        Arguments
-        ---------
-        slices: triple of slice
-            defines the x, y and z range
+        Parameters
+        ----------
+            slices: triple of slice
+                Defines the x, y and z range
         """
         if len(slices) != 3:
             raise TypeError(
@@ -153,9 +155,12 @@ class Space(AtlasConcept, configuration_folder="spaces"):
         """
         Get a volume of interest specification from this space.
 
-        Arguments
-        ---------
-        point1: 3D tuple defined in physical coordinates of this reference space
-        point2: 3D tuple defined in physical coordinates of this reference space
+        Parameters
+        ----------
+            point1: 3D tuple defined in physical coordinates of this reference space
+            point2: 3D tuple defined in physical coordinates of this reference space
+        Returns
+        -------
+            BoundingBox
         """
         return BoundingBox(point1, point2, self)

siibra/features/__init__.py

@@ -13,19 +13,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__all__ = ["cellular", "molecular", "fibres", "connectivity", "external"]
 
 from . import (
-    cellular,
-    molecular,
-    fibres,
     connectivity,
-    external
+    tabular,
+    image,
+    dataset,
 )
 
-from .basetypes.feature import Feature
-from .basetypes.cortical_profile import CorticalProfile
-from .basetypes.volume_of_interest import VolumeOfInterest
+
+from .feature import Feature
 get = Feature.match
 
 
@@ -33,14 +30,17 @@ TYPES = Feature._get_subclasses()
 
 
 def __dir__():
-    return [
-        "cellular",
-        "molecular",
-        "fibres",
-        "connectivity",
-        "external",
-        "Feature",
-        "get",
-        "CorticalProfile",
-        "VolumeOfInterest"
-    ]
+    return list(Feature.CATEGORIZED.keys())
+
+
+def __getattr__(attr: str):
+    if attr in Feature.CATEGORIZED:
+        return Feature.CATEGORIZED[attr]
+    else:
+        hint = ""
+        if isinstance(attr, str):
+            import difflib
+            closest = difflib.get_close_matches(attr, list(__dir__()), n=3)
+            if len(closest) > 0:
+                hint = f"Did you mean {' or '.join(closest)}?"
+        raise AttributeError(f"No such attribute: {__name__}.{attr} " + hint)

siibra/features/anchor.py

@@ -33,6 +33,7 @@ class AssignmentQualification(Enum):
     OVERLAPS = 2
     CONTAINED = 3
     CONTAINS = 4
+    APPROXIMATE = 5
 
     @property
     def verb(self):
@@ -45,6 +46,7 @@ class AssignmentQualification(Enum):
             'OVERLAPS': 'overlaps with',
             'CONTAINED': 'is contained in',
             'CONTAINS': 'contains',
+            'APPROXIMATE': 'approximates to',
         }
         return transl[self.name]
 
@@ -57,6 +59,7 @@ class AssignmentQualification(Enum):
             "OVERLAPS": "OVERLAPS",
             "CONTAINED": "CONTAINS",
             "CONTAINS": "CONTAINED",
+            "APPROXIMATE": "APPROXIMATE",
         }
         return AssignmentQualification[inverses[self.name]]
 
@@ -144,11 +147,11 @@ class AnatomicalAnchor:
         return self._location_cached
 
     @property
-    def parcellations(self):
+    def parcellations(self) -> List[Parcellation]:
         return list({region.root for region in self.regions})
 
     @property
-    def space(self):
+    def space(self) -> Space:
         # may be overriden by derived classes, e.g. in features.VolumeOfInterest
         if self.location is None:
             return None
@@ -158,10 +161,10 @@ class AnatomicalAnchor:
     @property
     def region_aliases(self):
         if self._aliases_cached is None:
-            self._aliases_cached = {
-                k: v
+            self._aliases_cached: Dict[str, Dict[str, str]] = {
+                species_str: region_alias_mapping
                 for s in self.species
-                for k, v in REGION_ALIASES.get(str(s), {}).get(self._regionspec, {}).items()
+                for species_str, region_alias_mapping in REGION_ALIASES.get(str(s), {}).get(self._regionspec, {}).items()
             }
         return self._aliases_cached
 
@@ -192,7 +195,7 @@ class AnatomicalAnchor:
                 for regionspec, qualificationspec in aliases.items():
                     for r in Parcellation.find_regions(regionspec, alt_species):
                         if r not in self._regions_cached:
-                            regions[r] = qualificationspec
+                            regions[r] = AssignmentQualification[qualificationspec.upper()]
             self.__class__._MATCH_MEMO[self._regionspec] = regions
         self._regions_cached = self.__class__._MATCH_MEMO[self._regionspec]
         

siibra/features/connectivity/__init__.py

@@ -16,11 +16,3 @@
 from .functional_connectivity import FunctionalConnectivity
 from .streamline_counts import StreamlineCounts
 from .streamline_lengths import StreamlineLengths
-
-
-def __dir__():
-    return [
-        "FunctionalConnectivity",
-        "StreamlineCounts",
-        "StreamlineLengths",
-    ]

siibra/features/connectivity/functional_connectivity.py

@@ -13,15 +13,23 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from ..basetypes import regional_connectivity
-
+from . import regional_connectivity
+from hashlib import md5
 
 class FunctionalConnectivity(
     regional_connectivity.RegionalConnectivity,
-    configuration_folder="features/connectivitymatrix/functional"
+    configuration_folder="features/connectivity/regional/functional",
+    category="connectivity"
 ):
     """Functional connectivity matrix grouped by a parcellation."""
 
     def __init__(self, paradigm: str, **kwargs):
         regional_connectivity.RegionalConnectivity.__init__(self, **kwargs)
         self.paradigm = paradigm
+
+        # paradign is used to distinguish functional connectivity features from each other.
+        assert self.paradigm, f"Functional connectivity must have paradigm defined!"
+
+    @property
+    def id(self):
+        return super().id + "--" + md5(self.paradigm.encode("utf-8")).hexdigest()

siibra/features/{basetypes → connectivity}/regional_connectivity.py

@@ -13,12 +13,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .feature import Feature
-from .tabular import Tabular
+from ..feature import Feature
+from ..tabular.tabular import Tabular
 
 from .. import anchor as _anchor
 
-from ...commons import logger, QUIET
+from ...commons import logger, QUIET, siibra_tqdm
 from ...core import region as _region
 from ...locations import pointset
 from ...retrieval.repositories import RepositoryConnector
@@ -26,14 +26,12 @@ from ...retrieval.repositories import RepositoryConnector
 from typing import Callable, Dict, Union, List
 import pandas as pd
 import numpy as np
-from tqdm import tqdm
 
 
 class RegionalConnectivity(Feature):
     """
-    Parcellation-averaged connectivity, providing one or more
-    matrices of a given modality for a given parcellation.
-
+    Parcellation-averaged connectivity, providing one or more matrices of a
+    given modality for a given parcellation.
     """
 
     def __init__(
@@ -48,8 +46,8 @@ class RegionalConnectivity(Feature):
         description: str = "",
         datasets: list = [],
     ):
-        """j
-        Construct a parcellation-averaged connectivty matrix.
+        """
+        Construct a parcellation-averaged connectivity matrix.
 
         Parameters
         ----------
@@ -57,7 +55,7 @@ class RegionalConnectivity(Feature):
             Name of the cohort used for computing the connectivity.
         modality: str
             Connectivity modality, typically set by derived classes.
-        regions: list of str
+        regions: list[str]
             Names of the regions from the parcellation
         connector: Connector
             Repository connector for loading the actual data array(s).
@@ -69,9 +67,9 @@ class RegionalConnectivity(Feature):
         anchor: AnatomicalAnchor
             anatomical localization of the matrix, expected to encode the parcellation
             in the region attribute.
-        description: str (optional)
+        description: str, optional
             textual description of this connectivity matrix.
-        datasets : list
+        datasets : list[Dataset]
             list of datasets corresponding to this feature.
         """
         Feature.__init__(
@@ -95,16 +93,24 @@ class RegionalConnectivity(Feature):
         """
         return list(self._files.keys())
 
+    @property
+    def name(self):
+        supername = super().name
+        return f"{supername} with cohort {self.cohort}"
+
     def get_matrix(self, subject: str = None):
         """
         Returns a matrix as a pandas dataframe.
 
         Parameters
         ----------
-        subject: str
+        subject: str, default: None
             Name of the subject (see ConnectivityMatrix.subjects for available names).
-            If "mean" or None is given, the mean is taken in case of multiple
-            available matrices.
+            If None, the mean is taken in case of multiple available matrices.
+        Returns
+        -------
+        pd.DataFrame
+            A square matrix with region names as the column and row names.
         """
         assert len(self) > 0
         if (subject is None) and (len(self) > 1):
@@ -116,21 +122,21 @@ class RegionalConnectivity(Feature):
             if "mean" not in self._matrices:
                 all_arrays = [
                     self._connector.get(fname, decode_func=self._decode_func)
-                    for fname in tqdm(
+                    for fname in siibra_tqdm(
                         self._files.values(),
                         total=len(self),
                         desc=f"Averaging {len(self)} connectivity matrices"
                     )
                 ]
                 self._matrices['mean'] = self._array_to_dataframe(np.stack(all_arrays).mean(0))
-            return self._matrices['mean']
+            return self._matrices['mean'].copy()
         if subject is None:
             subject = next(iter(self._files.keys()))
         if subject not in self._files:
             raise ValueError(f"Subject name '{subject}' not known, use one of: {', '.join(self._files)}")
         if subject not in self._matrices:
             self._matrices[subject] = self._load_matrix(subject)
-        return self._matrices[subject]
+        return self._matrices[subject].copy()
 
     def plot_matrix(self, subject: str = None, regions: List[str] = None, logscale: bool = False, **kwargs):
         """
@@ -181,9 +187,17 @@ class RegionalConnectivity(Feature):
         """
         Extract a regional profile from the matrix, to obtain a tabular data feature
         with the connectivity as the single column.
+
         Rows will be sorted by descending connection strength.
         Regions with connectivity smaller than "min_connectivity" will be discarded.
         If max_rows is given, only the subset of regions with highest connectivity is returned.
+
+        Parameters
+        ----------
+        region: str, Region
+        subject: str, default: None
+        min_connectivity: float, default: 0
+        max_rows: int, default: None
         """
         matrix = self.get_matrix(subject)
 
@@ -236,8 +250,15 @@ class RegionalConnectivity(Feature):
 
     def compute_centroids(self, space):
         """
-        compute the list of centroid coordinates corresponding to
-        matrix rows, in the given space.
+        Computes the list of centroid coordinates corresponding to
+        matrix rows, in the given reference space.
+
+        Parameters
+        ----------
+        space: Space, str
+        Returns
+        -------
+        list[tuple(float, float, float)]
         """
         result = []
         parcellations = self.anchor.represented_parcellations()
@@ -261,7 +282,7 @@ class RegionalConnectivity(Feature):
     def _array_to_dataframe(self, array: np.ndarray) -> pd.DataFrame:
         """
         Convert a numpy array with the connectivity matrix to
-        a dataframe with regions as column and row headers.
+        a DataFrame with regions as column and row headers.
         """
         df = pd.DataFrame(array)
         parcellations = self.anchor.represented_parcellations()
@@ -273,23 +294,15 @@ class RegionalConnectivity(Feature):
                 for i, regionname in enumerate(self.regions)
             }
         nrows = array.shape[0]
-        if len(indexmap) == nrows:
+        try:
+            assert len(indexmap) == nrows
             remapper = {
                 label - min(indexmap.keys()): region
                 for label, region in indexmap.items()
             }
             df = df.rename(index=remapper).rename(columns=remapper)
-        else:
-            labels = {r.index.label for r in parc.regiontree} - {None}
-            if max(labels) - min(labels) + 1 == nrows:
-                indexmap = {
-                    r.index.label - min(labels): r
-                    for r in parc.regiontree
-                    if r.index.label is not None
-                }
-                df = df.rename(index=indexmap).rename(columns=indexmap)
-            else:
-                logger.warn("Could not decode connectivity matrix regions.")
+        except:
+            raise RuntimeError("Could not decode connectivity matrix regions.")
         return df
 
     def _load_matrix(self, subject: str):

siibra/features/connectivity/streamline_counts.py

@@ -13,12 +13,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from ..basetypes import regional_connectivity
+from . import regional_connectivity
 
 
 class StreamlineCounts(
     regional_connectivity.RegionalConnectivity,
-    configuration_folder="features/connectivitymatrix/streamlinecounts"
+    configuration_folder="features/connectivity/regional/streamlinecounts",
+    category="connectivity"
 ):
     """Structural connectivity matrix of streamline counts grouped by a parcellation."""
 

siibra/features/connectivity/streamline_lengths.py

@@ -13,12 +13,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from ..basetypes import regional_connectivity
+from . import regional_connectivity
 
 
 class StreamlineLengths(
     regional_connectivity.RegionalConnectivity,
-    configuration_folder="features/connectivitymatrix/streamlinelengths"
+    configuration_folder="features/connectivity/regional/streamlinelengths",
+    category="connectivity"
 ):
     """Structural connectivity matrix of streamline lengths grouped by a parcellation."""
 

siibra/features/{basetypes → dataset}/__init__.py

@@ -12,3 +12,5 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+
+from .ebrains import EbrainsDataFeature

siibra/features/{external → dataset}/ebrains.py

@@ -16,12 +16,12 @@
 # simple data features anchored to a point in space
 
 from .. import anchor as _anchor
-from ..basetypes import feature
+from .. import feature
 
 from ...retrieval import datasets
 
 
-class EbrainsDataFeature(feature.Feature, datasets.EbrainsDataset):
+class EbrainsDataFeature(feature.Feature, datasets.EbrainsDataset, category='other'):
 
     def __init__(
         self,
@@ -64,7 +64,7 @@ class EbrainsDataFeature(feature.Feature, datasets.EbrainsDataset):
 
     @property
     def name(self):
-        return self._name_cached
+        return self._name
 
     @property
     def version_history(self):