siibra 1.0a1__1-py3-none-any.whl

siibra/features/tabular/layerwise_cell_density.py

@@ -0,0 +1,95 @@
+# Copyright 2018-2024
+# Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 . import cortical_profile
+from .. import anchor as _anchor
+from . import tabular
+from ..tabular.cell_density_profile import cell_reader, layer_reader
+
+from ... import commons
+from ...retrieval import requests
+
+import pandas as pd
+import numpy as np
+
+
+class LayerwiseCellDensity(
+    tabular.Tabular,
+    configuration_folder="features/tabular/layerstatistics/celldensity",
+    category='cellular'
+):
+
+    DESCRIPTION = (
+        "Layerwise estimated densities of detected cell bodies  (in detected cells per 0.1 cube millimeter) "
+        "obtained by applying a Deep Learning based instance segmentation algorithm (Contour Proposal Network; Upschulte "
+        "et al., Neuroimage 2022) to a 1 micron resolution cortical image patch prepared with modified Silver staining. "
+        "Densities have been computed per cortical layer after manual layer segmentation, by dividing the number of "
+        "detected cells in that layer with the area covered by the layer. Therefore, each profile contains 6 measurement points. "
+        "The cortical depth is estimated from the measured layer thicknesses."
+    )
+
+    def __init__(
+        self,
+        segmentfiles: list,
+        layerfiles: list,
+        anchor: _anchor.AnatomicalAnchor,
+        datasets: list = [],
+        id: str = None,
+        prerelease: bool = False,
+    ):
+        tabular.Tabular.__init__(
+            self,
+            description=self.DESCRIPTION,
+            modality="Cell body density",
+            anchor=anchor,
+            datasets=datasets,
+            data=None,  # lazy loading below
+            id=id,
+            prerelease=prerelease,
+        )
+        self.unit = "# detected cells/0.1mm3"
+        self._filepairs = list(zip(segmentfiles, layerfiles))
+        self._densities = None
+
+    def _load_densities(self):
+        density_dict = {}
+        for i, (cellfile, layerfile) in enumerate(self._filepairs):
+            try:
+                cells = requests.HttpRequest(cellfile, func=cell_reader).data
+                layers = requests.HttpRequest(layerfile, func=layer_reader).data
+            except requests.SiibraHttpRequestError as e:
+                print(str(e))
+                commons.logger.error(f"Skipping to bootstrap a {self.__class__.__name__} feature, cannot access file resource.")
+                continue
+            counts = cells.layer.value_counts()
+            areas = layers["Area(micron**2)"]
+            indices = np.intersect1d(areas.index, counts.index)
+            density_dict[i] = counts[indices] / areas * 100 ** 2 * 5
+        return pd.DataFrame(density_dict)
+
+    @property
+    def data(self):
+        if self._data_cached is None:
+            densities = self._load_densities()
+            self._data_cached = pd.DataFrame(
+                np.array([
+                    list(densities.mean(axis=1)),
+                    list(densities.std(axis=1))
+                ]).T,
+                columns=['mean', 'std'],
+                index=[cortical_profile.CorticalProfile.LAYERS[_] for _ in densities.index]
+            )
+            self._data_cached.index.name = 'layer'
+        return self._data_cached

siibra/features/tabular/receptor_density_fingerprint.py

@@ -0,0 +1,192 @@
+# Copyright 2018-2024
+# Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 .. import anchor as _anchor
+from . import tabular
+
+from ... import commons, vocabularies
+from ...retrieval import requests
+
+import pandas as pd
+import numpy as np
+from textwrap import wrap
+from typing import List
+
+
+class ReceptorDensityFingerprint(
+    tabular.Tabular,
+    configuration_folder="features/tabular/fingerprints/receptor",
+    category='molecular'
+):
+
+    DESCRIPTION = (
+        "Fingerprint of densities (in fmol/mg protein) of receptors for classical neurotransmitters "
+        "obtained by means of quantitative in vitro autoradiography. The fingerprint provides average "
+        "density measurments for different receptors measured in tissue samples from different subjects "
+        "together with the corresponding standard deviations. "
+    )
+
+    def __init__(
+        self,
+        tsvfile: str,
+        anchor: _anchor.AnatomicalAnchor,
+        datasets: list = [],
+        id: str = None,
+        prerelease: bool = False,
+    ):
+        """ Generate a receptor fingerprint from a URL to a .tsv file
+        formatted according to the structure used by Palomero-Gallagher et al.
+        """
+        tabular.Tabular.__init__(
+            self,
+            description=self.DESCRIPTION,
+            modality="Neurotransmitter receptor density",
+            anchor=anchor,
+            data=None,  # lazy loading below
+            datasets=datasets,
+            id=id,
+            prerelease=prerelease,
+        )
+        self._loader = requests.HttpRequest(tsvfile)
+
+    @property
+    def unit(self) -> str:
+        return self._loader.data.iloc[:, -1][0]
+
+    @property
+    def receptors(self) -> List[str]:
+        return list(self.data.index)
+
+    @property
+    def neurotransmitters(self) -> List[str]:
+        # TODO quite a lot of receptor features have undecipherable symbols, mainly double quoted receptor
+        # Likely ill-formed tsv's
+        return [
+            "{} ({})".format(
+                vocabularies.RECEPTOR_SYMBOLS[t]['neurotransmitter']['label'],
+                vocabularies.RECEPTOR_SYMBOLS[t]['neurotransmitter']['name'],
+            ) if t in vocabularies.RECEPTOR_SYMBOLS else
+            f"{t} (undeciphered)"
+            for t in self.receptors
+        ]
+
+    @property
+    def data(self):
+        if self._data_cached is None:
+            label_col, mean_col, std_col = list(self._loader.data.columns)[:3]
+            self._data_cached = pd.DataFrame(
+                np.array([
+                    self._loader.data[mean_col],
+                    self._loader.data[std_col]
+                ]).T,
+                index=self._loader.data[label_col],
+                columns=['mean', 'std']
+            )
+            self._data_cached.index.name = 'receptor'
+        return self._data_cached.copy()
+
+    @classmethod
+    def parse_tsv_data(cls, data: dict):
+        units = {list(v.values())[3] for v in data.values()}
+        labels = list(data.keys())
+        assert len(units) == 1
+        try:
+            mean = [data[_]["density (mean)"] for _ in labels]
+            std = [data[_]["density (sd)"] for _ in labels]
+        except KeyError as e:
+            print(str(e))
+            commons.logger.error("Could not parse fingerprint from this dictionary")
+        return {
+            'unit': next(iter(units)),
+            'labels': labels,
+            'means': [float(m) if m.isnumeric() else 0 for m in mean],
+            'stds': [float(s) if s.isnumeric() else 0 for s in std],
+        }
+
+    def polar_plot(self, *args, backend='matplotlib', **kwargs):
+        """
+        Create a polar plot of the fingerprint.
+        backend: str
+            "matplotlib" or "plotly"
+        """
+        if backend == "matplotlib":
+            try:
+                import matplotlib.pyplot as plt
+            except ImportError:
+                commons.logger.error("matplotlib not available. Plotting of fingerprints disabled.")
+                return None
+            from collections import deque
+
+            # default args
+            wrapwidth = 40
+            y = kwargs.pop("y") if "y" in kwargs else self.data.columns[0]
+            yerr = kwargs.pop("yerr") if "yerr" in kwargs else None
+            if yerr is None:
+                yerr = 'std' if 'std' in self.data.columns else None
+            ax = kwargs.pop("ax") if "ax" in kwargs else plt.subplot(111, projection="polar")
+
+            datafield = y or self.data.columns[0]
+            if yerr is None and 'std' in self.data.columns:
+                yerr = 'std'
+            # values = list(self.data[datafield])
+            angles = deque(np.linspace(0, 2 * np.pi, self.data.shape[0] + 1)[:-1][::-1])
+            angles.rotate(5)
+            angles = list(angles)
+            # for the values, repeat the first element to have a closed plot
+            indices = list(range(self.data.shape[0])) + [0]
+            y = list(self.data[datafield].iloc[indices])
+            plt.plot(angles + [angles[0]], y, "k-", lw=3, **kwargs)
+            if yerr:
+                bounds0 = y - self.data[yerr].iloc[indices]
+                plt.plot(angles + [angles[0]], bounds0, "k", lw=0.5, **kwargs)
+                bounds1 = y + self.data[yerr].iloc[indices]
+                plt.plot(angles + [angles[0]], bounds1, "k", lw=0.5, **kwargs)
+            ax.set_xticks(angles)
+            ax.set_xticklabels([_ for _ in self.data.index])
+            ax.set_ylabel(self.unit)
+            ax.set_title(
+                "\n".join(wrap(f"{self.modality} anchored at {self.anchor._regionspec}", wrapwidth))
+            )
+            ax.tick_params(pad=9, labelsize=10)
+            ax.tick_params(axis="y", labelsize=8)
+            plt.tight_layout()
+            return ax
+        elif backend == "plotly":
+            from plotly.express import line_polar
+            df = pd.DataFrame(
+                {
+                    "values": pd.concat(
+                        [
+                            self.data["mean"],
+                            self.data["mean"] - self.data["std"],
+                            self.data["mean"] + self.data["std"]
+                        ]
+                    ),
+                    "cat": (
+                        len(self.data) * ["mean"]
+                        + len(self.data) * ["mean - std"]
+                        + len(self.data) * ["mean + std"]
+                    )
+                }
+            )
+            return line_polar(
+                df, r="values", theta=df.index, color="cat", line_close=True, **kwargs
+            )
+        else:
+            raise NotImplementedError
+
+    def plot(self, *args, **kwargs):
+        kwargs['xlabel'] = ""
+        return super().plot(*args, **kwargs)

siibra/features/tabular/receptor_density_profile.py

@@ -0,0 +1,110 @@
+# Copyright 2018-2024
+# Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 .. import anchor as _anchor
+from . import cortical_profile
+
+from ... import vocabularies
+from ...commons import create_key
+from ...retrieval import requests
+
+
+class ReceptorDensityProfile(
+    cortical_profile.CorticalProfile,
+    configuration_folder="features/tabular/corticalprofiles/receptor",
+    category='molecular'
+):
+
+    DESCRIPTION = (
+        "Cortical profile of densities (in fmol/mg protein) of receptors for classical neurotransmitters "
+        "obtained by means of quantitative in vitro autoradiography. The profiles provide, for a "
+        "single tissue sample, an exemplary density distribution for a single receptor from the pial surface "
+        "to the border between layer VI and the white matter."
+    )
+
+    _filter_attrs = cortical_profile.CorticalProfile._filter_attrs + ["receptor"]
+
+    def __init__(
+        self,
+        receptor: str,
+        tsvfile: str,
+        anchor: _anchor.AnatomicalAnchor,
+        datasets: list = [],
+        id: str = None,
+        prerelease: bool = False,
+    ):
+        """Generate a receptor density profile from a URL to a .tsv file
+        formatted according to the structure used by Palomero-Gallagher et al.
+        """
+        cortical_profile.CorticalProfile.__init__(
+            self,
+            description=self.DESCRIPTION,
+            modality="Receptor density",
+            anchor=anchor,
+            datasets=datasets,
+            id=id,
+            prerelease=prerelease
+        )
+        self.receptor = receptor
+        self._data_cached = None
+        self._loader = requests.HttpRequest(tsvfile)
+        self._unit_cached = None
+
+    @property
+    def key(self):
+        return "{}_{}_{}_{}_{}".format(
+            create_key(self.__class__.__name__),
+            self.id,
+            create_key(self.species_name),
+            create_key(self.regionspec),
+            create_key(self.receptor)
+        )
+
+    @property
+    def receptor_fullname(self):
+        return vocabularies.RECEPTOR_SYMBOLS[self.receptor]['receptor']['name']
+
+    @property
+    def neurotransmitter(self):
+        return "{} ({})".format(
+            vocabularies.RECEPTOR_SYMBOLS[self.receptor]['neurotransmitter']['label'],
+            vocabularies.RECEPTOR_SYMBOLS[self.receptor]['neurotransmitter']['name'],
+        )
+
+    @property
+    def unit(self):
+        # triggers lazy loading of the HttpRequest
+        return self._loader.data.iloc[:, -1][0]
+
+    @property
+    def _values(self):
+        # triggers lazy loading of the HttpRequest
+        return self._loader.data.iloc[:, -2].values
+
+    @property
+    def _depths(self):
+        return self._loader.data.iloc[:, 0].values / 100.
+
+    @classmethod
+    def parse_tsv_data(self, data):
+        units = {list(v.values())[3] for v in data.values()}
+        assert len(units) == 1
+        return {
+            "depth": [float(k) / 100.0 for k in data.keys() if k.isnumeric()],
+            "density": [
+                float(list(v.values())[2]) for k, v in data.items() if k.isnumeric()
+            ],
+            "unit": next(iter(units)),
+        }

siibra/features/tabular/regional_timeseries_activity.py

@@ -0,0 +1,294 @@
+# Copyright 2018-2024
+# Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 . import tabular
+from ..feature import Compoundable
+
+from ...core import region as _region
+from .. import anchor as _anchor
+from ...commons import QUIET, siibra_tqdm
+from ...locations import pointcloud
+from ...retrieval.repositories import RepositoryConnector
+from ...retrieval.requests import HttpRequest
+
+from typing import Callable, List, Union
+import pandas as pd
+import numpy as np
+
+
+class RegionalTimeseriesActivity(tabular.Tabular, Compoundable):
+    """
+    Datasets that provide regional activity over time.
+    """
+
+    _filter_attrs = ["modality", "cohort", "subject"]
+    _compound_attrs = ["modality", "cohort"]
+
+    def __init__(
+        self,
+        cohort: str,
+        modality: str,
+        regions: list,
+        connector: RepositoryConnector,
+        decode_func: Callable,
+        filename: str,
+        anchor: _anchor.AnatomicalAnchor,
+        timestep: str,
+        description: str = "",
+        datasets: list = [],
+        subject: str = "average",
+        id: str = None,
+        prerelease: bool = False,
+    ):
+        """
+        """
+        tabular.Tabular.__init__(
+            self,
+            modality=modality,
+            description=description,
+            anchor=anchor,
+            datasets=datasets,
+            data=None,  # lazy loading below
+            id=id,
+            prerelease=prerelease,
+        )
+        self.cohort = cohort.upper()
+        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._table = None
+        self._subject = subject
+        val, unit = timestep.split(" ")
+        self.timestep = (float(val), unit)
+
+    @property
+    def subject(self):
+        """Returns the subject identifiers for which the table represents."""
+        return self._subject
+
+    @property
+    def name(self):
+        return f"{self.subject} - " + super().name + f" cohort: {self.cohort}"
+
+    @property
+    def data(self) -> pd.DataFrame:
+        """
+        Returns a table as a pandas dataframe where the index is a timeseries.
+        """
+        if self._table is None:
+            self._load_table()
+        return self._table.copy()
+
+    @classmethod
+    def _merge_elements(
+        cls,
+        elements: List["RegionalTimeseriesActivity"],
+        description: str,
+        modality: str,
+        anchor: _anchor.AnatomicalAnchor,
+    ):
+        assert len({f.cohort for f in elements}) == 1
+        assert len({f.timestep for f in elements}) == 1
+        merged = cls(
+            cohort=elements[0].cohort,
+            regions=elements[0].regions,
+            connector=elements[0]._connector,
+            decode_func=elements[0]._decode_func,
+            filename="",
+            timestep=" ".join(str(val) for val in elements[0].timestep),
+            subject="average",
+            description=description,
+            modality=modality,
+            anchor=anchor,
+            **{"paradigm": "average"} if getattr(elements[0], "paradigm") else {}
+        )
+        if isinstance(elements[0]._connector, HttpRequest):
+            getter = lambda elm: elm._connector.get()
+        else:
+            getter = lambda elm: elm._connector.get(elm._filename, decode_func=elm._decode_func)
+        all_arrays = [
+            getter(elm)
+            for elm in siibra_tqdm(
+                elements,
+                total=len(elements),
+                desc=f"Averaging {len(elements)} activity tables"
+            )
+        ]
+        merged._table = elements[0]._arraylike_to_dataframe(
+            np.stack(all_arrays).mean(0)
+        )
+        return merged
+
+    def _load_table(self):
+        """
+        Extract the timeseries table.
+        """
+        if isinstance(self._connector, HttpRequest):
+            array = self._connector.data
+        else:
+            array = self._connector.get(self._filename, decode_func=self._decode_func)
+        self._table = self._arraylike_to_dataframe(array)
+
+    def _arraylike_to_dataframe(self, array: Union[np.ndarray, pd.DataFrame]) -> pd.DataFrame:
+        if not isinstance(array, np.ndarray):
+            array = array.to_numpy()
+        ncols = array.shape[1]
+        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()
+            }
+            table = table.rename(columns=remapper)
+
+        return table
+
+    def __str__(self):
+        return self.name
+
+    def compute_centroids(self, space):
+        """
+        Computes the list of centroid coordinates corresponding to
+        dataframe columns, in the given reference space.
+
+        Parameters
+        ----------
+        space: Space, str
+
+        Returns
+        -------
+        list[tuple(float, float, float)]
+        """
+        result = []
+        parcellations = self.anchor.represented_parcellations()
+        assert len(parcellations) == 1
+        parcmap = next(iter(parcellations)).get_map(space)
+        all_centroids = parcmap.compute_centroids()
+        for regionname in self.regions:
+            region = parcmap.parcellation.get_region(regionname, allow_tuple=True)
+            if isinstance(region, tuple):  # deal with sets of matched regions
+                found = [c for r in region for c in r if c.name in all_centroids]
+            else:
+                found = [r for r in region if r.name in all_centroids]
+            assert len(found) > 0
+            result.append(
+                tuple(pointcloud.PointCloud(
+                    [all_centroids[r.name] for r in found], space=space
+                ).centroid)
+            )
+        return result
+
+    def plot(
+        self, regions: List[Union[str, "_region.Region"]] = None, *args,
+        backend="matplotlib", **kwargs
+    ):
+        """
+        Create a bar plot of averaged timeseries data per region.
+
+        Parameters
+        ----------
+        regions: List[str or Region]
+        subject: str, default: None
+            If None, returns the subject averaged table.
+        args and kwargs:
+            takes arguments and keyword arguments for the desired plotting
+            backend.
+        """
+        if isinstance(regions, (str, _region.Region)):
+            regions = [regions]
+        if regions is None:
+            regions = self.regions
+        indices = [self.regions.index(r) for r in regions]
+        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, regions: List[Union[str, "_region.Region"]] = None, *args,
+        backend="plotly", **kwargs
+    ):
+        """
+        Create a carpet plot ofthe timeseries data per region.
+
+        Parameters
+        ----------
+        regions: List[str or Region]
+        subject: str, default: None
+            If None, returns the subject averaged table.
+        args and kwargs:
+            takes arguments and keyword arguments for `plotly.express.imshow`
+        """
+        if backend != "plotly":
+            raise NotImplementedError("Currently, carpet plot is only implemented with `plotly`.")
+        if isinstance(regions, (str, _region.Region)):
+            regions = [regions]
+        if regions is None:
+            regions = self.regions
+        indices = [self.regions.index(r) for r in regions]
+        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,
+            **kwargs
+        )
+
+
+class RegionalBOLD(
+    RegionalTimeseriesActivity,
+    configuration_folder="features/tabular/activity_timeseries/bold",
+    category="functional"
+):
+    """
+    Blood-oxygen-level-dependent (BOLD) signals per region.
+    """
+
+    _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 super().name + f", paradigm: {self.paradigm}"