From a94b50e8ec85cc1d81cec9e9f28edaf1725ee34b Mon Sep 17 00:00:00 2001 From: ydcjeff Date: Tue, 23 Feb 2021 16:14:17 +0630 Subject: [PATCH 1/8] docs: rm type hints in ignite.metrics --- docs/requirements.txt | 2 +- docs/source/conf.py | 1 + ignite/metrics/accumulation.py | 14 +++--- ignite/metrics/accuracy.py | 6 +-- ignite/metrics/confusion_matrix.py | 30 ++++++------ ignite/metrics/epoch_metric.py | 8 ++-- ignite/metrics/fbeta.py | 12 ++--- ignite/metrics/loss.py | 8 ++-- ignite/metrics/mean_absolute_error.py | 10 ++++ ignite/metrics/mean_pairwise_distance.py | 12 +++++ ignite/metrics/mean_squared_error.py | 10 ++++ ignite/metrics/metric.py | 46 ++++++++++--------- ignite/metrics/metrics_lambda.py | 6 ++- ignite/metrics/multilabel_confusion_matrix.py | 7 +-- ignite/metrics/precision.py | 8 ++-- ignite/metrics/psnr.py | 6 +-- ignite/metrics/recall.py | 8 ++-- ignite/metrics/root_mean_squared_error.py | 10 ++++ ignite/metrics/running_average.py | 10 ++-- ignite/metrics/ssim.py | 16 +++---- ignite/metrics/top_k_categorical_accuracy.py | 11 +++++ 21 files changed, 150 insertions(+), 91 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 4c94a44e1dc8..f7b4ab9b632e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,3 @@ -sphinx==3.2.1 +sphinx==3.4 -e git+https://github.com/pytorch/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme sphinxcontrib-katex diff --git a/docs/source/conf.py b/docs/source/conf.py index a69170d460c4..2c8c5e660d30 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -208,6 +208,7 @@ autoclass_content = "both" autodoc_typehints = "description" +napoleon_attr_annotations = True # -- A patch that turns-off cross refs for type annotations ------------------ diff --git a/ignite/metrics/accumulation.py b/ignite/metrics/accumulation.py index c26d1758d79f..6a1d7091d58a 100644 --- a/ignite/metrics/accumulation.py +++ b/ignite/metrics/accumulation.py @@ -25,13 +25,13 @@ class VariableAccumulation(Metric): - `+batch_size` if input is a ND `torch.Tensor`. Batch size is the first dimension (`shape[0]`). Args: - op (callable): a callable to update accumulator. Method's signature is `(accumulator, output)`. + op: a callable to update accumulator. Method's signature is `(accumulator, output)`. For example, to compute arithmetic mean value, `op = lambda a, x: a + x`. - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's + device: specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. @@ -112,11 +112,11 @@ class Average(VariableAccumulation): # state.metrics['mean_custom_var'] -> average of output['custom_var'] Args: - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's + device: specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. """ @@ -159,11 +159,11 @@ class GeometricAverage(VariableAccumulation): is aggregated and added to the accumulator: `accumulator *= prod(x, dim=0)` Args: - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's + device: specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/accuracy.py b/ignite/metrics/accuracy.py index 460fec31688e..542adb16ec93 100644 --- a/ignite/metrics/accuracy.py +++ b/ignite/metrics/accuracy.py @@ -119,12 +119,12 @@ def thresholded_output_transform(output): Args: - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - is_multilabel (bool, optional): flag to use in multilabel case. By default, False. - device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's + is_multilabel: flag to use in multilabel case. By default, False. + device: specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/confusion_matrix.py b/ignite/metrics/confusion_matrix.py index d4fba5d4365d..a1305eb38c5d 100644 --- a/ignite/metrics/confusion_matrix.py +++ b/ignite/metrics/confusion_matrix.py @@ -21,17 +21,17 @@ class ConfusionMatrix(Metric): predicted classes. Args: - num_classes (int): Number of classes, should be > 1. See notes for more details. - average (str, optional): confusion matrix values averaging schema: None, "samples", "recall", "precision". + num_classes: Number of classes, should be > 1. See notes for more details. + average: confusion matrix values averaging schema: None, "samples", "recall", "precision". Default is None. If `average="samples"` then confusion matrix values are normalized by the number of seen samples. If `average="recall"` then confusion matrix values are normalized such that diagonal values represent class recalls. If `average="precision"` then confusion matrix values are normalized such that diagonal values represent class precisions. - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's + device: specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. @@ -161,8 +161,8 @@ def IoU(cm: ConfusionMatrix, ignore_index: Optional[int] = None) -> MetricsLambd .. math:: \text{J}(A, B) = \frac{ \lvert A \cap B \rvert }{ \lvert A \cup B \rvert } Args: - cm (ConfusionMatrix): instance of confusion matrix metric - ignore_index (int, optional): index to ignore, e.g. background index + cm: instance of confusion matrix metric + ignore_index: index to ignore, e.g. background index Returns: MetricsLambda @@ -212,8 +212,8 @@ def mIoU(cm: ConfusionMatrix, ignore_index: Optional[int] = None) -> MetricsLamb """Calculates mean Intersection over Union using :class:`~ignite.metrics.ConfusionMatrix` metric. Args: - cm (ConfusionMatrix): instance of confusion matrix metric - ignore_index (int, optional): index to ignore, e.g. background index + cm: instance of confusion matrix metric + ignore_index: index to ignore, e.g. background index Returns: MetricsLambda @@ -240,7 +240,7 @@ def cmAccuracy(cm: ConfusionMatrix) -> MetricsLambda: """Calculates accuracy using :class:`~ignite.metrics.ConfusionMatrix` metric. Args: - cm (ConfusionMatrix): instance of confusion matrix metric + cm: instance of confusion matrix metric Returns: MetricsLambda @@ -255,8 +255,8 @@ def cmPrecision(cm: ConfusionMatrix, average: bool = True) -> MetricsLambda: """Calculates precision using :class:`~ignite.metrics.ConfusionMatrix` metric. Args: - cm (ConfusionMatrix): instance of confusion matrix metric - average (bool, optional): if True metric value is averaged over all classes + cm: instance of confusion matrix metric + average: if True metric value is averaged over all classes Returns: MetricsLambda """ @@ -274,8 +274,8 @@ def cmRecall(cm: ConfusionMatrix, average: bool = True) -> MetricsLambda: """ Calculates recall using :class:`~ignite.metrics.ConfusionMatrix` metric. Args: - cm (ConfusionMatrix): instance of confusion matrix metric - average (bool, optional): if True metric value is averaged over all classes + cm: instance of confusion matrix metric + average: if True metric value is averaged over all classes Returns: MetricsLambda """ @@ -293,8 +293,8 @@ def DiceCoefficient(cm: ConfusionMatrix, ignore_index: Optional[int] = None) -> """Calculates Dice Coefficient for a given :class:`~ignite.metrics.ConfusionMatrix` metric. Args: - cm (ConfusionMatrix): instance of confusion matrix metric - ignore_index (int, optional): index to ignore, e.g. background index + cm: instance of confusion matrix metric + ignore_index: index to ignore, e.g. background index """ if not isinstance(cm, ConfusionMatrix): diff --git a/ignite/metrics/epoch_metric.py b/ignite/metrics/epoch_metric.py index cc8f3ec4a7c0..2ad5511dbbb6 100644 --- a/ignite/metrics/epoch_metric.py +++ b/ignite/metrics/epoch_metric.py @@ -31,17 +31,17 @@ class EpochMetric(Metric): e.g. ``[[0, 1, 0, 1], ]``. Args: - compute_fn (callable): a callable with the signature (`torch.tensor`, `torch.tensor`) takes as the input + compute_fn: a callable with the signature (`torch.tensor`, `torch.tensor`) takes as the input `predictions` and `targets` and returns a scalar. Input tensors will be on specified ``device`` (see arg below). - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - check_compute_fn (bool): if True, ``compute_fn`` is run on the first batch of data to ensure there are no + check_compute_fn: if True, ``compute_fn`` is run on the first batch of data to ensure there are no issues. If issues exist, user is warned that there might be an issue with the ``compute_fn``. Default, True. - device (str or torch.device, optional): optional device specification for internal storage. + device: optional device specification for internal storage. Warnings: EpochMetricWarning: User is warned that there are issues with ``compute_fn`` on a batch of data processed. diff --git a/ignite/metrics/fbeta.py b/ignite/metrics/fbeta.py index b417445c10ae..65f18a4e28cd 100644 --- a/ignite/metrics/fbeta.py +++ b/ignite/metrics/fbeta.py @@ -26,15 +26,15 @@ def Fbeta( where :math:`\beta` is a positive real factor. Args: - beta (float): weight of precision in harmonic mean - average (bool, optional): if True, F-beta score is computed as the unweighted average (across all classes + beta: weight of precision in harmonic mean + average: if True, F-beta score is computed as the unweighted average (across all classes in multiclass case), otherwise, returns a tensor with F-beta score for each class in multiclass case. - precision (Precision, optional): precision object metric with `average=False` to compute F-beta score - recall (Precision, optional): recall object metric with `average=False` to compute F-beta score - output_transform (callable, optional): a callable that is used to transform the + precision: precision object metric with `average=False` to compute F-beta score + recall: recall object metric with `average=False` to compute F-beta score + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the form expected by the metric. It is used only if precision or recall are not provided. - device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's + device: specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/loss.py b/ignite/metrics/loss.py index 18fc34a36d87..b7a323fc198b 100644 --- a/ignite/metrics/loss.py +++ b/ignite/metrics/loss.py @@ -13,10 +13,10 @@ class Loss(Metric): Calculates the average loss according to the passed loss_fn. Args: - loss_fn (callable): a callable taking a prediction tensor, a target + loss_fn: a callable taking a prediction tensor, a target tensor, optionally other arguments, and returns the average loss over all observations in the batch. - output_transform (callable): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the form expected by the metric. This can be useful if, for example, you have a multi-output model and @@ -24,9 +24,9 @@ class Loss(Metric): The output is expected to be a tuple `(prediction, target)` or (prediction, target, kwargs) where kwargs is a dictionary of extra keywords arguments. If extra keywords arguments are provided they are passed to `loss_fn`. - batch_size (callable): a callable taking a target tensor that returns the + batch_size: a callable taking a target tensor that returns the first dimension size (usually the batch size). - device (str or torch.device): specifies which device updates are accumulated on. Setting the + device: specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/mean_absolute_error.py b/ignite/metrics/mean_absolute_error.py index 461ed54f8ab2..f93b08453ce4 100644 --- a/ignite/metrics/mean_absolute_error.py +++ b/ignite/metrics/mean_absolute_error.py @@ -16,6 +16,16 @@ class MeanAbsoluteError(Metric): where :math:`y_{i}` is the prediction tensor and :math:`x_{i}` is ground true tensor. - ``update`` must receive output of the form ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ @reinit__is_reduced diff --git a/ignite/metrics/mean_pairwise_distance.py b/ignite/metrics/mean_pairwise_distance.py index 9751e8797a42..fc3a9ad68ae1 100644 --- a/ignite/metrics/mean_pairwise_distance.py +++ b/ignite/metrics/mean_pairwise_distance.py @@ -14,6 +14,18 @@ class MeanPairwiseDistance(Metric): Average of pairwise distances computed on provided batches. - ``update`` must receive output of the form ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + + Args: + p: the norm degree. Default: 2 + eps: Small value to avoid division by zero. Default: 1e-6 + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def __init__( diff --git a/ignite/metrics/mean_squared_error.py b/ignite/metrics/mean_squared_error.py index 682b56756bf0..131c04b2efd6 100644 --- a/ignite/metrics/mean_squared_error.py +++ b/ignite/metrics/mean_squared_error.py @@ -16,6 +16,16 @@ class MeanSquaredError(Metric): where :math:`y_{i}` is the prediction tensor and :math:`x_{i}` is ground true tensor. - ``update`` must receive output of the form ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ @reinit__is_reduced diff --git a/ignite/metrics/metric.py b/ignite/metrics/metric.py index 053d7d0224ba..02e2acba7de9 100644 --- a/ignite/metrics/metric.py +++ b/ignite/metrics/metric.py @@ -60,10 +60,10 @@ class EpochWise(MetricUsage): - :meth:`~ignite.metrics.Metric.completed` on every ``EPOCH_COMPLETED``. Attributes: - usage_name (str): usage name string + usage_name: usage name string """ - usage_name = "epoch_wise" + usage_name: str = "epoch_wise" def __init__(self) -> None: super(EpochWise, self).__init__( @@ -84,10 +84,10 @@ class BatchWise(MetricUsage): - :meth:`~ignite.metrics.Metric.completed` on every ``ITERATION_COMPLETED``. Attributes: - usage_name (str): usage name string + usage_name: usage name string """ - usage_name = "batch_wise" + usage_name: str = "batch_wise" def __init__(self) -> None: super(BatchWise, self).__init__( @@ -108,8 +108,8 @@ class BatchFiltered(MetricUsage): - :meth:`~ignite.metrics.Metric.completed` on every ``EPOCH_COMPLETED``. Args: - *args: Positional arguments to setup :attr:`~ignite.engine.events.Events.ITERATION_COMPLETED(*args, **kwargs)` - **kwargs: Keyword arguments to setup :attr:`~ignite.engine.events.Events.ITERATION_COMPLETED(*args, **kwargs)` + args: Positional arguments to setup :attr:`~ignite.engine.events.Events.ITERATION_COMPLETED(*args, **kwargs)` + kwargs: Keyword arguments to setup :attr:`~ignite.engine.events.Events.ITERATION_COMPLETED(*args, **kwargs)` handled by :meth:`~ignite.metrics.Metric.iteration_completed`. """ @@ -127,17 +127,17 @@ class Metric(metaclass=ABCMeta): Base class for all Metrics. Args: - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - device (str or torch.device): specifies which device updates are accumulated on. Setting the + device: specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. Attributes: - required_output_keys (tuple): dictionary defines required keys to be found in ``engine.state.output`` if the + required_output_keys: dictionary defines required keys to be found in ``engine.state.output`` if the latter is a dictionary. Default, ``("y_pred", "y")``. This is useful with custom metrics that can require other arguments than predictions ``y_pred`` and targets ``y``. See notes below for an example. @@ -196,7 +196,7 @@ def compute(self): """ # public class attribute - required_output_keys = ("y_pred", "y") # type: Optional[Tuple] + required_output_keys: Optional[Tuple] = ("y_pred", "y") # for backward compatibility _required_output_keys = required_output_keys @@ -267,7 +267,7 @@ def started(self, engine: Engine) -> None: `engine` with :meth:`~ignite.metrics.Metric.attach`. Args: - engine (Engine): the engine to which the metric must be attached + engine: the engine to which the metric must be attached """ self.reset() @@ -277,7 +277,7 @@ def iteration_completed(self, engine: Engine) -> None: `engine` with :meth:`~ignite.metrics.Metric.attach`. Args: - engine (Engine): the engine to which the metric must be attached + engine: the engine to which the metric must be attached """ output = self._output_transform(engine.state.output) @@ -300,8 +300,8 @@ def completed(self, engine: Engine, name: str) -> None: `engine` with :meth:`~ignite.metrics.Metric.attach`. Args: - engine (Engine): the engine to which the metric must be attached - name (str): the name of the metric used as key in dict `engine.state.metrics` + engine: the engine to which the metric must be attached + name: the name of the metric used as key in dict `engine.state.metrics` .. versionchanged:: 0.4.3 Added dict in metrics results. @@ -338,9 +338,9 @@ def attach(self, engine: Engine, name: str, usage: Union[str, MetricUsage] = Epo contain computed metric's value under provided name. Args: - engine (Engine): the engine to which the metric must be attached - name (str): the name of the metric to attach - usage (str or MetricUsage, optional): the usage of the metric. Valid string values should be + engine: the engine to which the metric must be attached + name: the name of the metric to attach + usage: the usage of the metric. Valid string values should be :attr:`ignite.metrics.EpochWise.usage_name` (default) or :attr:`ignite.metrics.BatchWise.usage_name`. @@ -381,8 +381,8 @@ def detach(self, engine: Engine, usage: Union[str, MetricUsage] = EpochWise()) - and another metric (e.g. more expensive one) is done every n-th training epoch. Args: - engine (Engine): the engine from which the metric must be detached - usage (str or MetricUsage, optional): the usage of the metric. Valid string values should be + engine: the engine from which the metric must be detached + usage: the usage of the metric. Valid string values should be 'epoch_wise' (default) or 'batch_wise'. Example: @@ -423,8 +423,8 @@ def is_attached(self, engine: Engine, usage: Union[str, MetricUsage] = EpochWise value is written to `engine.state.metrics` dictionary. Args: - engine (Engine): the engine checked from which the metric should be attached - usage (str or MetricUsage, optional): the usage of the metric. Valid string values should be + engine: the engine checked from which the metric should be attached + usage: the usage of the metric. Valid string values should be 'epoch_wise' (default) or 'batch_wise'. """ usage = self._check_usage(usage) @@ -530,7 +530,7 @@ def sync_all_reduce(*attrs: Any) -> Callable: See :doc:`metrics` on how to use it. Args: - *attrs: attribute names of decorated class + attrs: attribute names of decorated class """ @@ -566,6 +566,8 @@ def reinit__is_reduced(func: Callable) -> Callable: See :doc:`metrics` on how to use it. + Args: + func: A callable to reinit. """ @wraps(func) diff --git a/ignite/metrics/metrics_lambda.py b/ignite/metrics/metrics_lambda.py index 6514b71cfd00..eb41e101bb11 100644 --- a/ignite/metrics/metrics_lambda.py +++ b/ignite/metrics/metrics_lambda.py @@ -21,9 +21,11 @@ class MetricsLambda(Metric): automatically (but partially, e.g :meth:`~ignite.metrics.Metric.is_attached()` will return False). Args: - f (callable): the function that defines the computation - args (sequence): Sequence of other metrics or something + f: the function that defines the computation + args: Sequence of other metrics or something else that will be fed to ``f`` as arguments. + kwargs: Sequence of other metrics or something + else that will be fed to ``f`` as keyword arguments. Example: diff --git a/ignite/metrics/multilabel_confusion_matrix.py b/ignite/metrics/multilabel_confusion_matrix.py index 20f13fb7e525..673a154624ef 100644 --- a/ignite/metrics/multilabel_confusion_matrix.py +++ b/ignite/metrics/multilabel_confusion_matrix.py @@ -30,14 +30,15 @@ class MultiLabelConfusionMatrix(Metric): - The classes present in M are indexed as 0, ... , num_classes-1 as can be inferred from above. Args: - num_classes (int): Number of classes, should be > 1. - output_transform (callable, optional): a callable that is used to transform the + num_classes: Number of classes, should be > 1. + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's + device: specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. + normalized: whether to normalized confusion matrix by its sum or not. .. versionadded:: 0.5.0 diff --git a/ignite/metrics/precision.py b/ignite/metrics/precision.py index 50142b7f78a3..ed31eebe27c7 100644 --- a/ignite/metrics/precision.py +++ b/ignite/metrics/precision.py @@ -103,15 +103,15 @@ def thresholded_output_transform(output): Args: - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - average (bool, optional): if True, precision is computed as the unweighted average (across all classes + average: if True, precision is computed as the unweighted average (across all classes in multiclass case), otherwise, returns a tensor with the precision (for each class in multiclass case). - is_multilabel (bool, optional) flag to use in multilabel case. By default, value is False. If True, average + is_multilabel: flag to use in multilabel case. By default, value is False. If True, average parameter should be True and the average is computed across samples, instead of classes. - device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's + device: specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/psnr.py b/ignite/metrics/psnr.py index 8c00dba78725..7e930abb4ef6 100644 --- a/ignite/metrics/psnr.py +++ b/ignite/metrics/psnr.py @@ -20,12 +20,12 @@ class PSNR(Metric): - `y_pred` and `y` **must** have same dtype and same shape. Args: - data_range (int or float): The data range of the target image (distance between minimum + data_range: The data range of the target image (distance between minimum and maximum possible values). For other data types, please set the data range, otherwise an exception will be raised. - output_transform (callable, optional): A callable that is used to transform the Engine’s + output_transform: A callable that is used to transform the Engine’s process_function’s output into the form expected by the metric. - device (str or torch.device): specifies which device updates are accumulated on. + device: specifies which device updates are accumulated on. Setting the metric’s device to be the same as your update arguments ensures the update method is non-blocking. By default, CPU. diff --git a/ignite/metrics/recall.py b/ignite/metrics/recall.py index a11cb7d583bf..9ef4316c8806 100644 --- a/ignite/metrics/recall.py +++ b/ignite/metrics/recall.py @@ -50,15 +50,15 @@ def thresholded_output_transform(output): Args: - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - average (bool, optional): if True, precision is computed as the unweighted average (across all classes + average: if True, precision is computed as the unweighted average (across all classes in multiclass case), otherwise, returns a tensor with the precision (for each class in multiclass case). - is_multilabel (bool, optional) flag to use in multilabel case. By default, value is False. If True, average + is_multilabel: flag to use in multilabel case. By default, value is False. If True, average parameter should be True and the average is computed across samples, instead of classes. - device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's + device: specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/root_mean_squared_error.py b/ignite/metrics/root_mean_squared_error.py index 0197fcceca34..47722862970b 100644 --- a/ignite/metrics/root_mean_squared_error.py +++ b/ignite/metrics/root_mean_squared_error.py @@ -16,6 +16,16 @@ class RootMeanSquaredError(MeanSquaredError): where :math:`y_{i}` is the prediction tensor and :math:`x_{i}` is ground true tensor. - ``update`` must receive output of the form (y_pred, y) or `{'y_pred': y_pred, 'y': y}`. + + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def compute(self) -> Union[torch.Tensor, float]: diff --git a/ignite/metrics/running_average.py b/ignite/metrics/running_average.py index db36b1a90483..d5c251d2b859 100644 --- a/ignite/metrics/running_average.py +++ b/ignite/metrics/running_average.py @@ -13,14 +13,14 @@ class RunningAverage(Metric): """Compute running average of a metric or the output of process function. Args: - src (Metric or None): input source: an instance of :class:`~ignite.metrics.Metric` or None. The latter + src: input source: an instance of :class:`~ignite.metrics.Metric` or None. The latter corresponds to `engine.state.output` which holds the output of process function. - alpha (float, optional): running average decay factor, default 0.98 - output_transform (callable, optional): a function to use to transform the output if `src` is None and + alpha: running average decay factor, default 0.98 + output_transform: a function to use to transform the output if `src` is None and corresponds the output of process function. Otherwise it should be None. - epoch_bound (boolean, optional): whether the running average should be reset after each epoch (defaults + epoch_bound: whether the running average should be reset after each epoch (defaults to True). - device (str or torch.device, optional): specifies which device updates are accumulated on. Should be + device: specifies which device updates are accumulated on. Should be None when ``src`` is an instance of :class:`~ignite.metrics.Metric`, as the running average will use the ``src``'s device. Otherwise, defaults to CPU. Only applicable when the computed value from the metric is a tensor. diff --git a/ignite/metrics/ssim.py b/ignite/metrics/ssim.py index 664ee35ffbd8..67f3941050c5 100644 --- a/ignite/metrics/ssim.py +++ b/ignite/metrics/ssim.py @@ -14,17 +14,17 @@ class SSIM(Metric): Computes Structual Similarity Index Measure Args: - data_range (int or float): Range of the image. Typically, ``1.0`` or ``255``. - kernel_size (int or list or tuple of int): Size of the kernel. Default: (11, 11) - sigma (float or list or tuple of float): Standard deviation of the gaussian kernel. + data_range: Range of the image. Typically, ``1.0`` or ``255``. + kernel_size: Size of the kernel. Default: (11, 11) + sigma: Standard deviation of the gaussian kernel. Argument is used if ``gaussian=True``. Default: (1.5, 1.5) - k1 (float): Parameter of SSIM. Default: 0.01 - k2 (float): Parameter of SSIM. Default: 0.03 - gaussian (bool): ``True`` to use gaussian kernel, ``False`` to use uniform kernel - output_transform (callable, optional): A callable that is used to transform the + k1: Parameter of SSIM. Default: 0.01 + k2: Parameter of SSIM. Default: 0.03 + gaussian: ``True`` to use gaussian kernel, ``False`` to use uniform kernel + output_transform: A callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the form expected by the metric. - device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's + device: specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/top_k_categorical_accuracy.py b/ignite/metrics/top_k_categorical_accuracy.py index 20d948003ebc..b6bec2de3970 100644 --- a/ignite/metrics/top_k_categorical_accuracy.py +++ b/ignite/metrics/top_k_categorical_accuracy.py @@ -13,6 +13,17 @@ class TopKCategoricalAccuracy(Metric): Calculates the top-k categorical accuracy. - ``update`` must receive output of the form ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + + Args: + k: the k in “top-k”. + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def __init__( From 2179df5dd510acf05f17262513d2e4d6682992da Mon Sep 17 00:00:00 2001 From: ydcjeff Date: Tue, 23 Feb 2021 16:30:37 +0630 Subject: [PATCH 2/8] docs: rm type hints in ignite.distributed --- ignite/distributed/auto.py | 18 +++++++++--------- ignite/distributed/launcher.py | 20 ++++++++++---------- ignite/distributed/utils.py | 34 +++++++++++++++++----------------- 3 files changed, 36 insertions(+), 36 deletions(-) diff --git a/ignite/distributed/auto.py b/ignite/distributed/auto.py index 9764e38db6f7..1d6a585b0e63 100644 --- a/ignite/distributed/auto.py +++ b/ignite/distributed/auto.py @@ -50,8 +50,8 @@ def auto_dataloader(dataset: Dataset, **kwargs: Any) -> Union[DataLoader, "_MpDe ) Args: - dataset (Dataset): input torch dataset - **kwargs: keyword arguments for `torch DataLoader`_. + dataset: input torch dataset + kwargs: keyword arguments for `torch DataLoader`_. Returns: `torch DataLoader`_ or `XLA MpDeviceLoader`_ for XLA devices @@ -154,11 +154,11 @@ def auto_model(model: nn.Module, sync_bn: bool = False, **kwargs: Any) -> nn.Mod model = idist.auto_model(model) Args: - model (torch.nn.Module): model to adapt. - sync_bn (bool): if True, applies `torch convert_sync_batchnorm`_ to the model for native torch + model: model to adapt. + sync_bn: if True, applies `torch convert_sync_batchnorm`_ to the model for native torch distributed only. Default, False. Note, if using Nvidia/Apex, batchnorm conversion should be applied before calling ``amp.initialize``. - **kwargs: kwargs to model's wrapping class: `torch DistributedDataParallel`_ or `torch DataParallel`_ + kwargs: kwargs to model's wrapping class: `torch DistributedDataParallel`_ or `torch DataParallel`_ if applicable. Please, make sure to use acceptable kwargs for given backend. Returns: @@ -241,7 +241,7 @@ def auto_optim(optimizer: Optimizer) -> Optimizer: optimizer = idist.auto_optim(optimizer) Args: - optimizer (Optimizer): input torch optimizer + optimizer: input torch optimizer Returns: Optimizer @@ -276,9 +276,9 @@ class DistributedProxySampler(DistributedSampler): Input sampler is assumed to have a constant size. Args: - sampler (Sampler): Input torch data sampler. - num_replicas (int, optional): Number of processes participating in distributed training. - rank (int, optional): Rank of the current process within ``num_replicas``. + sampler: Input torch data sampler. + num_replicas: Number of processes participating in distributed training. + rank: Rank of the current process within ``num_replicas``. """ diff --git a/ignite/distributed/launcher.py b/ignite/distributed/launcher.py index 28f1a036c842..4d24979fee47 100644 --- a/ignite/distributed/launcher.py +++ b/ignite/distributed/launcher.py @@ -152,25 +152,25 @@ def training(local_rank, config, **kwargs): .. _horovodrun: https://horovod.readthedocs.io/en/latest/api.html#module-horovod.run Args: - backend (str, optional): backend to use: `nccl`, `gloo`, `xla-tpu`, `horovod`. If None, no distributed + backend: backend to use: `nccl`, `gloo`, `xla-tpu`, `horovod`. If None, no distributed configuration. - nproc_per_node (int, optional): optional argument, number of processes per + nproc_per_node: optional argument, number of processes per node to specify. If not None, :meth:`~ignite.distributed.Parallel.run` will spawn ``nproc_per_node`` processes that run input function with its arguments. - nnodes (int, optional): optional argument, number of nodes participating in distributed configuration. + nnodes: optional argument, number of nodes participating in distributed configuration. If not None, :meth:`~ignite.distributed.Parallel.run` will spawn ``nproc_per_node`` processes that run input function with its arguments. Total world size is `nproc_per_node * nnodes`. This option is only supported by native torch distributed module. For other modules, please setup ``spawn_kwargs`` with backend specific arguments. - node_rank (int, optional): optional argument, current machine index. Mandatory argument if ``nnodes`` is + node_rank: optional argument, current machine index. Mandatory argument if ``nnodes`` is specified and larger than one. This option is only supported by native torch distributed module. For other modules, please setup ``spawn_kwargs`` with backend specific arguments. - master_addr (str, optional): optional argument, master node TCP/IP address for torch native backends + master_addr: optional argument, master node TCP/IP address for torch native backends (`nccl`, `gloo`). Mandatory argument if ``nnodes`` is specified and larger than one. - master_port (int, optional): optional argument, master node port for torch native backends + master_port: optional argument, master node port for torch native backends (`nccl`, `gloo`). Mandatory argument if ``master_addr`` is specified. - **spawn_kwargs: kwargs to ``idist.spawn`` function. + spawn_kwargs: kwargs to ``idist.spawn`` function. .. versionchanged:: 0.4.2 ``backend`` now accepts `horovod` distributed framework. @@ -264,10 +264,10 @@ def training(local_rank, config, **kwargs): parallel.run(training, config, a=1, b=2) Args: - func (Callable): function to execute. First argument of the function should be `local_rank` - local process + func: function to execute. First argument of the function should be `local_rank` - local process index. - *args: positional arguments of ``func`` (without `local_rank`). - **kwargs: keyword arguments of ``func``. + args: positional arguments of ``func`` (without `local_rank`). + kwargs: keyword arguments of ``func``. """ if self._spawn_params is not None and self.backend is not None: diff --git a/ignite/distributed/utils.py b/ignite/distributed/utils.py index 793d89e13793..1376ce102930 100644 --- a/ignite/distributed/utils.py +++ b/ignite/distributed/utils.py @@ -52,7 +52,7 @@ def sync(temporary: bool = False) -> None: This method should be used when distributed context is manually created or destroyed. Args: - temporary (bool): If True, distributed model synchronization is done every call of ``idist.get_*`` methods. + temporary: If True, distributed model synchronization is done every call of ``idist.get_*`` methods. This may have a negative performance impact. """ global _model @@ -285,15 +285,15 @@ def train_fn(local_rank, a, b, c, d=12): idist.spawn("xla-tpu", train_fn, args=(a, b, c), kwargs_dict={"d": 23}, nproc_per_node=8) Args: - backend (str): backend to use: `nccl`, `gloo`, `xla-tpu`, `horovod` - fn (function): function to called as the entrypoint of the spawned process. + backend: backend to use: `nccl`, `gloo`, `xla-tpu`, `horovod` + fn: function to called as the entrypoint of the spawned process. This function must be defined at the top level of a module so it can be pickled and spawned. This is a requirement imposed by multiprocessing. The function is called as ``fn(i, *args, **kwargs_dict)``, where `i` is the process index and args is the passed through tuple of arguments. - args (tuple): arguments passed to `fn`. - kwargs_dict (Mapping): kwargs passed to `fn`. - nproc_per_node (int): number of processes to spawn on a single node. Default, 1. - **kwargs: acceptable kwargs according to provided backend: + args: arguments passed to `fn`. + kwargs_dict: kwargs passed to `fn`. + nproc_per_node: number of processes to spawn on a single node. Default, 1. + kwargs: acceptable kwargs according to provided backend: - | "nccl" or "gloo" : `nnodes` (default, 1), `node_rank` (default, 0), `master_addr` | (default, "127.0.0.1"), `master_port` (default, 2222), `timeout` to `dist.init_process_group`_ function @@ -329,8 +329,8 @@ def all_reduce(tensor: Union[torch.Tensor, float], op: str = "SUM") -> Union[tor """Helper method to perform all reduce operation. Args: - tensor (torch.Tensor or number): tensor or number to collect across participating processes. - op (str): reduction operation, "SUM" by default. Possible values: "SUM", "PRODUCT", "MIN", "MAX", "AND", "OR". + tensor: tensor or number to collect across participating processes. + op: reduction operation, "SUM" by default. Possible values: "SUM", "PRODUCT", "MIN", "MAX", "AND", "OR". Please, several values are not supported for the backend like "horovod". Returns: @@ -347,7 +347,7 @@ def all_gather(tensor: Union[torch.Tensor, float, str]) -> Union[torch.Tensor, f """Helper method to perform all gather operation. Args: - tensor (torch.Tensor or number or str): tensor or number or str to collect across participating processes. + tensor: tensor or number or str to collect across participating processes. Returns: torch.Tensor of shape ``(world_size * tensor.shape[0], tensor.shape[1], ...)`` if input is a tensor or @@ -365,9 +365,9 @@ def broadcast(tensor: Union[torch.Tensor, float, str], src: int = 0) -> Union[to """Helper method to perform broadcast operation. Args: - tensor (torch.Tensor or number or str): tensor or number or str to broadcast to participating processes. + tensor: tensor or number or str to broadcast to participating processes. Make sure to respect dtype of torch tensor input for all processes, otherwise execution will crash. - src (int): source rank. Default, 0. + src: source rank. Default, 0. Returns: torch.Tensor or string or number @@ -434,7 +434,7 @@ def run(local_rank, *args, **kwargs): # ... Args: - index (int): local rank or current process index + index: local rank or current process index """ from ignite.distributed.comp_models.base import ComputationModel @@ -487,8 +487,8 @@ def train_fn(local_rank, a, b, c): Args: - backend (str, optional): backend: `nccl`, `gloo`, `xla-tpu`, `horovod`. - **kwargs: acceptable kwargs according to provided backend: + backend: backend: `nccl`, `gloo`, `xla-tpu`, `horovod`. + kwargs: acceptable kwargs according to provided backend: - "nccl" or "gloo" : timeout(=timedelta(minutes=30)). @@ -543,8 +543,8 @@ def one_rank_only(rank: int = 0, with_barrier: bool = False) -> Callable: """Decorator to filter handlers wrt a rank number Args: - rank (int): rank number of the handler (default: 0). - with_barrier (bool): synchronisation with a barrier (default: False). + rank: rank number of the handler (default: 0). + with_barrier: synchronisation with a barrier (default: False). .. code-block:: python From 557bd3d74e4d13a5d3d002858f3afa987b952030 Mon Sep 17 00:00:00 2001 From: ydcjeff Date: Tue, 23 Feb 2021 18:21:18 +0630 Subject: [PATCH 3/8] docs: rm type hints in ignite.contrib.metrics --- ignite/contrib/metrics/average_precision.py | 4 ++-- ignite/contrib/metrics/precision_recall_curve.py | 4 ++-- ignite/contrib/metrics/regression/canberra_metric.py | 10 ++++++++++ .../metrics/regression/fractional_absolute_error.py | 10 ++++++++++ ignite/contrib/metrics/regression/fractional_bias.py | 9 +++++++++ .../regression/geometric_mean_absolute_error.py | 10 ++++++++++ .../geometric_mean_relative_absolute_error.py | 9 +++++++++ .../contrib/metrics/regression/manhattan_distance.py | 10 ++++++++++ .../metrics/regression/maximum_absolute_error.py | 9 +++++++++ .../metrics/regression/mean_absolute_relative_error.py | 9 +++++++++ ignite/contrib/metrics/regression/mean_error.py | 9 +++++++++ .../contrib/metrics/regression/mean_normalized_bias.py | 9 +++++++++ .../metrics/regression/median_absolute_error.py | 9 +++++++++ .../regression/median_absolute_percentage_error.py | 9 +++++++++ .../regression/median_relative_absolute_error.py | 9 +++++++++ ignite/contrib/metrics/regression/r2_score.py | 10 ++++++++++ .../contrib/metrics/regression/wave_hedges_distance.py | 10 ++++++++++ ignite/contrib/metrics/roc_auc.py | 8 ++++---- 18 files changed, 149 insertions(+), 8 deletions(-) diff --git a/ignite/contrib/metrics/average_precision.py b/ignite/contrib/metrics/average_precision.py index dc2b197156ca..e0d1e138b7cb 100644 --- a/ignite/contrib/metrics/average_precision.py +++ b/ignite/contrib/metrics/average_precision.py @@ -22,11 +22,11 @@ class AveragePrecision(EpochMetric): sklearn.metrics.average_precision_score.html#sklearn.metrics.average_precision_score>`_ . Args: - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - check_compute_fn (bool): Default False. If True, `average_precision_score + check_compute_fn: Default False. If True, `average_precision_score `_ is run on the first batch of data to ensure there are no issues. User will be warned in case there are any issues computing the function. diff --git a/ignite/contrib/metrics/precision_recall_curve.py b/ignite/contrib/metrics/precision_recall_curve.py index 95016a2eb16d..d800784a145b 100644 --- a/ignite/contrib/metrics/precision_recall_curve.py +++ b/ignite/contrib/metrics/precision_recall_curve.py @@ -23,11 +23,11 @@ class PrecisionRecallCurve(EpochMetric): sklearn.metrics.precision_recall_curve.html#sklearn.metrics.precision_recall_curve>`_ . Args: - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - check_compute_fn (bool): Default False. If True, `precision_recall_curve + check_compute_fn: Default False. If True, `precision_recall_curve `_ is run on the first batch of data to ensure there are no issues. User will be warned in case there are any issues computing the function. diff --git a/ignite/contrib/metrics/regression/canberra_metric.py b/ignite/contrib/metrics/regression/canberra_metric.py index 5bb3cb8cca67..5566019d3591 100644 --- a/ignite/contrib/metrics/regression/canberra_metric.py +++ b/ignite/contrib/metrics/regression/canberra_metric.py @@ -22,6 +22,16 @@ class CanberraMetric(_BaseRegression): .. _scikit-learn distance metrics: https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.DistanceMetric.html + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. + .. versionchanged:: 0.4.3 - Fixed implementation: ``abs`` in denominator. diff --git a/ignite/contrib/metrics/regression/fractional_absolute_error.py b/ignite/contrib/metrics/regression/fractional_absolute_error.py index 1e3cd93b04a2..3fb7ba9d1e08 100644 --- a/ignite/contrib/metrics/regression/fractional_absolute_error.py +++ b/ignite/contrib/metrics/regression/fractional_absolute_error.py @@ -20,6 +20,16 @@ class FractionalAbsoluteError(_BaseRegression): - `y` and `y_pred` must be of same shape `(N, )` or `(N, 1)`. __ https://arxiv.org/abs/1809.03006 + + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def reset(self) -> None: diff --git a/ignite/contrib/metrics/regression/fractional_bias.py b/ignite/contrib/metrics/regression/fractional_bias.py index 5806243a9c9e..c05323626b80 100644 --- a/ignite/contrib/metrics/regression/fractional_bias.py +++ b/ignite/contrib/metrics/regression/fractional_bias.py @@ -21,6 +21,15 @@ class FractionalBias(_BaseRegression): __ https://arxiv.org/abs/1809.03006 + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def reset(self) -> None: diff --git a/ignite/contrib/metrics/regression/geometric_mean_absolute_error.py b/ignite/contrib/metrics/regression/geometric_mean_absolute_error.py index 7e3db6bec67e..21dfba3e5b41 100644 --- a/ignite/contrib/metrics/regression/geometric_mean_absolute_error.py +++ b/ignite/contrib/metrics/regression/geometric_mean_absolute_error.py @@ -20,6 +20,16 @@ class GeometricMeanAbsoluteError(_BaseRegression): - `y` and `y_pred` must be of same shape `(N, )` or `(N, 1)`. __ https://arxiv.org/abs/1809.03006 + + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def reset(self) -> None: diff --git a/ignite/contrib/metrics/regression/geometric_mean_relative_absolute_error.py b/ignite/contrib/metrics/regression/geometric_mean_relative_absolute_error.py index 89bda597b370..17b113cb9fe6 100644 --- a/ignite/contrib/metrics/regression/geometric_mean_relative_absolute_error.py +++ b/ignite/contrib/metrics/regression/geometric_mean_relative_absolute_error.py @@ -22,6 +22,15 @@ class GeometricMeanRelativeAbsoluteError(_BaseRegression): __ https://arxiv.org/abs/1809.03006 + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def reset(self) -> None: diff --git a/ignite/contrib/metrics/regression/manhattan_distance.py b/ignite/contrib/metrics/regression/manhattan_distance.py index 9d884196f17b..d4bd11137495 100644 --- a/ignite/contrib/metrics/regression/manhattan_distance.py +++ b/ignite/contrib/metrics/regression/manhattan_distance.py @@ -21,6 +21,16 @@ class ManhattanDistance(_BaseRegression): __ https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.DistanceMetric.html + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. + .. versionchanged:: 0.4.3 - Fixed sklearn compatibility. diff --git a/ignite/contrib/metrics/regression/maximum_absolute_error.py b/ignite/contrib/metrics/regression/maximum_absolute_error.py index be248d784a03..70267ccfa24f 100644 --- a/ignite/contrib/metrics/regression/maximum_absolute_error.py +++ b/ignite/contrib/metrics/regression/maximum_absolute_error.py @@ -21,6 +21,15 @@ class MaximumAbsoluteError(_BaseRegression): __ https://arxiv.org/abs/1809.03006 + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def reset(self) -> None: diff --git a/ignite/contrib/metrics/regression/mean_absolute_relative_error.py b/ignite/contrib/metrics/regression/mean_absolute_relative_error.py index 1b448a6387a3..a8323c63011f 100644 --- a/ignite/contrib/metrics/regression/mean_absolute_relative_error.py +++ b/ignite/contrib/metrics/regression/mean_absolute_relative_error.py @@ -21,6 +21,15 @@ class MeanAbsoluteRelativeError(_BaseRegression): __ https://arxiv.org/ftp/arxiv/papers/1809/1809.03006.pdf + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def reset(self) -> None: diff --git a/ignite/contrib/metrics/regression/mean_error.py b/ignite/contrib/metrics/regression/mean_error.py index cc537f3faf53..e84fe58e0f76 100644 --- a/ignite/contrib/metrics/regression/mean_error.py +++ b/ignite/contrib/metrics/regression/mean_error.py @@ -21,6 +21,15 @@ class MeanError(_BaseRegression): __ https://arxiv.org/abs/1809.03006 + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def reset(self) -> None: diff --git a/ignite/contrib/metrics/regression/mean_normalized_bias.py b/ignite/contrib/metrics/regression/mean_normalized_bias.py index d10ec9170b00..b338556c0983 100644 --- a/ignite/contrib/metrics/regression/mean_normalized_bias.py +++ b/ignite/contrib/metrics/regression/mean_normalized_bias.py @@ -21,6 +21,15 @@ class MeanNormalizedBias(_BaseRegression): __ https://arxiv.org/abs/1809.03006 + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def reset(self) -> None: diff --git a/ignite/contrib/metrics/regression/median_absolute_error.py b/ignite/contrib/metrics/regression/median_absolute_error.py index a99f392a126d..616938ec4670 100644 --- a/ignite/contrib/metrics/regression/median_absolute_error.py +++ b/ignite/contrib/metrics/regression/median_absolute_error.py @@ -31,6 +31,15 @@ class MedianAbsoluteError(_BaseRegressionEpoch): __ https://arxiv.org/abs/1809.03006 + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def __init__(self, output_transform: Callable = lambda x: x): diff --git a/ignite/contrib/metrics/regression/median_absolute_percentage_error.py b/ignite/contrib/metrics/regression/median_absolute_percentage_error.py index 54929e6b642e..eac9492d6f52 100644 --- a/ignite/contrib/metrics/regression/median_absolute_percentage_error.py +++ b/ignite/contrib/metrics/regression/median_absolute_percentage_error.py @@ -31,6 +31,15 @@ class MedianAbsolutePercentageError(_BaseRegressionEpoch): __ https://arxiv.org/abs/1809.03006 + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def __init__(self, output_transform: Callable = lambda x: x): diff --git a/ignite/contrib/metrics/regression/median_relative_absolute_error.py b/ignite/contrib/metrics/regression/median_relative_absolute_error.py index 1d61f9fc7d7a..729b4353d058 100644 --- a/ignite/contrib/metrics/regression/median_relative_absolute_error.py +++ b/ignite/contrib/metrics/regression/median_relative_absolute_error.py @@ -31,6 +31,15 @@ class MedianRelativeAbsoluteError(_BaseRegressionEpoch): __ https://arxiv.org/abs/1809.03006 + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def __init__(self, output_transform: Callable = lambda x: x): diff --git a/ignite/contrib/metrics/regression/r2_score.py b/ignite/contrib/metrics/regression/r2_score.py index f48adf22e33d..d6df3e1b0ca3 100644 --- a/ignite/contrib/metrics/regression/r2_score.py +++ b/ignite/contrib/metrics/regression/r2_score.py @@ -20,6 +20,16 @@ class R2Score(_BaseRegression): - ``update`` must receive output of the form ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - `y` and `y_pred` must be of same shape `(N, )` or `(N, 1)` and of type `float32`. + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. + .. versionchanged:: 0.4.3 Works with DDP. """ diff --git a/ignite/contrib/metrics/regression/wave_hedges_distance.py b/ignite/contrib/metrics/regression/wave_hedges_distance.py index 6e436ba68136..6125e6cb1209 100644 --- a/ignite/contrib/metrics/regression/wave_hedges_distance.py +++ b/ignite/contrib/metrics/regression/wave_hedges_distance.py @@ -19,6 +19,16 @@ class WaveHedgesDistance(_BaseRegression): - `y` and `y_pred` must be of same shape `(N, )` or `(N, 1)`. __ https://arxiv.org/abs/1809.03006 + + Args: + output_transform: a callable that is used to transform the + :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. + By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. + device: specifies which device updates are accumulated on. Setting the + metric's device to be the same as your ``update`` arguments ensures the ``update`` method is + non-blocking. By default, CPU. """ def reset(self) -> None: diff --git a/ignite/contrib/metrics/roc_auc.py b/ignite/contrib/metrics/roc_auc.py index c54492be862f..750835d08b0c 100644 --- a/ignite/contrib/metrics/roc_auc.py +++ b/ignite/contrib/metrics/roc_auc.py @@ -34,11 +34,11 @@ class ROC_AUC(EpochMetric): sklearn.metrics.roc_auc_score.html#sklearn.metrics.roc_auc_score>`_ . Args: - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - check_compute_fn (bool): Default False. If True, `roc_curve + check_compute_fn: Default False. If True, `roc_curve `_ is run on the first batch of data to ensure there are no issues. User will be warned in case there are any issues computing the function. @@ -70,11 +70,11 @@ class RocCurve(EpochMetric): sklearn.metrics.roc_curve.html#sklearn.metrics.roc_curve>`_ . Args: - output_transform (callable, optional): a callable that is used to transform the + output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - check_compute_fn (bool): Default False. If True, `sklearn.metrics.roc_curve + check_compute_fn: Default False. If True, `sklearn.metrics.roc_curve `_ is run on the first batch of data to ensure there are no issues. User will be warned in case there are any issues computing the function. From 5386228fe8a79e5a9a506fa6218232dc9ffaf27b Mon Sep 17 00:00:00 2001 From: ydcjeff Date: Tue, 23 Feb 2021 22:01:05 +0630 Subject: [PATCH 4/8] fix: sphinx back to 3.2.1 --- docs/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index f7b4ab9b632e..4c94a44e1dc8 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,3 @@ -sphinx==3.4 +sphinx==3.2.1 -e git+https://github.com/pytorch/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme sphinxcontrib-katex From c43482031b5b61ed7cad9568a247e2e1e6b2a2ef Mon Sep 17 00:00:00 2001 From: ydcjeff Date: Wed, 24 Feb 2021 18:02:17 +0630 Subject: [PATCH 5/8] Revert "docs: rm type hints in ignite.metrics" This reverts commit a94b50e8ec85cc1d81cec9e9f28edaf1725ee34b. --- ignite/metrics/accumulation.py | 14 +++--- ignite/metrics/accuracy.py | 6 +-- ignite/metrics/confusion_matrix.py | 30 ++++++------ ignite/metrics/epoch_metric.py | 8 ++-- ignite/metrics/fbeta.py | 12 ++--- ignite/metrics/loss.py | 8 ++-- ignite/metrics/mean_absolute_error.py | 10 ---- ignite/metrics/mean_pairwise_distance.py | 12 ----- ignite/metrics/mean_squared_error.py | 10 ---- ignite/metrics/metric.py | 46 +++++++++---------- ignite/metrics/metrics_lambda.py | 6 +-- ignite/metrics/multilabel_confusion_matrix.py | 7 ++- ignite/metrics/precision.py | 8 ++-- ignite/metrics/psnr.py | 6 +-- ignite/metrics/recall.py | 8 ++-- ignite/metrics/root_mean_squared_error.py | 10 ---- ignite/metrics/running_average.py | 10 ++-- ignite/metrics/ssim.py | 16 +++---- ignite/metrics/top_k_categorical_accuracy.py | 11 ----- 19 files changed, 90 insertions(+), 148 deletions(-) diff --git a/ignite/metrics/accumulation.py b/ignite/metrics/accumulation.py index 6a1d7091d58a..c26d1758d79f 100644 --- a/ignite/metrics/accumulation.py +++ b/ignite/metrics/accumulation.py @@ -25,13 +25,13 @@ class VariableAccumulation(Metric): - `+batch_size` if input is a ND `torch.Tensor`. Batch size is the first dimension (`shape[0]`). Args: - op: a callable to update accumulator. Method's signature is `(accumulator, output)`. + op (callable): a callable to update accumulator. Method's signature is `(accumulator, output)`. For example, to compute arithmetic mean value, `op = lambda a, x: a + x`. - output_transform: a callable that is used to transform the + output_transform (callable, optional): a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - device: specifies which device updates are accumulated on. Setting the metric's + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. @@ -112,11 +112,11 @@ class Average(VariableAccumulation): # state.metrics['mean_custom_var'] -> average of output['custom_var'] Args: - output_transform: a callable that is used to transform the + output_transform (callable, optional): a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - device: specifies which device updates are accumulated on. Setting the metric's + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. """ @@ -159,11 +159,11 @@ class GeometricAverage(VariableAccumulation): is aggregated and added to the accumulator: `accumulator *= prod(x, dim=0)` Args: - output_transform: a callable that is used to transform the + output_transform (callable, optional): a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - device: specifies which device updates are accumulated on. Setting the metric's + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/accuracy.py b/ignite/metrics/accuracy.py index 542adb16ec93..460fec31688e 100644 --- a/ignite/metrics/accuracy.py +++ b/ignite/metrics/accuracy.py @@ -119,12 +119,12 @@ def thresholded_output_transform(output): Args: - output_transform: a callable that is used to transform the + output_transform (callable, optional): a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - is_multilabel: flag to use in multilabel case. By default, False. - device: specifies which device updates are accumulated on. Setting the metric's + is_multilabel (bool, optional): flag to use in multilabel case. By default, False. + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/confusion_matrix.py b/ignite/metrics/confusion_matrix.py index c03bd0929952..2694148ead19 100644 --- a/ignite/metrics/confusion_matrix.py +++ b/ignite/metrics/confusion_matrix.py @@ -21,17 +21,17 @@ class ConfusionMatrix(Metric): predicted classes. Args: - num_classes: Number of classes, should be > 1. See notes for more details. - average: confusion matrix values averaging schema: None, "samples", "recall", "precision". + num_classes (int): Number of classes, should be > 1. See notes for more details. + average (str, optional): confusion matrix values averaging schema: None, "samples", "recall", "precision". Default is None. If `average="samples"` then confusion matrix values are normalized by the number of seen samples. If `average="recall"` then confusion matrix values are normalized such that diagonal values represent class recalls. If `average="precision"` then confusion matrix values are normalized such that diagonal values represent class precisions. - output_transform: a callable that is used to transform the + output_transform (callable, optional): a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - device: specifies which device updates are accumulated on. Setting the metric's + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. @@ -161,8 +161,8 @@ def IoU(cm: ConfusionMatrix, ignore_index: Optional[int] = None) -> MetricsLambd .. math:: \text{J}(A, B) = \frac{ \lvert A \cap B \rvert }{ \lvert A \cup B \rvert } Args: - cm: instance of confusion matrix metric - ignore_index: index to ignore, e.g. background index + cm (ConfusionMatrix): instance of confusion matrix metric + ignore_index (int, optional): index to ignore, e.g. background index Returns: MetricsLambda @@ -212,8 +212,8 @@ def mIoU(cm: ConfusionMatrix, ignore_index: Optional[int] = None) -> MetricsLamb """Calculates mean Intersection over Union using :class:`~ignite.metrics.ConfusionMatrix` metric. Args: - cm: instance of confusion matrix metric - ignore_index: index to ignore, e.g. background index + cm (ConfusionMatrix): instance of confusion matrix metric + ignore_index (int, optional): index to ignore, e.g. background index Returns: MetricsLambda @@ -240,7 +240,7 @@ def cmAccuracy(cm: ConfusionMatrix) -> MetricsLambda: """Calculates accuracy using :class:`~ignite.metrics.ConfusionMatrix` metric. Args: - cm: instance of confusion matrix metric + cm (ConfusionMatrix): instance of confusion matrix metric Returns: MetricsLambda @@ -255,8 +255,8 @@ def cmPrecision(cm: ConfusionMatrix, average: bool = True) -> MetricsLambda: """Calculates precision using :class:`~ignite.metrics.ConfusionMatrix` metric. Args: - cm: instance of confusion matrix metric - average: if True metric value is averaged over all classes + cm (ConfusionMatrix): instance of confusion matrix metric + average (bool, optional): if True metric value is averaged over all classes Returns: MetricsLambda """ @@ -274,8 +274,8 @@ def cmRecall(cm: ConfusionMatrix, average: bool = True) -> MetricsLambda: """ Calculates recall using :class:`~ignite.metrics.ConfusionMatrix` metric. Args: - cm: instance of confusion matrix metric - average: if True metric value is averaged over all classes + cm (ConfusionMatrix): instance of confusion matrix metric + average (bool, optional): if True metric value is averaged over all classes Returns: MetricsLambda """ @@ -293,8 +293,8 @@ def DiceCoefficient(cm: ConfusionMatrix, ignore_index: Optional[int] = None) -> """Calculates Dice Coefficient for a given :class:`~ignite.metrics.ConfusionMatrix` metric. Args: - cm: instance of confusion matrix metric - ignore_index: index to ignore, e.g. background index + cm (ConfusionMatrix): instance of confusion matrix metric + ignore_index (int, optional): index to ignore, e.g. background index """ if not isinstance(cm, ConfusionMatrix): diff --git a/ignite/metrics/epoch_metric.py b/ignite/metrics/epoch_metric.py index 2ad5511dbbb6..cc8f3ec4a7c0 100644 --- a/ignite/metrics/epoch_metric.py +++ b/ignite/metrics/epoch_metric.py @@ -31,17 +31,17 @@ class EpochMetric(Metric): e.g. ``[[0, 1, 0, 1], ]``. Args: - compute_fn: a callable with the signature (`torch.tensor`, `torch.tensor`) takes as the input + compute_fn (callable): a callable with the signature (`torch.tensor`, `torch.tensor`) takes as the input `predictions` and `targets` and returns a scalar. Input tensors will be on specified ``device`` (see arg below). - output_transform: a callable that is used to transform the + output_transform (callable, optional): a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - check_compute_fn: if True, ``compute_fn`` is run on the first batch of data to ensure there are no + check_compute_fn (bool): if True, ``compute_fn`` is run on the first batch of data to ensure there are no issues. If issues exist, user is warned that there might be an issue with the ``compute_fn``. Default, True. - device: optional device specification for internal storage. + device (str or torch.device, optional): optional device specification for internal storage. Warnings: EpochMetricWarning: User is warned that there are issues with ``compute_fn`` on a batch of data processed. diff --git a/ignite/metrics/fbeta.py b/ignite/metrics/fbeta.py index 65f18a4e28cd..b417445c10ae 100644 --- a/ignite/metrics/fbeta.py +++ b/ignite/metrics/fbeta.py @@ -26,15 +26,15 @@ def Fbeta( where :math:`\beta` is a positive real factor. Args: - beta: weight of precision in harmonic mean - average: if True, F-beta score is computed as the unweighted average (across all classes + beta (float): weight of precision in harmonic mean + average (bool, optional): if True, F-beta score is computed as the unweighted average (across all classes in multiclass case), otherwise, returns a tensor with F-beta score for each class in multiclass case. - precision: precision object metric with `average=False` to compute F-beta score - recall: recall object metric with `average=False` to compute F-beta score - output_transform: a callable that is used to transform the + precision (Precision, optional): precision object metric with `average=False` to compute F-beta score + recall (Precision, optional): recall object metric with `average=False` to compute F-beta score + output_transform (callable, optional): a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the form expected by the metric. It is used only if precision or recall are not provided. - device: specifies which device updates are accumulated on. Setting the metric's + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/loss.py b/ignite/metrics/loss.py index 72f3b30d5e66..5991059ce26a 100644 --- a/ignite/metrics/loss.py +++ b/ignite/metrics/loss.py @@ -13,10 +13,10 @@ class Loss(Metric): Calculates the average loss according to the passed loss_fn. Args: - loss_fn: a callable taking a prediction tensor, a target + loss_fn (callable): a callable taking a prediction tensor, a target tensor, optionally other arguments, and returns the average loss over all observations in the batch. - output_transform: a callable that is used to transform the + output_transform (callable): a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the form expected by the metric. This can be useful if, for example, you have a multi-output model and @@ -24,9 +24,9 @@ class Loss(Metric): The output is expected to be a tuple `(prediction, target)` or (prediction, target, kwargs) where kwargs is a dictionary of extra keywords arguments. If extra keywords arguments are provided they are passed to `loss_fn`. - batch_size: a callable taking a target tensor that returns the + batch_size (callable): a callable taking a target tensor that returns the first dimension size (usually the batch size). - device: specifies which device updates are accumulated on. Setting the + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/mean_absolute_error.py b/ignite/metrics/mean_absolute_error.py index f93b08453ce4..461ed54f8ab2 100644 --- a/ignite/metrics/mean_absolute_error.py +++ b/ignite/metrics/mean_absolute_error.py @@ -16,16 +16,6 @@ class MeanAbsoluteError(Metric): where :math:`y_{i}` is the prediction tensor and :math:`x_{i}` is ground true tensor. - ``update`` must receive output of the form ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - - Args: - output_transform: a callable that is used to transform the - :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - device: specifies which device updates are accumulated on. Setting the - metric's device to be the same as your ``update`` arguments ensures the ``update`` method is - non-blocking. By default, CPU. """ @reinit__is_reduced diff --git a/ignite/metrics/mean_pairwise_distance.py b/ignite/metrics/mean_pairwise_distance.py index fc3a9ad68ae1..9751e8797a42 100644 --- a/ignite/metrics/mean_pairwise_distance.py +++ b/ignite/metrics/mean_pairwise_distance.py @@ -14,18 +14,6 @@ class MeanPairwiseDistance(Metric): Average of pairwise distances computed on provided batches. - ``update`` must receive output of the form ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - - Args: - p: the norm degree. Default: 2 - eps: Small value to avoid division by zero. Default: 1e-6 - output_transform: a callable that is used to transform the - :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - device: specifies which device updates are accumulated on. Setting the - metric's device to be the same as your ``update`` arguments ensures the ``update`` method is - non-blocking. By default, CPU. """ def __init__( diff --git a/ignite/metrics/mean_squared_error.py b/ignite/metrics/mean_squared_error.py index 131c04b2efd6..682b56756bf0 100644 --- a/ignite/metrics/mean_squared_error.py +++ b/ignite/metrics/mean_squared_error.py @@ -16,16 +16,6 @@ class MeanSquaredError(Metric): where :math:`y_{i}` is the prediction tensor and :math:`x_{i}` is ground true tensor. - ``update`` must receive output of the form ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - - Args: - output_transform: a callable that is used to transform the - :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - device: specifies which device updates are accumulated on. Setting the - metric's device to be the same as your ``update`` arguments ensures the ``update`` method is - non-blocking. By default, CPU. """ @reinit__is_reduced diff --git a/ignite/metrics/metric.py b/ignite/metrics/metric.py index 02e2acba7de9..053d7d0224ba 100644 --- a/ignite/metrics/metric.py +++ b/ignite/metrics/metric.py @@ -60,10 +60,10 @@ class EpochWise(MetricUsage): - :meth:`~ignite.metrics.Metric.completed` on every ``EPOCH_COMPLETED``. Attributes: - usage_name: usage name string + usage_name (str): usage name string """ - usage_name: str = "epoch_wise" + usage_name = "epoch_wise" def __init__(self) -> None: super(EpochWise, self).__init__( @@ -84,10 +84,10 @@ class BatchWise(MetricUsage): - :meth:`~ignite.metrics.Metric.completed` on every ``ITERATION_COMPLETED``. Attributes: - usage_name: usage name string + usage_name (str): usage name string """ - usage_name: str = "batch_wise" + usage_name = "batch_wise" def __init__(self) -> None: super(BatchWise, self).__init__( @@ -108,8 +108,8 @@ class BatchFiltered(MetricUsage): - :meth:`~ignite.metrics.Metric.completed` on every ``EPOCH_COMPLETED``. Args: - args: Positional arguments to setup :attr:`~ignite.engine.events.Events.ITERATION_COMPLETED(*args, **kwargs)` - kwargs: Keyword arguments to setup :attr:`~ignite.engine.events.Events.ITERATION_COMPLETED(*args, **kwargs)` + *args: Positional arguments to setup :attr:`~ignite.engine.events.Events.ITERATION_COMPLETED(*args, **kwargs)` + **kwargs: Keyword arguments to setup :attr:`~ignite.engine.events.Events.ITERATION_COMPLETED(*args, **kwargs)` handled by :meth:`~ignite.metrics.Metric.iteration_completed`. """ @@ -127,17 +127,17 @@ class Metric(metaclass=ABCMeta): Base class for all Metrics. Args: - output_transform: a callable that is used to transform the + output_transform (callable, optional): a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - device: specifies which device updates are accumulated on. Setting the + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. Attributes: - required_output_keys: dictionary defines required keys to be found in ``engine.state.output`` if the + required_output_keys (tuple): dictionary defines required keys to be found in ``engine.state.output`` if the latter is a dictionary. Default, ``("y_pred", "y")``. This is useful with custom metrics that can require other arguments than predictions ``y_pred`` and targets ``y``. See notes below for an example. @@ -196,7 +196,7 @@ def compute(self): """ # public class attribute - required_output_keys: Optional[Tuple] = ("y_pred", "y") + required_output_keys = ("y_pred", "y") # type: Optional[Tuple] # for backward compatibility _required_output_keys = required_output_keys @@ -267,7 +267,7 @@ def started(self, engine: Engine) -> None: `engine` with :meth:`~ignite.metrics.Metric.attach`. Args: - engine: the engine to which the metric must be attached + engine (Engine): the engine to which the metric must be attached """ self.reset() @@ -277,7 +277,7 @@ def iteration_completed(self, engine: Engine) -> None: `engine` with :meth:`~ignite.metrics.Metric.attach`. Args: - engine: the engine to which the metric must be attached + engine (Engine): the engine to which the metric must be attached """ output = self._output_transform(engine.state.output) @@ -300,8 +300,8 @@ def completed(self, engine: Engine, name: str) -> None: `engine` with :meth:`~ignite.metrics.Metric.attach`. Args: - engine: the engine to which the metric must be attached - name: the name of the metric used as key in dict `engine.state.metrics` + engine (Engine): the engine to which the metric must be attached + name (str): the name of the metric used as key in dict `engine.state.metrics` .. versionchanged:: 0.4.3 Added dict in metrics results. @@ -338,9 +338,9 @@ def attach(self, engine: Engine, name: str, usage: Union[str, MetricUsage] = Epo contain computed metric's value under provided name. Args: - engine: the engine to which the metric must be attached - name: the name of the metric to attach - usage: the usage of the metric. Valid string values should be + engine (Engine): the engine to which the metric must be attached + name (str): the name of the metric to attach + usage (str or MetricUsage, optional): the usage of the metric. Valid string values should be :attr:`ignite.metrics.EpochWise.usage_name` (default) or :attr:`ignite.metrics.BatchWise.usage_name`. @@ -381,8 +381,8 @@ def detach(self, engine: Engine, usage: Union[str, MetricUsage] = EpochWise()) - and another metric (e.g. more expensive one) is done every n-th training epoch. Args: - engine: the engine from which the metric must be detached - usage: the usage of the metric. Valid string values should be + engine (Engine): the engine from which the metric must be detached + usage (str or MetricUsage, optional): the usage of the metric. Valid string values should be 'epoch_wise' (default) or 'batch_wise'. Example: @@ -423,8 +423,8 @@ def is_attached(self, engine: Engine, usage: Union[str, MetricUsage] = EpochWise value is written to `engine.state.metrics` dictionary. Args: - engine: the engine checked from which the metric should be attached - usage: the usage of the metric. Valid string values should be + engine (Engine): the engine checked from which the metric should be attached + usage (str or MetricUsage, optional): the usage of the metric. Valid string values should be 'epoch_wise' (default) or 'batch_wise'. """ usage = self._check_usage(usage) @@ -530,7 +530,7 @@ def sync_all_reduce(*attrs: Any) -> Callable: See :doc:`metrics` on how to use it. Args: - attrs: attribute names of decorated class + *attrs: attribute names of decorated class """ @@ -566,8 +566,6 @@ def reinit__is_reduced(func: Callable) -> Callable: See :doc:`metrics` on how to use it. - Args: - func: A callable to reinit. """ @wraps(func) diff --git a/ignite/metrics/metrics_lambda.py b/ignite/metrics/metrics_lambda.py index eb41e101bb11..6514b71cfd00 100644 --- a/ignite/metrics/metrics_lambda.py +++ b/ignite/metrics/metrics_lambda.py @@ -21,11 +21,9 @@ class MetricsLambda(Metric): automatically (but partially, e.g :meth:`~ignite.metrics.Metric.is_attached()` will return False). Args: - f: the function that defines the computation - args: Sequence of other metrics or something + f (callable): the function that defines the computation + args (sequence): Sequence of other metrics or something else that will be fed to ``f`` as arguments. - kwargs: Sequence of other metrics or something - else that will be fed to ``f`` as keyword arguments. Example: diff --git a/ignite/metrics/multilabel_confusion_matrix.py b/ignite/metrics/multilabel_confusion_matrix.py index 673a154624ef..20f13fb7e525 100644 --- a/ignite/metrics/multilabel_confusion_matrix.py +++ b/ignite/metrics/multilabel_confusion_matrix.py @@ -30,15 +30,14 @@ class MultiLabelConfusionMatrix(Metric): - The classes present in M are indexed as 0, ... , num_classes-1 as can be inferred from above. Args: - num_classes: Number of classes, should be > 1. - output_transform: a callable that is used to transform the + num_classes (int): Number of classes, should be > 1. + output_transform (callable, optional): a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - device: specifies which device updates are accumulated on. Setting the metric's + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. - normalized: whether to normalized confusion matrix by its sum or not. .. versionadded:: 0.5.0 diff --git a/ignite/metrics/precision.py b/ignite/metrics/precision.py index ed31eebe27c7..50142b7f78a3 100644 --- a/ignite/metrics/precision.py +++ b/ignite/metrics/precision.py @@ -103,15 +103,15 @@ def thresholded_output_transform(output): Args: - output_transform: a callable that is used to transform the + output_transform (callable, optional): a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - average: if True, precision is computed as the unweighted average (across all classes + average (bool, optional): if True, precision is computed as the unweighted average (across all classes in multiclass case), otherwise, returns a tensor with the precision (for each class in multiclass case). - is_multilabel: flag to use in multilabel case. By default, value is False. If True, average + is_multilabel (bool, optional) flag to use in multilabel case. By default, value is False. If True, average parameter should be True and the average is computed across samples, instead of classes. - device: specifies which device updates are accumulated on. Setting the metric's + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/psnr.py b/ignite/metrics/psnr.py index 7e930abb4ef6..8c00dba78725 100644 --- a/ignite/metrics/psnr.py +++ b/ignite/metrics/psnr.py @@ -20,12 +20,12 @@ class PSNR(Metric): - `y_pred` and `y` **must** have same dtype and same shape. Args: - data_range: The data range of the target image (distance between minimum + data_range (int or float): The data range of the target image (distance between minimum and maximum possible values). For other data types, please set the data range, otherwise an exception will be raised. - output_transform: A callable that is used to transform the Engine’s + output_transform (callable, optional): A callable that is used to transform the Engine’s process_function’s output into the form expected by the metric. - device: specifies which device updates are accumulated on. + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric’s device to be the same as your update arguments ensures the update method is non-blocking. By default, CPU. diff --git a/ignite/metrics/recall.py b/ignite/metrics/recall.py index 9ef4316c8806..a11cb7d583bf 100644 --- a/ignite/metrics/recall.py +++ b/ignite/metrics/recall.py @@ -50,15 +50,15 @@ def thresholded_output_transform(output): Args: - output_transform: a callable that is used to transform the + output_transform (callable, optional): a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - average: if True, precision is computed as the unweighted average (across all classes + average (bool, optional): if True, precision is computed as the unweighted average (across all classes in multiclass case), otherwise, returns a tensor with the precision (for each class in multiclass case). - is_multilabel: flag to use in multilabel case. By default, value is False. If True, average + is_multilabel (bool, optional) flag to use in multilabel case. By default, value is False. If True, average parameter should be True and the average is computed across samples, instead of classes. - device: specifies which device updates are accumulated on. Setting the metric's + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/root_mean_squared_error.py b/ignite/metrics/root_mean_squared_error.py index 47722862970b..0197fcceca34 100644 --- a/ignite/metrics/root_mean_squared_error.py +++ b/ignite/metrics/root_mean_squared_error.py @@ -16,16 +16,6 @@ class RootMeanSquaredError(MeanSquaredError): where :math:`y_{i}` is the prediction tensor and :math:`x_{i}` is ground true tensor. - ``update`` must receive output of the form (y_pred, y) or `{'y_pred': y_pred, 'y': y}`. - - Args: - output_transform: a callable that is used to transform the - :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - device: specifies which device updates are accumulated on. Setting the - metric's device to be the same as your ``update`` arguments ensures the ``update`` method is - non-blocking. By default, CPU. """ def compute(self) -> Union[torch.Tensor, float]: diff --git a/ignite/metrics/running_average.py b/ignite/metrics/running_average.py index d5c251d2b859..db36b1a90483 100644 --- a/ignite/metrics/running_average.py +++ b/ignite/metrics/running_average.py @@ -13,14 +13,14 @@ class RunningAverage(Metric): """Compute running average of a metric or the output of process function. Args: - src: input source: an instance of :class:`~ignite.metrics.Metric` or None. The latter + src (Metric or None): input source: an instance of :class:`~ignite.metrics.Metric` or None. The latter corresponds to `engine.state.output` which holds the output of process function. - alpha: running average decay factor, default 0.98 - output_transform: a function to use to transform the output if `src` is None and + alpha (float, optional): running average decay factor, default 0.98 + output_transform (callable, optional): a function to use to transform the output if `src` is None and corresponds the output of process function. Otherwise it should be None. - epoch_bound: whether the running average should be reset after each epoch (defaults + epoch_bound (boolean, optional): whether the running average should be reset after each epoch (defaults to True). - device: specifies which device updates are accumulated on. Should be + device (str or torch.device, optional): specifies which device updates are accumulated on. Should be None when ``src`` is an instance of :class:`~ignite.metrics.Metric`, as the running average will use the ``src``'s device. Otherwise, defaults to CPU. Only applicable when the computed value from the metric is a tensor. diff --git a/ignite/metrics/ssim.py b/ignite/metrics/ssim.py index 67f3941050c5..664ee35ffbd8 100644 --- a/ignite/metrics/ssim.py +++ b/ignite/metrics/ssim.py @@ -14,17 +14,17 @@ class SSIM(Metric): Computes Structual Similarity Index Measure Args: - data_range: Range of the image. Typically, ``1.0`` or ``255``. - kernel_size: Size of the kernel. Default: (11, 11) - sigma: Standard deviation of the gaussian kernel. + data_range (int or float): Range of the image. Typically, ``1.0`` or ``255``. + kernel_size (int or list or tuple of int): Size of the kernel. Default: (11, 11) + sigma (float or list or tuple of float): Standard deviation of the gaussian kernel. Argument is used if ``gaussian=True``. Default: (1.5, 1.5) - k1: Parameter of SSIM. Default: 0.01 - k2: Parameter of SSIM. Default: 0.03 - gaussian: ``True`` to use gaussian kernel, ``False`` to use uniform kernel - output_transform: A callable that is used to transform the + k1 (float): Parameter of SSIM. Default: 0.01 + k2 (float): Parameter of SSIM. Default: 0.03 + gaussian (bool): ``True`` to use gaussian kernel, ``False`` to use uniform kernel + output_transform (callable, optional): A callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the form expected by the metric. - device: specifies which device updates are accumulated on. Setting the metric's + device (str or torch.device): specifies which device updates are accumulated on. Setting the metric's device to be the same as your ``update`` arguments ensures the ``update`` method is non-blocking. By default, CPU. diff --git a/ignite/metrics/top_k_categorical_accuracy.py b/ignite/metrics/top_k_categorical_accuracy.py index b6bec2de3970..20d948003ebc 100644 --- a/ignite/metrics/top_k_categorical_accuracy.py +++ b/ignite/metrics/top_k_categorical_accuracy.py @@ -13,17 +13,6 @@ class TopKCategoricalAccuracy(Metric): Calculates the top-k categorical accuracy. - ``update`` must receive output of the form ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - - Args: - k: the k in “top-k”. - output_transform: a callable that is used to transform the - :class:`~ignite.engine.engine.Engine`'s ``process_function``'s 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. - By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - device: specifies which device updates are accumulated on. Setting the - metric's device to be the same as your ``update`` arguments ensures the ``update`` method is - non-blocking. By default, CPU. """ def __init__( From 0384a26de5fed00d1b02783c106aeab533bb3dc6 Mon Sep 17 00:00:00 2001 From: ydcjeff Date: Wed, 24 Feb 2021 18:03:07 +0630 Subject: [PATCH 6/8] Revert "docs: rm type hints in ignite.distributed" This reverts commit 2179df5dd510acf05f17262513d2e4d6682992da. --- ignite/distributed/auto.py | 18 +++++++++--------- ignite/distributed/launcher.py | 20 ++++++++++---------- ignite/distributed/utils.py | 34 +++++++++++++++++----------------- 3 files changed, 36 insertions(+), 36 deletions(-) diff --git a/ignite/distributed/auto.py b/ignite/distributed/auto.py index 1d6a585b0e63..9764e38db6f7 100644 --- a/ignite/distributed/auto.py +++ b/ignite/distributed/auto.py @@ -50,8 +50,8 @@ def auto_dataloader(dataset: Dataset, **kwargs: Any) -> Union[DataLoader, "_MpDe ) Args: - dataset: input torch dataset - kwargs: keyword arguments for `torch DataLoader`_. + dataset (Dataset): input torch dataset + **kwargs: keyword arguments for `torch DataLoader`_. Returns: `torch DataLoader`_ or `XLA MpDeviceLoader`_ for XLA devices @@ -154,11 +154,11 @@ def auto_model(model: nn.Module, sync_bn: bool = False, **kwargs: Any) -> nn.Mod model = idist.auto_model(model) Args: - model: model to adapt. - sync_bn: if True, applies `torch convert_sync_batchnorm`_ to the model for native torch + model (torch.nn.Module): model to adapt. + sync_bn (bool): if True, applies `torch convert_sync_batchnorm`_ to the model for native torch distributed only. Default, False. Note, if using Nvidia/Apex, batchnorm conversion should be applied before calling ``amp.initialize``. - kwargs: kwargs to model's wrapping class: `torch DistributedDataParallel`_ or `torch DataParallel`_ + **kwargs: kwargs to model's wrapping class: `torch DistributedDataParallel`_ or `torch DataParallel`_ if applicable. Please, make sure to use acceptable kwargs for given backend. Returns: @@ -241,7 +241,7 @@ def auto_optim(optimizer: Optimizer) -> Optimizer: optimizer = idist.auto_optim(optimizer) Args: - optimizer: input torch optimizer + optimizer (Optimizer): input torch optimizer Returns: Optimizer @@ -276,9 +276,9 @@ class DistributedProxySampler(DistributedSampler): Input sampler is assumed to have a constant size. Args: - sampler: Input torch data sampler. - num_replicas: Number of processes participating in distributed training. - rank: Rank of the current process within ``num_replicas``. + sampler (Sampler): Input torch data sampler. + num_replicas (int, optional): Number of processes participating in distributed training. + rank (int, optional): Rank of the current process within ``num_replicas``. """ diff --git a/ignite/distributed/launcher.py b/ignite/distributed/launcher.py index 4d24979fee47..28f1a036c842 100644 --- a/ignite/distributed/launcher.py +++ b/ignite/distributed/launcher.py @@ -152,25 +152,25 @@ def training(local_rank, config, **kwargs): .. _horovodrun: https://horovod.readthedocs.io/en/latest/api.html#module-horovod.run Args: - backend: backend to use: `nccl`, `gloo`, `xla-tpu`, `horovod`. If None, no distributed + backend (str, optional): backend to use: `nccl`, `gloo`, `xla-tpu`, `horovod`. If None, no distributed configuration. - nproc_per_node: optional argument, number of processes per + nproc_per_node (int, optional): optional argument, number of processes per node to specify. If not None, :meth:`~ignite.distributed.Parallel.run` will spawn ``nproc_per_node`` processes that run input function with its arguments. - nnodes: optional argument, number of nodes participating in distributed configuration. + nnodes (int, optional): optional argument, number of nodes participating in distributed configuration. If not None, :meth:`~ignite.distributed.Parallel.run` will spawn ``nproc_per_node`` processes that run input function with its arguments. Total world size is `nproc_per_node * nnodes`. This option is only supported by native torch distributed module. For other modules, please setup ``spawn_kwargs`` with backend specific arguments. - node_rank: optional argument, current machine index. Mandatory argument if ``nnodes`` is + node_rank (int, optional): optional argument, current machine index. Mandatory argument if ``nnodes`` is specified and larger than one. This option is only supported by native torch distributed module. For other modules, please setup ``spawn_kwargs`` with backend specific arguments. - master_addr: optional argument, master node TCP/IP address for torch native backends + master_addr (str, optional): optional argument, master node TCP/IP address for torch native backends (`nccl`, `gloo`). Mandatory argument if ``nnodes`` is specified and larger than one. - master_port: optional argument, master node port for torch native backends + master_port (int, optional): optional argument, master node port for torch native backends (`nccl`, `gloo`). Mandatory argument if ``master_addr`` is specified. - spawn_kwargs: kwargs to ``idist.spawn`` function. + **spawn_kwargs: kwargs to ``idist.spawn`` function. .. versionchanged:: 0.4.2 ``backend`` now accepts `horovod` distributed framework. @@ -264,10 +264,10 @@ def training(local_rank, config, **kwargs): parallel.run(training, config, a=1, b=2) Args: - func: function to execute. First argument of the function should be `local_rank` - local process + func (Callable): function to execute. First argument of the function should be `local_rank` - local process index. - args: positional arguments of ``func`` (without `local_rank`). - kwargs: keyword arguments of ``func``. + *args: positional arguments of ``func`` (without `local_rank`). + **kwargs: keyword arguments of ``func``. """ if self._spawn_params is not None and self.backend is not None: diff --git a/ignite/distributed/utils.py b/ignite/distributed/utils.py index 1376ce102930..793d89e13793 100644 --- a/ignite/distributed/utils.py +++ b/ignite/distributed/utils.py @@ -52,7 +52,7 @@ def sync(temporary: bool = False) -> None: This method should be used when distributed context is manually created or destroyed. Args: - temporary: If True, distributed model synchronization is done every call of ``idist.get_*`` methods. + temporary (bool): If True, distributed model synchronization is done every call of ``idist.get_*`` methods. This may have a negative performance impact. """ global _model @@ -285,15 +285,15 @@ def train_fn(local_rank, a, b, c, d=12): idist.spawn("xla-tpu", train_fn, args=(a, b, c), kwargs_dict={"d": 23}, nproc_per_node=8) Args: - backend: backend to use: `nccl`, `gloo`, `xla-tpu`, `horovod` - fn: function to called as the entrypoint of the spawned process. + backend (str): backend to use: `nccl`, `gloo`, `xla-tpu`, `horovod` + fn (function): function to called as the entrypoint of the spawned process. This function must be defined at the top level of a module so it can be pickled and spawned. This is a requirement imposed by multiprocessing. The function is called as ``fn(i, *args, **kwargs_dict)``, where `i` is the process index and args is the passed through tuple of arguments. - args: arguments passed to `fn`. - kwargs_dict: kwargs passed to `fn`. - nproc_per_node: number of processes to spawn on a single node. Default, 1. - kwargs: acceptable kwargs according to provided backend: + args (tuple): arguments passed to `fn`. + kwargs_dict (Mapping): kwargs passed to `fn`. + nproc_per_node (int): number of processes to spawn on a single node. Default, 1. + **kwargs: acceptable kwargs according to provided backend: - | "nccl" or "gloo" : `nnodes` (default, 1), `node_rank` (default, 0), `master_addr` | (default, "127.0.0.1"), `master_port` (default, 2222), `timeout` to `dist.init_process_group`_ function @@ -329,8 +329,8 @@ def all_reduce(tensor: Union[torch.Tensor, float], op: str = "SUM") -> Union[tor """Helper method to perform all reduce operation. Args: - tensor: tensor or number to collect across participating processes. - op: reduction operation, "SUM" by default. Possible values: "SUM", "PRODUCT", "MIN", "MAX", "AND", "OR". + tensor (torch.Tensor or number): tensor or number to collect across participating processes. + op (str): reduction operation, "SUM" by default. Possible values: "SUM", "PRODUCT", "MIN", "MAX", "AND", "OR". Please, several values are not supported for the backend like "horovod". Returns: @@ -347,7 +347,7 @@ def all_gather(tensor: Union[torch.Tensor, float, str]) -> Union[torch.Tensor, f """Helper method to perform all gather operation. Args: - tensor: tensor or number or str to collect across participating processes. + tensor (torch.Tensor or number or str): tensor or number or str to collect across participating processes. Returns: torch.Tensor of shape ``(world_size * tensor.shape[0], tensor.shape[1], ...)`` if input is a tensor or @@ -365,9 +365,9 @@ def broadcast(tensor: Union[torch.Tensor, float, str], src: int = 0) -> Union[to """Helper method to perform broadcast operation. Args: - tensor: tensor or number or str to broadcast to participating processes. + tensor (torch.Tensor or number or str): tensor or number or str to broadcast to participating processes. Make sure to respect dtype of torch tensor input for all processes, otherwise execution will crash. - src: source rank. Default, 0. + src (int): source rank. Default, 0. Returns: torch.Tensor or string or number @@ -434,7 +434,7 @@ def run(local_rank, *args, **kwargs): # ... Args: - index: local rank or current process index + index (int): local rank or current process index """ from ignite.distributed.comp_models.base import ComputationModel @@ -487,8 +487,8 @@ def train_fn(local_rank, a, b, c): Args: - backend: backend: `nccl`, `gloo`, `xla-tpu`, `horovod`. - kwargs: acceptable kwargs according to provided backend: + backend (str, optional): backend: `nccl`, `gloo`, `xla-tpu`, `horovod`. + **kwargs: acceptable kwargs according to provided backend: - "nccl" or "gloo" : timeout(=timedelta(minutes=30)). @@ -543,8 +543,8 @@ def one_rank_only(rank: int = 0, with_barrier: bool = False) -> Callable: """Decorator to filter handlers wrt a rank number Args: - rank: rank number of the handler (default: 0). - with_barrier: synchronisation with a barrier (default: False). + rank (int): rank number of the handler (default: 0). + with_barrier (bool): synchronisation with a barrier (default: False). .. code-block:: python From bd5723ef7d8e3a208974c6f222b0ced066076b49 Mon Sep 17 00:00:00 2001 From: ydcjeff Date: Thu, 25 Feb 2021 13:37:29 +0630 Subject: [PATCH 7/8] remove unnecessary device, __init__ --- ignite/contrib/metrics/regression/canberra_metric.py | 5 ----- ignite/contrib/metrics/regression/manhattan_distance.py | 5 ----- ignite/contrib/metrics/regression/median_absolute_error.py | 3 --- .../metrics/regression/median_absolute_percentage_error.py | 3 --- .../metrics/regression/median_relative_absolute_error.py | 3 --- ignite/contrib/metrics/regression/r2_score.py | 5 ----- 6 files changed, 24 deletions(-) diff --git a/ignite/contrib/metrics/regression/canberra_metric.py b/ignite/contrib/metrics/regression/canberra_metric.py index 28feeae42348..787bd39cb6d9 100644 --- a/ignite/contrib/metrics/regression/canberra_metric.py +++ b/ignite/contrib/metrics/regression/canberra_metric.py @@ -38,11 +38,6 @@ class CanberraMetric(_BaseRegression): - Works with DDP. """ - def __init__( - self, output_transform: Callable = lambda x: x, device: Union[str, torch.device] = torch.device("cpu") - ) -> None: - super(CanberraMetric, self).__init__(output_transform, device) - @reinit__is_reduced def reset(self) -> None: self._sum_of_errors = torch.tensor(0.0, device=self._device) diff --git a/ignite/contrib/metrics/regression/manhattan_distance.py b/ignite/contrib/metrics/regression/manhattan_distance.py index d4bd11137495..2bdd7aabf876 100644 --- a/ignite/contrib/metrics/regression/manhattan_distance.py +++ b/ignite/contrib/metrics/regression/manhattan_distance.py @@ -37,11 +37,6 @@ class ManhattanDistance(_BaseRegression): - Workes with DDP. """ - def __init__( - self, output_transform: Callable = lambda x: x, device: Union[str, torch.device] = torch.device("cpu") - ): - super(ManhattanDistance, self).__init__(output_transform, device) - @reinit__is_reduced def reset(self) -> None: self._sum_of_errors = torch.tensor(0.0, device=self._device) diff --git a/ignite/contrib/metrics/regression/median_absolute_error.py b/ignite/contrib/metrics/regression/median_absolute_error.py index 616938ec4670..1c490f1a380a 100644 --- a/ignite/contrib/metrics/regression/median_absolute_error.py +++ b/ignite/contrib/metrics/regression/median_absolute_error.py @@ -37,9 +37,6 @@ class MedianAbsoluteError(_BaseRegressionEpoch): 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. By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - device: specifies which device updates are accumulated on. Setting the - metric's device to be the same as your ``update`` arguments ensures the ``update`` method is - non-blocking. By default, CPU. """ def __init__(self, output_transform: Callable = lambda x: x): diff --git a/ignite/contrib/metrics/regression/median_absolute_percentage_error.py b/ignite/contrib/metrics/regression/median_absolute_percentage_error.py index eac9492d6f52..5358f25c43a2 100644 --- a/ignite/contrib/metrics/regression/median_absolute_percentage_error.py +++ b/ignite/contrib/metrics/regression/median_absolute_percentage_error.py @@ -37,9 +37,6 @@ class MedianAbsolutePercentageError(_BaseRegressionEpoch): 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. By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - device: specifies which device updates are accumulated on. Setting the - metric's device to be the same as your ``update`` arguments ensures the ``update`` method is - non-blocking. By default, CPU. """ def __init__(self, output_transform: Callable = lambda x: x): diff --git a/ignite/contrib/metrics/regression/median_relative_absolute_error.py b/ignite/contrib/metrics/regression/median_relative_absolute_error.py index 729b4353d058..c797c41cbc66 100644 --- a/ignite/contrib/metrics/regression/median_relative_absolute_error.py +++ b/ignite/contrib/metrics/regression/median_relative_absolute_error.py @@ -37,9 +37,6 @@ class MedianRelativeAbsoluteError(_BaseRegressionEpoch): 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. By default, metrics require the output as ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - device: specifies which device updates are accumulated on. Setting the - metric's device to be the same as your ``update`` arguments ensures the ``update`` method is - non-blocking. By default, CPU. """ def __init__(self, output_transform: Callable = lambda x: x): diff --git a/ignite/contrib/metrics/regression/r2_score.py b/ignite/contrib/metrics/regression/r2_score.py index d6df3e1b0ca3..285f14d6c959 100644 --- a/ignite/contrib/metrics/regression/r2_score.py +++ b/ignite/contrib/metrics/regression/r2_score.py @@ -34,11 +34,6 @@ class R2Score(_BaseRegression): Works with DDP. """ - def __init__( - self, output_transform: Callable = lambda x: x, device: Union[str, torch.device] = torch.device("cpu"), - ): - super(R2Score, self).__init__(output_transform, device) - @reinit__is_reduced def reset(self) -> None: self._num_examples = 0 From 5748d0412001e6702b2c07fe6c033babc7d699b8 Mon Sep 17 00:00:00 2001 From: ydcjeff Date: Thu, 25 Feb 2021 17:29:23 +0630 Subject: [PATCH 8/8] add Metric.__init__ docstring for no __init__ for contrib.metrics --- ignite/contrib/metrics/regression/canberra_metric.py | 2 ++ ignite/contrib/metrics/regression/fractional_absolute_error.py | 2 ++ ignite/contrib/metrics/regression/fractional_bias.py | 2 ++ .../metrics/regression/geometric_mean_absolute_error.py | 2 ++ .../regression/geometric_mean_relative_absolute_error.py | 3 ++- ignite/contrib/metrics/regression/manhattan_distance.py | 2 ++ ignite/contrib/metrics/regression/maximum_absolute_error.py | 2 ++ .../contrib/metrics/regression/mean_absolute_relative_error.py | 2 ++ ignite/contrib/metrics/regression/mean_error.py | 2 ++ ignite/contrib/metrics/regression/mean_normalized_bias.py | 2 ++ ignite/contrib/metrics/regression/r2_score.py | 2 ++ ignite/contrib/metrics/regression/wave_hedges_distance.py | 2 ++ 12 files changed, 24 insertions(+), 1 deletion(-) diff --git a/ignite/contrib/metrics/regression/canberra_metric.py b/ignite/contrib/metrics/regression/canberra_metric.py index 787bd39cb6d9..c0c81de49105 100644 --- a/ignite/contrib/metrics/regression/canberra_metric.py +++ b/ignite/contrib/metrics/regression/canberra_metric.py @@ -22,6 +22,8 @@ class CanberraMetric(_BaseRegression): .. _scikit-learn distance metrics: https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.DistanceMetric.html + Parameters are inherited from ``Metric.__init__``. + Args: output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the diff --git a/ignite/contrib/metrics/regression/fractional_absolute_error.py b/ignite/contrib/metrics/regression/fractional_absolute_error.py index 3fb7ba9d1e08..a76e07e59800 100644 --- a/ignite/contrib/metrics/regression/fractional_absolute_error.py +++ b/ignite/contrib/metrics/regression/fractional_absolute_error.py @@ -21,6 +21,8 @@ class FractionalAbsoluteError(_BaseRegression): __ https://arxiv.org/abs/1809.03006 + Parameters are inherited from ``Metric.__init__``. + Args: output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the diff --git a/ignite/contrib/metrics/regression/fractional_bias.py b/ignite/contrib/metrics/regression/fractional_bias.py index c05323626b80..ba362512ad76 100644 --- a/ignite/contrib/metrics/regression/fractional_bias.py +++ b/ignite/contrib/metrics/regression/fractional_bias.py @@ -21,6 +21,8 @@ class FractionalBias(_BaseRegression): __ https://arxiv.org/abs/1809.03006 + Parameters are inherited from ``Metric.__init__``. + Args: output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the diff --git a/ignite/contrib/metrics/regression/geometric_mean_absolute_error.py b/ignite/contrib/metrics/regression/geometric_mean_absolute_error.py index 21dfba3e5b41..a3aec7fae992 100644 --- a/ignite/contrib/metrics/regression/geometric_mean_absolute_error.py +++ b/ignite/contrib/metrics/regression/geometric_mean_absolute_error.py @@ -21,6 +21,8 @@ class GeometricMeanAbsoluteError(_BaseRegression): __ https://arxiv.org/abs/1809.03006 + Parameters are inherited from ``Metric.__init__``. + Args: output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the diff --git a/ignite/contrib/metrics/regression/geometric_mean_relative_absolute_error.py b/ignite/contrib/metrics/regression/geometric_mean_relative_absolute_error.py index 17b113cb9fe6..35a1817fae2a 100644 --- a/ignite/contrib/metrics/regression/geometric_mean_relative_absolute_error.py +++ b/ignite/contrib/metrics/regression/geometric_mean_relative_absolute_error.py @@ -19,9 +19,10 @@ class GeometricMeanRelativeAbsoluteError(_BaseRegression): - ``update`` must receive output of the form ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - `y` and `y_pred` must be of same shape `(N, )` or `(N, 1)`. - __ https://arxiv.org/abs/1809.03006 + Parameters are inherited from ``Metric.__init__``. + Args: output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the diff --git a/ignite/contrib/metrics/regression/manhattan_distance.py b/ignite/contrib/metrics/regression/manhattan_distance.py index 2bdd7aabf876..e0e308328fd9 100644 --- a/ignite/contrib/metrics/regression/manhattan_distance.py +++ b/ignite/contrib/metrics/regression/manhattan_distance.py @@ -21,6 +21,8 @@ class ManhattanDistance(_BaseRegression): __ https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.DistanceMetric.html + Parameters are inherited from ``Metric.__init__``. + Args: output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the diff --git a/ignite/contrib/metrics/regression/maximum_absolute_error.py b/ignite/contrib/metrics/regression/maximum_absolute_error.py index 70267ccfa24f..a6e1b49073d8 100644 --- a/ignite/contrib/metrics/regression/maximum_absolute_error.py +++ b/ignite/contrib/metrics/regression/maximum_absolute_error.py @@ -21,6 +21,8 @@ class MaximumAbsoluteError(_BaseRegression): __ https://arxiv.org/abs/1809.03006 + Parameters are inherited from ``Metric.__init__``. + Args: output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the diff --git a/ignite/contrib/metrics/regression/mean_absolute_relative_error.py b/ignite/contrib/metrics/regression/mean_absolute_relative_error.py index a8323c63011f..faac99ddb6c3 100644 --- a/ignite/contrib/metrics/regression/mean_absolute_relative_error.py +++ b/ignite/contrib/metrics/regression/mean_absolute_relative_error.py @@ -21,6 +21,8 @@ class MeanAbsoluteRelativeError(_BaseRegression): __ https://arxiv.org/ftp/arxiv/papers/1809/1809.03006.pdf + Parameters are inherited from ``Metric.__init__``. + Args: output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the diff --git a/ignite/contrib/metrics/regression/mean_error.py b/ignite/contrib/metrics/regression/mean_error.py index e84fe58e0f76..e6b0905748ca 100644 --- a/ignite/contrib/metrics/regression/mean_error.py +++ b/ignite/contrib/metrics/regression/mean_error.py @@ -21,6 +21,8 @@ class MeanError(_BaseRegression): __ https://arxiv.org/abs/1809.03006 + Parameters are inherited from ``Metric.__init__``. + Args: output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the diff --git a/ignite/contrib/metrics/regression/mean_normalized_bias.py b/ignite/contrib/metrics/regression/mean_normalized_bias.py index b338556c0983..b94594a29780 100644 --- a/ignite/contrib/metrics/regression/mean_normalized_bias.py +++ b/ignite/contrib/metrics/regression/mean_normalized_bias.py @@ -21,6 +21,8 @@ class MeanNormalizedBias(_BaseRegression): __ https://arxiv.org/abs/1809.03006 + Parameters are inherited from ``Metric.__init__``. + Args: output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the diff --git a/ignite/contrib/metrics/regression/r2_score.py b/ignite/contrib/metrics/regression/r2_score.py index 285f14d6c959..f420ca80d5bc 100644 --- a/ignite/contrib/metrics/regression/r2_score.py +++ b/ignite/contrib/metrics/regression/r2_score.py @@ -20,6 +20,8 @@ class R2Score(_BaseRegression): - ``update`` must receive output of the form ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y}``. - `y` and `y_pred` must be of same shape `(N, )` or `(N, 1)` and of type `float32`. + Parameters are inherited from ``Metric.__init__``. + Args: output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the diff --git a/ignite/contrib/metrics/regression/wave_hedges_distance.py b/ignite/contrib/metrics/regression/wave_hedges_distance.py index 6125e6cb1209..9bf1248a4e1d 100644 --- a/ignite/contrib/metrics/regression/wave_hedges_distance.py +++ b/ignite/contrib/metrics/regression/wave_hedges_distance.py @@ -20,6 +20,8 @@ class WaveHedgesDistance(_BaseRegression): __ https://arxiv.org/abs/1809.03006 + Parameters are inherited from ``Metric.__init__``. + Args: output_transform: a callable that is used to transform the :class:`~ignite.engine.engine.Engine`'s ``process_function``'s output into the