事件处理器#

模型检查点加载器#

class monai.handlers.CheckpointLoader(load_path, load_dict, name=None, map_location=None, strict=True, strict_shape=True)[源码]#

CheckpointLoader 作为一个 Ignite 处理器，用于从文件加载检查点数据。它可以加载网络、优化器、学习率调度器等变量。如果在 torch.nn.DataParallel 之后保存检查点，则需要按照 PyTorch 的建议保存 model.module，然后使用此加载器加载模型。

使用示例

trainer = SupervisedTrainer(...)
save_dict = {
    "trainer": trainer,
    "net": network,
    "opt": optimizer,
    "lr": lr_scheduler,
}

map_location = "cuda:0"
# checkpoint needs to have same save_dict for this to work
handler = CheckpointLoader(load_path="/test/checkpoint.pt", load_dict=save_dict, map_location=map_location, strict=True)
handler(trainer)
# Trainer now has the same state as stored, including the number of epochs and iterations completed
# so you can resume an interrupted training at the place where it left
参数:

  • load_path (str) – 检查点的文件路径，它应该是一个 PyTorch 的 pth 文件。

  • load_dict (dict) –

    加载检查点的目标对象。示例

    {'network': net, 'optimizer': optimizer, 'lr_scheduler': lr_scheduler}

  • name (Optional[str, None]) – 所使用的 logging.logger 的标识符；如果为 None，则默认为 engine.logger。

  • map_location (Optional[dict, None]) – 在分布式训练/评估中加载模型时，需要提供合适的 map_location 参数，以防止进程干扰其他进程的设备。如果缺少 map_location，torch.load 将首先把模型加载到 CPU，然后将每个参数复制回其保存时的位置，这将导致同一台机器上的所有进程使用同一组设备。

  • strict (bool) – 是否严格执行要求：load_dict 中每一项的 state_dict 的键和数据形状必须与检查点中对应项的 state_dict 匹配，默认为 True。

  • strict_shape (bool) – 是否强制要求检查点中匹配层的形状一致。如果为 False，它将跳过与检查点内容形状不同的层，并忽略 strict 参数。这对于迁移学习是一个有用的高级特性。用户应当完全了解哪些层的形状会发生变化。默认为 True。

注意：如果 strict_shape=False，则只会加载 torch.nn.Module 的检查点，并跳过 load_dict 中的其他项。

例如，如果当前模型中某些层的形状无法与检查点匹配，当前优化器的 parameter_group 可能也无法与检查点匹配，因此会跳过为优化器加载检查点。

有关加载检查点的更多详细信息，请参阅：https://pytorch.ac.cn/ignite/v0.4.5/generated/ignite.handlers.checkpoint.Checkpoint.html #ignite.handlers.checkpoint.Checkpoint.load_objects. https://pytorch.ac.cn/docs/stable/generated/torch.nn.Module.html#torch.nn.Module.load_state_dict。

attach(engine)[源码]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

模型检查点保存器#

class monai.handlers.CheckpointSaver(save_dir, save_dict, name=None, file_prefix='', save_final=False, final_filename=None, save_key_metric=False, key_metric_name=None, key_metric_n_saved=1, key_metric_filename=None, key_metric_save_state=False, key_metric_greater_or_equal=False, key_metric_negative_sign=False, epoch_level=True, save_interval=0, n_saved=None)[源码]#

CheckpointSaver 作为一个 Ignite 处理器，用于将检查点数据保存到文件。它支持根据指标结果、epoch 编号、迭代编号以及最后模型或异常情况进行保存。

参数:

  • save_dir (str) – 保存检查点的目标目录。

  • save_dict (dict) –

    保存到检查点的源对象。示例

    {'network': net, 'optimizer': optimizer, 'lr_scheduler': lr_scheduler}

  • name (Optional[str, None]) – 所使用的 logging.logger 的标识符；如果为 None，则默认为 engine.logger。

  • file_prefix (str) – 保存对象的文件名前缀。

  • save_final (bool) – 是否在最终迭代或出现异常时保存检查点或会话。如果需要在抛出异常时保存检查点，请将此处理器放在处理器列表中的 StatsHandler 之前，因为 Ignite 的逻辑只能触发第一个附加的 EXCEPTION_RAISED 事件处理器。

  • final_filename (Optional[str, None]) – 如果 save_final=True，设置一个固定的文件名来保存最终模型。如果为 None，则默认为 checkpoint_final_iteration=N.pt。

  • save_key_metric (bool) – 是否在训练期间当关键指标值高于所有之前的值时保存检查点或会话。指标保留 4 位小数，检查点名称为：{file_prefix}_key_metric=0.XXXX.pth。

  • key_metric_name (Optional[str, None]) – ignite 指标字典中关键指标的名称。如果为 None，则使用 engine.state.key_metric。

  • key_metric_n_saved (int) – 保存前 N 个检查点或会话，按关键指标值降序排列。

  • key_metric_filename (Optional[str, None]) – 设置最佳指标模型的固定文件名。如果不为 None，则 key_metric_n_saved 应设为 1，且仅保留最佳模型。

  • key_metric_save_state (bool) – 是否在检查点文件中保存关键指标的跟踪列表。如果为 True，则将在检查点文件中保存一个带有 checkpointer 键的对象，以与 ignite 中 Checkpoint 的 include_self 参数保持一致。通常用于恢复训练并对比当前指标与之前的 N 个值。

  • key_metric_greater_or_equal (bool) – 如果为 True，则保存最新的得分相同的模型。否则，保存第一个得分相同的模型。默认为 False。

  • key_metric_negative_sign (bool) – 是否在指标分数前加负号以比较指标，因为对于类似误差的指标，值越小越好（而对象保存是保留分数较大的）。默认为 False。

  • epoch_level (bool) – 在训练期间每 N 个 epoch 或每 N 次迭代保存检查点。True 为 epoch 级别，False 为迭代级别。

  • save_interval (int) – 每 N 个 epoch 保存检查点，默认为 0，即不保存。

  • n_saved (Optional[int, None]) – 保存最新的 N 个 epoch 或迭代级别的检查点，‘None’ 表示全部保存。

注意

CheckpointHandler 可用于训练、验证或评估。已保存文件的示例：

  • checkpoint_iteration=400.pt

  • checkpoint_iteration=800.pt

  • checkpoint_epoch=1.pt

  • checkpoint_final_iteration=1000.pt

  • checkpoint_key_metric=0.9387.pt

attach(engine)[源码]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

completed(engine)[源码]#

训练或验证/评估完成事件的回调。如果配置了 save_final 为 True，则保存最终检查点。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

exception_raised(engine, e)[源码]#

训练或验证/评估异常事件的回调。如果配置了 save_final 为 True，则保存当前数据作为最终检查点。此回调可能会被跳过，因为 Ignite 的逻辑只能触发第一个附加的 EXCEPTION_RAISED 事件处理器。

参数:

  • engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

  • e (Exception) – 在 engine.run() 期间被 Ignite 捕获的异常。

返回类型:

None

interval_completed(engine)[源码]#

训练 epoch/迭代完成事件的回调。如果配置了 save_interval = N，则保存检查点。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

load_state_dict(state_dict)[源码]#

如果配置了根据关键指标值保存检查点，则用于恢复关键指标跟踪列表内部状态的工具。注意在保存上一个检查点时要设置 key_metric_save_state=True。

示例

CheckpointSaver(
    ...
    save_key_metric=True,
    key_metric_save_state=True,  # config to also save the state of this saver
).attach(engine)
engine.run(...)

# resumed training with a new CheckpointSaver
saver = CheckpointSaver(save_key_metric=True, ...)
# load the previous key metric tracking list into saver
CheckpointLoader("/test/model.pt"), {"checkpointer": saver}).attach(engine)
返回类型:

None

metrics_completed(engine)[源码]#

在 epoch 完成时，比较训练或验证中的指标并保存模型的回调。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

指标保存器#

class monai.handlers.MetricsSaver(save_dir, metrics='*', metric_details=None, batch_transform=<function MetricsSaver.<lambda>>, summary_ops=None, save_rank=0, delimiter=', ', output_type='csv')[源码]#

用于将指标值和详细信息保存到文件的 ignite 处理器。

参数:

  • save_dir (str) – 保存指标和指标详细信息的目录。

  • metrics (UnionType[str, Sequence[str], None]) – 预期保存到文件的最终指标。可以是 None、“*” 或字符串列表。None - 不保存任何指标。 “*” - 将 engine.state.metrics 字典中的所有现有指标分别保存到文件中。 字符串列表 - 指定要保存的预期指标。默认为 “*”，即将所有指标保存到 metrics.csv。

  • metric_details (Union[Sequence[str], str, None]) – 预期保存到文件的指标详细信息。数据来源于 engine.state.metric_details，它由不同的 Metrics 提供，通常是指标计算中的某些中间值。例如：验证数据集中每个图像每个通道的平均 dice。它必须包含至少 2 个维度：(batch, classes, …)，如果不是，将 unsqueeze 到 2 个维度。此参数可以是 None、“*” 或字符串列表。None - 不保存任何指标详情。 “*” - 将 engine.state.metric_details 字典中的所有现有指标详情分别保存到文件中。 字符串列表 - 指定要保存的预期指标的详细信息。如果不为 None，每个 metric_details 数组将保存为一个独立的 {metric name}_raw.csv 文件。

  • batch_transform (Callable) – 一个可调用对象，用于从 ignite.engine.state.batch 中提取输入图像的 meta_data 字典。其目的是从 meta_data 中获取输入文件名，并将其与指标详情一起存储。engine.state 和 batch_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • summary_ops (Union[Sequence[str], str, None]) –

    用于生成摘要报告的预期计算操作。可以是 None、“*” 或字符串列表，默认为 None。None - 不为每个预期的 metric_details 生成摘要报告。 “*” - 使用所有支持的操作为每个 metric_details 生成摘要报告。 字符串列表 - 使用指定的操作为每个 metric_details 生成摘要报告，这些操作应在列表内：[“mean”, “median”, “max”, “min”, “<int>percentile”, “std”, “notnans”]。 “<int>percentile” 中的数字应在 [0, 100] 之间，例如：“15percentile”。默认：“90percentile”。更多详情，请查看：https://numpy.com.cn/doc/stable/reference/generated/numpy.nanpercentile.html。注意：对于总体摘要，它首先计算每个图像所有类别的 nanmean，然后计算摘要。生成的摘要报告示例

    class    mean    median    max    5percentile 95percentile  notnans
class0  6.0000   6.0000   7.0000   5.1000      6.9000       2.0000
class1  6.0000   6.0000   6.0000   6.0000      6.0000       1.0000
mean    6.2500   6.2500   7.0000   5.5750      6.9250       2.0000

  • save_rank (int) – 在多 GPU 验证中，仅在指定 rank 上的处理器会保存到文件，默认为 0。

  • delimiter (str) – 保存文件中的分隔符字符，默认为 “,”，因为默认输出类型为 csv。与此保持一致：https://docs.pythonlang.cn/3/library/csv.html#csv.Dialect.delimiter。

  • output_type (str) – 预期的输出文件类型，支持的类型：[“csv”]，默认为 “csv”。

attach(engine)[源码]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

CSV 保存器#

class monai.handlers.ClassificationSaver(output_dir='./', filename='predictions.csv', delimiter=', ', overwrite=True, batch_transform=<function ClassificationSaver.<lambda>>, output_transform=<function ClassificationSaver.<lambda>>, name=None, save_rank=0, saver=None)[源码]#

在完成每次迭代时触发的事件处理器，用于将分类预测保存为 CSV 文件。如果运行在分布式数据并行模式下，仅在指定的 rank 上保存 CSV 文件。

__init__(output_dir='./', filename='predictions.csv', delimiter=', ', overwrite=True, batch_transform=<function ClassificationSaver.<lambda>>, output_transform=<function ClassificationSaver.<lambda>>, name=None, save_rank=0, saver=None)[源码]#
参数:

  • output_dir (str) – 如果 saver=None，输出 CSV 文件的目录。

  • filename (str) – 如果 saver=None，保存的 CSV 文件名。

  • delimiter (str) – 保存文件中的分隔符字符，默认为 “,”，因为默认输出类型为 csv。与此保持一致：https://docs.pythonlang.cn/3/library/csv.html#csv.Dialect.delimiter。

  • overwrite (bool) – 如果 saver=None，是否覆盖现有文件内容。如果为 True，保存前将清除文件；否则将新内容追加到文件末尾。

  • batch_transform (Callable) – 一个可调用对象，用于从 ignite.engine.state.batch 中提取输入图像的 meta_data 字典。其目的是从 meta_data 中获取输入文件名，并将其与分类结果一起存储。engine.state 和 batch_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • output_transform (Callable) – 一个可调用对象，用于从 ignite.engine.state.output 中提取模型预测数据。其输出的第一个维度将被视为 batch 维度。batch 中的每个项目将被单独保存。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • name (Optional[str, None]) – 所使用的 logging.logger 的标识符，默认为 engine.logger。

  • save_rank (int) – 在多 GPU 验证中，仅在指定 rank 上的处理器会保存到 CSV 文件，默认为 0。

  • saver (Optional[CSVSaver, None]) – 用于保存分类结果的 saver 实例。如果为 None，则在内部创建一个 CSVSaver。saver 必须提供 save_batch(batch_data, meta_data) 和 finalize() API。

attach(engine)[源码]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

Ignite 指标处理器#

class monai.handlers.IgniteMetricHandler(metric_fn=None, loss_fn=None, output_transform=<function IgniteMetricHandler.<lambda>>, save_details=True, reduction=mean, get_not_nans=False)[源码]#

基于 ignite 事件处理器机制的基类指标类。输入的 prediction 或 label 数据可以是带 batch 和 channel 维度的 PyTorch Tensor 或 numpy 数组，也可以是不带 batch 维度的 PyTorch Tensor 或 numpy 数组列表。

参数:

  • metric_fn (Optional[CumulativeIterationMetric, None]) – 用于在每次迭代后计算原始指标结果的可调用函数或类。期望返回形状为 (batch, channel, …) 的 Tensor，或者 tuple (Tensor, not_nans)。

  • loss_fn (Optional[_Loss, None]) – 用于生成 LossMetric 的 torch _Loss 函数。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的 mean_dice。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

  • reduction (UnionType[MetricReduction, str]) – LossMetric 的参数，请参阅该类了解详细信息。

  • get_not_nans (bool) – LossMetric 的参数，请参阅该类了解详细信息。

attach(engine, name)[源码]#

将当前指标附加到提供的引擎。在引擎运行结束时，engine.state.metrics 字典将包含以提供的名称命名的计算指标值。

参数:

  • engine (Engine) – 必须附加指标的引擎。

  • name (str) – 要附加的指标名称。

返回类型:

None

compute()[源码]#
引发异常:

NotComputableError – 当在 update 发生之前调用 compute 时触发。

返回类型:

Any

reset()#

将指标重置为其初始状态。

默认情况下，此方法在每个 epoch 开始时调用。

返回类型:

None

update(output)#
参数:

output (Sequence[Tensor]) – 包含 [y_pred, y] 内容的序列。

引发异常:

ValueError – 当 output 长度不为 2 时。metric_fn 仅支持 y_pred 和 y。

返回类型:

None

Mean Dice 指标处理器#

class monai.handlers.MeanDice(include_background=True, reduction=mean, num_classes=None, output_transform=<function MeanDice.<lambda>>, save_details=True, return_with_label=False)[源码]#

从全尺寸 Tensor 计算 Dice 分数指标，并对 batch、类通道、迭代进行平均。

__init__(include_background=True, reduction=mean, num_classes=None, output_transform=<function MeanDice.<lambda>>, save_details=True, return_with_label=False)[源码]#
参数:

  • include_background (bool) – 是否在预测输出的第一个通道上包含 dice 计算。默认为 True。

  • reduction (UnionType[MetricReduction, str]) – 定义减少指标的模式，仅对 not-nan 值执行减少。可用的减少模式：{"none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"}，默认为 "mean"。如果为 “none”，则不进行减少。

  • num_classes (Optional[int, None]) – 输入通道的数量（始终包括背景）。当此值为 None 时，将使用 y_pred.shape[1]。此选项在 y_pred 和 y 均为单通道类别索引且类别数量未自动从数据推断出来时非常有用。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的 mean dice。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

  • return_with_label (UnionType[bool, list[str]]) – 是否返回带标签的指标，仅在 reduction 为 “mean_batch” 时有效。如果为 True，则使用 “label_{index}” 作为对应于 C 通道的键；如果 ‘include_background’ 为 True，则索引从 “0” 开始，否则从 “1” 开始。它还可以采用标签名称列表。结果将作为字典返回。

另请参阅

monai.metrics.meandice.compute_dice()

Mean IoU 指标处理器#

class monai.handlers.MeanIoUHandler(include_background=True, reduction=mean, output_transform=<function MeanIoUHandler.<lambda>>, save_details=True)[源码]#

从全尺寸 Tensor 计算 IoU 分数指标，并对 batch、类通道、迭代进行平均。

__init__(include_background=True, reduction=mean, output_transform=<function MeanIoUHandler.<lambda>>, save_details=True)[源码]#
参数:

  • include_background (bool) – 是否在预测输出的第一个通道上包含 iou 计算。默认为 True。

  • reduction (UnionType[MetricReduction, str]) – 定义减少指标的模式，仅对 not-nan 值执行减少。可用的减少模式：{"none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"}，默认为 "mean"。如果为 “none”，则不进行减少。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的 mean iou。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

另请参阅

monai.metrics.meaniou.compute_iou()

ROC AUC 指标处理器#

class monai.handlers.ROCAUC(average=macro, output_transform=<function ROCAUC.<lambda>>)[源码]#

计算接收者操作特征曲线下面积 (ROC AUC)。在 epoch 期间累积预测值和真值，并应用 compute_roc_auc。

参数:

  • average (UnionType[Average, str]) –

    {"macro", "weighted", "micro", "none"} 如果不是二分类，则执行平均值的类型。默认为 "macro"。

    • "macro": 计算每个标签的指标，并求其无加权平均值。

      这不考虑标签不平衡。

    • "weighted": 计算每个标签的指标，并求其加权平均值，

      权重由支持度（每个标签的真实实例数量）决定。

    • "micro": 通过将标签指标矩阵的每个元素视为一个标签，全局计算指标。

      指标。

    • "none": 返回每个类别的分数。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

注意

ROCAUC 期望 y 由 0 和 1 组成。y_pred 必须是概率估计值或置信度值。

平均精度指标处理器#

class monai.handlers.AveragePrecision(average=macro, output_transform=<function AveragePrecision.<lambda>>)[源码]#

计算平均精度 (AP)。在 epoch 期间累积预测值和真值，并应用 compute_average_precision。

参数:

  • average (UnionType[Average, str]) –

    {"macro", "weighted", "micro", "none"} 如果不是二分类，则执行平均值的类型。默认为 "macro"。

    • "macro": 计算每个标签的指标，并求其无加权平均值。

      这不考虑标签不平衡。

    • "weighted": 计算每个标签的指标，并求其加权平均值，

      权重由支持度（每个标签的真实实例数量）决定。

    • "micro": 通过将标签指标矩阵的每个元素视为一个标签，全局计算指标。

      指标。

    • "none": 返回每个类别的分数。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

注意

平均精度期望 y 由 0 和 1 组成。y_pred 必须是概率估计值或置信度值。

混淆矩阵指标处理器#

class monai.handlers.ConfusionMatrix(include_background=True, metric_name='hit_rate', compute_sample=False, reduction=mean, output_transform=<function ConfusionMatrix.<lambda>>, save_details=True)[源码]#

从全尺寸 Tensor 计算混淆矩阵相关的指标，并对 batch、类通道、迭代进行平均。

__init__(include_background=True, metric_name='hit_rate', compute_sample=False, reduction=mean, output_transform=<function ConfusionMatrix.<lambda>>, save_details=True)[源码]#
参数:

  • include_background (bool) – 是否在预测输出的第一个通道上包含指标计算。默认为 True。

  • metric_name (str) – ["sensitivity", "specificity", "precision", "negative predictive value", "miss rate", "fall out", "false discovery rate", "false omission rate", "prevalence threshold", "threat score", "accuracy", "balanced accuracy", "f1 score", "matthews correlation coefficient", "fowlkes mallows index", "informedness", "markedness"] 某些指标有多个别名（如前述维基百科页面所示），您也可以输入这些名称。

  • compute_sample (bool) – 在减少时，如果为 True，每个样本的指标将首先基于每个混淆矩阵计算。如果为 False，则先对混淆矩阵进行减少，默认为 False。

  • reduction (UnionType[MetricReduction, str]) – 定义减少指标的模式，仅对 not-nan 值执行减少。可用的减少模式：{"none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"}，默认为 "mean"。如果为 “none”，则不进行减少。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的 TP/TN/FP/FN。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

另请参阅

monai.metrics.confusion_matrix()

Hausdorff 距离指标处理器#

class monai.handlers.HausdorffDistance(include_background=False, distance_metric='euclidean', percentile=None, directed=False, reduction=mean, output_transform=<function HausdorffDistance.<lambda>>, save_details=True)[源码]#

从全尺寸 Tensor 计算 Hausdorff 距离，并对 batch、类通道、迭代进行平均。

__init__(include_background=False, distance_metric='euclidean', percentile=None, directed=False, reduction=mean, output_transform=<function HausdorffDistance.<lambda>>, save_details=True)[源码]#
参数:

  • include_background (bool) – 是否在预测输出的第一个通道上包含距离计算。默认为 False。

  • distance_metric (str) – : ["euclidean", "chessboard", "taxicab"] 用于计算表面距离的度量标准。默认为 "euclidean"。

  • percentile (Optional[float, None]) – 一个 0 到 100 之间的可选浮点数。如果指定，将获得 Hausdorff 距离的相应百分位数，而不是最大结果。默认为 None。

  • directed (bool) – 是否计算定向 Hausdorff 距离。默认为 False。

  • reduction (UnionType[MetricReduction, str]) – 定义减少指标的模式，仅对 not-nan 值执行减少。可用的减少模式：{"none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"}，默认为 "mean"。如果为 “none”，则不进行减少。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的 hausdorff 距离。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

表面距离指标处理器#

class monai.handlers.SurfaceDistance(include_background=False, symmetric=False, distance_metric='euclidean', reduction=mean, output_transform=<function SurfaceDistance.<lambda>>, save_details=True)[源码]#

从全尺寸 Tensor 计算表面距离，并对 batch、类通道、迭代进行平均。

__init__(include_background=False, symmetric=False, distance_metric='euclidean', reduction=mean, output_transform=<function SurfaceDistance.<lambda>>, save_details=True)[源码]#
参数:

  • include_background (bool) – 是否在预测输出的第一个通道上包含距离计算。默认为 False。

  • symmetric (bool) – 是否计算 seg_pred 和 seg_gt 之间的对称平均表面距离。默认为 False。

  • distance_metric (str) – : ["euclidean", "chessboard", "taxicab"] 用于计算表面距离的度量标准。默认为 "euclidean"。

  • reduction (UnionType[MetricReduction, str]) – 定义减少指标的模式，仅对 not-nan 值执行减少。可用的减少模式：{"none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"}，默认为 "mean"。如果为 “none”，则不进行减少。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的 surface dice。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

全景质量指标处理器#

class monai.handlers.PanopticQuality(num_classes, metric_name='pq', reduction=mean_batch, match_iou_threshold=0.5, smooth_numerator=1e-06, output_transform=<function PanopticQuality.<lambda>>, save_details=True)[源码]#

从全尺寸 Tensor 计算全景质量，并对 batch、类通道、迭代进行平均。

__init__(num_classes, metric_name='pq', reduction=mean_batch, match_iou_threshold=0.5, smooth_numerator=1e-06, output_transform=<function PanopticQuality.<lambda>>, save_details=True)[源码]#
参数:

  • num_classes (int) – 类别数量。该数字不应包含背景。

  • metric_name (str) – 输出指标。该值可以是 “pq”、“sq” 或 “rq”。

  • reduction (UnionType[MetricReduction, str]) – 定义减少指标的模式，仅对 not-nan 值执行减少。可用的减少模式：{"none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"}，默认为 self.reduction。如果为 “none”，则不进行减少。

  • match_iou_threshold (float) – 用于确定 y_pred 和 y 之间配对的 IOU 阈值。通常应 >= 0.5，y_pred 和 y 的实例之间的配对是唯一的。如果设置 match_iou_threshold < 0.5，此函数使用 Munkres 分配来查找唯一配对的最大数量。

  • smooth_numerator (float) – 加到分子上的一个小数常量，以避免除以零。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的 panoptic quality。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

另请参阅

monai.metrics.panoptic_quality.compute_panoptic_quality()

校准误差指标处理器#

class monai.handlers.CalibrationError(num_bins=20, include_background=True, calibration_reduction=expected, metric_reduction=mean, output_transform=<function CalibrationError.<lambda>>, save_details=True)[源码]#

用于在训练或评估期间计算校准误差的 Ignite 处理器。

为什么校准很重要

一个校准良好的模型产生的概率估计与正确性的真实可能性相匹配。例如，置信度为 80% 的预测应该有大约 80% 的概率是正确的。现代神经网络通常表现出较差的校准（通常过于自信），这在医学成像中可能会造成问题，因为概率估计可能为临床决策提供依据。

此处理器封装了 CalibrationErrorMetric 以供 PyTorch Ignite 引擎使用，自动计算并汇总跨迭代的校准误差。

支持的校准指标

  • 期望校准误差 (ECE): 每桶误差的加权平均值（最常见）。

  • 平均校准误差 (ACE): 各桶之间的无加权平均值。

  • 最大校准误差 (MCE): 最坏情况下的校准误差。

参数:

  • num_bins (int) – 用于校准计算的等间距桶的数量。默认为 20。

  • include_background (bool) – 是否在计算中包含第一个通道（索引 0）。对于分割任务，设置为 False 以排除背景。默认为 True。

  • calibration_reduction (UnionType[CalibrationReduction, str]) – 校准误差减少模式。选项："expected" (ECE), "average" (ACE), "maximum" (MCE)。默认为 "expected"。

  • metric_reduction (UnionType[MetricReduction, str]) – 在计算每个样本的误差后，跨 batch/通道的减少模式。选项："none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"。默认为 "mean"。

  • output_transform (Callable) – 用于从 engine.state.output 中提取 (y_pred, y) 的可调用对象。请参阅 Ignite concepts 和 MONAI 教程仓库中的 batch output transform 教程。

  • save_details (bool) – 如果为 True，将每个样本/每个通道的指标值保存到 engine.state.metric_details[name]。默认为 True。

参考

  • Guo, C., et al. “On Calibration of Modern Neural Networks.” ICML 2017. https://pmlr.com.cn/v70/guo17a.html

  • Barfoot, T., et al. “Average Calibration Losses for Reliable Uncertainty in Medical Image Segmentation.” arXiv:2506.03942v3, 2025. https://arxiv.org/abs/2506.03942v3

另请参阅

示例

>>> from monai.handlers import CalibrationError, from_engine
>>> from ignite.engine import Engine
>>>
>>> def evaluation_step(engine, batch):
...     # Returns dict with "pred" (probabilities) and "label" (one-hot)
...     return {"pred": model(batch["image"]), "label": batch["label"]}
>>>
>>> evaluator = Engine(evaluation_step)
>>>
>>> # Attach calibration error handler
>>> CalibrationError(
...     num_bins=15,
...     include_background=False,
...     calibration_reduction="expected",
...     output_transform=from_engine(["pred", "label"]),
... ).attach(evaluator, name="ECE")
>>>
>>> # After evaluation, access results
>>> evaluator.run(val_loader)
>>> ece = evaluator.state.metrics["ECE"]
>>> print(f"Expected Calibration Error: {ece:.4f}")

均方误差指标处理器#

class monai.handlers.MeanSquaredError(reduction=mean, output_transform=<function MeanSquaredError.<lambda>>, save_details=True)[源码]#

从全尺寸 Tensor 计算均方误差，并对 batch、迭代进行平均。

__init__(reduction=mean, output_transform=<function MeanSquaredError.<lambda>>, save_details=True)[源码]#
参数:

  • reduction (UnionType[MetricReduction, str]) – 定义减少指标的模式，仅对 not-nan 值执行减少。可用的减少模式：{"none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"}，默认为 "mean"。如果为 “none”，则不进行减少。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的均方误差。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

另请参阅

monai.metrics.MSEMetric

平均绝对误差指标处理器#

class monai.handlers.MeanAbsoluteError(reduction=mean, output_transform=<function MeanAbsoluteError.<lambda>>, save_details=True)[源码]#

从全尺寸 Tensor 计算平均绝对误差，并对 batch、迭代进行平均。

__init__(reduction=mean, output_transform=<function MeanAbsoluteError.<lambda>>, save_details=True)[源码]#
参数:

  • reduction (UnionType[MetricReduction, str]) – 定义减少指标的模式，仅对 not-nan 值执行减少。可用的减少模式：{"none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"}，默认为 "mean"。如果为 “none”，则不进行减少。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的均方误差。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

另请参阅

monai.metrics.MAEMetric

均方根误差指标处理器#

class monai.handlers.RootMeanSquaredError(reduction=mean, output_transform=<function RootMeanSquaredError.<lambda>>, save_details=True)[源码]#

从全尺寸 Tensor 计算均方根误差，并对 batch、迭代进行平均。

__init__(reduction=mean, output_transform=<function RootMeanSquaredError.<lambda>>, save_details=True)[源码]#
参数:

  • reduction (UnionType[MetricReduction, str]) – 定义减少指标的模式，仅对 not-nan 值执行减少。可用的减少模式：{"none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"}，默认为 "mean"。如果为 “none”，则不进行减少。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的均方误差。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

另请参阅

monai.metrics.RMSEMetric

峰值信噪比指标处理器#

class monai.handlers.PeakSignalToNoiseRatio(max_val, reduction=mean, output_transform=<function PeakSignalToNoiseRatio.<lambda>>, save_details=True)[源码]#

从全尺寸 Tensor 计算峰值信噪比，并对 batch、迭代进行平均。

__init__(max_val, reduction=mean, output_transform=<function PeakSignalToNoiseRatio.<lambda>>, save_details=True)[源码]#
参数:

  • max_val (UnionType[int, float]) – 图像/体积的动态范围（即，允许的最大值和最小值之间的差异，例如 uint8 图像为 255）。

  • reduction (UnionType[MetricReduction, str]) – 定义减少指标的模式，仅对 not-nan 值执行减少。可用的减少模式：{"none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"}，默认为 "mean"。如果为 “none”，则不进行减少。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的均方误差。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

  • reduction – {"none", "mean", "sum", "mean_batch", "sum_batch",

另请参阅

monai.metrics.PSNRMetric

Metrics Reloaded 二进制指标处理器#

class monai.handlers.MetricsReloadedBinaryHandler(metric_name, include_background=True, reduction=mean, get_not_nans=False, output_transform=<function MetricsReloadedBinaryHandler.<lambda>>, save_details=True)[source]#

MetricsReloadedBinary 的处理器，用于封装 MetricsReloaded 的二进制成对指标。

__init__(metric_name, include_background=True, reduction=mean, get_not_nans=False, output_transform=<function MetricsReloadedBinaryHandler.<lambda>>, save_details=True)[source]#
参数:

  • metric_name (str) – 来自 MetricsReloaded 软件包的二进制指标名称。

  • include_background (bool) – 是否对预测输出的第一个通道进行计算。默认为 True。

  • reduction (UnionType[MetricReduction, str]) – 定义指标的缩减模式，仅对 not-nan 值应用缩减。可用缩减模式：{"none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"}，默认为 "mean"。如果设为“none”，则不进行缩减。

  • get_not_nans (bool) – 是否返回 not_nans 计数。如果为 True，aggregate() 返回 (metric, not_nans)。这里 not_nans 计算该指标非 NaN 的数量，因此其形状与指标形状相同。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的 TP/TN/FP/FN。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

另请参阅

monai.metrics.wrapper()

Metrics Reloaded 分类指标处理器#

class monai.handlers.MetricsReloadedCategoricalHandler(metric_name, include_background=True, reduction=mean, get_not_nans=False, smooth_dr=1e-05, output_transform=<function MetricsReloadedCategoricalHandler.<lambda>>, save_details=True)[source]#

MetricsReloadedCategorical 的处理器，用于封装 MetricsReloaded 的分类成对指标。

__init__(metric_name, include_background=True, reduction=mean, get_not_nans=False, smooth_dr=1e-05, output_transform=<function MetricsReloadedCategoricalHandler.<lambda>>, save_details=True)[source]#
参数:

  • metric_name (str) – 来自 MetricsReloaded 软件包的分类指标名称。

  • include_background (bool) – 是否对预测输出的第一个通道进行计算。默认为 True。

  • reduction (UnionType[MetricReduction, str]) – 定义指标的缩减模式，仅对 not-nan 值应用缩减。可用缩减模式：{"none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"}，默认为 "mean"。如果设为“none”，则不进行缩减。

  • get_not_nans (bool) – 是否返回 not_nans 计数。如果为 True，aggregate() 返回 (metric, not_nans)。这里 not_nans 计算该指标非 NaN 的数量，因此其形状与指标形状相同。

  • smooth_dr (float) – 为分母添加的一个小常数，以避免 nan。注意：应大于零。

  • output_transform (Callable) – 用于从 ignite.engine.state.output 中提取 y_pred 和 y，然后构建 (y_pred, y) 对的可调用对象，其中 y_pred 和 y 可以是 batch-first 的 Tensor，或者是 channel-first 的 Tensor 列表。update() 需要 (y_pred, y) 形式。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例见教程：Project-MONAI/tutorials。

  • save_details (bool) – 是否按图像保存指标计算详情，例如：每个图像的 TP/TN/FP/FN。默认为 True，并将以指标名称为键保存到 engine.state.metric_details 字典中。

另请参阅

monai.metrics.wrapper()

指标记录器#

class monai.handlers.MetricLogger(loss_transform=<function _get_loss_from_output>, metric_transform=<function MetricLogger.<lambda>>, evaluator=None)[source]#

从所连接的训练器中收集每次迭代的指标和损失值。它还会从给定的评估器对象中收集指标值（该评估器预计在训练 epoch 结束时执行评估）。此类可用于在一个地方收集损失和指标值，以便与检查点保存器一起存储（提供 Pytorch 和 Ignite 预期的 state_dict 和 load_state_dict 方法），并用于训练期间的绘图。

示例：

# 构建一个评估器，将平均 Dice 指标值保存在键 “val_mean_dice” 中 evaluator = SupervisedEvaluator(…, key_val_metric={“val_mean_dice”: MeanDice(…)})

# 构建记录器并与评估器关联，以从其中提取指标值 logger = MetricLogger(evaluator=evaluator)

# 将记录器作为处理器传递给训练器，以便记录损失值 trainer = SupervisedTrainer(…, train_handlers=[logger, ValidationHandler(1, evaluator)])

# 运行训练，logger.loss 将是一个 (iteration, loss) 值列表，logger.metrics 是一个以 “val_mean_dice” 为键的字典，存储 (iteration, metric) 值列表 trainer.run()

参数:

  • loss_transform (Callable) – 将训练器状态中的 output 值转换为损失值。engine.state 和 loss_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例请见教程：Project-MONAI/tutorials。

  • metric_transform (Callable) – 将来自训练器/评估器状态的指标值转换为可存储的值。

  • evaluator (Optional[Engine, None]) – 可选的评估器，用于在评估运行结束时消耗其指标结果。

attach(engine)[source]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

attach_evaluator(evaluator)[source]#

将事件处理器附加到给定的评估器上，以记录其中的指标值。

参数:

evaluator (Engine) – 实现网络评估的 Ignite Engine。

返回类型:

None

log_metrics(engine)[source]#

记录给定引擎状态成员中的指标。

参数:

engine (Engine) – 要记录的 Ignite Engine。

返回类型:

None

日志文件处理器#

class monai.handlers.LogfileHandler(output_dir, filename='log.txt', loglevel=20, formatter='%(asctime)s %(name)s %(levelname)s: %(message)s', create_dir=True)[source]#

当开始事件发生时，向所连接引擎的记录器添加一个 logging.FileHandler，并在完成事件发生时将其移除。

需要一个处理器在完成事件发生时移除 FileHandler 对象，以便不同引擎的后续运行仅写入它们应当写入的日志文件，而不是之前的文件。多个处理器可以写入同一个文件，这允许训练和评估引擎对象的输出合并在一个文件中。如果给定的输出目录不存在，默认情况下它会在开始事件发生时被创建。这可以与 CheckpointSaver 结合使用，将日志文件保存到与已保存检查点相同的目标路径。由于处理器可能在初始化期间的其他日志记录事件之后添加，因此并非所有日志数据都会被保留。

参数:

  • output_dir (str) – 保存日志文件的目录。

  • filename (str) – 保存日志的文件名。

  • loglevel (int) – 处理器的日志级别。

  • formatter (str) – 为处理器设置的 logging.Formatter 的格式字符串。

  • create_dir (bool) – 如果为 True，则在 output_dir 不存在时创建它。

训练统计处理器#

class monai.handlers.StatsHandler(iteration_log=True, epoch_log=True, epoch_print_logger=None, iteration_print_logger=None, output_transform=<function StatsHandler.<lambda>>, global_epoch_transform=<function StatsHandler.<lambda>>, state_attributes=None, name='monai.handlers.StatsHandler', tag_name='Loss', key_var_format='{}: {:.4f} ')[source]#

StatsHandler 为所有日志打印逻辑定义了一组 Ignite 事件处理器。它可以用于任何 Ignite Engine（训练器、验证器和评估器），并支持使用预定义的记录器进行 epoch 级和迭代级的日志记录。

注意，如果 name 为 None，此类将利用 engine.logger 作为记录器，否则使用 logging.getLogger(name)。在这两种情况下，务必确保日志级别至少为 INFO。要更改日志级别，请在将此处理器附加到引擎运行之前调用 import ignite; ignite.utils.setup_logger(name)（当 name 不为 None 时）或 engine.logger = ignite.utils.setup_logger(engine.logger.name, reset=True)（当 name 为 None 时）。

默认行为

  • 当 EPOCH_COMPLETED 时，使用 self.logger 记录 engine.state.metrics。

  • 当 ITERATION_COMPLETED 时，使用 self.logger 记录 self.output_transform(engine.state.output)。

使用示例

import ignite
import monai

trainer = ignite.engine.Engine(lambda x, y: [0.0])  # an example trainer
monai.handlers.StatsHandler(name="train_stats").attach(trainer)

trainer.run(range(3), max_epochs=4)

更多示例详情请见教程：Project-MONAI/tutorials。

__init__(iteration_log=True, epoch_log=True, epoch_print_logger=None, iteration_print_logger=None, output_transform=<function StatsHandler.<lambda>>, global_epoch_transform=<function StatsHandler.<lambda>>, state_attributes=None, name='monai.handlers.StatsHandler', tag_name='Loss', key_var_format='{}: {:.4f} ')[source]#
参数:

  • iteration_log (UnionType[bool, Callable[Engine, int, bool]]) – 是否在迭代完成时记录数据，默认为 True。iteration_log 也可以是一个函数，它将被解释为事件过滤器（详细信息请参见 https://pytorch.ac.cn/ignite/generated/ignite.engine.events.Events.html）。事件过滤器函数接收引擎和事件值（迭代）作为输入，并应返回 True/False。事件过滤有助于自定义迭代记录频率。

  • epoch_log (UnionType[bool, Callable[Engine, int, bool]]) – 是否在 epoch 完成时记录数据，默认为 True。epoch_log 也可以是一个函数，它将被解释为事件过滤器。有关更多详细信息，请参阅 iteration_log 参数。

  • epoch_print_logger (Optional[Callable[Engine, Any], None]) – 用于 epoch 级日志记录的自定义可调用打印机。必须接受参数 “engine”，如果为 None，则使用默认打印机。

  • iteration_print_logger (Optional[Callable[Engine, Any], None]) – 用于迭代级日志记录的自定义可调用打印机。必须接受参数 “engine”，如果为 None，则使用默认打印机。

  • output_transform (Callable) – 一个可调用对象，用于将 ignite.engine.state.output 转换为要打印的标量，或 {键: 标量} 的字典。在后一种情况下，输出字符串将格式化为 key: value。默认情况下，此值记录发生在每次迭代完成时。默认行为是打印 output[0] 中的损失，因为 output 是解集列表，我们为解集列表的每一项复制了损失值。engine.state 和 output_transform 继承自 ignite 概念：https://pytorch.ac.cn/ignite/concepts.html#state，解释和使用示例请见教程：Project-MONAI/tutorials。

  • global_epoch_transform (Callable) – 一个可调用对象，用于自定义全局 epoch 编号。例如，在评估中，评估器引擎可能希望打印与训练器引擎同步的 epoch 编号。

  • state_attributes (Optional[Sequence[str], None]) – 预期的 engine.state 属性，如果提供，将在 epoch 完成时提取它们。

  • name (UnionType[str, None]) – 要使用的 logging.logger 的标识符，如果为 None，则默认为 engine.logger。

  • tag_name (str) – 当迭代输出是标量时，tag_name 用于向记录器打印 tag_name: scalar_value。默认为 'Loss'。

  • key_var_format (str) – 控制 key: value 输出字符串格式的格式字符串。

attach(engine)[source]#

向指定的 Ignite 引擎注册一组 Ignite 事件处理器。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

epoch_completed(engine)[source]#

用于训练或验证/评估 epoch 完成事件的处理器。打印 epoch 级日志，默认值来自 Ignite engine.state.metrics 字典。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

exception_raised(_engine, e)[source]#

用于训练或验证/评估异常引发事件的处理器。打印异常信息和回溯。此回调可能会被跳过，因为 Ignite 的逻辑只能触发 EXCEPTION_RAISED 事件的第一个附加处理器。

参数:

  • _engine (Engine) – Ignite Engine，未使用的参数。

  • e (Exception) – 在 engine.run() 期间被 Ignite 捕获的异常。

返回类型:

None

iteration_completed(engine)[source]#

用于训练或验证/评估迭代完成事件的处理器。打印迭代级日志，默认值来自 Ignite engine.state.output。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

Tensorboard 处理器#

class monai.handlers.TensorBoardHandler(summary_writer=None, log_dir='./runs')[source]#

用于将数据写入 TensorBoard 的处理器的基类。

参数:

  • summary_writer (Union[SummaryWriter, SummaryWriter, None]) – 用户可以指定 TensorBoard 或 TensorBoardX SummaryWriter，默认创建一个新的 TensorBoard 编写器。

  • log_dir (str) – 如果使用默认 SummaryWriter，将日志写入此目录，默认为 ./runs。

close()[source]#

如果此 TensorBoard 处理器中创建了 summary writer，则将其关闭。

class monai.handlers.TensorBoardStatsHandler(summary_writer=None, log_dir='./runs', iteration_log=True, epoch_log=True, epoch_event_writer=None, iteration_event_writer=None, output_transform=<function TensorBoardStatsHandler.<lambda>>, global_epoch_transform=<function TensorBoardStatsHandler.<lambda>>, state_attributes=None, tag_name='Loss')[source]#

TensorBoardStatsHandler 为所有 TensorBoard 逻辑定义了一组 Ignite 事件处理器。它可以用于任何 Ignite Engine（训练器、验证器和评估器），并支持使用预定义的 TensorBoard 事件编写器进行 epoch 级和迭代级的日志记录。预期的输入数据源是 Ignite engine.state.output 和 engine.state.metrics。

默认行为

  • 当 EPOCH_COMPLETED 时，将 engine.state.metrics 中的每个字典项写入 TensorBoard。

  • 当 ITERATION_COMPLETED 时，将 self.output_transform(engine.state.output) 中的每个字典项写入 TensorBoard。

用法示例请见教程：Project-MONAI/tutorials。

__init__(summary_writer=None, log_dir='./runs', iteration_log=True, epoch_log=True, epoch_event_writer=None, iteration_event_writer=None, output_transform=<function TensorBoardStatsHandler.<lambda>>, global_epoch_transform=<function TensorBoardStatsHandler.<lambda>>, state_attributes=None, tag_name='Loss')[source]#
参数:

  • summary_writer (Union[SummaryWriter, SummaryWriter, None]) – 用户可以指定 TensorBoard 或 TensorBoardX SummaryWriter，默认创建一个新的 TensorBoard 编写器。

  • log_dir (str) – 如果使用默认 SummaryWriter，将日志写入此目录，默认为 ./runs。

  • iteration_log (UnionType[bool, Callable[Engine, int, bool], int]) – 是否在迭代完成时将数据写入 TensorBoard，默认为 True。iteration_log 也可以是函数或整数。如果为整数，它将被解释为调用 iteration_event_writer 的迭代间隔。如果为函数，它将被解释为事件过滤器（详情请参见 https://pytorch.ac.cn/ignite/generated/ignite.engine.events.Events.html）。事件过滤器函数接收引擎和事件值（迭代）作为输入，并应返回 True/False。

  • epoch_log (UnionType[bool, Callable[Engine, int, bool], int]) – 是否在 epoch 完成时将数据写入 TensorBoard，默认为 True。epoch_log 也可以是函数或整数。如果为整数，它将被解释为调用 epoch_event_writer 的 epoch 间隔。如果为函数，它将被解释为事件过滤器。有关更多详细信息，请参阅 iteration_log 参数。

  • epoch_event_writer (Optional[Callable[Engine, Any, Any], None]) – 用于 epoch 级的自定义可调用 TensorBoard 编写器。必须接受参数 “engine” 和 “summary_writer”，如果为 None，则使用默认事件编写器。

  • iteration_event_writer (Optional[Callable[Engine, Any, Any], None]) – 用于迭代级的自定义可调用 TensorBoard 编写器。必须接受参数 “engine” 和 “summary_writer”，如果为 None，则使用默认事件编写器。

  • output_transform (Callable) – 一个可调用对象，用于将 ignite.engine.state.output 转换为要绘图的标量，或 {键: 标量} 的字典。在后一种情况下，输出字符串将格式化为 key: value。默认情况下，此值绘图发生在每次迭代完成时。默认行为是打印 output[0] 中的损失。详情见上文。

  • global_epoch_transform (Callable) – 一个可调用对象，用于自定义全局 epoch 编号。例如，在评估中，评估器引擎可能希望在绘制 epoch 与指标曲线时使用训练器引擎的 epoch 编号。

  • state_attributes (Optional[Sequence[str], None]) – 预期的 engine.state 属性，如果提供，将在 epoch 完成时提取它们。

  • tag_name (str) – 当迭代输出是标量时，tag_name 用于绘图，默认为 'Loss'。

attach(engine)[source]#

向指定的 Ignite 引擎注册一组 Ignite 事件处理器。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

epoch_completed(engine)[source]#

用于训练或验证/评估 epoch 完成事件的处理器。写入 epoch 级事件，默认值来自 Ignite engine.state.metrics 字典。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

iteration_completed(engine)[source]#

用于训练或验证/评估迭代完成事件的处理器。写入迭代级事件，默认值来自 Ignite engine.state.output。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

class monai.handlers.TensorBoardImageHandler(summary_writer=None, log_dir='./runs', interval=1, epoch_level=True, batch_transform=<function TensorBoardImageHandler.<lambda>>, output_transform=<function TensorBoardImageHandler.<lambda>>, global_iter_transform=<function TensorBoardImageHandler.<lambda>>, index=0, max_channels=1, frame_dim=-3, max_frames=64)[source]#

TensorBoardImageHandler 是一个 Ignite 事件处理器，可以将图像、标签和输出可视化为 2D/3D 图像。2D 输出（形状为 Batch, channel, H, W）将使用批次中的第一个元素作为简单图像显示。对于 3D 到 ND 的输出（形状为 Batch, channel, H, W, D），每张图像（self.max_channels 数量）的最后三个维度将沿着最后一个轴（通常是深度）显示为动画 GIF。如果编写器来自 TensorBoardX，且数据有 3 个通道且 max_channels=3，它将绘制为 RGB 视频。

它可以用于任何 Ignite Engine（训练器、验证器和评估器）。用户可以轻松地将其添加到引擎中以处理任何预期的事件，例如：EPOCH_COMPLETED, ITERATION_COMPLETED。预期的输入数据源是 ignite 的 engine.state.batch 和 engine.state.output。

默认行为

  • 当事件触发时，在 TensorBoard 上将 y_pred 显示为图像（3D 为 GIF）。

  • 需要使用 batch_transform 和 output_transform 来指定要显示多少图像以及显示哪个通道。

  • 期望 batch_transform(engine.state.batch) 返回数据格式: (image[N, channel, …], label[N, channel, …])。

  • 期望 output_transform(engine.state.output) 返回一个 torch 张量，格式为 (y_pred[N, channel, …], loss)。

用法示例请见教程：Project-MONAI/tutorials。

__init__(summary_writer=None, log_dir='./runs', interval=1, epoch_level=True, batch_transform=<function TensorBoardImageHandler.<lambda>>, output_transform=<function TensorBoardImageHandler.<lambda>>, global_iter_transform=<function TensorBoardImageHandler.<lambda>>, index=0, max_channels=1, frame_dim=-3, max_frames=64)[source]#
参数:

  • summary_writer (Union[SummaryWriter, SummaryWriter, None]) – 用户可以指定 TensorBoard 或 TensorBoardX SummaryWriter，默认创建一个新的 TensorBoard 编写器。

  • log_dir (str) – 如果使用默认 SummaryWriter，将日志写入此目录，默认为 ./runs。

  • interval (int) – 每 N 个 epoch 或每 N 次迭代绘制 engine.state 中的内容，默认为 1。

  • epoch_level (bool) – 每 N 个 epoch 或 N 次迭代绘制内容。True 表示 epoch 级，False 表示迭代级。

  • batch_transform (Callable) – 一个可调用对象，用于从 ignite.engine.state.batch 中提取 image 和 label，然后构建 (image, label) 对。例如：如果 ignite.engine.state.batch 为 {“image”: xxx, “label”: xxx, “other”: xxx}，batch_transform 可以是 lambda x: (x[“image”], x[“label”])。将使用结果从 result[0][index] 绘制图像，并从 result[1][index] 绘制标签。

  • output_transform (Callable) – 一个可调用对象，用于从 ignite.engine.state.output 中提取 predictions 数据，将使用结果从 result[index] 绘制输出。

  • global_iter_transform (Callable) – 一个可调用对象，用于自定义 TensorBoard 的全局步数。例如，在评估中，评估器引擎需要知道来自训练器的当前 epoch。

  • index (int) – 绘制数据批次中的哪个元素，默认为第一个元素。

  • max_channels (int) – 要绘制的通道数。

  • frame_dim (int) – 如果将 3D 图像绘制为 GIF，指定用作帧的维度，期望输入数据形状为 NCHWD，默认为 -3（第一个空间维度）。

  • max_frames (int) – 如果在 TensorBoardX 中将 3D RGB 图像绘制为视频，将 FPS 设置为 max_frames。

attach(engine)[source]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

学习率调度处理器#

class monai.handlers.LrScheduleHandler(lr_scheduler, print_lr=True, name=None, epoch_level=True, step_transform=<function LrScheduleHandler.<lambda>>)[source]#

Ignite 处理器，用于根据 PyTorch LR 调度器更新学习率。

__init__(lr_scheduler, print_lr=True, name=None, epoch_level=True, step_transform=<function LrScheduleHandler.<lambda>>)[source]#
参数:

  • lr_scheduler (UnionType[_LRScheduler, ReduceLROnPlateau]) – 通常，lr_scheduler 应该是 PyTorch 的 lr_scheduler 对象。如果是自定义版本，必须具有 step 和 get_last_lr 方法。

  • print_lr (bool) – 是否通过日志打印出最新的学习率。

  • name (Optional[str, None]) – 所使用的 logging.logger 的标识符；如果为 None，则默认为 engine.logger。

  • epoch_level (bool) – 在每个 epoch 或每次迭代后执行 lr_scheduler.step()。True 表示 epoch 级，False 表示迭代级。

  • step_transform (Callable[Engine, Any]) – 一个可调用对象，用于在必要时将来自 engine 的信息转换为 lr_scheduler.step() 函数的预期输入数据。

引发异常:

TypeError – 当 step_transform 不是 callable 时引发。

attach(engine)[source]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

验证处理器#

class monai.handlers.ValidationHandler(interval, validator=None, epoch_level=True, exec_at_start=False)[source]#

将验证器附加到 Ignite 中的训练器引擎。它支持每 N 个 epoch 或每 N 次迭代执行验证。

__init__(interval, validator=None, epoch_level=True, exec_at_start=False)[source]#
参数:

  • interval (int) – 在训练期间每 N 个 epoch 或每 N 次迭代进行验证。

  • validator (Optional[Evaluator, None]) – 触发验证时运行验证器，应为 Evaluator。如果为 None，则应在训练前调用 set_validator()。

  • epoch_level (bool) – 每 N 个 epoch 或 N 次迭代执行验证。True 为 epoch 级，False 为迭代级。

  • exec_at_start (bool) – 是否在开始训练时先执行一次验证。默认为 False。这对某些迁移学习案例尤其有用，可以在训练前验证初始模型。

引发异常:

TypeError – 当 validator 不是 monai.engines.evaluator.Evaluator 时引发。

attach(engine)[source]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

set_validator(validator)[source]#

如果未在 __init__() 中设置，则设置验证器。

返回类型:

None

SmartCache 处理器#

class monai.handlers.SmartCacheHandler(smartcacher)[source]#

将 SmartCache 逻辑附加到 Ignite 中的引擎。主要包括 SmartCacheDataset 的 start、update_cache 和 shutdown 函数。

__init__(smartcacher)[source]#
参数:

smartcacher (SmartCacheDataset) – 预定义的 SmartCacheDataset，将其附加到引擎。

引发异常:

TypeError – 当 smartcacher 不是 monai.data.SmartCacheDataset 时引发。

attach(engine)[source]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

completed(engine)[source]#

用于训练或验证/评估完成事件的回调。停止 SmartCacheDataset 的替换线程。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

epoch_completed(engine)[source]#

用于训练或验证/评估 epoch 完成事件的回调。用替换数据更新缓存内容。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

started(engine)[source]#

用于训练或验证/评估开始事件的回调。启动 SmartCacheDataset 的替换线程。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

参数调度处理器#

class monai.handlers.ParamSchedulerHandler(parameter_setter, value_calculator, vc_kwargs, epoch_level=False, name=None, event=None)[source]#

通用的参数值调度器。默认情况下，它可以使用线性、指数、步进或多步函数进行调度。也可以传递 Callables 以实现自定义调度逻辑。

参数:

  • parameter_setter (Callable) – 设置所需参数的函数。

  • value_calculator (Union[str,Callable]) – 字符串（‘linear’, ‘exponential’, ‘step’ 或 ‘multistep’）或用于自定义逻辑的 Callable。

  • vc_kwargs (Dict) – 存储 value_calculator 所需参数的字典。

  • epoch_level (bool) – 步进是基于 epoch 还是迭代。默认为 False。

  • name (Optional[str]) – 要使用的 logging.logger 的标识符，如果为 None，则默认为 engine.logger。

  • event (Optional[str]) – 处理程序附加到的事件。默认为 Events.ITERATION_COMPLETED。

attach(engine)[source]#
参数:

engine (Engine) – 用于训练的 Ignite Engine。

返回类型:

None

早停处理器#

class monai.handlers.EarlyStopHandler(patience, score_function, trainer=None, min_delta=0.0, cumulative_delta=False, epoch_level=True)[source]#

EarlyStopHandler 是一个 Ignite 处理器，用于在经过一定数量的事件后若无改进则停止训练。它基于 ignite 中的 EarlyStopping 处理器。

参数:

  • patience (int) – 如果没有改进则等待的事件数量，超过此数量后停止训练。

  • score_function (Callable) – 它应该是一个接受单个参数的函数，即处理器所附加的 Engine 对象（可以是训练器或验证器），并返回一个 float 得分。如果得分更高，则视为有改进。

  • trainer (Optional[Engine, None]) – 如果没有改进则用于停止运行的训练器引擎；如果为 None，则必须在训练前调用 set_trainer()。

  • min_delta (float) – 被视为改进的最小得分增加量，即增加量小于或等于 min_delta 时，将计为无改进。

  • cumulative_delta (bool) – 如果为 True，min_delta 定义了自上次 patience 重置以来的增加量；否则，它定义了上一个事件之后的增加量，默认为 False。

  • epoch_level (bool) – 在每个 epoch 还是附加引擎的每次迭代时检查提前停止；True 为 epoch 级别，False 为迭代级别，默认为 epoch 级别。

注意

如果在分布式训练中使用每次迭代的损失值来检测提前停止，那么不同 rank 中的值可能会有所不同。在分布式训练中使用此处理器时，请注意，为防止“dist.destroy_process_group()”挂起，可以使用“all_reduce”操作在所有 rank 之间同步停止信号。该机制可以在 score_function 中实现。以下是一个示例。

import os

import torch
import torch.distributed as dist


def score_function(engine):
    val_metric = engine.state.metrics["val_mean_dice"]
    if dist.is_initialized():
        device = torch.device("cuda:" + os.environ["LOCAL_RANK"])
        val_metric = torch.tensor([val_metric]).to(device)
        dist.all_reduce(val_metric, op=dist.ReduceOp.SUM)
        val_metric /= dist.get_world_size()
        return val_metric.item()
    return val_metric

用户可以将此处理器附加到验证器引擎以检测验证指标并停止训练，在这种情况下，score_function 在验证器引擎上执行，而 trainer 是训练器引擎。

attach(engine)[source]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

set_trainer(trainer)[source]#

如果未在 __init__() 中正确设置训练器，则在此处设置。

返回类型:

None

垃圾回收处理器#

class monai.handlers.GarbageCollector(trigger_event='epoch', log_level=10)[source]#

在每个 epoch 之后运行垃圾回收

参数:

  • trigger_event (UnionType[str, Events, CallableEventWithFilter]) – 触发此处理器的事件。 - “epoch”，在每个 epoch 完成后（相当于 ignite.engine.Events.EPOCH_COMPLETED） - “iteration”，在每次迭代完成后（相当于 ignite.engine.Events.ITERATION_COMPLETED） - 任何来自 ignite.engine.Events 的 ignite 内置事件。默认为 “epoch”。

  • log_level (int) – 一些垃圾回收信息的日志级别（整数）。默认为 10 (DEBUG)。 - 50 (CRITICAL) - 40 (ERROR) - 30 (WARNING) - 20 (INFO) - 10 (DEBUG) - 0 (NOTSET)

后处理#

class monai.handlers.PostProcessing(transform, event='MODEL_COMPLETED')[source]#

Ignite 处理器，用于在引擎的后处理之后执行额外的后处理。因此，用户可以在引擎后处理和此后处理处理器之间插入其他处理器。如果将 monai.transforms 中的组件作为 transform 使用，建议先在引擎中（设置 decollate=True）或在 DecollateBatch 处理器中解批（decollate）engine.state.batch 和 engine.state.batch。

__init__(transform, event='MODEL_COMPLETED')[source]#
参数:

  • transform (Callable) – 在 engine.state.batch 和 engine.state.output 上执行的可调用函数，也可以是组合变换。

  • event (str) – 附加处理器的预期事件，应为 “MODEL_COMPLETED” 或 “ITERATION_COMPLETED”。默认为 “MODEL_COMPLETED”。

attach(engine)[source]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

解批（Decollate batch）#

class monai.handlers.DecollateBatch(event='MODEL_COMPLETED', detach=True, decollate_batch=True, batch_keys=None, decollate_output=True, output_keys=None, allow_missing_keys=False)[source]#

Ignite 处理器，用于对 engine.state.batch 和 engine.state.output 执行 decollate batch 逻辑。典型用法是在引擎中设置 decollate=False，先执行一些后处理逻辑，然后再解批，否则引擎会在后处理之前解批。

参数:

  • event (str) – 附加处理器的预期事件，应为 “MODEL_COMPLETED” 或 “ITERATION_COMPLETED”。默认为 “MODEL_COMPLETED”。

  • detach (bool) – 是否分离张量。标量张量将被分离为数值类型，而不是 torch 张量。

  • decollate_batch (bool) – 是否解批 ignite 引擎的 engine.state.batch。

  • batch_keys (Union[Collection[Hashable], Hashable, None]) – 如果 decollate_batch=True，指定 engine.state.batch 中要解批的相应项的键。请注意，它将删除未指定的其他键。如果为 None，将解批所有键。它将标量值复制到解批列表的每一项中。

  • decollate_output (bool) – 是否解批 ignite 引擎的 engine.state.output。

  • output_keys (Union[Collection[Hashable], Hashable, None]) – 如果 decollate_output=True，指定 engine.state.output 中要解批的相应项的键。请注意，它将删除未指定的其他键。如果为 None，将解批所有键。它将标量值复制到解批列表的每一项中。

  • allow_missing_keys (bool) – 如果键丢失，不要引发异常。

attach(engine)[source]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

MLFlow 处理器#

class monai.handlers.MLFlowHandler(tracking_uri=None, iteration_log=True, epoch_log=True, epoch_logger=None, iteration_logger=None, dataset_logger=None, dataset_dict=None, dataset_keys=image, output_transform=<function MLFlowHandler.<lambda>>, global_epoch_transform=<function MLFlowHandler.<lambda>>, state_attributes=None, tag_name='Loss', experiment_name='monai_experiment', run_name=None, experiment_param=None, artifacts=None, optimizer_param_names='lr', close_on_complete=False)[source]#

MLFlowHandler 为 MLFlow 跟踪逻辑定义了一组 Ignite 事件处理器。它可以用于任何 Ignite 引擎（训练器、验证器和评估器）。它可以同时跟踪 epoch 级别和迭代级别的日志，以便 MLFlow 可以存储数据并进行可视化。预期数据源是 Ignite engine.state.output 和 engine.state.metrics。

默认行为

  • 当 EPOCH_COMPLETED 时，跟踪 engine.state.metrics 中的每个字典项到 MLFlow。

  • 当 ITERATION_COMPLETED 时，跟踪 self.output_transform(engine.state.output) 中的预期项到 MLFlow，默认为 Loss。

用法示例请见教程：Project-MONAI/tutorials。

参数:

  • tracking_uri (Optional[str, None]) – 连接到跟踪 URI。也可以设置 MLFLOW_TRACKING_URI 环境变量，让 MLflow 从中查找 URI。在这两种情况下，URI 既可以是远程服务器的 HTTP/HTTPS URI、数据库连接字符串，也可以是将数据记录到目录的本地路径。URI 默认为路径 mlruns。更多详细信息请参考： https://mlflow.org.cn/docs/latest/python_api/mlflow.html#mlflow.set_tracking_uri。

  • iteration_log (UnionType[bool, Callable[Engine, int, bool]]) – 是否在迭代完成时将数据记录到 MLFlow，默认为 True。iteration_log 也可以是一个函数，它将被解释为事件过滤器（详细信息请参见 https://pytorch.ac.cn/ignite/generated/ignite.engine.events.Events.html）。事件过滤器函数接受 engine 和事件值（迭代）作为输入，并应返回 True/False。

  • epoch_log (UnionType[bool, Callable[Engine, int, bool]]) – 是否在 epoch 完成时将数据记录到 MLFlow，默认为 True。epoch_log 也可以是一个函数，它将被解释为事件过滤器。更多详细信息请参见 iteration_log 参数。

  • epoch_logger (Optional[Callable[Engine, Any], None]) – 用于 MLFlow epoch 级别记录的自定义可调用记录器。必须接受参数 “engine”，如果为 None，则使用默认记录器。

  • iteration_logger (Optional[Callable[Engine, Any], None]) – 用于 MLFlow 迭代级别记录的自定义可调用记录器。必须接受参数 “engine”，如果为 None，则使用默认记录器。

  • dataset_logger (Optional[Callable[Mapping[str, Dataset], Any], None]) – 用于记录数据集信息的自定义可调用记录器。必须接受参数 “dataset_dict”，如果为 None，则使用默认记录器。

  • dataset_dict (Optional[Mapping[str, Dataset], None]) – 一个字典，其中键是数据集名称，值是需要记录的 PyTorch 数据集。此参数仅在 MLFlow 版本 >= 2.4.0 时有用。关于如何使用 MLFlow 记录数据的更多详细信息，请访问网站： https://mlflow.org.cn/docs/latest/python_api/mlflow.data.html。

  • dataset_keys (str) – 用于指示数据集中需要由 MLFlow 存储的内容的键或键集合。

  • output_transform (Callable) – 一个用于将 ignite.engine.state.output 转换为标量（用于跟踪）或 {key: scalar} 字典的可调用对象。默认情况下，此值记录发生在每次迭代完成时。默认行为是跟踪 output[0] 中的损失，因为输出是一个解批列表，我们为解批列表中的每一项复制了损失值。engine.state 和 output_transform 继承自 ignite 概念： https://pytorch-ignite.ai/concepts/03-state/，教程中有解释和使用示例： Project-MONAI/tutorials。

  • global_epoch_transform (Callable) – 一个用于自定义全局 epoch 编号的可调用对象。例如，在评估中，评估器引擎可能需要跟踪与训练器引擎同步的 epoch 编号。

  • state_attributes (Optional[Sequence[str], None]) – 预期的 engine.state 属性，如果提供，将在 epoch 完成时提取它们。

  • tag_name (str) – 当迭代输出为标量时，使用 tag_name 进行跟踪，默认为 ‘Loss’。

  • experiment_name (str) – MLflow 的实验名称，默认为 ‘monai_experiment’。实验可用于记录多个运行。

  • run_name (Optional[str, None]) – 实验中的运行名称。运行可用于记录关于工作流的信息，如损失、指标等。

  • experiment_param (Optional[dict, None]) – 一个记录在整个工作流中不会改变的参数的字典，如 torch 版本、cuda 版本等。

  • artifacts (Union[str, Sequence[Path], None]) – 运行工作流后需要记录的图像路径。

  • optimizer_param_names (UnionType[str, Sequence[str]]) – 运行工作流期间需要记录的优化器中的参数名称，默认为 ‘lr’。

  • close_on_complete (bool) – 是否在工作流的 complete 阶段关闭 mlflow 运行，默认为 False。

关于 MLFlow 使用的更多详细信息，请参考： https://mlflow.org.cn/docs/latest/index.html。

attach(engine)[source]#

向指定的 Ignite 引擎注册一组 Ignite 事件处理器。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

close()[source]#

停止当前运行的 MLFlow 记录器。

返回类型:

None

complete()[source]#

训练或验证/评估完成事件的处理器。

返回类型:

None

epoch_completed(engine)[source]#

训练或验证/评估 epoch 完成事件的处理器。跟踪 epoch 级别日志，默认值来自 Ignite engine.state.metrics 字典。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

iteration_completed(engine)[source]#

训练或验证/评估迭代完成事件的处理器。跟踪迭代级别日志。

参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

start(engine)[source]#

检查 MLFlow 状态，如果未激活则启动。

返回类型:

None

ClearML 处理器#

class monai.handlers.ClearMLHandler(project_name, task_name, output_uri, tags, reuse_last_task_id, continue_last_task, auto_connect_frameworks, auto_connect_arg_parser)[source]#

将所有内容记录到 ClearML 的处理器基类。关于 ClearML 使用的更多详细信息，请参考： https://clearml.machinelearning.org.cn/docs/latest/docs/references/sdk/task

用法示例请见教程：Project-MONAI/tutorials。

__init__(project_name, task_name, output_uri, tags, reuse_last_task_id, continue_last_task, auto_connect_frameworks, auto_connect_arg_parser)[source]#
参数:

  • project_name (UnionType[str, None]) – ClearML 项目名称，默认为 ‘MONAI’。

  • task_name (UnionType[str, None]) – ClearML 任务名称，默认为 ‘monai_experiment’。

  • output_uri (UnionType[str, bool]) – 输出模型和其他工件的默认位置，默认为 ‘True’。

  • tags (UnionType[Sequence[str], None]) – 将标签列表 (str) 添加到创建的任务中，默认为 ‘None’。

  • reuse_last_task_id (bool) – 使用先前使用的任务 ID 强制执行新任务（实验），默认为 ‘True’。

  • continue_last_task (bool) – 继续执行先前执行的任务（实验），默认为 ‘False’。

  • auto_connect_frameworks (UnionType[bool, Mapping[str, UnionType[bool, str, list]]]) – 自动连接框架，默认为 ‘True’。

  • auto_connect_arg_parser (UnionType[bool, Mapping[str, bool]]) – 自动将 argparse 对象连接到任务，默认为 ‘True’。

class monai.handlers.ClearMLStatsHandler(project_name='MONAI', task_name='monai_experiment', output_uri=True, tags=None, reuse_last_task_id=True, continue_last_task=False, auto_connect_frameworks=True, auto_connect_arg_parser=True, *args, **kwargs)[source]#

通过继承 TensorBoardStatsHandler 类来编写 tensorboard 统计信息的类。来自 Tensorboard 的所有内容都会自动记录到 ClearML。

用法示例请见教程：Project-MONAI/tutorials。

__init__(project_name='MONAI', task_name='monai_experiment', output_uri=True, tags=None, reuse_last_task_id=True, continue_last_task=False, auto_connect_frameworks=True, auto_connect_arg_parser=True, *args, **kwargs)[source]#
参数:

  • project_name (UnionType[str, None]) – ClearML 项目名称，默认为 ‘MONAI’。

  • task_name (UnionType[str, None]) – ClearML 任务名称，默认为 ‘monai_experiment’。

  • output_uri (UnionType[str, bool]) – 输出模型和其他工件的默认位置，默认为 ‘True’。

  • tags (Optional[Sequence[str], None]) – 将标签列表 (str) 添加到创建的任务中，默认为 ‘None’。

  • reuse_last_task_id (bool) – 使用先前使用的任务 ID 强制执行新任务（实验），默认为 ‘True’。

  • continue_last_task (bool) – 继续执行先前执行的任务（实验），默认为 ‘False’。

  • auto_connect_frameworks (UnionType[bool, Mapping[str, UnionType[bool, str, list]]]) – 自动连接框架，默认为 ‘True’。

  • auto_connect_arg_parser (UnionType[bool, Mapping[str, bool]]) – 自动将 argparse 对象连接到任务，默认为 ‘True’。

class monai.handlers.ClearMLImageHandler(project_name='MONAI', task_name='monai_experiment', output_uri=True, tags=None, reuse_last_task_id=True, continue_last_task=False, auto_connect_frameworks=True, auto_connect_arg_parser=True, *args, **kwargs)[source]#

此类继承了 TensorBoardImageHandler 类的所有功能。来自 Tensorboard 的所有内容都会自动记录到 ClearML。

用法示例请见教程：Project-MONAI/tutorials。

__init__(project_name='MONAI', task_name='monai_experiment', output_uri=True, tags=None, reuse_last_task_id=True, continue_last_task=False, auto_connect_frameworks=True, auto_connect_arg_parser=True, *args, **kwargs)[source]#
参数:

  • project_name (UnionType[str, None]) – ClearML 项目名称，默认为 ‘MONAI’。

  • task_name (UnionType[str, None]) – ClearML 任务名称，默认为 ‘monai_experiment’。

  • output_uri (UnionType[str, bool]) – 输出模型和其他工件的默认位置，默认为 ‘True’。

  • tags (Optional[Sequence[str], None]) – 将标签列表 (str) 添加到创建的任务中，默认为 ‘None’。

  • reuse_last_task_id (bool) – 使用先前使用的任务 ID 强制执行新任务（实验），默认为 ‘True’。

  • continue_last_task (bool) – 继续执行先前执行的任务（实验），默认为 ‘False’。

  • auto_connect_frameworks (UnionType[bool, Mapping[str, UnionType[bool, str, list]]]) – 自动连接框架，默认为 ‘True’。

  • auto_connect_arg_parser (UnionType[bool, Mapping[str, bool]]) – 自动将 argparse 对象连接到任务，默认为 ‘True’。

NVTX 处理器#

用于分析 MONAI ignite 工作流的 NVIDIA 工具扩展包装器

class monai.handlers.nvtx_handlers.MarkHandler(event, msg=None)[source]#

标记在某个点发生的瞬时事件。

参数:

msg (Optional[str, None]) – 与范围关联的 ASCII 消息

attach(engine)[source]#

将 NVTX 标记添加到特定的 Ignite 事件 :type engine: Engine :param engine: Ignite 引擎，可以是训练器、验证器或评估器。

返回类型:

None

class monai.handlers.nvtx_handlers.RangeHandler(events, msg=None)[source]#

将 NVTX 范围附加到一对 Ignite 事件。它在第一个事件处推送 NVTX 范围，并在第二个事件处弹出它。存储已启动范围的从零开始的深度。

参数:

  • events (UnionType[str, tuple[UnionType[str, Events], UnionType[str, Events]]]) – 一个字符串、一对 Ignite 事件、一对 Ignite 事件字面量或一对 Ignite 事件和字面量。如果提供单个字符串，它应该描述一对默认 Ignite 事件的基名称，带有 _STARTED 和 _COMPLETED 后缀（如 “EPOCH” 对应 Events.EPOCH_STARTED 和 Events.EPOCH_COMPLETED）。接受的事件有：BATCH、ITERATION、EPOCH 和 ENGINE。如果是字面量对，每一项都应该是 Ignite 事件的字面量等价物，例如：(“EPOCH_STARTED” 和 “EPOCH_COMPLETED”)。可以将事件和字面量组合，如 (Events.EPOCH_STARTED 和 “EPOCH_COMPLETED”)。有关事件的完整列表，请查看 https://pytorch.ac.cn/ignite/generated/ignite.engine.events.Events.html。

  • msg (Optional[str, None]) – 与范围关联的 ASCII 消息。如果未提供，第一个事件的名称将被分配给 NVTX 范围。

attach(engine)[source]#

将 NVTX 范围附加到特定 Ignite 事件 :type engine: Engine :param engine: Ignite 引擎，可以是训练器、验证器或评估器。

返回类型:

None

create_paired_events(event)[source]#

从事件前缀名称创建 Ignite 事件对

返回类型:

tuple[Events, Events]

resolve_events(events)[source]#

解析输入事件以创建 Ignite 事件对

返回类型:

tuple[Events, Events]

class monai.handlers.nvtx_handlers.RangePopHandler(event)[source]#

在特定事件处，弹出先前推送的范围。存储已启动范围的从零开始的深度。

参数:

msg – 与范围关联的 ASCII 消息

attach(engine)[source]#

在特定 Ignite 事件处弹出 NVTX 范围 :type engine: Engine :param engine: Ignite 引擎，可以是训练器、验证器或评估器。

返回类型:

None

class monai.handlers.nvtx_handlers.RangePushHandler(event, msg=None)[source]#

在特定事件处，将范围推送到嵌套范围跨度的堆栈上。存储已启动范围的从零开始的深度。

参数:

msg (Optional[str, None]) – 与范围关联的 ASCII 消息

attach(engine)[source]#

在特定 Ignite 事件处推送 NVTX 范围 :type engine: Engine :param engine: Ignite 引擎，可以是训练器、验证器或评估器。

返回类型:

None

实用工具#

monai.handlers.utils.from_engine(keys, first=False)[source]#

处理字典或字典列表（例如：engine.state.batch 或 engine.state.output）时，简化 ignite 组件的 batch_transform 或 output_transform 参数的实用函数。用户只需设置预期的键，它将返回一个可调用函数，用于从字典中提取数据并分别构造一个元组。

如果数据是解批后的字典列表，则分别提取预期的键并构造列表。例如，如果数据是 [{“A”: 1, “B”: 2}, {“A”: 3, “B”: 4}]，from_engine([“A”, “B”]): ([1, 3], [2, 4])。

它可以帮助避免复杂的 lambda 函数，并使指标参数更直接。例如，设置第一个键作为预测值，第二个键作为标签，以从 engine.state.output 获取指标所需的预期数据。 

from monai.handlers import MeanDice, from_engine

metric = MeanDice(
    include_background=False,
    output_transform=from_engine(["pred", "label"])
)
参数:

  • keys (UnionType[Collection[Hashable], Hashable]) – 用于从字典或解批后的字典列表中提取数据的指定键。

  • first (bool) – 如果输入数据是字典列表，是否仅从第一项中提取指定键；它用于提取没有批处理维度且在解批时被复制到每个字典中的标量数据，如 loss 等。

返回类型:

可调用对象

monai.handlers.utils.stopping_fn_from_loss()[source]#

返回一个使用损失值的 ignite.handlers.EarlyStopping 停止函数。

返回类型:

Callable[Engine, Any]

monai.handlers.utils.stopping_fn_from_metric(metric_name)[source]#

返回一个使用给定指标名称的 ignite.handlers.EarlyStopping 停止函数。

返回类型:

Callable[Engine, Any]

monai.handlers.utils.write_metrics_reports(save_dir, images, metrics, metric_details, summary_ops, deli=',', output_type='csv', class_labels=None)[source]#

将指标写入文件的实用函数，包含 3 个部分：1. 如果 metrics 字典不为 None，将整体指标写入文件，每一行都是一个指标名称和值对。2. 如果 metric_details 字典不为 None，将每幅图像的原始指标数据写入文件，每一行对应 1 幅图像。3. 如果 summary_ops 不为 None，根据对 metric_details 的操作计算汇总并写入文件。

参数:

  • save_dir (UnionType[str, PathLike]) – 保存所有指标报告的目录。

  • images (UnionType[Sequence[str], None]) – 对应于 metric_details 数据的每个输入图像的名称或路径。如果为 None，将使用索引号作为每个输入图像的文件名。

  • metrics (UnionType[dict[str, UnionType[Tensor, ndarray]], None]) – (指标名称, 指标值) 对的字典。

  • metric_details (UnionType[dict[str, UnionType[Tensor, ndarray]], None]) – (指标名称, 指标原始值) 对的字典，通常来自指标计算，例如，原始值可以是每个输入图像每个通道的 mean_dice。

  • summary_ops (UnionType[str, Sequence[str], None]) –

    用于生成摘要报告的预期计算操作。可以是 None、“*” 或字符串列表，默认为 None。None - 不为每个预期的 metric_details 生成摘要报告。 “*” - 使用所有支持的操作为每个 metric_details 生成摘要报告。 字符串列表 - 使用指定的操作为每个 metric_details 生成摘要报告，这些操作应在列表内：[“mean”, “median”, “max”, “min”, “<int>percentile”, “std”, “notnans”]。 “<int>percentile” 中的数字应在 [0, 100] 之间，例如：“15percentile”。默认：“90percentile”。更多详情，请查看：https://numpy.com.cn/doc/stable/reference/generated/numpy.nanpercentile.html。注意：对于总体摘要，它首先计算每个图像所有类别的 nanmean，然后计算摘要。生成的摘要报告示例

    class    mean    median    max    5percentile 95percentile  notnans
class0  6.0000   6.0000   7.0000   5.1000      6.9000       2.0000
class1  6.0000   6.0000   6.0000   6.0000      6.0000       1.0000
mean    6.2500   6.2500   7.0000   5.5750      6.9250       2.0000

  • deli (str) – 已保存文件中的分隔符字符，默认为 “,”，因为默认输出类型为 csv。与以下内容保持一致： https://docs.pythonlang.cn/3/library/csv.html#csv.Dialect.delimiter。

  • output_type (str) – 预期的输出文件类型，支持的类型：[“csv”]，默认为 “csv”。

  • class_labels (Optional[list[str], None]) – 用于在输出报告中命名类别的类名列表，如果为 None，则使用 “class0”, …, “classn”，默认为 None。

返回类型:

None

概率图处理器#

class monai.handlers.probability_maps.ProbMapProducer(output_dir='./', output_postfix='', prob_key='pred', dtype=<class 'numpy.float64'>, name=None)[source]#

在完成每次迭代时触发的事件处理器，用于计算并保存概率图。此处理器使用来自 MetaTensor 的元数据来创建概率图。这可以通过使用 monai.data.SlidingPatchWSIDataset 或 monai.data.MaskedPatchWSIDataset 作为数据集来轻松实现。

__init__(output_dir='./', output_postfix='', prob_key='pred', dtype=<class 'numpy.float64'>, name=None)[source]#
参数:

  • output_dir (str) – 用于保存概率图的输出目录。

  • output_postfix (str) – 附加到所有输出文件名的字符串。

  • prob_key (str) – 与模型概率输出相关联的键。

  • dtype (UnionType[dtype, type, str, None]) – 存储概率图的数据类型。默认为 np.float64。

  • name (Optional[str, None]) – 所使用的 logging.logger 的标识符，默认为 engine.logger。

attach(engine)[source]#
参数:

engine (Engine) – Ignite 引擎，它可以是训练器、验证器或评估器。

返回类型:

None

save_prob_map(name)[source]#

此方法在图像推理完成后保存其概率图，并从内存中删除该概率图。

参数:

name (str) – 要保存的图像名称。

返回类型:

None

本页目录
显示源码