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

junifer/preprocess/smoothing/smoothing.py

@@ -0,0 +1,174 @@
+"""Provide class for smoothing."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import Any, ClassVar, Dict, List, Optional, Tuple, Type, Union
+
+from ...api.decorators import register_preprocessor
+from ...utils import logger, raise_error
+from ..base import BasePreprocessor
+from ._afni_smoothing import AFNISmoothing
+from ._fsl_smoothing import FSLSmoothing
+from ._nilearn_smoothing import NilearnSmoothing
+
+
+__all__ = ["Smoothing"]
+
+
+@register_preprocessor
+class Smoothing(BasePreprocessor):
+    """Class for smoothing.
+
+    Parameters
+    ----------
+    using : {"nilearn", "afni", "fsl"}
+        Implementation to use for smoothing:
+
+        * "nilearn" : Use :func:`nilearn.image.smooth_img`
+        * "afni" : Use AFNI's ``3dBlurToFWHM``
+        * "fsl" : Use FSL SUSAN's ``susan``
+
+    on : {"T1w", "T2w", "BOLD"} or list of the options
+        The data type to apply smoothing to.
+    smoothing_params : dict, optional
+        Extra parameters for smoothing as a dictionary (default None).
+        If ``using="nilearn"``, then the valid keys are:
+
+        * ``fmhw`` : scalar, ``numpy.ndarray``, tuple or list of scalar, \
+                     "fast" or None
+            Smoothing strength, as a full-width at half maximum, in
+            millimeters:
+
+            - If nonzero scalar, width is identical in all 3 directions.
+            - If ``numpy.ndarray``, tuple, or list, it must have 3 elements,
+              giving the FWHM along each axis. If any of the elements is 0 or
+              None, smoothing is not performed along that axis.
+            - If ``"fast"``, a fast smoothing will be performed with a filter
+              ``[0.2, 1, 0.2]`` in each direction and a normalisation to
+              preserve the local average value.
+            - If None, no filtering is performed (useful when just removal of
+              non-finite values is needed).
+
+        else if ``using="afni"``, then the valid keys are:
+
+        * ``fwhm`` : int or float
+            Smooth until the value. AFNI estimates the smoothing and then
+            applies smoothing to reach ``fwhm``.
+
+        else if ``using="fsl"``, then the valid keys are:
+
+        * ``brightness_threshold`` : float
+            Threshold to discriminate between noise and the underlying image.
+            The value should be set greater than the noise level and less than
+            the contrast of the underlying image.
+        * ``fwhm`` : float
+            Spatial extent of smoothing.
+
+    """
+
+    _CONDITIONAL_DEPENDENCIES: ClassVar[List[Dict[str, Union[str, Type]]]] = [
+        {
+            "using": "nilearn",
+            "depends_on": NilearnSmoothing,
+        },
+        {
+            "using": "afni",
+            "depends_on": AFNISmoothing,
+        },
+        {
+            "using": "fsl",
+            "depends_on": FSLSmoothing,
+        },
+    ]
+
+    def __init__(
+        self,
+        using: str,
+        on: Union[List[str], str],
+        smoothing_params: Optional[Dict] = None,
+    ) -> None:
+        """Initialize the class."""
+        # Validate `using` parameter
+        valid_using = [dep["using"] for dep in self._CONDITIONAL_DEPENDENCIES]
+        if using not in valid_using:
+            raise_error(
+                f"Invalid value for `using`, should be one of: {valid_using}"
+            )
+        self.using = using
+        self.smoothing_params = (
+            smoothing_params if smoothing_params is not None else {}
+        )
+        super().__init__(on=on)
+
+    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
+            preprocessor.
+
+        """
+        return ["T1w", "T2w", "BOLD"]
+
+    def get_output_type(self, input_type: str) -> str:
+        """Get output type.
+
+        Parameters
+        ----------
+        input_type : str
+            The data type input to the preprocessor.
+
+        Returns
+        -------
+        str
+            The data type output by the preprocessor.
+
+        """
+        # Does not add any new keys
+        return input_type
+
+    def preprocess(
+        self,
+        input: Dict[str, Any],
+        extra_input: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[Dict[str, Any], Optional[Dict[str, Dict[str, Any]]]]:
+        """Preprocess.
+
+        Parameters
+        ----------
+        input : dict
+            The input from the Junifer Data object.
+        extra_input : dict, optional
+            The other fields in the Junifer Data object.
+
+        Returns
+        -------
+        dict
+            The computed result as dictionary.
+        None
+            Extra "helper" data types as dictionary to add to the Junifer Data
+            object.
+
+        """
+        logger.debug("Smoothing")
+
+        # Conditional preprocessor
+        if self.using == "nilearn":
+            preprocessor = NilearnSmoothing()
+        elif self.using == "afni":
+            preprocessor = AFNISmoothing()
+        elif self.using == "fsl":
+            preprocessor = FSLSmoothing()
+        # Smooth
+        output = preprocessor.preprocess(  # type: ignore
+            data=input["data"],
+            **self.smoothing_params,
+        )
+
+        # Modify target data
+        input["data"] = output
+
+        return input, None

junifer/preprocess/smoothing/tests/test_smoothing.py

@@ -0,0 +1,94 @@
+"""Provide tests for Smoothing."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+
+import pytest
+
+from junifer.datareader import DefaultDataReader
+from junifer.pipeline.utils import _check_afni, _check_fsl
+from junifer.preprocess import Smoothing
+from junifer.testing.datagrabbers import SPMAuditoryTestingDataGrabber
+
+
+@pytest.mark.parametrize(
+    "data_type",
+    ["T1w", "BOLD"],
+)
+def test_Smoothing_nilearn(data_type: str) -> None:
+    """Test Smoothing using nilearn.
+
+    Parameters
+    ----------
+    data_type : str
+        The parametrized data type.
+
+    """
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Read data
+        element_data = DefaultDataReader().fit_transform(dg["sub001"])
+        # Preprocess data
+        output = Smoothing(
+            using="nilearn",
+            on=data_type,
+            smoothing_params={"fwhm": "fast"},
+        ).fit_transform(element_data)
+
+        assert isinstance(output, dict)
+
+
+@pytest.mark.parametrize(
+    "data_type",
+    ["T1w", "BOLD"],
+)
+@pytest.mark.skipif(
+    _check_afni() is False, reason="requires AFNI to be in PATH"
+)
+def test_Smoothing_afni(data_type: str) -> None:
+    """Test Smoothing using AFNI.
+
+    Parameters
+    ----------
+    data_type : str
+        The parametrized data type.
+
+    """
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Read data
+        element_data = DefaultDataReader().fit_transform(dg["sub001"])
+        # Preprocess data
+        output = Smoothing(
+            using="afni",
+            on=data_type,
+            smoothing_params={"fwhm": 3},
+        ).fit_transform(element_data)
+
+        assert isinstance(output, dict)
+
+
+@pytest.mark.parametrize(
+    "data_type",
+    ["T1w", "BOLD"],
+)
+@pytest.mark.skipif(_check_fsl() is False, reason="requires FSL to be in PATH")
+def test_Smoothing_fsl(data_type: str) -> None:
+    """Test Smoothing using FSL.
+
+    Parameters
+    ----------
+    data_type : str
+        The parametrized data type.
+
+    """
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Read data
+        element_data = DefaultDataReader().fit_transform(dg["sub001"])
+        # Preprocess data
+        output = Smoothing(
+            using="fsl",
+            on=data_type,
+            smoothing_params={"brightness_threshold": 10.0, "fwhm": 3.0},
+        ).fit_transform(element_data)
+
+        assert isinstance(output, dict)

junifer/preprocess/warping/__init__.py

@@ -4,3 +4,6 @@
 # License: AGPL
 
 from .space_warper import SpaceWarper
+
+
+__all__ = ["SpaceWarper"]

junifer/preprocess/warping/_ants_warper.py

@@ -20,6 +20,9 @@ from ...pipeline import WorkDirManager
 from ...utils import logger, run_ext_cmd
 
 
+__all__ = ["ANTsWarper"]
+
+
 class ANTsWarper:
     """Class for space warping via ANTs antsApplyTransforms.
 

junifer/preprocess/warping/_fsl_warper.py

@@ -19,6 +19,9 @@ from ...pipeline import WorkDirManager
 from ...utils import logger, run_ext_cmd
 
 
+__all__ = ["FSLWarper"]
+
+
 class FSLWarper:
     """Class for space warping via FSL FLIRT.
 

junifer/stats.py

@@ -1,4 +1,4 @@
-"""Provide functions for statistics."""
+"""Statistical functions and helpers."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Synchon Mandal <s.mandal@fz-juelich.de>
@@ -13,6 +13,9 @@ from scipy.stats.mstats import winsorize
 from .utils import logger, raise_error
 
 
+__all__ = ["get_aggfunc_by_name", "count", "winsorized_mean", "select"]
+
+
 def get_aggfunc_by_name(
     name: str, func_params: Optional[Dict[str, Any]] = None
 ) -> Callable:

junifer/storage/__init__.py

@@ -1,4 +1,4 @@
-"""Provide imports for storage sub-package."""
+"""Storages for storing extracted features."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Synchon Mandal <s.mandal@fz-juelich.de>
@@ -8,3 +8,11 @@ from .base import BaseFeatureStorage
 from .pandas_base import PandasBaseFeatureStorage
 from .sqlite import SQLiteFeatureStorage
 from .hdf5 import HDF5FeatureStorage
+
+
+__all__ = [
+    "BaseFeatureStorage",
+    "PandasBaseFeatureStorage",
+    "SQLiteFeatureStorage",
+    "HDF5FeatureStorage",
+]

junifer/storage/base.py

@@ -15,6 +15,9 @@ from ..utils import raise_error
 from .utils import process_meta
 
 
+__all__ = ["BaseFeatureStorage"]
+
+
 class BaseFeatureStorage(ABC):
     """Abstract base class for feature storage.
 
@@ -189,7 +192,7 @@ class BaseFeatureStorage(ABC):
 
         Parameters
         ----------
-        kind : {"matrix", "timeseries", "vector"}
+        kind : {"matrix", "timeseries", "vector", "scalar_table"}
             The storage kind.
         **kwargs
             The keyword arguments.
@@ -218,6 +221,10 @@ class BaseFeatureStorage(ABC):
             )
         elif kind == "vector":
             self.store_vector(meta_md5=meta_md5, element=t_element, **kwargs)
+        elif kind == "scalar_table":
+            self.store_scalar_table(
+                meta_md5=meta_md5, element=t_element, **kwargs
+            )
 
     def store_matrix(
         self,
@@ -313,6 +320,38 @@ class BaseFeatureStorage(ABC):
             klass=NotImplementedError,
         )
 
+    def store_scalar_table(
+        self,
+        meta_md5: str,
+        element: Dict,
+        data: np.ndarray,
+        col_names: Optional[Iterable[str]] = None,
+        row_names: Optional[Iterable[str]] = None,
+        row_header_col_name: Optional[str] = "feature",
+    ) -> None:
+        """Store table with scalar values.
+
+        Parameters
+        ----------
+        meta_md5 : str
+            The metadata MD5 hash.
+        element : dict
+            The element as a dictionary.
+        data : numpy.ndarray
+            The timeseries data to store.
+        col_names : list or tuple of str, optional
+            The column labels (default None).
+        row_names : str, optional
+            The row labels (default None).
+        row_header_col_name : str, optional
+            The column name for the row header column (default "feature").
+
+        """
+        raise_error(
+            msg="Concrete classes need to implement store_scalar_table().",
+            klass=NotImplementedError,
+        )
+
     @abstractmethod
     def collect(self) -> None:
         """Collect data."""

junifer/storage/hdf5.py

@@ -26,6 +26,9 @@ from .base import BaseFeatureStorage
 from .utils import element_to_prefix, matrix_to_vector, store_matrix_checks
 
 
+__all__ = ["HDF5FeatureStorage"]
+
+
 def _create_chunk(
     chunk_data: List[np.ndarray],
     kind: str,
@@ -56,7 +59,8 @@ def _create_chunk(
     Raises
     ------
     ValueError
-        If `kind` is not one of ['vector', 'matrix', 'timeseries'].
+        If `kind` is not one of ['vector', 'matrix', 'timeseries',
+        'scalar_table'].
 
     """
     if kind in ["vector", "matrix"]:
@@ -77,7 +81,7 @@ def _create_chunk(
             chunk_size=tuple(array_chunk_size),
             n_chunk=i_chunk,
         )
-    elif kind == "timeseries":
+    elif kind in ["timeseries", "scalar_table"]:
         out = ChunkedList(
             data=chunk_data,
             size=element_count,
@@ -86,7 +90,8 @@ def _create_chunk(
     else:
         raise_error(
             f"Invalid kind: {kind}. "
-            "Must be one of ['vector', 'matrix', 'timeseries']."
+            "Must be one of ['vector', 'matrix', 'timeseries',"
+            "'scalar_table']."
         )
     return out
 
@@ -146,7 +151,7 @@ class HDF5FeatureStorage(BaseFeatureStorage):
             uri.parent.mkdir(parents=True, exist_ok=True)
 
         # Available storage kinds
-        storage_types = ["vector", "timeseries", "matrix"]
+        storage_types = ["vector", "timeseries", "matrix", "scalar_table"]
 
         super().__init__(
             uri=uri,
@@ -169,7 +174,7 @@ class HDF5FeatureStorage(BaseFeatureStorage):
             storage.
 
         """
-        return ["matrix", "vector", "timeseries"]
+        return ["matrix", "vector", "timeseries", "scalar_table"]
 
     def _fetch_correct_uri_for_io(self, element: Optional[Dict]) -> str:
         """Return proper URI for I/O based on `element`.
@@ -508,6 +513,26 @@ class HDF5FeatureStorage(BaseFeatureStorage):
             columns = hdf_data["column_headers"]
             # Convert data from 3D to 2D
             reshaped_data = np.concatenate(all_data, axis=0)
+        elif hdf_data["kind"] == "scalar_table":
+            # Create dictionary for aggregating index data
+            element_idx = defaultdict(list)
+            all_data = []
+            for idx, element in enumerate(hdf_data["element"]):
+                # Get row count for the element
+                t_data = hdf_data["data"][idx]
+                all_data.append(t_data)
+                n_rows = len(hdf_data["row_headers"])
+                # Set rows for the index
+                for key, val in element.items():
+                    element_idx[key].extend([val] * n_rows)
+                # Add extra column for row header column name
+                element_idx[hdf_data["row_header_column_name"]].extend(
+                    hdf_data["row_headers"]
+                )
+            # Set column headers for dataframe
+            columns = hdf_data["column_headers"]
+            # Convert data from 3D to 2D
+            reshaped_data = np.concatenate(all_data, axis=0)
 
         # Create dataframe for index
         idx_df = pd.DataFrame(data=element_idx)  # type: ignore
@@ -643,7 +668,7 @@ class HDF5FeatureStorage(BaseFeatureStorage):
 
         Parameters
         ----------
-        kind : {"matrix", "vector", "timeseries"}
+        kind : {"matrix", "vector", "timeseries", "scalar_table"}
             The storage kind.
         meta_md5 : str
             The metadata MD5 hash.
@@ -739,8 +764,8 @@ class HDF5FeatureStorage(BaseFeatureStorage):
             )
 
             t_data = stored_data["data"]
-            if kind == "timeseries":
-                t_data.append(data)
+            if kind in ["timeseries", "scalar_table"]:
+                t_data += data
             else:
                 t_data = np.concatenate((t_data, data), axis=-1)
             # Existing entry; append to existing
@@ -921,6 +946,43 @@ class HDF5FeatureStorage(BaseFeatureStorage):
             row_header_column_name="timepoint",
         )
 
+    def store_scalar_table(
+        self,
+        meta_md5: str,
+        element: Dict,
+        data: np.ndarray,
+        col_names: Optional[Iterable[str]] = None,
+        row_names: Optional[Iterable[str]] = None,
+        row_header_col_name: Optional[str] = "feature",
+    ) -> None:
+        """Store table with scalar values.
+
+        Parameters
+        ----------
+        meta_md5 : str
+            The metadata MD5 hash.
+        element : dict
+            The element as a dictionary.
+        data : numpy.ndarray
+            The scalar table data to store.
+        col_names : list or tuple of str, optional
+            The column labels (default None).
+        row_names : str, optional
+            The row labels (default None).
+        row_header_col_name : str, optional
+            The column name for the row header column (default "feature").
+
+        """
+        self._store_data(
+            kind="scalar_table",
+            meta_md5=meta_md5,
+            element=[element],  # convert to list
+            data=[data],  # convert to list
+            column_headers=col_names,
+            row_headers=row_names,
+            row_header_column_name=row_header_col_name,
+        )
+
     def collect(self) -> None:
         """Implement data collection.
 
@@ -1029,7 +1091,7 @@ class HDF5FeatureStorage(BaseFeatureStorage):
                     kind = static_data["kind"]
 
                 # Append the "dynamic" data
-                if kind == "timeseries":
+                if kind in ["timeseries", "scalar_table"]:
                     chunk_data.extend(t_data["data"])
                 else:
                     chunk_data.append(t_data["data"])

junifer/storage/pandas_base.py

@@ -15,6 +15,9 @@ from ..utils import raise_error
 from .base import BaseFeatureStorage
 
 
+__all__ = ["PandasBaseFeatureStorage"]
+
+
 class PandasBaseFeatureStorage(BaseFeatureStorage):
     """Abstract base class for feature storage via pandas.
 

junifer/storage/sqlite.py

@@ -25,6 +25,9 @@ if TYPE_CHECKING:
     from sqlalchemy.engine import Engine
 
 
+__all__ = ["SQLiteFeatureStorage"]
+
+
 @register_storage
 class SQLiteFeatureStorage(PandasBaseFeatureStorage):
     """Concrete implementation for feature storage via SQLite.