add autodoc to docs/

Author: henrykrumb

docs/source/conf.py

@@ -9,29 +9,32 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+from pathlib import Path
+import sys
+
+module_path = Path(__file__).parents[2].resolve()
+sys.path.insert(0, module_path.as_posix())
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'nca-models'
-copyright = '2024, Henry Krumb'
-author = 'Henry Krumb'
+project = "NCALab"
+copyright = "2025, MECLab TU Darmstadt"
+author = "Henry Krumb"
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-]
+extensions = ["sphinx.ext.doctest", "autoapi.extension"]
+
+autoapi_type = "python"
+autoapi_dirs = [module_path / "ncalab"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -44,9 +47,9 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = "alabaster"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]

ncalab/experiment.py

@@ -0,0 +1,18 @@
+from os import PathLike
+import json
+
+from .paths import WEIGHTS_PATH
+
+
+class Experiment:
+    def __init__(self, model_name: str):
+        self.model_name = model_name
+        self.model_path = WEIGHTS_PATH / (model_name + ".pth")
+
+    @staticmethod
+    def load(path: PathLike):
+        with open(path, "r") as f:
+            d = json.load(f)
+        model_name = d["model_name"]
+        experiment = Experiment(model_name)
+        return experiment

ncalab/models/basicNCA.py

@@ -29,6 +29,10 @@ def __init__(
 
 
 class BasicNCAModel(nn.Module):
+    """
+    Abstract base class for NCA models.
+    """
+
     def __init__(
         self,
         device: torch.device,
@@ -47,20 +51,20 @@ def __init__(
         pad_noise: bool = False,
         autostepper: Optional[AutoStepper] = None,
     ):
-        """Basic abstract class for NCA models.
-
-        Args:
-            device (device): Pytorch device descriptor.
-            num_image_channels (int): Number of channels reserved for input image.
-            num_hidden_channels (int): Number of hidden channels (communication channels).
-            num_output_channels (int): Number of output channels.
-            fire_rate (float, optional): Fire rate for stochastic weight update. Defaults to 0.5.
-            hidden_size (int, optional): Number of neurons in hidden layer. Defaults to 128.
-            use_alive_mask (bool, optional): Whether to use alive masking during training. Defaults to False.
-            immutable_image_channels (bool, optional): If image channels should be fixed during inference,
-                which is the case for most segmentation or classification problems. Defaults to True.
-            num_learned_filters (int, optional): Number of learned filters. If zero, use two sobel filters instead. Defaults to 2.
-            dx_noise (float)
+        """
+        Constructor.
+        
+        :param device [device]: Pytorch device descriptor.
+        :param num_image_channels [int]: Number of channels reserved for input image.
+        :param num_hidden_channels [int]: Number of hidden channels (communication channels).
+        :param num_output_channels [int]: Number of output channels.
+        :param fire_rate [float]: Fire rate for stochastic weight update. Defaults to 0.5.
+        :param hidden_size [int]: Number of neurons in hidden layer. Defaults to 128.
+        :param use_alive_mask [bool]: Whether to use alive masking during training. Defaults to False.
+        :param immutable_image_channels [bool]: If image channels should be fixed during inference,
+            which is the case for most segmentation or classification problems. Defaults to True.
+        :param num_learned_filters [int]: Number of learned filters. If zero, use two sobel filters instead. Defaults to 2.
+        :param dx_noise [float]:
         """
         super(BasicNCAModel, self).__init__()
 
@@ -130,6 +134,14 @@ def __init__(
         self.meta: dict = {}
 
     def prepare_input(self, x):
+        """
+        Preprocess input. Intended to be overwritten by subclass, if preprocessing
+        is necessary.
+
+        :param x [torch.Tensor]: Input tensor to preprocess.
+
+        :returns: Processed tensor.
+        """
         return x
 
     def alive(self, x):

ncalab/models/cascadeNCA.py

@@ -19,10 +19,14 @@ def downscale(image, scale):
 
 
 class CascadeNCA(BasicNCAModel):
+    """
+    Chain multiple instances of the same NCA model, operating at different
+    image scales.
+    """
+
     def __init__(self, backbone: BasicNCAModel, scales: List[int], steps: List[int]):
         """
-        Chain multiple instances of the same NCA model, operating at different
-        image scales.
+        Constructor.
 
         Args:
             backbone (Type): _description_

ncalab/models/classificationNCA.py

@@ -25,19 +25,18 @@ def __init__(
         pad_noise: bool = False,
     ):
         """
-        Args:
-            device (torch.device): Compute device.
-            num_image_channels (int): _description_
-            num_hidden_channels (int): _description_
-            num_classes (int): _description_
-            fire_rate (float, optional): _description_. Defaults to 0.5.
-            hidden_size (int, optional): _description_. Defaults to 128.
-            use_alive_mask (bool, optional): _description_. Defaults to False.
-            immutable_image_channels (bool, optional): _description_. Defaults to True.
-            learned_filters (int, optional): _description_. Defaults to 0.
-            pixel_wise_loss (bool, optional): Whether a prediction per pixel is desired, like in self-classifying MNIST. Defaults to False.
-            filter_padding (str, optional): _description_. Defaults to "reflect".
-            pad_noise (bool, optional): _description_. Defaults to False.
+        :param device [torch.device]: Compute device.
+        :param num_image_channels [int]: _description_
+        :param num_hidden_channels [int]: _description_
+        :param num_classes [int]: _description_
+        :param fire_rate [float]: _description_. Defaults to 0.5.
+        :param hidden_size [int]: _description_. Defaults to 128.
+        :param use_alive_mask [bool]: _description_. Defaults to False.
+        :param immutable_image_channels [bool]: _description_. Defaults to True.
+        :param learned_filters [int]: _description_. Defaults to 0.
+        :param pixel_wise_loss [bool]: Whether a prediction per pixel is desired, like in self-classifying MNIST. Defaults to False.
+        :param filter_padding [str]: _description_. Defaults to "reflect".
+        :param pad_noise [bool]: _description_. Defaults to False.
         """
         super(ClassificationNCAModel, self).__init__(
             device,
@@ -59,15 +58,14 @@ def __init__(
     def classify(
         self, image: torch.Tensor, steps: int = 100, reduce: bool = False
     ) -> torch.Tensor:
-        """_summary_
+        """
+        Predict classification for an input image.
 
-        Args:
-            image (torch.Tensor): Input image.
-            steps (int, optional): Inference steps. Defaults to 100.
-            reduce (bool, optional): Return a single softmax probability. Defaults to False.
+        :param image [torch.Tensor]: Input image.
+        :param steps [int]: Inference steps. Defaults to 100.
+        :param reduce [bool]: Return a single softmax probability. Defaults to False.
 
-        Returns:
-            (torch.Tensor): Single class index or vector of logits.
+        :returns [torch.Tensor]: Single class index or vector of logits.
         """
         with torch.no_grad():
             x = image.clone()

ncalab/search/search.py

@@ -135,6 +135,7 @@ def search(
                 )
                 writer = SummaryWriter(comment=experiment_name)
                 model = self.model_class(self.device, **model_args)
+                # TODO: allow k-fold
                 trainer = BasicNCATrainer(model, **trainer_args)
                 summary = trainer.train(
                     dataloader_train,

ncalab/training/kfold.py

@@ -11,11 +11,22 @@
 
 
 class TrainValRecord:
+    """
+    Helper class, storing a training / validation data split to generate
+    respective DataLoader objects.
+    """
+
     def __init__(
         self,
         train: List[str],
         val: List[str],
     ):
+        """
+        Constructor.
+
+        :param train (List[str]): List of training image file paths
+        :param val (List[str]): List of validation image file paths
+        """
         self.train = train
         self.val = val
 
@@ -26,6 +37,10 @@ def dataloaders(
         transform=None,
         batch_sizes=None,
     ):
+        """
+        Generate a pair of training and validation DataLoader objects, based on
+        a given DataSet subtype.
+        """
         if batch_sizes is None:
             batch_sizes = {"train": 8, "val": 8}
         dataset_train = DatasetType(path, self.train, transform)
@@ -45,7 +60,14 @@ def dataloaders(
 
 
 class SplitDefinition:
+    """
+    Stores a k-fold cross-validation split.
+    """
+
     def __init__(self):
+        """
+        Constructor.
+        """
         self.folds: List[None | TrainValRecord] = []
         self.dataloader_test = None
 
@@ -55,18 +77,21 @@ def read(path: PosixPath):
         Reads json files with split definitions, similar to those created by nnUNet.
 
         Format is like
-        [
-            {
-                "train": [ "filename0", "filename1",... ]
-                "val": [ "filename2", "filename3",... ]
-            },
-            {
-                ...
-            }
-        ]
-
-        Args:
-            path (PosixPath): Path to JSON file containing split definition.
+
+        .. highlight:: python
+        .. code-block:: python
+
+            [
+                {
+                    "train": [ "filename0", "filename1",... ]
+                    "val": [ "filename2", "filename3",... ]
+                },
+                {
+                    ...
+                }
+            ]
+
+        :param path [PosixPath]: Path to JSON file containing split definition.
         """
         with open(path, "r") as f:
             d = json.load(f)
@@ -89,9 +114,15 @@ def __getitem__(self, idx) -> TrainValRecord:
 
 class KFoldCrossValidationTrainer:
     def __init__(self, trainer: BasicNCATrainer, split: SplitDefinition):
+        """
+        Constructor.
+
+        :param trainer [BasicNCATrainer]: BasicNCATrainer, to train each individual fold.
+        :param split [SplitDefinition]: Definition of the split used for k-fold cross-training.
+        """
         self.trainer = trainer
         self.model_prototype = copy.deepcopy(trainer.nca)
-        self.model_name = trainer.model_path.with_suffix('')
+        self.model_name = trainer.model_path.with_suffix("")
         self.split = split
 
     def train(
@@ -102,6 +133,18 @@ def train(
         batch_sizes: None | Dict = None,
         save_every: int | None = None,
     ) -> List[TrainingSummary]:
+        """
+        Run training loop with a single function call.
+
+        :param DatasetType [Type]: Type of dataset class to use.
+        :param datapath [Path]: _description_
+        :param transform: Data transform, e.g. initialized via Albumentations.
+        :param batch_sizes: Dict of batch sizes per set, e.g. {"train": 8, "val": 16}. Defaults to None.
+        :param save_every [int]: _description_. Defaults to None.
+        :param plot_function: Plot function override. If None, use model's default. Defaults to None.
+
+        :returns [List[TrainingSummary]]: List of TrainingSummary objects, one per fold.
+        """
         k = len(self.split)
         summaries = []
         for i in range(k):