Docstrings (#109)

CONTRIBUTING.md

@@ -20,6 +20,9 @@ To run tests with coverage locally:
 `pytest tests --color=yes --cov --cov-report=term-missing`
 This will also be run automatically when a PR is made to master and a codecov report will be generated telling you if your PR increased or decreased coverage.
 
+## Doc Generation
+Docstrings are generated using github action. but you can generate them using
+`sphinx-build -M html docs/source/ docs/Cbuild/`
 
 ## Branching and PRs
 - Users that have been added to the CellMap organization and the DaCapo project should be able to develop directly into the CellMap fork of DaCapo. Other users will need to create a fork.

dacapo/__init__.py

@@ -1,6 +1,24 @@
+"""
+dacapo module
+==============
+
+This module contains several useful methods for performing common tasks in dacapo library.
+
+Modules:
+-----------
+Options            - Deals with configuring aspects of the program's operations.
+experiments        - This module is responsible for conducting experiments.
+apply              - Applies the results of the training process to the given dataset.
+train              - Trains the model using given data set.
+validate           - This module is for validating the model.
+predict            - This module is used to generate predictions based on the model.
+
+"""
+
 from .options import Options  # noqa
 from . import experiments  # noqa
 from .apply import apply  # noqa
 from .train import train  # noqa
 from .validate import validate  # noqa
 from .predict import predict  # noqa
+

dacapo/compute_context/local_torch.py

@@ -1,13 +1,27 @@
-from .compute_context import ComputeContext
+"""
+This module provides the LocalTorch class which is used to determine and set the local torch device (CPU or GPU) for 
+computation. This information can be particularly useful for deep learning computations where use of GPU can 
+significantly speed up computations.
 
+"""
+from .compute_context import ComputeContext
 import torch
 import attr
 
 from typing import Optional
 
-
 @attr.s
 class LocalTorch(ComputeContext):
+    """
+    The LocalTorch class is a subclass of the ComputeContext class. It is decorated with the attrs library, which 
+    provides a convenient way of structuring data. It focuses on determining the type of device on which torch 
+    computations will be done. It defaults to GPU (if available) over CPU.
+    
+    Attributes:
+        _device (Optional[str]): This stores the type of device on which torch computations are to be done. It can 
+        take "cuda" for GPU or "cpu" for CPU. None value results in automatic detection of device type.
+    """
+
     _device: Optional[str] = attr.ib(
         default=None,
         metadata={
@@ -18,6 +32,10 @@ class LocalTorch(ComputeContext):
 
     @property
     def device(self):
+        """
+        A property method that returns the torch device object. It automatically detects and uses "cuda" (GPU) if 
+        available, else it falls back on using "cpu".
+        """
         if self._device is None:
             if torch.cuda.is_available():
                 return torch.device("cuda")

dacapo/experiments/__init__.py

@@ -1,7 +1,50 @@
+"""
+This module imports the components of the funkelab dacapo python library which are required
+to build models and run configurations. It also includes functionalities to perform training,
+validation and retrieving statistics or scores from these processes.
+
+This includes:
+
+    - Definition and structure of the Model.
+    - Configuration and execution of a Run.
+    - Settings and preferences for a Run through RunConfig.
+    - Extraction of statistics from each iteration in a training through TrainingIterationStats.
+    - Overall statistics from a full training session through TrainingStats.
+    - Scores from each iteration in validation through ValidationIterationScores.
+    - Overall scores from a full validation session through ValidationScores.
+"""
+
 from .model import Model  # noqa
+"""
+Defining the structure and methods for Model in the library
+"""
+
 from .run import Run  # noqa
+"""
+Defining the structure and methods for Run in the library. This includes setting up a run, execution and returning results.
+"""
+
 from .run_config import RunConfig  # noqa
+"""
+Defining the settings and configurations available for use during a run.
+"""
+
 from .training_iteration_stats import TrainingIterationStats  # noqa
+"""
+Provides functionalities to extract and present statistics from each training iteration during a run.
+"""
+
 from .training_stats import TrainingStats  # noqa
+"""
+Provides functionalities to extract and present overall training statistics from a complete run.
+"""
+
 from .validation_iteration_scores import ValidationIterationScores  # noqa
+"""
+Provides functionalities to extract and present scores from each validation iteration during a run.
+"""
+
 from .validation_scores import ValidationScores  # noqa
+"""
+Provides functionalities to extract and present overall validation scores from a complete run.
+"""

dacapo/experiments/architectures/architecture.py

@@ -6,35 +6,74 @@
 
 
 class Architecture(torch.nn.Module, ABC):
+    """
+    An abstract base class for defining the architecture of a neural network model. 
+    It is inherited from PyTorch's Module and built-in class `ABC` (Abstract Base Classes).
+    Other classes can inherit this class to define their own specific variations of architecture.
+    It requires to implement several property methods, and also includes additional methods related to the architecture design.
+    """
     @property
     @abstractmethod
     def input_shape(self) -> Coordinate:
-        """The spatial input shape (i.e., not accounting for channels and batch
-        dimensions) of this architecture."""
+        """
+        Abstract method to define the spatial input shape for the neural network architecture.
+        The shape should not account for the channels and batch dimensions.
+
+        Returns:
+            Coordinate: The spatial input shape.
+        """
         pass
 
     @property
     def eval_shape_increase(self) -> Coordinate:
         """
-        How much to increase the input shape during prediction.
+        Provides information about how much to increase the input shape during prediction.
+
+        Returns:
+            Coordinate: An instance representing the amount to increase in each dimension of the input shape.
         """
         return Coordinate((0,) * self.input_shape.dims)
 
     @property
     @abstractmethod
     def num_in_channels(self) -> int:
-        """Return the number of input channels this architecture expects."""
+        """
+        Abstract method to return number of input channels required by the architecture.
+
+        Returns:
+            int: Required number of input channels.
+        """
         pass
 
     @property
     @abstractmethod
     def num_out_channels(self) -> int:
-        """Return the number of output channels of this architecture."""
+        """
+        Abstract method to return the number of output channels provided by the architecture.
+
+        Returns:
+            int: Number of output channels.
+        """
         pass
 
     @property
     def dims(self) -> int:
+        """
+        Returns the number of dimensions of the input shape.
+        
+        Returns:
+            int: The number of dimensions. 
+        """
         return self.input_shape.dims
 
     def scale(self, input_voxel_size: Coordinate) -> Coordinate:
-        return input_voxel_size
+        """
+        Method to scale the input voxel size as required by the architecture.
+
+        Args:
+            input_voxel_size (Coordinate): The original size of the input voxel.
+
+        Returns:
+            Coordinate: The scaled voxel size.
+        """
+        return input_voxel_size

dacapo/experiments/architectures/architecture_config.py

@@ -1,15 +1,23 @@
 import attr
-
 from typing import Tuple
 
 
 @attr.s
 class ArchitectureConfig:
-    """Base class for architecture configurations. Each subclass of an
-    `Architecture` should have a corresponding config class derived from
-    `ArchitectureConfig`.
     """
+    A class to represent the base configurations of any architecture.
+
+    Attributes
+    ----------
+    name : str
+        a unique name for the architecture.
+
+    Methods
+    -------
+    verify()
+        validates the given architecture.
 
+    """
     name: str = attr.ib(
         metadata={
             "help_text": "A unique name for this architecture. This will be saved so "
@@ -20,6 +28,13 @@ class ArchitectureConfig:
 
     def verify(self) -> Tuple[bool, str]:
         """
-        Check whether this is a valid architecture
+        A method to validate an architecture configuration.
+
+        Returns
+        -------
+        bool
+            A flag indicating whether the config is valid or not.
+        str
+            A description of the architecture.
         """
-        return True, "No validation for this Architecture"
+        return True, "No validation for this Architecture"

dacapo/experiments/architectures/dummy_architecture.py

@@ -1,12 +1,34 @@
-from .architecture import Architecture
+"""
+This module implements dummy architecture layer for a 3D convolutional neural network.
 
-from funlib.geometry import Coordinate
+Classes:
+    DummyArchitecture(Architecture)
+"""
 
+from .architecture import Architecture
+from funlib.geometry import Coordinate
 import torch
 
 
 class DummyArchitecture(Architecture):
+    """
+    A class used to represent a dummy architecture layer for a 3D CNN. 
+    
+    Attributes:
+        channels_in: An integer representing the number of input channels.
+        channels_out: An integer representing the number of output channels.
+        conv: A 3D convolution object.
+        input_shape: A coordinate object representing the shape of the input.
+        
+    Methods:
+        forward(x): Performs the forward pass of the network.
+    """
+
     def __init__(self, architecture_config):
+        """
+        Args:
+            architecture_config: An object containing the configuration settings for the architecture.
+        """
         super().__init__()
 
         self.channels_in = architecture_config.num_in_channels
@@ -16,15 +38,42 @@ def __init__(self, architecture_config):
 
     @property
     def input_shape(self):
+        """
+        Returns the input shape for this architecture.
+        
+        Returns:
+            Coordinate: Input shape of the architecture.
+        """
         return Coordinate(40, 20, 20)
 
     @property
     def num_in_channels(self):
+        """
+        Returns the number of input channels for this architecture.
+        
+        Returns:
+            int: Number of input channels.
+        """
         return self.channels_in
 
     @property
     def num_out_channels(self):
+        """
+        Returns the number of output channels for this architecture.
+        
+        Returns:
+            int: Number of output channels.
+        """
         return self.channels_out
 
     def forward(self, x):
-        return self.conv(x)
+        """
+        Perform the forward pass of the network.
+        
+        Args:
+            x: Input tensor.
+            
+        Returns:
+            Tensor: Output tensor after the forward pass.
+        """
+        return self.conv(x)

dacapo/experiments/architectures/dummy_architecture_config.py

@@ -8,8 +8,19 @@
 
 @attr.s
 class DummyArchitectureConfig(ArchitectureConfig):
-    """This is just a dummy architecture config used for testing. None of the
-    attributes have any particular meaning."""
+    """A dummy architecture configuration class used for testing purposes.
+    
+    It extends the base class "ArchitectureConfig". This class contains dummy attributes and always
+    returns that the configuration is invalid when verified.
+
+    Attributes:
+        architecture_type (:obj:`DummyArchitecture`): A class attribute assigning 
+            the DummyArchitecture class to this configuration.
+        num_in_channels (int): The number of input channels. This is a dummy attribute and has no real
+            functionality or meaning.
+        num_out_channels (int): The number of output channels. This is also a dummy attribute and
+            has no real functionality or meaning.
+    """
 
     architecture_type = DummyArchitecture
 
@@ -18,4 +29,13 @@ class DummyArchitectureConfig(ArchitectureConfig):
     num_out_channels: int = attr.ib(metadata={"help_text": "Dummy attribute."})
 
     def verify(self) -> Tuple[bool, str]:
-        return False, "This is a DummyArchitectureConfig and is never valid"
+        """Verifies the configuration validity.
+
+        Since this is a dummy configuration for testing purposes, this method always returns False
+        indicating that the configuration is invalid.
+
+        Returns:
+            tuple: A tuple containing a boolean validity flag and a reason message string.
+        """
+
+        return False, "This is a DummyArchitectureConfig and is never valid"

dacapo/experiments/arraytypes/arraytype.py

@@ -14,4 +14,11 @@ class ArrayType(ABC):
     @property
     @abstractmethod
     def interpolatable(self) -> bool:
-        pass
+        """
+        This is an abstract method which should be overridden in each of the subclasses 
+        to determine if an array is interpolatable or not.
+
+        Returns:
+            bool: True if the array is interpolatable, False otherwise.
+        """
+        pass