Fix and enhance wrong doc-strings of all batch_transform and output_transform

monai/handlers/classification_saver.py

@@ -57,12 +57,12 @@ def __init__(
             filename: if `saver=None`, name of the saved CSV file name.
             overwrite: if `saver=None`, whether to overwriting existing file content, if True,
                 will clear the file before saving. otherwise, will apend new content to the file.
-            batch_transform: a callable that is used to transform the
-                ignite.engine.batch into expected format to extract the meta_data dictionary.
-            output_transform: a callable that is used to transform the
-                ignite.engine.output into the form expected model prediction data.
-                The first dimension of this transform's output will be treated as the
-                batch dimension. Each item in the batch will be saved individually.
+            batch_transform: a callable that is used to extract the `meta_data` dictionary of
+                the input images from `ignite.engine.state.batch`. the purpose is to get the input
+                filenames from the `meta_data` and store with classification results together.
+            output_transform: a callable that is used to extract the model prediction data from
+                `ignite.engine.state.output`. the first dimension of its output will be treated as
+                the batch dimension. each item in the batch will be saved individually.
             name: identifier of logging.logger to use, defaulting to `engine.logger`.
             save_rank: only the handler on specified rank will save to CSV file in multi-gpus validation,
                 default to 0.

monai/handlers/confusion_matrix.py

@@ -40,7 +40,11 @@ def __init__(
                 ``"informedness"``, ``"markedness"``]
                 Some of the metrics have multiple aliases (as shown in the wikipedia page aforementioned),
                 and you can also input those names instead.
-            output_transform: transform the ignite.engine.state.output into [y_pred, y] pair.
+            output_transform: callable to extract `y_pred` and `y` from `ignite.engine.state.output` then
+                construct `(y_pred, y)` pair, where `y_pred` and `y` can be `batch-first` Tensors or
+                lists of `channel-first` Tensors. the form of `(y_pred, y)` is required by the `update()`.
+                for example: if `ignite.engine.state.output` is `{"pred": xxx, "label": xxx, "other": xxx}`,
+                output_transform can be `lambda x: (x["pred"], x["label"])`.
             save_details: whether to save metric computation details per image, for example: TP/TN/FP/FN of every image.
                 default to True, will save to `engine.state.metric_details` dict with the metric name as key.
 

monai/handlers/hausdorff_distance.py

@@ -41,7 +41,11 @@ def __init__(
                 percentile of the Hausdorff Distance rather than the maximum result will be achieved.
                 Defaults to ``None``.
             directed: whether to calculate directed Hausdorff distance. Defaults to ``False``.
-            output_transform: transform the ignite.engine.state.output into [y_pred, y] pair.
+            output_transform: callable to extract `y_pred` and `y` from `ignite.engine.state.output` then
+                construct `(y_pred, y)` pair, where `y_pred` and `y` can be `batch-first` Tensors or
+                lists of `channel-first` Tensors. the form of `(y_pred, y)` is required by the `update()`.
+                for example: if `ignite.engine.state.output` is `{"pred": xxx, "label": xxx, "other": xxx}`,
+                output_transform can be `lambda x: (x["pred"], x["label"])`.
             save_details: whether to save metric computation details per image, for example: hausdorff distance
                 of every image. default to True, will save to `engine.state.metric_details` dict with the metric name as key.
 

monai/handlers/ignite_metric.py

@@ -35,7 +35,11 @@ class IgniteMetric(Metric):  # type: ignore[valid-type, misc] # due to optional_
     Args:
         metric_fn: callable function or class to compute raw metric results after every iteration.
             expect to return a Tensor with shape (batch, channel, ...) or tuple (Tensor, not_nans).
-        output_transform: transform the ignite.engine.state.output into [y_pred, y] pair.
+        output_transform: callable to extract `y_pred` and `y` from `ignite.engine.state.output` then
+            construct `(y_pred, y)` pair, where `y_pred` and `y` can be `batch-first` Tensors or
+            lists of `channel-first` Tensors. the form of `(y_pred, y)` is required by the `update()`.
+            for example: if `ignite.engine.state.output` is `{"pred": xxx, "label": xxx, "other": xxx}`,
+            output_transform can be `lambda x: (x["pred"], x["label"])`.
         save_details: whether to save metric computation details per image, for example: mean_dice of every image.
             default to True, will save to `engine.state.metric_details` dict with the metric name as key.
 

monai/handlers/mean_dice.py

@@ -32,7 +32,11 @@ def __init__(
         Args:
             include_background: whether to include dice computation on the first channel of the predicted output.
                 Defaults to True.
-            output_transform: transform the ignite.engine.state.output into [y_pred, y] pair.
+            output_transform: callable to extract `y_pred` and `y` from `ignite.engine.state.output` then
+                construct `(y_pred, y)` pair, where `y_pred` and `y` can be `batch-first` Tensors or
+                lists of `channel-first` Tensors. the form of `(y_pred, y)` is required by the `update()`.
+                for example: if `ignite.engine.state.output` is `{"pred": xxx, "label": xxx, "other": xxx}`,
+                output_transform can be `lambda x: (x["pred"], x["label"])`.
             save_details: whether to save metric computation details per image, for example: mean dice of every image.
                 default to True, will save to `engine.state.metric_details` dict with the metric name as key.
 

monai/handlers/metrics_saver.py

@@ -45,8 +45,9 @@ class MetricsSaver:
             "*" - save all the existing metric_details in `engine.state.metric_details` dict into separate files.
             list of strings - specify the metric_details of expected metrics to save.
             if not None, every metric_details array will save a separate `{metric name}_raw.csv` file.
-        batch_transform: callable function to extract the meta_dict from input batch data if saving metric details.
-            used to extract filenames from input dict data.
+        batch_transform: a callable that is used to extract the `meta_data` dictionary of
+            the input images from `ignite.engine.state.batch` if saving metric details. the purpose is to get the
+            input filenames from the `meta_data` and store with metric details together.
         summary_ops: expected computation operations to generate the summary report.
             it can be: None, "*" or list of strings, default to None.
             None - don't generate summary report for every expected metric_details.

monai/handlers/regression_metrics.py

@@ -29,7 +29,11 @@ def __init__(
         """
 
         Args:
-            output_transform: transform the ignite.engine.state.output into [y_pred, y] pair.
+            output_transform: callable to extract `y_pred` and `y` from `ignite.engine.state.output` then
+                construct `(y_pred, y)` pair, where `y_pred` and `y` can be `batch-first` Tensors or
+                lists of `channel-first` Tensors. the form of `(y_pred, y)` is required by the `update()`.
+                for example: if `ignite.engine.state.output` is `{"pred": xxx, "label": xxx, "other": xxx}`,
+                output_transform can be `lambda x: (x["pred"], x["label"])`.
             save_details: whether to save metric computation details per image, for example: mean squared error of every image.
                 default to True, will save to `engine.state.metric_details` dict with the metric name as key.
 

monai/handlers/roc_auc.py

@@ -33,10 +33,11 @@ class ROCAUC(IgniteMetric):  # type: ignore[valid-type, misc]  # due to optional
                 indicator matrix as a label.
             - ``"none"``: the scores for each class are returned.
 
-        output_transform: a callable that is used to transform the
-            :class:`~ignite.engine.Engine` `process_function` output into the
-            form expected by the metric. This can be useful if, for example, you have a multi-output model and
-            you want to compute the metric with respect to one of the outputs.
+        output_transform: callable to extract `y_pred` and `y` from `ignite.engine.state.output` then
+            construct `(y_pred, y)` pair, where `y_pred` and `y` can be `batch-first` Tensors or
+            lists of `channel-first` Tensors. the form of `(y_pred, y)` is required by the `update()`.
+            for example: if `ignite.engine.state.output` is `{"pred": xxx, "label": xxx, "other": xxx}`,
+            output_transform can be `lambda x: (x["pred"], x["label"])`.
 
     Note:
         ROCAUC expects y to be comprised of 0's and 1's.

monai/handlers/segmentation_saver.py

@@ -101,13 +101,12 @@ def __init__(
                 output_dir: /output,
                 data_root_dir: /foo/bar,
                 output will be: /output/test1/image/image_seg.nii.gz
-            batch_transform: a callable that is used to transform the
-                ignite.engine.batch into expected format to extract the meta_data dictionary.
-                it can be used to extract the input image meta data: filename, affine, original_shape, etc.
-            output_transform: a callable that is used to transform the
-                ignite.engine.output into the form expected image data.
-                The first dimension of this transform's output will be treated as the
-                batch dimension. Each item in the batch will be saved individually.
+            batch_transform: a callable that is used to extract the `meta_data` dictionary of the input images
+                from `ignite.engine.state.batch`. the purpose is to extract necessary information from the meta data:
+                filename, affine, original_shape, etc.
+            output_transform: a callable that is used to extract the model prediction data from
+                `ignite.engine.state.output`. the first dimension of its output will be treated as the batch dimension.
+                each item in the batch will be saved individually.
             name: identifier of logging.logger to use, defaulting to `engine.logger`.
 
         """

monai/handlers/stats_handler.py

@@ -59,7 +59,7 @@ def __init__(
             iteration_print_logger: customized callable printer for iteration level logging.
                 Must accept parameter "engine", use default printer if None.
             output_transform: a callable that is used to transform the
-                ``ignite.engine.output`` into a scalar to print, or a dictionary of {key: scalar}.
+                ``ignite.engine.state.output`` into a scalar to print, or a dictionary of {key: scalar}.
                 In the latter case, the output string will be formatted as key: value.
                 By default this value logging happens when every iteration completed.
             global_epoch_transform: a callable that is used to customize global epoch number.

monai/handlers/surface_distance.py

@@ -38,7 +38,11 @@ def __init__(
                 `seg_pred` and `seg_gt`. Defaults to ``False``.
             distance_metric: : [``"euclidean"``, ``"chessboard"``, ``"taxicab"``]
                 the metric used to compute surface distance. Defaults to ``"euclidean"``.
-            output_transform: transform the ignite.engine.state.output into [y_pred, y] pair.
+            output_transform: callable to extract `y_pred` and `y` from `ignite.engine.state.output` then
+                construct `(y_pred, y)` pair, where `y_pred` and `y` can be `batch-first` Tensors or
+                lists of `channel-first` Tensors. the form of `(y_pred, y)` is required by the `update()`.
+                for example: if `ignite.engine.state.output` is `{"pred": xxx, "label": xxx, "other": xxx}`,
+                output_transform can be `lambda x: (x["pred"], x["label"])`.
             save_details: whether to save metric computation details per image, for example: surface dice
                 of every image. default to True, will save to `engine.state.metric_details` dict with the metric name as key.
 

monai/handlers/tensorboard_handlers.py

@@ -98,7 +98,7 @@ def __init__(
                 Must accept parameter "engine" and "summary_writer", use default event writer if None.
             iteration_interval: the iteration interval at which the iteration_event_writer is called. Defaults to 1.
             output_transform: a callable that is used to transform the
-                ``ignite.engine.output`` into a scalar to plot, or a dictionary of {key: scalar}.
+                ``ignite.engine.state.output`` into a scalar to plot, or a dictionary of {key: scalar}.
                 In the latter case, the output string will be formatted as key: value.
                 By default this value plotting happens when every iteration completed.
             global_epoch_transform: a callable that is used to customize global epoch number.
@@ -258,10 +258,12 @@ def __init__(
             interval: plot content from engine.state every N epochs or every N iterations, default is 1.
             epoch_level: plot content from engine.state every N epochs or N iterations. `True` is epoch level,
                 `False` is iteration level.
-            batch_transform: a callable that is used to transform the
-                ``ignite.engine.batch`` into expected format to extract several label data.
-            output_transform: a callable that is used to transform the
-                ``ignite.engine.output`` into expected format to extract several output data.
+            batch_transform: a callable that is used to extract `image` and `label` from `ignite.engine.state.batch`,
+                then construct `(image, label)` pair. for example: if `ignite.engine.state.batch` is `{"image": xxx,
+                "label": xxx, "other": xxx}`, `batch_transform` can be `lambda x: (x["image"], x["label"])`.
+                will use the result to plot image from `result[0][index]` and plot label from `result[1][index]`.
+            output_transform: a callable that is used to extract the `predictions` data from
+                `ignite.engine.state.output`, will use the result to plot output from `result[index]`.
             global_iter_transform: a callable that is used to customize global step number for TensorBoard.
                 For example, in evaluation, the evaluator engine needs to know current epoch from trainer.
             index: plot which element in a data batch, default is the first element.