siibra 0.4a76__py3-none-any.whl → 0.5a1__py3-none-any.whl

siibra/features/tabular/regional_timeseries_activity.py

@@ -14,26 +14,26 @@
 # limitations under the License.
 
 from . import tabular
+from ..feature import Compoundable
 
 from .. import anchor as _anchor
-
-from ...commons import logger, QUIET, siibra_tqdm
+from ...commons import QUIET
 from ...locations import pointset
 from ...retrieval.repositories import RepositoryConnector
+from ...retrieval.requests import HttpRequest
 
-from typing import Callable, Dict, List
+from typing import Callable, List
 import pandas as pd
 import numpy as np
 
 
-class RegionalTimeseriesActivity(tabular.Tabular):
+class RegionalTimeseriesActivity(tabular.Tabular, Compoundable):
     """
     Datasets that provide regional activity over time.
     """
 
-    DESCRIPTION = (
-        ""
-    )
+    _filter_attrs = ["modality", "cohort", "subject"]
+    _compound_attrs = ["modality", "cohort"]
 
     def __init__(
         self,
@@ -42,103 +42,88 @@ class RegionalTimeseriesActivity(tabular.Tabular):
         regions: list,
         connector: RepositoryConnector,
         decode_func: Callable,
-        files: Dict[str, str],
+        filename: str,
         anchor: _anchor.AnatomicalAnchor,
         timestep: str,
         description: str = "",
         datasets: list = [],
-        paradigm: str = ""
+        subject: str = "average"
     ):
         """
         """
         tabular.Tabular.__init__(
             self,
             modality=modality,
-            description=description or '\n'.join({ds.description for ds in datasets}),
+            description=description,
             anchor=anchor,
             datasets=datasets,
             data=None  # lazy loading below
         )
         self.cohort = cohort.upper()
-        self._connector = connector
-        self._files = files
+        if isinstance(connector, str) and connector:
+            self._connector = HttpRequest(connector, decode_func)
+        else:
+            self._connector = connector
+        self._filename = filename
         self._decode_func = decode_func
         self.regions = regions
-        self._tables = {}
-        self.paradigm = paradigm
-        self.timestep = timestep
+        self._table = None
+        self._subject = subject
+        val, unit = timestep.split(" ")
+        self.timestep = (float(val), unit)
 
     @property
-    def subjects(self):
-        """
-        Returns the subject identifiers for which signal tables are available.
-        """
-        return list(self._files.keys())
+    def subject(self):
+        """Returns the subject identifiers for which the matrix represents."""
+        return self._subject
 
     @property
     def name(self):
-        supername = super().name
-        return f"{supername} with paradigm {self.paradigm}"
+        return f"{super().name} with cohort {self.cohort} - subject {self.subject}"
 
-    def get_table(self, subject: str = None):
+    @property
+    def data(self) -> pd.DataFrame:
         """
-        Returns a pandas dataframe where the column headers are regions and the
-        indcies indicate disctrete timesteps.
-
-        Parameters
-        ----------
-        subject: str, default: None
-            Name of the subject (see RegionalTimeseriesActivity.subjects for available names).
-            If None, the mean is taken in case of multiple available data tables.
-        Returns
-        -------
-        pd.DataFrame
-            A table with region names as the column and timesteps as indices.
+        Returns a table as a pandas dataframe where the index is a timeseries.
         """
-        assert len(self) > 0
-        if (subject is None) and (len(self) > 1):
-            # multiple signal tables available, but no subject given - return mean table
-            logger.info(
-                f"No subject name supplied, returning mean signal table across {len(self)} subjects. "
-                "You might alternatively specify an individual subject."
-            )
-            if "mean" not in self._tables:
-                all_arrays = [
-                    self._connector.get(fname, decode_func=self._decode_func)
-                    for fname in siibra_tqdm(
-                        self._files.values(),
-                        total=len(self),
-                        desc=f"Averaging {len(self)} signal tables"
-                    )
-                ]
-                self._tables['mean'] = self._array_to_dataframe(np.stack(all_arrays).mean(0))
-            return self._tables['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._tables:
-            self._tables[subject] = self._load_table(subject)
-        return self._tables[subject].copy()
+        if self._table is None:
+            self._load_table()
+        return self._table.copy()
 
-    def _load_table(self, subject: str):
+    def _load_table(self):
         """
         Extract the timeseries table.
         """
-        assert subject in self.subjects
-        array = self._connector.get(self._files[subject], decode_func=self._decode_func)
-        return self._array_to_dataframe(array)
-
-    def __len__(self):
-        return len(self._files)
+        array = self._connector.get(self._filename, decode_func=self._decode_func)
+        if not isinstance(array, np.ndarray):
+            assert isinstance(array, pd.DataFrame)
+            array = array.to_numpy()
+        ncols = array.shape[1]
+        self._table = pd.DataFrame(
+            array,
+            index=pd.TimedeltaIndex(
+                np.arange(0, array.shape[0]) * self.timestep[0],
+                unit=self.timestep[1],
+                name="time"
+            )
+        )
+        parcellations = self.anchor.represented_parcellations()
+        assert len(parcellations) == 1
+        parc = next(iter(parcellations))
+        with QUIET:
+            columnmap = {
+                i: parc.get_region(regionname, allow_tuple=True)
+                for i, regionname in enumerate(self.regions)
+            }
+        if len(columnmap) == ncols:
+            remapper = {
+                label - min(columnmap.keys()): region
+                for label, region in columnmap.items()
+            }
+            self._table = self._table.rename(columns=remapper)
 
     def __str__(self):
-        return "{} with paradigm {} for {} from {} cohort ({} signal tables)".format(
-            self.modality, self.paradigm,
-            "_".join(p.name for p in self.anchor.parcellations),
-            self.cohort,
-            len(self._files),
-        )
+        return self.name
 
     def compute_centroids(self, space):
         """
@@ -172,31 +157,8 @@ class RegionalTimeseriesActivity(tabular.Tabular):
             )
         return result
 
-    def _array_to_dataframe(self, array: np.ndarray) -> pd.DataFrame:
-        """
-        Convert a numpy array with the regional activity data to
-        a DataFrame with regions as column headers and timesteps as indices.
-        """
-        df = pd.DataFrame(array)
-        parcellations = self.anchor.represented_parcellations()
-        assert len(parcellations) == 1
-        parc = next(iter(parcellations))
-        with QUIET:
-            indexmap = {
-                i: parc.get_region(regionname, allow_tuple=True)
-                for i, regionname in enumerate(self.regions)
-            }
-        ncols = array.shape[1]
-        if len(indexmap) == ncols:
-            remapper = {
-                label - min(indexmap.keys()): region
-                for label, region in indexmap.items()
-            }
-            df = df.rename(columns=remapper)
-        return df
-
     def plot(
-        self, subject: str = None, regions: List[str] = None, *args,
+        self, regions: List[str] = None, *args,
         backend="matplotlib", **kwargs
     ):
         """
@@ -214,12 +176,12 @@ class RegionalTimeseriesActivity(tabular.Tabular):
         if regions is None:
             regions = self.regions
         indices = [self.regions.index(r) for r in regions]
-        table = self.get_table(subject).iloc[:, indices]
+        table = self.data.iloc[:, indices]
         table.columns = [str(r) for r in table.columns]
         return table.mean().plot(kind="bar", *args, backend=backend, **kwargs)
 
     def plot_carpet(
-        self, subject: str = None, regions: List[str] = None, *args,
+        self, regions: List[str] = None, *args,
         backend="plotly", **kwargs
     ):
         """
@@ -238,12 +200,17 @@ class RegionalTimeseriesActivity(tabular.Tabular):
         if regions is None:
             regions = self.regions
         indices = [self.regions.index(r) for r in regions]
-        table = self.get_table(subject).iloc[:, indices]
+        table = self.data.iloc[:, indices].reset_index(drop=True)
         table.columns = [str(r) for r in table.columns]
+        kwargs["title"] = kwargs.get("title", f"{self.modality}" + f" for subject={self.subject}")
+        kwargs["labels"] = kwargs.get("labels", {
+            "xlabel": self.data.index.to_numpy(dtype='timedelta64[ms]')}
+        )
         from plotly.express import imshow
         return imshow(
+            *args,
             table.T,
-            title=f"{self.modality}" + f" for subject={subject}" if subject else ""
+            **kwargs
         )
 
 
@@ -256,4 +223,16 @@ class RegionalBOLD(
     Blood-oxygen-level-dependent (BOLD) signals per region.
     """
 
-    pass
+    _filter_attrs = RegionalTimeseriesActivity._filter_attrs + ["paradigm"]
+    _compound_attrs = RegionalTimeseriesActivity._compound_attrs + ["paradigm"]
+
+    def __init__(self, paradigm: str, **kwargs):
+        RegionalTimeseriesActivity.__init__(self, **kwargs)
+        self.paradigm = paradigm
+
+        # paradign is used to distinguish functional connectivity features from each other.
+        assert self.paradigm, "RegionalBOLD must have paradigm defined!"
+
+    @property
+    def name(self):
+        return f"{super().name}, paradigm {self.paradigm}"

siibra/features/tabular/tabular.py

@@ -74,6 +74,14 @@ class Tabular(feature.Feature):
         **kwargs
             takes Matplotlib.pyplot keyword arguments
         """
+        wrapwidth = kwargs.pop("textwrap") if "textwrap" in kwargs else 40
+        kwargs["title"] = kwargs.get(
+            "title",
+            "\n".join(wrap(
+                f"{self.modality} in {', '.join({_.name for _ in self.anchor.regions})}",
+                wrapwidth
+            ))
+        )
         kwargs["kind"] = kwargs.get("kind", "bar")
         kwargs["y"] = kwargs.get("y", self.data.columns[0])
         if backend == "matplotlib":
@@ -82,8 +90,6 @@ class Tabular(feature.Feature):
             except ImportError:
                 commons.logger.error("matplotlib not available. Plotting of fingerprints disabled.")
                 return None
-
-            wrapwidth = kwargs.pop("textwrap") if "textwrap" in kwargs else 40
             # default kwargs
             if kwargs.get("error_y") is None:
                 kwargs["yerr"] = kwargs.get("yerr", 'std' if 'std' in self.data.columns else None)
@@ -93,10 +99,6 @@ class Tabular(feature.Feature):
                 "ylabel",
                 f"{kwargs['y']}{yerr_label} {self.unit if hasattr(self, 'unit') else ''}"
             )
-            kwargs["title"] = kwargs.get(
-                "title",
-                "\n".join(wrap(f"{self.modality} in {', '.join({_.name for _ in self.anchor.regions})}", wrapwidth))
-            )
             kwargs["grid"] = kwargs.get("grid", True)
             kwargs["legend"] = kwargs.get("legend", False)
             ax = self.data.plot(*args, backend=backend, **kwargs)
@@ -105,14 +107,24 @@ class Tabular(feature.Feature):
             plt.tight_layout()
             return ax
         elif backend == "plotly":
+            kwargs["title"] = kwargs["title"].replace("\n", "<br>")
             kwargs["error_y"] = kwargs.get("error_y", 'std' if 'std' in self.data.columns else None)
             error_y_label = f" &plusmn; {kwargs.get('error_y')}" if kwargs.get('error_y') else ''
             kwargs["labels"] = {
-                "index": kwargs.pop("xlabel", ""),
-                "value": kwargs.pop("ylabel", f"{kwargs.get('y')}{error_y_label} {self.unit if hasattr(self, 'unit') else ''}")
+                "index": kwargs.pop("xlabel", None) or kwargs.pop("index", ""),
+                "value": kwargs.pop("ylabel", None) or kwargs.pop(
+                    "value",
+                    f"{kwargs.get('y')}{error_y_label} {self.unit if hasattr(self, 'unit') else ''}"
+                )
             }
             fig = self.data.plot(*args, backend=backend, **kwargs)
-            fig.update_layout(yaxis_title=kwargs["labels"]['value'])
+            fig.update_layout(
+                yaxis_title=kwargs["labels"]['value'],
+                title=dict(
+                    automargin=True, yref="container", xref="container",
+                    pad=dict(t=40), xanchor="left", yanchor="top"
+                )
+            )
             return fig
         else:
             return self.data.plot(*args, backend=backend, **kwargs)

siibra/livequeries/bigbrain.py

@@ -29,15 +29,10 @@ from os import path
 
 class WagstylProfileLoader:
 
-    REPO = "https://github.com/kwagstyl/cortical_layers_tutorial"
-    BRANCH = "main"
-    PROFILES_FILE_LEFT = "https://data-proxy.ebrains.eu/api/v1/public/buckets/d-26d25994-634c-40af-b88f-2a36e8e1d508/profiles/profiles_left.txt"
-    PROFILES_FILE_RIGHT = "https://data-proxy.ebrains.eu/api/v1/public/buckets/d-26d25994-634c-40af-b88f-2a36e8e1d508/profiles/profiles_right.txt"
+    REPO = "https://github.com/kwagstyl/cortical_layers_tutorial/raw/main"
+    PROFILES_FILE_LEFT = "data/profiles_left.npy"
     THICKNESSES_FILE_LEFT = "data/thicknesses_left.npy"
-    THICKNESSES_FILE_RIGHT = ""
-    MESH_FILE_LEFT = "gray_left_327680.surf.gii"
-    MESH_FILE_RIGHT = "gray_right_327680.surf.gii"
-    BASEURL = "https://ftp.bigbrainproject.org/bigbrain-ftp/BigBrainRelease.2015/3D_Surfaces/Apr7_2016/gii/"
+    MESH_FILE_LEFT = "data/gray_left_327680.surf.gii"
     _profiles = None
     _vertices = None
     _boundary_depths = None
@@ -53,31 +48,25 @@ class WagstylProfileLoader:
     @classmethod
     def _load(cls):
         # read thicknesses, in mm, and normalize by their last column which is the total thickness
-        thickness_left = requests.HttpRequest(f"{cls.REPO}/raw/{cls.BRANCH}/{cls.THICKNESSES_FILE_LEFT}").data.T
-        thickness_right = np.zeros(shape=thickness_left.shape)  # TODO: replace with thickness data for te right hemisphere
-        thickness = np.concatenate((thickness_left[:, :-1], thickness_right[:, :-1]))  # last column is the computed total thickness
-        total_thickness = thickness.sum(1)
+        thickness = requests.HttpRequest(f"{cls.REPO}/{cls.THICKNESSES_FILE_LEFT}").data.T
+        total_thickness = thickness[:, :-1].sum(1)  # last column is the computed total thickness
         valid = np.where(total_thickness > 0)[0]
         cls._boundary_depths = np.c_[np.zeros_like(valid), (thickness[valid, :] / total_thickness[valid, None]).cumsum(1)]
         cls._boundary_depths[:, -1] = 1  # account for float calculation errors
 
         # find profiles with valid thickness
-        if not all(
-            path.exists(cache.CACHE.build_filename(url))
-            for url in [cls.PROFILES_FILE_LEFT, cls.PROFILES_FILE_RIGHT]
-        ):
+        profile_l_url = f"{cls.REPO}/{cls.PROFILES_FILE_LEFT}"
+        if not path.exists(cache.CACHE.build_filename(profile_l_url)):
             logger.info(
                 "First request to BigBrain profiles. Preprocessing the data "
                 "now. This may take a little."
             )
-        profiles_l = requests.HttpRequest(cls.PROFILES_FILE_LEFT).data.to_numpy()
-        profiles_r = requests.HttpRequest(cls.PROFILES_FILE_RIGHT).data.to_numpy()
-        cls._profiles = np.concatenate((profiles_l, profiles_r))[valid, :]
+        profiles_l_all = requests.HttpRequest(profile_l_url).data
+        cls._profiles = profiles_l_all[valid, :]
 
         # read mesh vertices
-        mesh_left = requests.HttpRequest(f"{cls.BASEURL}/{cls.MESH_FILE_LEFT}").data
-        mesh_right = requests.HttpRequest(f"{cls.BASEURL}/{cls.MESH_FILE_RIGHT}").data
-        mesh_vertices = np.concatenate((mesh_left.darrays[0].data, mesh_right.darrays[0].data))
+        mesh_left = requests.HttpRequest(f"{cls.REPO}/{cls.MESH_FILE_LEFT}").data
+        mesh_vertices = mesh_left.darrays[0].data
         cls._vertices = mesh_vertices[valid, :]
 
         logger.debug(f"{cls._profiles.shape[0]} BigBrain intensity profiles.")

siibra/locations/__init__.py

@@ -14,7 +14,71 @@
 # limitations under the License.
 """Handles spatial concepts and spatial operation like warping between spaces."""
 
-from .location import WholeBrain
+from .location import WholeBrain, Location
 from .point import Point
 from .pointset import PointSet
 from .boundingbox import BoundingBox
+
+
+def reassign_union(loc0: 'Location', loc1: 'Location') -> 'Location':
+    """
+    Add two locations of same or diffrent type to find their union as a
+    Location object.
+    Note
+    ----
+    `loc1` will be warped to `loc0` they are not in the same space.
+    Parameters
+    ----------
+    loc0 : Location
+        _description_
+    loc1 : Location
+        _description_
+    Returns
+    -------
+    Location
+        - Point U Point = PointSet
+        - Point U PointSet = PointSet
+        - PointSet U PointSet = PointSet
+        - BoundingBox U BoundingBox = BoundingBox
+        - BoundingBox U PointSet = BoundingBox
+        - BoundingBox U Point = BoundingBox
+        - WholeBrain U Location = NotImplementedError
+        (all operations are commutative)
+    """
+    if loc0 is None or loc1 is None:
+        return loc0 or loc1
+
+    if isinstance(loc0, WholeBrain) or isinstance(loc1, WholeBrain):
+        raise NotImplementedError("Union of WholeBrains is not yet implemented.")
+
+    loc1_w = loc1.warp(loc0.space)  # adopt the space of the first location
+
+    if isinstance(loc0, Point):  # turn Points to PointSets
+        return reassign_union(
+            PointSet([loc0], space=loc0.space, sigma_mm=loc0.sigma), loc1_w
+        )
+
+    if isinstance(loc0, PointSet):
+        if isinstance(loc1_w, PointSet):
+            points = set(loc0.points + loc1_w.points)
+            return PointSet(
+                points,
+                space=loc0.space,
+                sigma_mm=[p.sigma for p in points],
+            )
+        if isinstance(loc1_w, BoundingBox):
+            return reassign_union(loc0.boundingbox, loc1_w)
+
+    if isinstance(loc0, BoundingBox) and isinstance(loc1_w, BoundingBox):
+        points = [loc0.minpoint, loc0.maxpoint, loc1_w.minpoint, loc1_w.maxpoint]
+        return BoundingBox(
+            point1=[min(p[i] for p in points) for i in range(3)],
+            point2=[max(p[i] for p in points) for i in range(3)],
+            space=loc0.space,
+            sigma_mm=[loc0.minpoint.sigma, loc0.maxpoint.sigma]
+        )
+
+    return reassign_union(loc1_w, loc0)
+
+
+Location.union = reassign_union

siibra/locations/boundingbox.py

@@ -273,22 +273,6 @@ class BoundingBox(location.Location):
                 .boundingbox
             )
 
-    def union(self, other):
-        """
-        Computes the union of this boudning box with another one.
-
-        Args:
-            other (BoundingBox): Another bounding box
-        """
-        warped = other.warp(self.space)
-        points = [self.minpoint, self.maxpoint, warped.minpoint, warped.maxpoint]
-        return BoundingBox(
-            point1=[min(p[i] for p in points) for i in range(3)],
-            point2=[max(p[i] for p in points) for i in range(3)],
-            space=self.space,
-            sigma_mm=[self.minpoint.sigma, self.maxpoint.sigma]
-        )
-
     def clip(self, xyzmax, xyzmin=(0, 0, 0)):
         """
         Returns a new bounding box obtained by clipping at the given maximum coordinate.

siibra/locations/location.py

@@ -98,6 +98,19 @@ class Location(ABC):
                 f"[{','.join(str(l) for l in iter(self))}]"
             )
 
+    def __repr__(self):
+        return f"{self.__class__.__name__}: {self}"
+
+    @staticmethod
+    def union(loc0: 'Location', loc1: 'Location') -> 'Location':
+        """
+        Reassigned at the locations module level for static typing and to avoid
+        circular imports. See siibra.locations.__init__.reassign_union()
+        """
+        raise NotImplementedError(
+            "This method is designed to be reassigned at the module level"
+        )
+
 
 class WholeBrain(Location):
     """

siibra/locations/pointset.py

@@ -159,9 +159,7 @@ class PointSet(location.Location):
         return len(self.points)
 
     def __str__(self):
-        return f"Set of points {self.space.name}: " + ", ".join(
-            f"({','.join(str(v) for v in p)})" for p in self
-        )
+        return f"Set of {len(self)} points in the {self.boundingbox}"
 
     @property
     def boundingbox(self):

siibra/retrieval/cache.py

@@ -19,7 +19,7 @@ import os
 from appdirs import user_cache_dir
 import tempfile
 
-from ..commons import logger, SIIBRA_CACHEDIR
+from ..commons import logger, SIIBRA_CACHEDIR, SKIP_CACHEINIT_MAINTENANCE
 
 
 def assert_folder(folder):
@@ -64,7 +64,10 @@ class Cache:
                 cls.folder = SIIBRA_CACHEDIR
             cls.folder = assert_folder(cls.folder)
             cls._instance = cls.__new__(cls)
-            cls._instance.run_maintenance()
+            if SKIP_CACHEINIT_MAINTENANCE:
+                logger.debug("Will not run maintenance on cache as SKIP_CACHE_MAINTENANCE is set to True.")
+            else:
+                cls._instance.run_maintenance()
         return cls._instance
 
     def clear(self):
@@ -77,7 +80,6 @@ class Cache:
     def run_maintenance(self):
         """ Shrinks the cache by deleting oldest files first until the total size
         is below cache size (Cache.SIZE) given in GiB."""
-
         # build sorted list of cache files and their os attributes
         files = [os.path.join(self.folder, fname) for fname in os.listdir(self.folder)]
         sfiles = sorted([(fn, os.stat(fn)) for fn in files], key=lambda t: t[1].st_atime)