Update examples and add BOLD signal example (#445)

* Doc: Increase width of the body

* Maint: update examples

* Test examples with python 3.8

* Doc: Add BOLD signal example

* Doc: use 100dvw instead of 1000px max width

* Add carpet_plot to BOLD example

Author: AhmetNSimsek

examples/03_data_features/008_functional_timeseries.py

@@ -0,0 +1,71 @@
+# Copyright 2018-2021
+# 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.
+
+"""
+Parcellation-based functional data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`siibra` provides access to parcellation-averaged functional data such as
+blood-oxygen-level-dependent (BOLD) signals.
+"""
+
+# %%
+import siibra
+# sphinx_gallery_thumbnail_number = 1
+
+# %%
+# We start by selecting an atlas parcellation.
+jubrain = siibra.parcellations.get("julich 2.9")
+
+# %%
+# The matrices are queried as expected, using `siibra.features.get`,
+# passing the parcellation as a concept.
+# Here, we query for structural connectivity matrices.
+features = siibra.features.get(jubrain, siibra.features.functional.RegionalBOLD)
+print(f"Found {len(features)} parcellation-based BOLD signals for {jubrain}.")
+
+# %%
+# We fetch the first result, which is a specific `RegionalBOLD` object.
+bold = features[0]
+print(f"RegionalBOLD features reflects {bold.modality} of {bold.cohort} cohort.")
+print(bold.name)
+print("\n" + bold.description)
+
+# Subjects are encoded via anonymized ids:
+print(bold.subjects)
+
+
+# %%
+# The parcellation-based functional data are provided as pandas DataFrames
+# with region objects as columns and indices as time step.
+subject = bold.subjects[0]
+table = bold.get_table(subject)
+print(f"Timestep: {bold.timestep}")
+table[jubrain.get_region("hOc3v left")]
+
+# %%
+# We can visualize the signal strength per region by time via a carpet plot.
+# In fact, `plot_carpet` method can take a list of regions to display the
+# data for selected regions only.
+selected_regions = [
+    'SF (Amygdala) left', 'SF (Amygdala) right', 'Area Ph2 (PhG) left',
+    'Area Ph2 (PhG) right', 'Area Fo4 (OFC) left', 'Area Fo4 (OFC) right',
+    'Area 7A (SPL) left', 'Area 7A (SPL) right', 'CA1 (Hippocampus) left',
+    'CA1 (Hippocampus) right', 'CA1 (Hippocampus) left', 'CA1 (Hippocampus) right'
+]
+bold.plot_carpet(subject=bold.subjects[0], regions=selected_regions)
+# %%
+# Alternatively, we can visualize the mean signal strength per region:
+bold.plot(subject=bold.subjects[0], regions=selected_regions)

siibra/features/tabular/regional_timeseries_activity.py

@@ -18,11 +18,10 @@
 from .. import anchor as _anchor
 
 from ...commons import logger, QUIET, siibra_tqdm
-from ...core import region as _region
 from ...locations import pointset
 from ...retrieval.repositories import RepositoryConnector
 
-from typing import Callable, Dict, Union
+from typing import Callable, Dict, List
 import pandas as pd
 import numpy as np
 
@@ -196,11 +195,57 @@ def _array_to_dataframe(self, array: np.ndarray) -> pd.DataFrame:
             df = df.rename(columns=remapper)
         return df
 
-    def plot(self, subject: str = None, *args, backend="matplotlib", **kwargs):
-        table = self.get_table(subject)
+    def plot(
+        self, subject: str = None, regions: List[str] = None, *args,
+        backend="matplotlib", **kwargs
+    ):
+        """
+        Create a bar plot of averaged timeseries data per region.
+
+        Parameters
+        ----------
+        regions: str, 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 regions is None:
+            regions = self.regions
+        indices = [self.regions.index(r) for r in regions]
+        table = self.get_table(subject).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,
+        backend="plotly", **kwargs
+    ):
+        """
+        Create a carpet plot ofthe timeseries data per region.
+
+        Parameters
+        ----------
+        regions: str, 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 regions is None:
+            regions = self.regions
+        indices = [self.regions.index(r) for r in regions]
+        table = self.get_table(subject).iloc[:, indices]
+        table.columns = [str(r) for r in table.columns]
+        from plotly.express import imshow
+        return imshow(
+            table.T,
+            title=f"{self.modality}" + f" for subject={subject}" if subject else ""
+        )
+
 
 class RegionalBOLD(
     RegionalTimeseriesActivity,