junifer 0.0.4.dev829__py3-none-any.whl → 0.0.5__py3-none-any.whl

junifer/markers/functional_connectivity/edge_functional_connectivity_parcels.py

@@ -12,6 +12,9 @@ from ..utils import _ets
 from .functional_connectivity_base import FunctionalConnectivityBase
 
 
+__all__ = ["EdgeCentricFCParcels"]
+
+
 @register_marker
 class EdgeCentricFCParcels(FunctionalConnectivityBase):
     """Class for edge-centric FC using parcellations.
@@ -19,36 +22,40 @@ class EdgeCentricFCParcels(FunctionalConnectivityBase):
     Parameters
     ----------
     parcellation : str or list of str
-        The name(s) of the parcellation(s). Check valid options by calling
-        :func:`.list_parcellations`.
+        The name(s) of the parcellation(s) to use.
+        See :func:`.list_parcellations` for options.
     agg_method : str, optional
-        The method to perform aggregation of BOLD time series.
-        Check valid options in :func:`.get_aggfunc_by_name`
+        The method to perform aggregation using.
+        See :func:`.get_aggfunc_by_name` for options
         (default "mean").
     agg_method_params : dict, optional
-        Parameters to pass to the aggregation function. Check valid options in
-        :func:`.get_aggfunc_by_name` (default None).
-    cor_method : str, optional
-        The method to perform correlation. Check valid options in
-        :class:`nilearn.connectome.ConnectivityMeasure`
-        (default "covariance").
-    cor_method_params : dict, optional
-        Parameters to pass to the correlation function. Check valid options in
-        :class:`nilearn.connectome.ConnectivityMeasure` (default None).
+        Parameters to pass to the aggregation function.
+        See :func:`.get_aggfunc_by_name` for options
+        (default None).
+    conn_method : str, optional
+        The method to perform connectivity measure using.
+        See :class:`.JuniferConnectivityMeasure` for options
+        (default "correlation").
+    conn_method_params : dict, optional
+        Parameters to pass to :class:`.JuniferConnectivityMeasure`.
+        If None, ``{"empirical": True}`` will be used, which would mean
+        :class:`sklearn.covariance.EmpiricalCovariance` is used to compute
+        covariance. If usage of :class:`sklearn.covariance.LedoitWolf` is
+        desired, ``{"empirical": False}`` should be passed
+        (default None).
     masks : str, dict or list of dict or str, optional
         The specification of the masks to apply to regions before extracting
         signals. Check :ref:`Using Masks <using_masks>` for more details.
         If None, will not apply any mask (default None).
     name : str, optional
-        The name of the marker. If None, will use the class name (default
-        None).
+        The name of the marker. If None, will use
+        ``BOLD_EdgeCentricFCParcels`` (default None).
 
     References
     ----------
     .. [1] Jo et al. (2021)
-            Subject identification using
-            edge-centric functional connectivity
-            doi: https://doi.org/10.1016/j.neuroimage.2021.118204
+           Subject identification using edge-centric functional connectivity.
+           https://doi.org/10.1016/j.neuroimage.2021.118204
 
     """
 
@@ -57,8 +64,8 @@ class EdgeCentricFCParcels(FunctionalConnectivityBase):
         parcellation: Union[str, List[str]],
         agg_method: str = "mean",
         agg_method_params: Optional[Dict] = None,
-        cor_method: str = "covariance",
-        cor_method_params: Optional[Dict] = None,
+        conn_method: str = "correlation",
+        conn_method_params: Optional[Dict] = None,
         masks: Union[str, Dict, List[Union[Dict, str]], None] = None,
         name: Optional[str] = None,
     ) -> None:
@@ -66,8 +73,8 @@ class EdgeCentricFCParcels(FunctionalConnectivityBase):
         super().__init__(
             agg_method=agg_method,
             agg_method_params=agg_method_params,
-            cor_method=cor_method,
-            cor_method_params=cor_method_params,
+            conn_method=conn_method,
+            conn_method_params=conn_method_params,
             masks=masks,
             name=name,
         )
@@ -95,23 +102,29 @@ class EdgeCentricFCParcels(FunctionalConnectivityBase):
             to the user or stored in the storage by calling the store method
             with this as a parameter. The dictionary has the following keys:
 
-            * ``data`` : the actual computed values as a numpy.ndarray
-            * ``col_names`` : the column labels for the computed values as list
+            * ``aggregation`` : dictionary with the following keys:
+
+                - ``data`` : ROI values as ``numpy.ndarray``
+                - ``col_names`` : ROI labels as list of str
 
         """
-        parcel_aggregation = ParcelAggregation(
+        # Perform aggregation
+        aggregation = ParcelAggregation(
             parcellation=self.parcellation,
             method=self.agg_method,
             method_params=self.agg_method_params,
             masks=self.masks,
             on="BOLD",
-        )
-
-        bold_aggregated = parcel_aggregation.compute(
-            input, extra_input=extra_input
-        )
+        ).compute(input, extra_input=extra_input)
+        # Compute edgewise timeseries
         ets, edge_names = _ets(
-            bold_aggregated["data"], bold_aggregated["col_names"]
+            bold_ts=aggregation["aggregation"]["data"],
+            roi_names=aggregation["aggregation"]["col_names"],
         )
 
-        return {"data": ets, "col_names": edge_names}
+        return {
+            "aggregation": {
+                "data": ets,
+                "col_names": edge_names,
+            },
+        }

junifer/markers/functional_connectivity/edge_functional_connectivity_spheres.py

@@ -12,6 +12,9 @@ from ..utils import _ets, raise_error
 from .functional_connectivity_base import FunctionalConnectivityBase
 
 
+__all__ = ["EdgeCentricFCSpheres"]
+
+
 @register_marker
 class EdgeCentricFCSpheres(FunctionalConnectivityBase):
     """Class for edge-centric FC using coordinates (spheres).
@@ -19,42 +22,48 @@ class EdgeCentricFCSpheres(FunctionalConnectivityBase):
     Parameters
     ----------
     coords : str
-        The name of the coordinates list to use. See
-        :func:`.list_coordinates` for options.
-    radius : float, optional
-        The radius of the sphere in mm. If None, the signal will be extracted
-        from a single voxel. See :class:`nilearn.maskers.NiftiSpheresMasker`
-        for more information (default None).
+        The name of the coordinates list to use.
+        See :func:`.list_coordinates` for options.
+    radius : positive float, optional
+        The radius of the sphere around each coordinates in millimetres.
+        If None, the signal will be extracted from a single voxel.
+        See :class:`.JuniferNiftiSpheresMasker` for more information
+        (default None).
     allow_overlap : bool, optional
         Whether to allow overlapping spheres. If False, an error is raised if
-        the spheres overlap (default is False).
+        the spheres overlap (default False).
     agg_method : str, optional
-        The aggregation method to use.
-        See :func:`.get_aggfunc_by_name` for more information
-        (default None).
+        The method to perform aggregation using.
+        See :func:`.get_aggfunc_by_name` for options
+        (default "mean").
     agg_method_params : dict, optional
-        The parameters to pass to the aggregation method (default None).
-    cor_method : str, optional
-        The method to perform correlation using. Check valid options in
-        :class:`nilearn.connectome.ConnectivityMeasure` (default "covariance").
-    cor_method_params : dict, optional
-        Parameters to pass to the correlation function. Check valid options in
-        :class:`nilearn.connectome.ConnectivityMeasure` (default None).
+        Parameters to pass to the aggregation function.
+        See :func:`.get_aggfunc_by_name` for options
+        (default None).
+    conn_method : str, optional
+        The method to perform connectivity measure using.
+        See :class:`.JuniferConnectivityMeasure` for options
+        (default "correlation").
+    conn_method_params : dict, optional
+        Parameters to pass to :class:`.JuniferConnectivityMeasure`.
+        If None, ``{"empirical": True}`` will be used, which would mean
+        :class:`sklearn.covariance.EmpiricalCovariance` is used to compute
+        covariance. If usage of :class:`sklearn.covariance.LedoitWolf` is
+        desired, ``{"empirical": False}`` should be passed
+        (default None).
     masks : str, dict or list of dict or str, optional
         The specification of the masks to apply to regions before extracting
         signals. Check :ref:`Using Masks <using_masks>` for more details.
         If None, will not apply any mask (default None).
     name : str, optional
-        The name of the marker. By default, it will use
-        KIND_EdgeCentricFCSpheres where KIND is the kind of data it
-        was applied to (default None).
+        The name of the marker. If None, will use
+        ``BOLD_EdgeCentricFCSpheres`` (default None).
 
     References
     ----------
     .. [1] Jo et al. (2021)
-            Subject identification using
-            edge-centric functional connectivity
-            doi: https://doi.org/10.1016/j.neuroimage.2021.118204
+           Subject identification using edge-centric functional connectivity.
+           https://doi.org/10.1016/j.neuroimage.2021.118204
 
     """
 
@@ -65,8 +74,8 @@ class EdgeCentricFCSpheres(FunctionalConnectivityBase):
         allow_overlap: bool = False,
         agg_method: str = "mean",
         agg_method_params: Optional[Dict] = None,
-        cor_method: str = "covariance",
-        cor_method_params: Optional[Dict] = None,
+        conn_method: str = "correlation",
+        conn_method_params: Optional[Dict] = None,
         masks: Union[str, Dict, List[Union[Dict, str]], None] = None,
         name: Optional[str] = None,
     ) -> None:
@@ -78,8 +87,8 @@ class EdgeCentricFCSpheres(FunctionalConnectivityBase):
         super().__init__(
             agg_method=agg_method,
             agg_method_params=agg_method_params,
-            cor_method=cor_method,
-            cor_method_params=cor_method_params,
+            conn_method=conn_method,
+            conn_method_params=conn_method_params,
             masks=masks,
             name=name,
         )
@@ -107,11 +116,14 @@ class EdgeCentricFCSpheres(FunctionalConnectivityBase):
             to the user or stored in the storage by calling the store method
             with this as a parameter. The dictionary has the following keys:
 
-            * ``data`` : the actual computed values as a numpy.ndarray
-            * ``col_names`` : the column labels for the computed values as list
+            * ``aggregation`` : dictionary with the following keys:
+
+                - ``data`` : ROI values as ``numpy.ndarray``
+                - ``col_names`` : ROI labels as list of str
 
         """
-        sphere_aggregation = SphereAggregation(
+        # Perform aggregation
+        aggregation = SphereAggregation(
             coords=self.coords,
             radius=self.radius,
             allow_overlap=self.allow_overlap,
@@ -119,12 +131,13 @@ class EdgeCentricFCSpheres(FunctionalConnectivityBase):
             method_params=self.agg_method_params,
             masks=self.masks,
             on="BOLD",
-        )
-        bold_aggregated = sphere_aggregation.compute(
-            input, extra_input=extra_input
-        )
+        ).compute(input, extra_input=extra_input)
+        # Compute edgewise timeseries
         ets, edge_names = _ets(
-            bold_aggregated["data"], bold_aggregated["col_names"]
+            bold_ts=aggregation["aggregation"]["data"],
+            roi_names=aggregation["aggregation"]["col_names"],
         )
 
-        return {"data": ets, "col_names": edge_names}
+        return {
+            "aggregation": {"data": ets, "col_names": edge_names},
+        }

junifer/markers/functional_connectivity/functional_connectivity_base.py

@@ -7,60 +7,74 @@
 from abc import abstractmethod
 from typing import Any, ClassVar, Dict, List, Optional, Set, Union
 
-from nilearn.connectome import ConnectivityMeasure
-from sklearn.covariance import EmpiricalCovariance
+from sklearn.covariance import EmpiricalCovariance, LedoitWolf
 
+from ...external.nilearn import JuniferConnectivityMeasure
 from ...utils import raise_error
 from ..base import BaseMarker
 
 
+__all__ = ["FunctionalConnectivityBase"]
+
+
 class FunctionalConnectivityBase(BaseMarker):
     """Abstract base class for functional connectivity markers.
 
     Parameters
     ----------
     agg_method : str, optional
-        The method to perform aggregation using. Check valid options in
-        :func:`.get_aggfunc_by_name` (default "mean").
+        The method to perform aggregation using.
+        Check valid options in :func:`.get_aggfunc_by_name`
+        (default "mean").
     agg_method_params : dict, optional
-        Parameters to pass to the aggregation function. Check valid options in
-        :func:`.get_aggfunc_by_name` (default None).
-    cor_method : str, optional
-        The method to perform correlation using. Check valid options in
-        :class:`nilearn.connectome.ConnectivityMeasure`
-        (default "covariance").
-    cor_method_params : dict, optional
-        Parameters to pass to the correlation function. Check valid options in
-        :class:`nilearn.connectome.ConnectivityMeasure` (default None).
+        Parameters to pass to the aggregation function.
+        Check valid options in :func:`.get_aggfunc_by_name`
+        (default None).
+    conn_method : str, optional
+        The method to perform connectivity measure using.
+        Check valid options in :class:`.JuniferConnectivityMeasure`
+        (default "correlation").
+    conn_method_params : dict, optional
+        Parameters to pass to :class:`.JuniferConnectivityMeasure`.
+        If None, ``{"empirical": True}`` will be used, which would mean
+        :class:`sklearn.covariance.EmpiricalCovariance` is used to compute
+        covariance. If usage of :class:`sklearn.covariance.LedoitWolf` is
+        desired, ``{"empirical": False}`` should be passed
+        (default None).
     masks : str, dict or list of dict or str, optional
         The specification of the masks to apply to regions before extracting
         signals. Check :ref:`Using Masks <using_masks>` for more details.
         If None, will not apply any mask (default None).
     name : str, optional
-        The name of the marker. If None, will use the class name (default
-        None).
+        The name of the marker. If None, will use ``BOLD_<class_name>``
+        (default None).
 
     """
 
     _DEPENDENCIES: ClassVar[Set[str]] = {"nilearn", "scikit-learn"}
 
+    _MARKER_INOUT_MAPPINGS: ClassVar[Dict[str, Dict[str, str]]] = {
+        "BOLD": {
+            "functional_connectivity": "matrix",
+        },
+    }
+
     def __init__(
         self,
         agg_method: str = "mean",
         agg_method_params: Optional[Dict] = None,
-        cor_method: str = "covariance",
-        cor_method_params: Optional[Dict] = None,
+        conn_method: str = "correlation",
+        conn_method_params: Optional[Dict] = None,
         masks: Union[str, Dict, List[Union[Dict, str]], None] = None,
         name: Optional[str] = None,
     ) -> None:
         self.agg_method = agg_method
         self.agg_method_params = agg_method_params
-        self.cor_method = cor_method
-        self.cor_method_params = cor_method_params or {}
-
-        # default to nilearn behavior
-        self.cor_method_params["empirical"] = self.cor_method_params.get(
-            "empirical", False
+        self.conn_method = conn_method
+        self.conn_method_params = conn_method_params or {}
+        # Reverse of nilearn behavior
+        self.conn_method_params["empirical"] = self.conn_method_params.get(
+            "empirical", True
         )
         self.masks = masks
         super().__init__(on="BOLD", name=name)
@@ -77,33 +91,6 @@ class FunctionalConnectivityBase(BaseMarker):
             klass=NotImplementedError,
         )
 
-    def get_valid_inputs(self) -> List[str]:
-        """Get valid data types for input.
-
-        Returns
-        -------
-        list of str
-            The list of data types that can be used as input for this marker.
-
-        """
-        return ["BOLD"]
-
-    def get_output_type(self, input_type: str) -> str:
-        """Get output type.
-
-        Parameters
-        ----------
-        input_type : str
-            The data type input to the marker.
-
-        Returns
-        -------
-        str
-            The storage type output by the marker.
-
-        """
-        return "matrix"
-
     def compute(
         self,
         input: Dict[str, Any],
@@ -125,30 +112,44 @@ class FunctionalConnectivityBase(BaseMarker):
         Returns
         -------
         dict
-            The computed result as dictionary. The following keys will be
-            included in the dictionary:
+            The computed result as dictionary. This will be either returned
+            to the user or stored in the storage by calling the store method
+            with this as a parameter. The dictionary has the following keys:
+
+            * ``functional_connectivity`` : dictionary with the following keys:
 
-            * ``data`` : functional connectivity matrix as a ``numpy.ndarray``.
-            * ``row_names`` : row names as a list
-            * ``col_names`` : column names as a list
-            * ``matrix_kind`` : the kind of matrix (tril, triu or full)
+              - ``data`` : functional connectivity matrix as ``numpy.ndarray``
+              - ``row_names`` : ROI labels as list of str
+              - ``col_names`` : ROI labels as list of str
+              - ``matrix_kind`` : the kind of matrix (tril, triu or full)
 
         """
         # Perform necessary aggregation
         aggregation = self.aggregate(input, extra_input=extra_input)
-        # Compute correlation
-        if self.cor_method_params["empirical"]:
-            connectivity = ConnectivityMeasure(
-                cov_estimator=EmpiricalCovariance(),  # type: ignore
-                kind=self.cor_method,
-            )
+        # Set covariance estimator
+        if self.conn_method_params["empirical"]:
+            cov_estimator = EmpiricalCovariance(store_precision=False)
         else:
-            connectivity = ConnectivityMeasure(kind=self.cor_method)
+            cov_estimator = LedoitWolf(store_precision=False)
+        # Compute correlation
+        connectivity = JuniferConnectivityMeasure(
+            cov_estimator=cov_estimator,
+            kind=self.conn_method,
+            **{
+                k: v
+                for k, v in self.conn_method_params.items()
+                if k != "empirical"
+            },
+        )
         # Create dictionary for output
-        out = {}
-        out["data"] = connectivity.fit_transform([aggregation["data"]])[0]
-        # Create column names
-        out["row_names"] = aggregation["col_names"]
-        out["col_names"] = aggregation["col_names"]
-        out["matrix_kind"] = "tril"
-        return out
+        return {
+            "functional_connectivity": {
+                "data": connectivity.fit_transform(
+                    [aggregation["aggregation"]["data"]]
+                )[0],
+                # Create column names
+                "row_names": aggregation["aggregation"]["col_names"],
+                "col_names": aggregation["aggregation"]["col_names"],
+                "matrix_kind": "tril",
+            },
+        }

junifer/markers/functional_connectivity/functional_connectivity_parcels.py

@@ -12,6 +12,9 @@ from ..parcel_aggregation import ParcelAggregation
 from .functional_connectivity_base import FunctionalConnectivityBase
 
 
+__all__ = ["FunctionalConnectivityParcels"]
+
+
 @register_marker
 class FunctionalConnectivityParcels(FunctionalConnectivityBase):
     """Class for functional connectivity using parcellations.
@@ -19,28 +22,34 @@ class FunctionalConnectivityParcels(FunctionalConnectivityBase):
     Parameters
     ----------
     parcellation : str or list of str
-        The name(s) of the parcellation(s). Check valid options by calling
-        :func:`.list_parcellations`.
+        The name(s) of the parcellation(s) to use.
+        See :func:`.list_parcellations` for options.
     agg_method : str, optional
-        The method to perform aggregation using. Check valid options in
-        :func:`.get_aggfunc_by_name` (default "mean").
+        The method to perform aggregation using.
+        See :func:`.get_aggfunc_by_name` for options
+        (default "mean").
     agg_method_params : dict, optional
-        Parameters to pass to the aggregation function. Check valid options in
-        :func:`.get_aggfunc_by_name` (default None).
-    cor_method : str, optional
-        The method to perform correlation using. Check valid options in
-        :class:`nilearn.connectome.ConnectivityMeasure`
-        (default "covariance").
-    cor_method_params : dict, optional
-        Parameters to pass to the correlation function. Check valid options in
-        :class:`nilearn.connectome.ConnectivityMeasure` (default None).
+        Parameters to pass to the aggregation function.
+        See :func:`.get_aggfunc_by_name` for options
+        (default None).
+    conn_method : str, optional
+        The method to perform connectivity measure using.
+        See :class:`.JuniferConnectivityMeasure` for options
+        (default "correlation").
+    conn_method_params : dict, optional
+        Parameters to pass to :class:`.JuniferConnectivityMeasure`.
+        If None, ``{"empirical": True}`` will be used, which would mean
+        :class:`sklearn.covariance.EmpiricalCovariance` is used to compute
+        covariance. If usage of :class:`sklearn.covariance.LedoitWolf` is
+        desired, ``{"empirical": False}`` should be passed
+        (default None).
     masks : str, dict or list of dict or str, optional
         The specification of the masks to apply to regions before extracting
         signals. Check :ref:`Using Masks <using_masks>` for more details.
         If None, will not apply any mask (default None).
     name : str, optional
-        The name of the marker. If None, will use the class name (default
-        None).
+        The name of the marker. If None, will use
+        ``BOLD_FunctionalConnectivityParcels`` (default None).
 
     """
 
@@ -49,8 +58,8 @@ class FunctionalConnectivityParcels(FunctionalConnectivityBase):
         parcellation: Union[str, List[str]],
         agg_method: str = "mean",
         agg_method_params: Optional[Dict] = None,
-        cor_method: str = "covariance",
-        cor_method_params: Optional[Dict] = None,
+        conn_method: str = "correlation",
+        conn_method_params: Optional[Dict] = None,
         masks: Union[str, Dict, List[Union[Dict, str]], None] = None,
         name: Optional[str] = None,
     ) -> None:
@@ -58,8 +67,8 @@ class FunctionalConnectivityParcels(FunctionalConnectivityBase):
         super().__init__(
             agg_method=agg_method,
             agg_method_params=agg_method_params,
-            cor_method=cor_method,
-            cor_method_params=cor_method_params,
+            conn_method=conn_method,
+            conn_method_params=conn_method_params,
             masks=masks,
             name=name,
         )
@@ -87,16 +96,16 @@ class FunctionalConnectivityParcels(FunctionalConnectivityBase):
             to the user or stored in the storage by calling the store method
             with this as a parameter. The dictionary has the following keys:
 
-            * ``data`` : the actual computed values as a numpy.ndarray
-            * ``col_names`` : the column labels for the computed values as list
+            * ``aggregation`` : dictionary with the following keys:
+
+                - ``data`` : ROI values as ``numpy.ndarray``
+                - ``col_names`` : ROI labels as list of str
 
         """
-        parcel_aggregation = ParcelAggregation(
+        return ParcelAggregation(
             parcellation=self.parcellation,
             method=self.agg_method,
             method_params=self.agg_method_params,
             masks=self.masks,
             on="BOLD",
-        )
-        # Return the 2D timeseries after parcel aggregation
-        return parcel_aggregation.compute(input, extra_input=extra_input)
+        ).compute(input=input, extra_input=extra_input)