📝 Fix and add InnerEye/ML/*.py docs

InnerEye/Common/common_util.py

@@ -307,16 +307,19 @@ def check_properties_are_not_none(obj: Any, ignore: Optional[List[str]] = None)
 
 def initialize_instance_variables(func: Callable) -> Callable:
  """
- Automatically assigns the input parameters.
-
- >>> class process:
- ... @initialize_instance_variables
- ... def __init__(self, cmd, reachable=False, user='root'):
- ... pass
- >>> p = process('halt', True)
- >>> # noinspection PyUnresolvedReferences
- >>> p.cmd, p.reachable, p.user
- ('halt', True, 'root')
+ Automatically assigns the input parameters. Example usage::
+
+ class process:
+ @initialize_instance_variables
+ def __init__(self, cmd, reachable=False, user='root'):
+ pass
+ p = process('halt', True)
+ print(p.cmd, p.reachable, p.user)
+
+ Outputs::
+
+ ('halt', True, 'root')
+
  """
  names, varargs, keywords, defaults, _, _, _ = inspect.getfullargspec(func)
 

InnerEye/ML/deep_learning_config.py

@@ -120,12 +120,10 @@ def create(project_root: Path,
 
  :param project_root: The root folder that contains the code that submitted the present training run.
  When running inside the InnerEye repository, it is the git repo root. When consuming InnerEye as a package,
- this should be the root of the source code that calls the package.
-
+ this should be the root of the source code that calls the package.
  :param is_offline_run: If true, this is a run outside AzureML. If False, it is inside AzureML.
  :param model_name: The name of the model that is trained. This is used to generate a run-specific output
  folder.
-
  :param output_to: If provided, the output folders will be created as a subfolder of this argument. If not
  given, the output folders will be created inside of the project root.
  """

InnerEye/ML/lightning_container.py

@@ -31,16 +31,18 @@ class InnerEyeInference(abc.ABC):
  form of inference is slightly different from what PyTorch Lightning does in its `Trainer.test` method. In
  particular, this inference can be executed on any of the training, validation, or test set.
 
- The inference code calls the methods in this order:
-
- model.on_inference_start()
- for dataset_split in [Train, Val, Test]
- model.on_inference_epoch_start(dataset_split, is_ensemble_model=False)
- for batch_idx, item in enumerate(dataloader[dataset_split])):
- model_outputs = model.forward(item)
- model.inference_step(item, batch_idx, model_outputs)
- model.on_inference_epoch_end()
- model.on_inference_end()
+ The inference code calls the methods in this order::
+
+ model.on_inference_start()
+
+ for dataset_split in [Train, Val, Test]
+ model.on_inference_epoch_start(dataset_split, is_ensemble_model=False)
+ for batch_idx, item in enumerate(dataloader[dataset_split])):
+ model_outputs = model.forward(item)
+ model.inference_step(item, batch_idx, model_outputs)
+ model.on_inference_epoch_end()
+ model.on_inference_end()
+
  """
 
  def on_inference_start(self) -> None:

InnerEye/ML/metrics_dict.py

@@ -713,8 +713,9 @@ def load_execution_mode_metrics_from_df(df: pd.DataFrame,
  """
  Helper function to create BinaryClassificationMetricsDict grouped by ModelExecutionMode and epoch
  from a given dataframe. The following columns must exist in the provided data frame:
- >>> LoggingColumns.DataSplit
- >>> LoggingColumns.Epoch
+
+ * LoggingColumns.DataSplit
+ * LoggingColumns.Epoch
 
  :param df: DataFrame to use for creating the metrics dict.
  :param is_classification_metrics: If the current metrics are for classification or not.

InnerEye/ML/model_training.py

@@ -326,7 +326,7 @@ def model_train(checkpoint_path: Optional[Path],
 def aggregate_and_create_subject_metrics_file(outputs_folder: Path) -> None:
  """
  This functions takes all the subject metrics file written by each GPU (one file per GPU) and aggregates them into
- one single metrics file. Results is saved in config.outputs_folder / mode.value / SUBJECT_METRICS_FILE_NAME.
+ one single metrics file. Results is saved in ``config.outputs_folder / mode.value / SUBJECT_METRICS_FILE_NAME``.
  This is done for the metrics files for training and for validation data separately.
 
  :param config: model config

InnerEye/ML/normalize_and_visualize_dataset.py

@@ -45,8 +45,9 @@ def create_parser(yaml_file_path: Path) -> ParserResult:
  Create a parser for all runner arguments, even though we are only using a subset of the arguments.
  This way, we can get secrets handling in a consistent way.
  In particular, this will create arguments for
- --local_dataset
- --azure_dataset_id
+
+ * ``--local_dataset``
+ * ``--azure_dataset_id``
  """
  parser = create_runner_parser(SegmentationModelBase)
  NormalizeAndVisualizeConfig.add_args(parser)
@@ -67,9 +68,11 @@ def get_configs(default_model_config: SegmentationModelBase,
 def main(yaml_file_path: Path) -> None:
  """
  Invoke either by
- * specifying a model, '--model Lung'
- * or specifying dataset and normalization parameters separately: --azure_dataset_id=foo --norm_method=None
- In addition, the arguments '--image_channel' and '--gt_channel' must be specified (see below).
+
+ * specifying a model, ``--model Lung``
+ * or specifying dataset and normalization parameters separately: ``--azure_dataset_id=foo --norm_method=None``
+
+ In addition, the arguments ``--image_channel`` and ``--gt_channel`` must be specified.
  """
  config, runner_config, args = get_configs(SegmentationModelBase(should_validate=False), yaml_file_path)
  dataset_config = DatasetConfig(name=config.azure_dataset_id,

docs/source/rst/api/ML/core.rst

@@ -1,4 +1,4 @@
-InnerEye/ML Core
+ML Core
 ================
 
 .. toctree::

docs/source/rst/api/ML/core/lightning.rst

@@ -2,6 +2,7 @@ Lightning Components
 ================================
 
 .. automodule:: InnerEye.ML.lightning_base
+ :exclude-members: configure_optimizers
 
 .. automodule:: InnerEye.ML.lightning_container