junifer 0.0.2.dev297__tar.gz → 0.0.2.dev320__tar.gz

{junifer-0.0.2.dev297 → junifer-0.0.2.dev320}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: junifer
-Version: 0.0.2.dev297
+Version: 0.0.2.dev320
 Summary: JUelich NeuroImaging FEature extractoR
 Author-email: Fede Raimondo <f.raimondo@fz-juelich.de>, Synchon Mandal <s.mandal@fz-juelich.de>
 Maintainer-email: Fede Raimondo <f.raimondo@fz-juelich.de>, Synchon Mandal <s.mandal@fz-juelich.de>

{junifer-0.0.2.dev297 → junifer-0.0.2.dev320}/docs/builtin.rst

@@ -1,5 +1,7 @@
 .. include:: links.inc
 
+.. _builtin:
+
 Built-in Pipeline steps and data
 ================================
 

{junifer-0.0.2.dev297 → junifer-0.0.2.dev320}/docs/changes/latest.inc

@@ -65,6 +65,10 @@ Enhancements
 
 - Force datalad to be non-interactive on _queued_ jobs (:gh:`201` by `Fede Raimondo`_).
 
+- Add more documentation on registering parcellations, coordinates, and masks (:gh:`166` by `Leonard Sasse`_)
+
+- Expose a :func:`junifer.data.parcellations.merge_parcellations` function to merge a list of parcellations (:gh:`146` by Leonard Sasse`_).
+
 Bugs
 ~~~~
 

junifer-0.0.2.dev320/docs/extending/coordinates.rst

@@ -0,0 +1,132 @@
+.. include:: ../links.inc
+
+.. _adding_coordinates:
+
+Adding Coordinates
+==================
+
+Instead of using whole-brain parcellations to aggregate voxel-wise signals from
+MR images (as for example in the
+:class:`junifer.markers.parcel_aggregation.ParcelAggregation` marker), Junifer
+allows you to specify a set of coordinates around which to draw spheres to
+aggregate (for example using the
+:class:`junifer.markers.sphere_aggregation.SphereAggregation` marker) the MR
+signals from individual voxels. Now, before you start specifying your own sets
+of coordinates, check the coordinates that Junifer already has
+:ref:`built in already<builtin>`. If you simply want to use a well known set of
+coordinates from the literature, there is a reasonable chance, that Junifer
+provides them already.
+
+If you checked the in-built coordinates, and they are not there already (for
+example if you came up with your own set of coordinates), then Junifer provides
+an easy way for you to register them using the
+:func:`junifer.data.coordinates.register_coordinates` function, so you can use
+your own set of coordinates within a Junifer pipeline.
+
+From the API reference, we can see that it has 3 positional arguments
+(``name``, ``coordinates``, and ``voi_names``) as well as one
+optional keyword argument (``overwrite``).
+
+The ``name`` argument takes a string indicating the name you want to give to
+this set of coordinates. This ``name`` can be used to obtain and operate on a
+set of coordinates in Junifer. For example, you can obtain your coordinates
+after registration by providing ``name`` to
+:func:`junifer.data.coordinates.load_coordinates`. We could simply call it
+``"my_set_of_coordinates"``, but likely you want a more descriptive and more
+informative name most of the time.
+
+The ``coordinates`` argument takes the actual coordinates as a 2-dimensional
+:func:`numpy.array`. It contains one row for every location, and three columns
+(one for each spatial dimension). That is, the first, second, and third columns
+indicate the x-, y-, and z-coordinates in MNI space respectively. Note, that
+Junifer (as of yet) only works in MNI space, and so therefore these coordinates
+should always be real-world coordinates of the MNI space. From this description
+it follows that the number of rows in the array correspond to the number of
+coordinates that belong to this set.
+
+Lastly, the ``voi_names`` argument takes a list of strings indicating the names
+of each coordinate (i.e. volume-of-interest) in the ``coordinates`` array.
+Therefore, the length of this list should correspond to the number of rows in
+the coordinates array. Now, we know everything we need to register a set of
+coordinates.
+
+Step 1: Prepare code to register a set of coordinates
+-----------------------------------------------------
+
+Let's make a simple script to register our coordinates. We could simply call it
+``register_coordinates.py``. We may start by importing the appropriate
+packages:
+
+.. code-block:: python
+
+  from junifer.data import register_coordinates
+  import numpy as np
+
+For the sake of this example, we can create a set of coordinates that belong
+to the default mode network (DMN), and register this set of coordinates with
+Junifer. Note, that Junifer already has a
+:ref:`set of coordinates built-in<builtin>` ("DMNBuckner") that is associated
+with the DMN. Here, we use the DMN coordinates used in a
+`nilearn example <https://nilearn.github.io/dev/auto_examples/03_connectivity/plot_sphere_based_connectome.html>`_.
+
+.. code-block:: python
+
+  dmn_coords = np.array(
+      [[0, -52, 18],
+      [-46, -68, 32],
+      [46, -68, 32],
+      [1, 50, -5]]
+  )
+  voi_names = [
+      "Posterior Cingulate Cortex",
+      "Left Temporoparietal junction",
+      "Right Temporoparietal junction",
+      "Medial prefrontal cortex",
+  ]
+
+As you can see, we have four rows, and therefore four locations in the brain
+associated with this set of coordinates. The variable ``voi_names`` reflects this
+as it contains four strings indicating the name of each location. We can now
+simply use this to register our coordinates:
+
+.. code-block:: python
+
+  register_coordinates(
+      name="DMNCustom",
+      coordinates=dmn_coords,
+      voi_names=voi_names
+  )
+
+Now, when we run this script, Junifer registers these coordinates and we can
+use them in subsequent analyses. Let's now consider how to use coordinate
+registration in combination with
+:ref:`codeless configuration using a YAML file<codeless>`.
+
+Step 2: Add coordinate registration to the YAML file
+----------------------------------------------------
+
+In order to register your coordinates for a pipeline configured by a YAML file,
+you can use the ``with`` keyword provided by Junifer:
+
+.. code-block:: yaml
+
+  with:
+    - registering_my_parcellation.py
+
+Afterwards continue configuring the rest of your pipeline in this YAML file,
+and you will be able to use this set of coordinates using the name you gave it
+during registration (in our example "DMNCustom"). We can add a
+:class:`junifer.markers.sphere_aggregation.SphereAggregation` to demonstrate
+how this can be done:
+
+.. code-block:: yaml
+
+  markers:
+    - name: DMNCustom_mean
+      kind: SphereAggregation
+      coords: DMNCustom
+      radius: 5
+      method: mean
+
+This will aggregate signals from a sphere around each of our coordinates with a
+radius of 5mm.

{junifer-0.0.2.dev297 → junifer-0.0.2.dev320}/docs/extending/index.rst

@@ -25,4 +25,7 @@ datagrabbers, preprocessing and markers, following the *junifer* way.
 
    extension
    datagrabber
-   marker
+   marker
+   parcellations
+   coordinates
+   masks

junifer-0.0.2.dev320/docs/extending/masks.rst

@@ -0,0 +1,82 @@
+.. include:: ../links.inc
+
+.. _adding_masks:
+
+Adding Masks
+============
+
+Many processing steps and markers in Junifer allow you to specify a binary
+mask to select voxels you want to include in the analysis. There are a number
+of masks :ref:`in-built in Junifer already<builtin>`, so check if any of them
+suit your needs. Check how to use these masks :ref:`here<using_masks>`. Once
+you know how to use these masks, and you checked whether the in-built masks
+suit your needs, and you have found that they don't, you can come back here to
+learn how to use your own masks.
+
+The principle is fairly simple and quite similar to :ref:`adding_parcellations`
+and :ref:`adding_coordinates`. Junifer provides a
+:func:`junifer.data.masks.register_mask` function that lets you register your
+own custom masks. It consists of two positional arguments (``name`` and
+``mask_path``) and one optional keyword argument (``overwrite``).
+
+The ``name`` argument is a string indicating the name of the mask. This name
+is used to refer to that mask in Junifer internally in order to obtain the
+actual mask data and perform operations on it. For example, using the name you
+can load a mask after registration using the
+:func:`junifer.data.masks.load_mask` function.
+
+The ``mask_path`` should contain the path to a valid NIfTI image with binary
+voxel values (i.e. 0 or 1). This data can then be used by Junifer to mask other
+MR images.
+
+Step 1: Prepare code to register a mask
+---------------------------------------
+
+A simple script called ``register_mask.py`` to register a mask could look as
+follows:
+
+.. code-block:: python
+
+  from junifer.data import register_custom_mask
+  from pathlib import Path
+
+  # this path is only an example, of course use the correct path
+  # on your system:
+  mask_path = Path("..") / ".." / "my_custom_mask.nii.gz"
+
+  register_mask(name="my_custom_mask", mask_path=mask_path)
+
+Simple, right? Now we just have to configure a YAML file to register this mask
+so we can use it for :ref:`codeless configuration of junifer<codeless>`.
+
+Step 2: Configure a YAML file for registration of a mask
+--------------------------------------------------------
+
+In order to do this, we can use the ``with`` keyword provided by Junifer:
+
+.. code-block:: yaml
+
+  with:
+    - register_custom_mask.py
+
+Then we can use this mask for any processing step or marker that takes in a
+mask as an argument. For example:
+
+.. code-block:: yaml
+
+  markers:
+    - name: CustomMaskParcelAggregation_mean
+      kind: ParcelAggregation
+      parcellation: Schaefer200x17
+      method: mean
+      masks: "my_custom_mask"
+
+Now, you can simply use this YAML file to run your pipeline. One important
+point to keep in mind is that if the paths given in ``register_custom_mask.py``
+are relative paths, they will be interpreted by Junifer as relative to the
+jobs directory (i.e. where Junifer will create submit files, logs directory and
+so on). For simplicity, you may just want to use absolute paths to avoid
+confusion, yet using relative paths is likely a better way to make your
+pipeline directory/repository more portable and therefore more reproducible for
+others. Really, once you understand how these paths are interpreted by Junifer,
+it is quite easy.

junifer-0.0.2.dev320/docs/extending/parcellations.rst

@@ -0,0 +1,123 @@
+.. include:: ../links.inc
+
+.. _adding_parcellations:
+
+Adding Parcellations
+====================
+
+Before you start adding your own parcellations, check whether Junifer has
+the parcellation :ref:`in-built already<builtin>`. Perhaps, what is available
+there will suffice to achieve your goals. However, of course Junifer will not
+have every parcellation available that you may want to use, and if so, it will
+be nice to be able to add it yourself using a format that Junifer understands.
+Similarly, you may even be interested in creating your own custom parcellations
+and then adding them to Junifer, so you can use Junifer to obtain different
+markers to assess and validate your own parcellation. So, how can you do this?
+
+Since both of these use-cases are quite common, and not being able to use your
+favourite parcellation is of course quite a buzzkill, Junifer actually provides
+the easy-to-use :func:`junifer.data.parcellations.register_parcellation`
+function to do just that. Let's try to understand the API reference
+and then use this function to register our own parcellation.
+
+From the API reference, we can see that it has 3 positional arguments
+(``name``, ``parcellation_path``, and ``parcels_labels``) as well as one
+optional keyword argument (``overwrite``).
+
+The ``name`` of the parcellation is up to you and will be the name that Junifer
+will use to refer to this particular parcellation. You can think of this as
+being similar to a key in a python dictionary, i.e. a key that is used to
+obtain and operate on the actual parcellation data. This ``name`` must always
+be a string. For example, we could call our parcellation
+``"my_custom_parcellation"`` (Note, that in a real-world use case this is
+likely not a good name, and you should try to choose a meaningful name that
+conveys as much relevant information about your parcellation as necessary).
+
+The ``parcellation_path`` must be a ``str`` or ``Path`` object indicating a
+path to a valid ``NIfTI`` image, which contains integer labels indicating the
+individual regions-of-interest (ROIs) of your parcellation. The background in
+this parcellation should be indicated by 0, and the labels of ROIs should go
+from 1 to N (where N is the total number of ROIs in your parcellation). Now,
+we nearly have everything we need.
+
+Lastly, we also want to make sure that we can associate each integer label with
+a human readable name (i.e. the name for each ROI). This serves naming the
+features that parcellation-based markers produce in an unambiguous way, such
+that a user can easily identify which ROIs were used to produce a specific
+feature (multiple ROIs, because some features consist of information from two
+or more ROIs, as for example in functional connectivity). Therefore, we provide
+Junifer with a list of strings, that contains the names for each ROI. In this
+list, the label at the i-th position indicates the i-th integer label (i.e. the
+first label in this list corresponds to the first integer label in the
+parcellation and so on).
+
+Step 1: Prepare code to register a parcellation
+-----------------------------------------------
+
+Now we know everything that we need to know to make sure Junifer can use our
+own parcellation to compute any parcellation-based marker. For example,
+a simple example could look like this:
+
+.. code-block:: python
+
+  from junifer.data import register_parcellation
+
+  from pathlib import Path
+  import numpy as np
+
+  # these are of course just example paths, replace it with your own:
+  path_to_parcellation = (
+      Path("..") / ".." / "parcellations" / "my_custom_parcellation.nii.gz"
+  )
+  path_to_labels = (
+      Path("..") / ".." / "labels" / "my_custom_parcellation_labels.txt"
+  )
+
+  my_labels = list(np.loadtxt(path_to_labels, dtype=str))
+
+  register_parcellation(
+      name="my_custom_parcellation",
+      parcellation_path=path_to_parcellation,
+      parcels_labels=my_labels
+  )
+
+We can run this code and it seems to work, however, how can we actually
+include the custom parcellation in a Junifer pipeline using a
+:ref:`code-less YAML configuration<codeless>`?
+
+Step 2: Add parcellation registration to the YAML file
+------------------------------------------------------
+
+In order to use the parcellation in a Junifer pipeline configured by a YAML
+file, we can save the above code in a python file, say
+``registering_my_parcellation.py``. We can then simply add this file using the
+``with`` keyword provided by Junifer:
+
+.. code-block:: yaml
+
+  with:
+    - registering_my_parcellation.py
+
+Afterwards continue configuring the rest of the pipeline in this YAML file, and
+you will be able to use this parcellation using the name you gave the
+parcellation when registering it. For example, we can add a
+:class:`junifer.markers.parcel_aggregation.ParcelAggregation` marker to
+demonstrate how this can be done:
+
+.. code-block:: yaml
+
+  markers:
+    - name: CustomParcellation_mean
+      kind: ParcelAggregation
+      parcellation: my_custom_parcellation
+      method: mean
+
+Now, you can simply use this YAML file to run your pipeline. One important
+point to keep in mind is that if the paths given in
+``registering_my_parcellation.py`` are relative paths, they will be interpreted
+by Junifer as relative to the jobs directory (i.e. where Junifer will create
+submit files, logs directory and so on). For simplicity, you may just want to
+use absolute paths to avoid confusion, yet using relative paths is likely a
+better way to make your pipeline directory/repository more portable and
+therefore more reproducible for others. Really, once you understand how these
+paths are interpreted by Junifer, it is quite easy.

junifer-0.0.2.dev320/junifer/_version.py

@@ -0,0 +1,4 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+__version__ = version = '0.0.2.dev320'
+__version_tuple__ = version_tuple = (0, 0, 2, 'dev320')

{junifer-0.0.2.dev297 → junifer-0.0.2.dev320}/junifer/data/__init__.py

@@ -13,6 +13,7 @@ from .parcellations import (
     list_parcellations,
     load_parcellation,
     register_parcellation,
+    merge_parcellations,
 )
 
 from .masks import (

{junifer-0.0.2.dev297 → junifer-0.0.2.dev320}/junifer/data/coordinates.py

@@ -64,7 +64,10 @@ def register_coordinates(
     name : str
         The name of the coordinates.
     coordinates : numpy.ndarray
-        The coordinates.
+        The coordinates. This should be a 2-dimensional array with three
+        columns. Each row corresponds to a volume-of-interest (VOI) and each
+        column corresponds to a spatial dimension (i.e. x, y, and
+        z-coordinates).
     voi_names : list of str
         The names of the VOIs.
     overwrite : bool, optional

{junifer-0.0.2.dev297 → junifer-0.0.2.dev320}/junifer/data/parcellations.py

@@ -16,9 +16,9 @@ import nibabel as nib
 import numpy as np
 import pandas as pd
 import requests
-from nilearn import datasets
+from nilearn import datasets, image
 
-from ..utils.logging import logger, raise_error
+from ..utils.logging import logger, raise_error, warn_with_log
 from .utils import closest_resolution
 
 
@@ -700,3 +700,84 @@ def _retrieve_suit(
     ].to_list()
 
     return parcellation_fname, labels
+
+
+def merge_parcellations(
+    parcellations_list: List["Nifti1Image"],
+    parcellations_names: List[str],
+    labels_lists: List[List[str]],
+) -> Tuple["Nifti1Image", List[str]]:
+    """Merge all parcellations from a list into one parcellation.
+
+    Parameters
+    ----------
+    parcellations_list : list of niimg-like object
+        List of parcellations to merge.
+    parcellations_names: list of str
+        List of names for parcellations at the corresponding indices.
+    labels_lists : list of list of str
+        A list of lists. Each list in the list contains the labels for the
+        parcellation at the corresponding index.
+
+    Returns
+    -------
+    parcellation : niimg-like object
+        The parcellation that results from merging the list of input
+        parcellations.
+    labels : list of str
+        List of labels for the resultant parcellation.
+
+    """
+    # Check for duplicated labels
+    labels_lists_flat = [item for sublist in labels_lists for item in sublist]
+    if len(labels_lists_flat) != len(set(labels_lists_flat)):
+        warn_with_log(
+            "The parcellations have duplicated labels. "
+            "Each label will be prefixed with the parcellation name."
+        )
+        for i_parcellation, t_labels in enumerate(labels_lists):
+            labels_lists[i_parcellation] = [
+                f"{parcellations_names[i_parcellation]}_{t_label}"
+                for t_label in t_labels
+            ]
+    overlapping_voxels = False
+    ref_parc = parcellations_list[0]
+    parc_data = ref_parc.get_fdata()
+
+    labels = labels_lists[0]
+
+    for t_parc, t_labels in zip(parcellations_list[1:], labels_lists[1:]):
+        if t_parc.shape != ref_parc.shape:
+            warn_with_log(
+                "The parcellations have different resolutions!"
+                "Resampling all parcellations to the first one in the list."
+            )
+            t_parc = image.resample_to_img(
+                t_parc, ref_parc, interpolation="nearest", copy=True
+            )
+
+        # Get the data from this parcellation
+        t_parc_data = t_parc.get_fdata().copy()  # must be copied
+        # Increase the values of each ROI to match the labels
+        t_parc_data[t_parc_data != 0] += len(labels)
+
+        # Only set new values for the voxels that are 0
+        # This makes sure that the voxels that are in multiple
+        # parcellations are assigned to the parcellation that was
+        # first in the list.
+        if np.any(parc_data[t_parc_data != 0] != 0):
+            overlapping_voxels = True
+
+        parc_data[parc_data == 0] += t_parc_data[parc_data == 0]
+        labels.extend(t_labels)
+
+    if overlapping_voxels:
+        warn_with_log(
+            "The parcellations have overlapping voxels. "
+            "The overlapping voxels will be assigned to the "
+            "parcellation that was first in the list."
+        )
+
+    parcellation_img_res = image.new_img_like(parcellations_list[0], parc_data)
+
+    return parcellation_img_res, labels