siibra 1.0a1__1-py3-none-any.whl

siibra/features/tabular/cortical_profile.py

@@ -0,0 +1,322 @@
+# 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 .. import anchor as _anchor
+
+import pandas as pd
+from typing import Union, Dict, Tuple, List
+from textwrap import wrap
+import numpy as np
+
+
+class CorticalProfile(tabular.Tabular, Compoundable):
+    """
+    Represents a 1-dimensional profile of measurements along cortical depth,
+    measured at relative depths between 0 representing the pial surface,
+    and 1 corresponding to the gray/white matter boundary.
+
+    Mandatory attributes are the list of depth coordinates and the list of
+    corresponding measurement values, which have to be of equal length,
+    as well as a unit and description of the measurements.
+
+    Optionally, the depth coordinates of layer boundaries can be specified.
+
+    Most attributes are modelled as properties, so dervide classes are able
+    to implement lazy loading instead of direct initialiation.
+
+    """
+
+    LAYERS = {0: "0", 1: "I", 2: "II", 3: "III", 4: "IV", 5: "V", 6: "VI", 7: "WM"}
+    BOUNDARIES = list(zip(list(LAYERS.keys())[:-1], list(LAYERS.keys())[1:]))
+
+    _filter_attrs = ["modality"]
+    _compound_attrs = ["modality"]
+
+    def __init__(
+        self,
+        description: str,
+        modality: str,
+        anchor: _anchor.AnatomicalAnchor,
+        depths: Union[list, np.ndarray] = None,
+        values: Union[list, np.ndarray] = None,
+        unit: str = None,
+        boundary_positions: Dict[Tuple[int, int], float] = None,
+        datasets: list = [],
+        id: str = None,
+        prerelease: bool = False,
+    ):
+        """Initialize profile.
+
+        Parameters
+        ----------
+        description: str
+            Human-readable of the modality of the measurements.
+        modality: str
+            Short textual description of the modality of measurements.
+        anchor: AnatomicalAnchor
+        depths: list, default: None
+            List of cortical depth positions corresponding to each
+            measurement, all in the range [0..1]
+        values: list, default: None
+            List of the actual measurements at each depth position.
+            Length must correspond to 'depths'.
+        unit: str, default: None
+            Textual identifier for the unit of measurements.
+        boundary_positions: dict, default: None
+            Dictionary of depths at which layer boundaries were identified.
+            Keys are tuples of layer numbers, e.g. (1,2), and values are
+            cortical depth positions in the range [0..1].
+        datasets : list[Dataset]
+            list of datasets corresponding to this feature
+        """
+
+        # cached properties will be revealed as property functions,
+        # so derived classes may choose to override for lazy loading.
+        self._unit = unit
+        self._depths_cached = depths
+        self._values_cached = values
+        self._boundary_positions = boundary_positions
+
+        tabular.Tabular.__init__(
+            self,
+            modality=modality,
+            description=description,
+            anchor=anchor,
+            data=None,  # lazy loader below
+            datasets=datasets,
+            id=id,
+            prerelease=prerelease,
+        )
+
+    def _check_sanity(self):
+        # check plausibility of the profile
+        assert isinstance(self._depths, (list, np.ndarray)), "Some depths are not valid"
+        assert isinstance(self._values, (list, np.ndarray)), "Some values are not valid"
+        assert len(self._values) == len(self._depths), "There exist uneven number of depths and values"
+        assert all(0 <= d <= 1 for d in self._depths), "Some depths is not between 0 and 1"
+        if self.boundaries_mapped:
+            assert all(0 <= d <= 1 for d in self.boundary_positions.values()), "Some boundary positions are not between 0 and 1"
+            assert all(
+                layerpair in self.BOUNDARIES
+                for layerpair in self.boundary_positions.keys()
+            ), "Some value in BOUNDARIES are not mapped in boundary_positions"
+
+    @property
+    def unit(self) -> str:
+        """Optionally overridden in derived classes."""
+        if self._unit is None:
+            raise NotImplementedError(f"'unit' not set for {self.__class__.__name__}.")
+        return self._unit
+
+    @property
+    def boundary_positions(self) -> Dict[Tuple[int, int], float]:
+        if self._boundary_positions is None:
+            return {}
+        else:
+            return self._boundary_positions
+
+    def assign_layer(self, depth: float):
+        """Compute the cortical layer for a given depth from the
+        layer boundary positions. If no positions are available
+        for this profile, return None."""
+        assert 0 <= depth <= 1
+        if len(self.boundary_positions) == 0:
+            return None
+        else:
+            return max(
+                [l2 for (l1, l2), d in self.boundary_positions.items() if d < depth]
+            )
+
+    @property
+    def boundaries_mapped(self) -> bool:
+        if self.boundary_positions is None:
+            return False
+        else:
+            return all((b in self.boundary_positions) for b in self.BOUNDARIES)
+
+    @property
+    def _layers(self):
+        """List of layers assigned to each measurments,
+        if layer boundaries are available for this features.
+        """
+        if self.boundaries_mapped:
+            return [self.assign_layer(d) for d in self._depths]
+        else:
+            return None
+
+    @property
+    def data(self):
+        """Return a pandas Series representing the profile."""
+        self._check_sanity()
+        iscompound = len(self._values.shape) > 1 and self._values.shape[1] == 2
+        if iscompound:
+            columns = [f"{self.modality} mean ({self.unit})", "std"]
+        else:
+            columns = [f"{self.modality} ({self.unit})"]
+        return pd.DataFrame(self._values, index=self._depths, columns=columns)
+
+    @classmethod
+    def _merge_elements(
+        cls,
+        elements: List["CorticalProfile"],
+        description: str,
+        modality: str,
+        anchor: _anchor.AnatomicalAnchor,
+    ):
+        assert all(np.array_equal(elements[0]._depths, f._depths) for f in elements)
+        assert len({f.unit for f in elements}) == 1
+        values_stacked = np.stack([f._values for f in elements])
+        return CorticalProfile(
+            description=description,
+            modality=modality,
+            anchor=anchor,
+            depths=np.stack([f._depths for f in elements]).mean(0),
+            values=np.stack([values_stacked.mean(0), values_stacked.std(0)]).T,
+            unit=elements[0].unit,
+            boundary_positions=None,
+        )
+
+    def plot(self, *args, backend="matplotlib", **kwargs):
+        """
+        Plot the profile.
+
+        Parameters
+        ----------
+        backend: str
+            "matplotlib", "plotly", or others supported by pandas DataFrame
+            plotting backend.
+        **kwargs
+            Keyword arguments are passed on to the plot command. 'layercolor'
+            can be used to specify a color for cortical layer shading.
+        """
+        wrapwidth = kwargs.pop("textwrap") if "textwrap" in kwargs else 40
+        kwargs["title"] = kwargs.get("title", "\n".join(wrap(self.name, wrapwidth)))
+        layercolor = kwargs.pop("layercolor", "gray")
+
+        iscompound = len(self._values.shape) > 1 and self._values.shape[1] == 2
+        ymax = max(
+            0,
+            sum(self._values.max(axis=0)) if iscompound else self._values.max()
+        )
+        if backend == "matplotlib":
+            kwargs["xlabel"] = kwargs.get("xlabel", "Cortical depth")
+            kwargs["ylabel"] = kwargs.get("ylabel", self.unit)
+            kwargs["grid"] = kwargs.get("grid", True)
+            axs = self.data.iloc[:, 0].plot(*args, **kwargs, backend=backend)
+            axs.set_ylim(kwargs.get("ylim", (0, ymax)))
+
+            if self.boundaries_mapped:
+                bvals = list(self.boundary_positions.values())
+                for i, (d1, d2) in enumerate(list(zip(bvals[:-1], bvals[1:]))):
+                    axs.text(
+                        d1 + (d2 - d1) / 2.0,
+                        10,
+                        self.LAYERS[i + 1],
+                        weight="normal",
+                        ha="center",
+                    )
+                    if i % 2 == 0:
+                        axs.axvspan(d1, d2, color=layercolor, alpha=0.3)
+
+            axs.set_title(axs.get_title(), fontsize="medium")
+
+            if iscompound:
+                axs.set_ylabel(f"average {kwargs['ylabel']} \u00b1 std")
+                av = self.data.values[:, 0]
+                std = self.data.values[:, 1]
+                axs.fill_between(self.data.index.values, av - std, av + std, alpha=0.5)
+
+            return axs
+
+        elif backend == "plotly":
+            kwargs["title"] = kwargs["title"].replace("\n", "<br>")
+            kwargs["labels"] = {
+                "index": kwargs.pop("xlabel", None) or kwargs.pop("index", "Cortical depth"),
+                "value": kwargs.pop("ylabel", None) or kwargs.pop("value", self.unit)
+            }
+            fig = self.data.iloc[:, 0].plot(*args, **kwargs, backend=backend)
+            if self.boundaries_mapped:
+                bvals = list(self.boundary_positions.values())
+                for i, (d1, d2) in enumerate(list(zip(bvals[:-1], bvals[1:]))):
+                    fig.add_vrect(
+                        x0=d1, x1=d2, line_width=0, fillcolor=layercolor,
+                        opacity=0.2 if i % 2 == 0 else 0.0,
+                        label=dict(text=self.LAYERS[i + 1], textposition="bottom center")
+                    )
+            fig.update_layout(
+                showlegend=False,
+                yaxis_range=(0, ymax),
+                title=dict(
+                    automargin=True, yref="container", xref="container",
+                    pad=dict(t=40), xanchor="left", yanchor="top"
+                )
+            )
+            if iscompound:
+                from plotly.graph_objects import Scatter
+                x = self.data.index.values
+                av = self.data.values[:, 0]
+                std = self.data.values[:, 1]
+                fig.update_layout(yaxis_title=f"average {kwargs['labels']['value']} &plusmn; std")
+                fig.add_traces(
+                    Scatter(
+                        x=np.concatenate((x, x[::-1])),  # x, then x reversed
+                        y=np.concatenate((av + std, (av - std)[::-1])),  # upper, then lower reversed
+                        fill='toself',
+                        fillcolor='rgba(0,100,80,0.5)',
+                        line=dict(color='rgba(255,255,255,0)'),
+                        hoverinfo="skip",
+                        showlegend=False
+                    )
+                )
+            return fig
+        else:
+            return self.data.plot(*args, **kwargs, backend=backend)
+
+    @property
+    def _depths(self):
+        """
+        Returns a list of the relative cortical depths of the measured values in the range [0..1].
+
+        To be implemented in derived class.
+        """
+        if self._depths_cached is None:
+            raise NotImplementedError(
+                f"'_depths' not available for {self.__class__.__name__}."
+            )
+        return self._depths_cached
+
+    @property
+    def _values(self):
+        """
+        Returns a list of the measured values per depth.
+
+        To be implemented in derived class.
+        """
+        if self._values_cached is None:
+            raise NotImplementedError(
+                f"'_values' not available for {self.__class__.__name__}."
+            )
+        return self._values_cached
+
+    @property
+    def name(self):
+        if hasattr(self, "receptor"):
+            return super().name + f": {self.receptor}"
+        if hasattr(self, "location"):
+            return super().name + f": {self.location.coordinate}"
+        return super().name

siibra/features/tabular/gene_expression.py

@@ -0,0 +1,257 @@
+# 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 ...retrieval.datasets import GenericDataset
+
+import pandas as pd
+from textwrap import wrap
+from typing import List
+try:
+    from typing import TypedDict
+except ImportError:
+    from typing_extensions import TypedDict
+
+
+class GeneExpressions(
+    tabular.Tabular,
+    category='molecular'
+):
+    """
+    A set gene expressions for different candidate genes
+    measured inside a brain structure.
+    """
+
+    DESCRIPTION = """
+    Gene expressions extracted from microarray data in the Allen Atlas.
+    """
+
+    ALLEN_ATLAS_NOTIFICATION = """
+    For retrieving microarray data, siibra connects to the web API of
+    the Allen Brain Atlas (© 2015 Allen Institute for Brain Science),
+    available from https://brain-map.org/api/index.html. Any use of the
+    microarray data needs to be in accordance with their terms of use,
+    as specified at https://alleninstitute.org/legal/terms-use/.
+    """
+
+    DATASET = GenericDataset(
+        name="An anatomically comprehensive atlas of the adult human brain transcriptome",
+        contributors=[
+            'Michael J. Hawrylycz',
+            'Ed S. Lein',
+            'Angela L. Guillozet-Bongaarts',
+            'Elaine H. Shen',
+            'Lydia Ng',
+            'Jeremy A. Miller',
+            'Louie N. van de Lagemaat',
+            'Kimberly A. Smith',
+            'Amanda Ebbert',
+            'Zackery L. Riley',
+            'Chris Abajian',
+            'Christian F. Beckmann',
+            'Amy Bernard',
+            'Darren Bertagnolli',
+            'Andrew F. Boe',
+            'Preston M. Cartagena',
+            'M. Mallar Chakravarty',
+            'Mike Chapin',
+            'Jimmy Chong',
+            'Rachel A. Dalley',
+            'Barry David Daly',
+            'Chinh Dang',
+            'Suvro Datta',
+            'Nick Dee',
+            'Tim A. Dolbeare',
+            'Vance Faber',
+            'David Feng',
+            'David R. Fowler',
+            'Jeff Goldy',
+            'Benjamin W. Gregor',
+            'Zeb Haradon',
+            'David R. Haynor',
+            'John G. Hohmann',
+            'Steve Horvath',
+            'Robert E. Howard',
+            'Andreas Jeromin',
+            'Jayson M. Jochim',
+            'Marty Kinnunen',
+            'Christopher Lau',
+            'Evan T. Lazarz',
+            'Changkyu Lee',
+            'Tracy A. Lemon',
+            'Ling Li',
+            'Yang Li',
+            'John A. Morris',
+            'Caroline C. Overly',
+            'Patrick D. Parker',
+            'Sheana E. Parry',
+            'Melissa Reding',
+            'Joshua J. Royall',
+            'Jay Schulkin',
+            'Pedro Adolfo Sequeira',
+            'Clifford R. Slaughterbeck',
+            'Simon C. Smith',
+            'Andy J. Sodt',
+            'Susan M. Sunkin',
+            'Beryl E. Swanson',
+            'Marquis P. Vawter',
+            'Derric Williams',
+            'Paul Wohnoutka',
+            'H. Ronald Zielke',
+            'Daniel H. Geschwind',
+            'Patrick R. Hof',
+            'Stephen M. Smith',
+            'Christof Koch',
+            'Seth G. N. Grant',
+            'Allan R. Jones'
+        ],
+        url="https://doi.org/10.1038%2Fnature11405",
+        description='Neuroanatomically precise, genome-wide maps of transcript '
+            'distributions are critical resources to complement genomic '
+            'sequence data and to correlate functional and genetic brain '
+            'architecture. Here we describe the generation and analysis '
+            'of a transcriptional atlas of the adult human brain, '
+            'comprising extensive histological analysis and comprehensive '
+            'microarray profiling of ~900 neuroanatomically precise '
+            'subdivisions in two individuals. Transcriptional regulation '
+            'varies enormously by anatomical location, with different '
+            'regions and their constituent cell types displaying robust '
+            'molecular signatures that are highly conserved between '
+            'individuals. Analysis of differential gene expression and '
+            'gene co-expression relationships demonstrates that brain-'
+            'wide variation strongly reflects the distributions of major '
+            'cell classes such as neurons, oligodendrocytes, astrocytes '
+            'and microglia. Local neighbourhood relationships between '
+            'fine anatomical subdivisions are associated with discrete '
+            'neuronal subtypes and genes involved with synaptic '
+            'transmission. The neocortex displays a relatively '
+            'homogeneous transcriptional pattern, but with distinct '
+            'features associated selectively with primary sensorimotor '
+            'cortices and with enriched frontal lobe expression. Notably, '
+            'the spatial topography of the neocortex is strongly '
+            'reflected in its molecular topography— the closer two '
+            'cortical regions, the more similar their transcriptomes. '
+            'This freely accessible online data resource forms a high-'
+            'resolution transcriptional baseline for neurogenetic studies '
+            'of normal and abnormal human brain function.'
+            ""
+            "For retrieving microarray data, siibra connects to the web API of "
+            "the Allen Brain Atlas (© 2015 Allen Institute for Brain Science), "
+            "available from https://brain-map.org/api/index.html. Any use of the "
+            "microarray data needs to be in accordance with their terms of use, "
+            "as specified at https://alleninstitute.org/legal/terms-use/."
+    )
+
+    class _DonorDict(TypedDict):
+        id: int
+        name: str
+        race: str
+        age: int
+        gender: str
+
+    class _SampleStructure(TypedDict):
+        id: int
+        name: str
+        abbreviation: str
+        color: str
+
+    def __init__(
+        self,
+        levels: List[float],
+        z_scores: List[float],
+        genes: List[str],
+        additional_columns: dict,
+        anchor: _anchor.AnatomicalAnchor,
+        datasets: List = [DATASET]
+    ):
+        """
+        Construct gene expression table.
+
+        Parameters
+        ----------
+        levels : list of float
+            Expression levels measured
+        z_scores : list of float
+            corresponding z scores measured
+        genes : list of str
+            Name of the gene corresponding to each measurement
+        additional_columns : dict of list
+            columns with additional data to be added to the tabular feature.
+            Keys give column names, values are lists with the column data.
+            Each list given needs to have the same length as expression_levels
+        anchor: AnatomicalAnchor
+        datasets : list
+            list of datasets corresponding to this feature
+        """
+        assert len(z_scores) == len(levels)
+        assert len(genes) == len(levels)
+        if additional_columns is not None:
+            assert all(len(lst) == len(levels) for lst in additional_columns.values())
+        else:
+            additional_columns = {}
+
+        _data_cahced = pd.DataFrame(
+            dict(
+                **{'level': levels, 'zscore': z_scores, 'gene': genes},
+                **additional_columns
+            )
+        )
+        # data.index.name = 'probe_id'
+        tabular.Tabular.__init__(
+            self,
+            description=(
+                (self.DESCRIPTION + self.ALLEN_ATLAS_NOTIFICATION)
+                .replace('\n', ' ')
+                .replace('\t', '')
+                .strip()
+            ),
+            modality="Gene expression",
+            anchor=anchor,
+            data=_data_cahced,
+            datasets=datasets
+        )
+        self.unit = "expression level"
+
+    def plot(self, *args, backend="matplotlib", **kwargs):
+        """
+        Create a box plot per gene.
+
+        Parameters
+        ----------
+        backend: str
+            "matplotlib", "plotly", or others supported by pandas DataFrame
+            plotting backend.
+        **kwargs
+            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"
+        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)
+        elif backend == "plotly":
+            kwargs["title"] = kwargs["title"].replace('\n', "<br>")
+            return self.data.plot(y='level', x='gene', backend=backend, **kwargs)
+        else:
+            return self.data.plot(*args, backend=backend, **kwargs)

siibra/features/tabular/layerwise_bigbrain_intensities.py

@@ -0,0 +1,62 @@
+# 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 tabular
+
+import pandas as pd
+import numpy as np
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from ...features.anchor import AnatomicalAnchor
+
+
+class LayerwiseBigBrainIntensities(
+    tabular.Tabular,
+    category='cellular'
+):
+
+    DESCRIPTION = (
+        "Layerwise averages and standard deviations of of BigBrain staining intensities "
+        "computed by Konrad Wagstyl, as described in the publication "
+        "'Wagstyl, K., et al (2020). BigBrain 3D atlas of "
+        "cortical layers: Cortical and laminar thickness gradients diverge in sensory and "
+        "motor cortices. PLoS Biology, 18(4), e3000678. "
+        "http://dx.doi.org/10.1371/journal.pbio.3000678."
+        "The data is taken from the tutorial at "
+        "https://github.com/kwagstyl/cortical_layers_tutorial. Each vertex is "
+        "assigned to the regional map when queried."
+    )
+
+    def __init__(
+        self,
+        anchor: "AnatomicalAnchor",
+        means: list,
+        stds: list,
+    ):
+        data = pd.DataFrame(
+            np.array([means, stds]).T,
+            columns=['mean', 'std'],
+            index=list(cortical_profile.CorticalProfile.LAYERS.values())[1: -1]
+        )
+        data.index.name = "layer"
+        tabular.Tabular.__init__(
+            self,
+            description=self.DESCRIPTION,
+            modality="Modified silver staining",
+            anchor=anchor,
+            data=data
+        )