Improvements to aydin docstrings

aydin/features/base.py

@@ -1,8 +1,11 @@
 import os
 from abc import ABC, abstractmethod
 from os.path import join
+from typing import Optional, Tuple, List
+
 import jsonpickle
 import numpy
+from numpy import ndarray
 
 from aydin.util.misc.json import encode_indent
 from aydin.util.log.log import lprint, lsection
@@ -30,7 +33,7 @@ def __init__(self):
 
     def save(self, path: str):
         """
-        Saves a 'all-batteries-inlcuded' feature generator at a given path (folder)
+        Saves a 'all-batteries-included' feature generator at a given path (folder)
 
         Parameters
         ----------
@@ -94,15 +97,15 @@ def get_receptive_field_radius(self):
     def compute(
         self,
         image,
-        exclude_center_feature=False,
-        exclude_center_value=False,
-        features=None,
-        feature_last_dim=True,
-        passthrough_channels=None,
-        num_reserved_features=0,
-        excluded_voxels=None,
-        spatial_feature_offset=None,
-        spatial_feature_scale=None,
+        exclude_center_feature: bool = False,
+        exclude_center_value: bool = False,
+        features: ndarray = None,
+        feature_last_dim: bool = True,
+        passthrough_channels: Optional[Tuple[bool]] = None,
+        num_reserved_features: int = 0,
+        excluded_voxels: Optional[List[Tuple[int]]] = None,
+        spatial_feature_offset: Optional[Tuple[float, ...]] = None,
+        spatial_feature_scale: Optional[Tuple[float, ...]] = None,
     ):
         """
         Computes the features given an image. If the input image is of shape (d,h,w),
@@ -112,15 +115,44 @@ def compute(
         ----------
         image : numpy.ndarray
             image for which features are computed
+
         exclude_center_feature : bool
+            If true, features that use the image
+            patch's center pixel are entirely excluded from teh set of computed
+            features.
+
         exclude_center_value : bool
-        features
+            If true, the center pixel is never used
+            to compute any feature, different feature generation algorithms can
+            take different approaches to acheive that.
+
+        features : ndarray
+            If None the feature array is allocated internally,
+            if not None the provided array is used to store the features.
+
         feature_last_dim : bool
-        passthrough_channels
+            If True the last dimension of the feature
+            array is the feature dimension, if False then it is the first
+            dimension.
+
+        passthrough_channels : Optional[Tuple[bool]]
+            Optional tuple of booleans that specify which channels are 'pass-through'
+            channels, i.e. channels that are not featurised and directly used as features.
+
         num_reserved_features : int
-        excluded_voxels
-        spatial_feature_offset
-        spatial_feature_scale
+            Number of features to be left as blank,
+            useful when adding features separately.
+
+        excluded_voxels : Optional[List[Tuple[int]]]
+            List of pixel coordinates -- expressed as tuple of ints relative to the central pixel --
+            that will be excluded from any computed features. This is used for implementing
+            'extended blind-spot' N2S denoising approaches.
+
+        spatial_feature_offset: Optional[Tuple[float, ...]]
+            Offset vector to be applied (added) to the spatial features (if used).
+
+        spatial_feature_scale: Optional[Tuple[float, ...]]
+            Scale vector to be applied (multiplied) to the spatial features (if used).
 
         Returns
         -------

aydin/features/extensible_features.py

@@ -1,4 +1,7 @@
+from typing import Optional, Tuple, List
+
 import numpy
+from numpy import ndarray
 
 from aydin.features.base import FeatureGeneratorBase
 from aydin.features.groups.base import FeatureGroupBase
@@ -8,6 +11,8 @@
 class ExtensibleFeatureGenerator(FeatureGeneratorBase):
     """
     Extensible Feature Generator class
+
+
     """
 
     def __init__(self):
@@ -82,15 +87,15 @@ def get_receptive_field_radius(self) -> int:
     def compute(
         self,
         image,
-        exclude_center_feature=False,
-        exclude_center_value=False,
-        features=None,
-        feature_last_dim=True,
-        passthrough_channels=None,
-        num_reserved_features=0,
-        excluded_voxels=None,
-        spatial_feature_offset=None,
-        spatial_feature_scale=None,
+        exclude_center_feature: bool = False,
+        exclude_center_value: bool = False,
+        features: ndarray = None,
+        feature_last_dim: bool = True,
+        passthrough_channels: Optional[Tuple[bool]] = None,
+        num_reserved_features: int = 0,
+        excluded_voxels: Optional[List[Tuple[int]]] = None,
+        spatial_feature_offset: Optional[Tuple[float, ...]] = None,
+        spatial_feature_scale: Optional[Tuple[float, ...]] = None,
     ):
         """
         Computes the features given an image. If the input image is of shape (d,h,w),
@@ -99,16 +104,45 @@ def compute(
         Parameters
         ----------
         image : numpy.ndarray
-        image for which features are computed
+            image for which features are computed
+
         exclude_center_feature : bool
+            If true, features that use the image
+            patch's center pixel are entirely excluded from teh set of computed
+            features.
+
         exclude_center_value : bool
-        features
+            If true, the center pixel is never used
+            to compute any feature, different feature generation algorithms can
+            take different approaches to acheive that.
+
+        features : ndarray
+            If None the feature array is allocated internally,
+            if not None the provided array is used to store the features.
+
         feature_last_dim : bool
-        passthrough_channels
+            If True the last dimension of the feature
+            array is the feature dimension, if False then it is the first
+            dimension.
+
+        passthrough_channels : Optional[Tuple[bool]]
+            Optional tuple of booleans that specify which channels are 'pass-through'
+            channels, i.e. channels that are not featurised and directly used as features.
+
         num_reserved_features : int
-        excluded_voxels
-        spatial_feature_offset
-        spatial_feature_scale
+            Number of features to be left as blank,
+            useful when adding features separately.
+
+        excluded_voxels : Optional[List[Tuple[int]]]
+            List of pixel coordinates -- expressed as tuple of ints relative to the central pixel --
+            that will be excluded from any computed features. This is used for implementing
+            'extended blind-spot' N2S denoising approaches.
+
+        spatial_feature_offset: Optional[Tuple[float, ...]]
+            Offset vector to be applied (added) to the spatial features (if used).
+
+        spatial_feature_scale: Optional[Tuple[float, ...]]
+            Scale vector to be applied (multiplied) to the spatial features (if used).
 
         Returns
         -------

aydin/features/groups/convolutional.py

@@ -2,6 +2,7 @@
 
 import numpy
 from numpy import ndarray
+from numpy.typing import ArrayLike
 from scipy.ndimage import convolve, gaussian_filter
 
 from aydin.features.groups.base import FeatureGroupBase
@@ -11,9 +12,19 @@
 class ConvolutionalFeatures(FeatureGroupBase):
     """
     Convolutional Feature Group class
+
+    Generates convolutional features given a set of kernels.
     """
 
-    def __init__(self, kernels: Optional[Sequence[ndarray]]):
+    def __init__(self, kernels: Optional[Sequence[ArrayLike]]):
+        """
+        Constructor that configures these features.
+
+        Parameters
+        ----------
+        kernels : Optional[Sequence[ArrayLike]]
+            Sequence of kernels to use to compiute features.
+        """
         super().__init__()
         self.kernels = kernels if kernels is None else list(kernels)
         self.image = None

aydin/features/groups/dct.py

@@ -8,9 +8,26 @@
 class DCTFeatures(ConvolutionalFeatures):
     """
     DCT Feature Group class
+
+    Generates Discrete Cosine Transform (DCT) features.
     """
 
     def __init__(self, size: int, max_freq: float = 0.75, power: float = 0.5):
+        """
+        Constructor that configures these features.
+
+        Parameters
+        ----------
+        size : int
+            Size of the DCT filters
+        max_freq : float
+            Maximum frequency of DCT filters
+            (advanced)
+        power : float
+            Filters can be exponentiated to a given power to change behaviour.
+            (advanced)
+
+        """
         super().__init__(kernels=None)
         self.size = size
         self.max_freq = max_freq

aydin/features/groups/extract_kernels.py

@@ -1,23 +1,52 @@
 from functools import reduce
 from math import sqrt
 from operator import mul
-from typing import Tuple, Union, Optional
+from typing import Tuple, Union, Optional, Sequence
 import matplotlib.pyplot as plt
 import numpy as np
+from numpy.typing import ArrayLike
 from sklearn.cluster import MiniBatchKMeans
 from sklearn.feature_extraction.image import _extract_patches
 
 from aydin.util.log.log import lprint, lsection
 
 
 def extract_kernels(
-    image,
+    image: ArrayLike,
     size: int = 7,
     num_kernels: int = None,
     num_patches: int = 1e5,
     num_iterations: int = 100,
     display: bool = False,
-):
+) -> Sequence[ArrayLike]:
+    """
+    Extracts representative kernels from a given image using MiniBatchKMeans.
+
+    Parameters
+    ----------
+    image: ArrayLike
+        Image to compute kernels for.
+
+    size: int
+        Size of the kernels
+
+    num_kernels: int
+        Number of kernels to extract
+
+    num_patches: int
+        Number of image patches to consider.
+
+    num_iterations: int
+        Number of iterations.
+
+    display: bool
+        When True a napari window opens up to display the kernels.
+
+    Returns
+    -------
+    Sequence of kernels.
+
+    """
     if num_kernels is None:
         num_kernels = size ** image.ndim
 

aydin/features/groups/learned_conv.py

@@ -7,6 +7,9 @@
 class LearnedConvolutionalFeatures(ConvolutionalFeatures):
     """
     Learned Convolutions Feature Group class
+
+    Generates features by learning convolutional filters on the basis of the
+    image itself.
     """
 
     def __init__(
@@ -15,6 +18,18 @@ def __init__(
         num_kernels: Optional[int],
         num_patches: Union[int, float] = 1e5,
     ):
+        """
+        Constructor that configures these features.
+
+        Parameters
+        ----------
+        size : int
+            Filter size
+        num_kernels : Optional[int]
+            Number of kernels (filters)
+        num_patches : Union[int, float]
+            Number of patches used for learning the kernels.
+        """
         super().__init__(kernels=None)
         self.size = size
         self.num_kernels = num_kernels

aydin/features/groups/median.py

@@ -10,9 +10,19 @@
 class MedianFeatures(FeatureGroupBase):
     """
     Median Feature Group class
+
+    Generates features by applying median filters of increasing sizes (radii).
     """
 
     def __init__(self, radii: Sequence[int]):
+        """
+        Constructor that configures these features.
+
+        Parameters
+        ----------
+        radii : Sequence[int]
+            Sequence of radii to be used for the median filters.
+        """
         super().__init__()
         self.radii = tuple(radii)
         self.image = None

aydin/features/groups/random.py

@@ -10,9 +10,24 @@
 class RandomFeatures(ConvolutionalFeatures):
     """
     Random Feature Group class
+
+    Generates features by convolving the image with a random set of filters.
     """
 
     def __init__(self, size: int, num_features: Optional[int] = None):
+        """
+        Constructor that configures these features.
+
+        Parameters
+        ----------
+
+        size : int
+            Size of the kernels used.
+
+        num_features : Optional[int]
+            Number of features to generate. If None the maximum number of features
+            that may be linearly independent is used.
+        """
         super().__init__(kernels=None)
         self.size = size
         self._num_features = num_features