← Về thư mục
📄 / / profiles / r-and-d / raw_evidence / scientific-agent-skills / skills / pathml / references / machine_learning.md

Machine learning, inference batching, and model trust

This reference targets PathML 3.0.5 from PyPI. GitHub v3.0.7 changes Torch dependencies and ONNX export behavior but is not published on PyPI as of 2026-07-23; do not mix v3.0.7 source instructions into a 3.0.5 environment.

Stable ML exports

from pathml.ml import (
    GNNLayer,
    HACTNet,
    HoVerNet,
    TileDataset,
    loss_hovernet,
    post_process_batch_hovernet,
)

The documented dataset import is usually:

from pathml.datasets import TileDataset

PathML provides model architectures and helpers. Stable constructors do not accept pretrained=True, do not expose mode="fast", and do not download official HoVer-Net/HACTNet checkpoints automatically.

HoVer-Net

Stable constructor:

from pathml.ml import HoVerNet

model = HoVerNet(n_classes=6)

Use the class count and label order from the exact dataset schema. PanNuke's stable PathML representation can use five nucleus categories plus background; do not silently map labels from another implementation.

Training helpers:

from pathml.ml import loss_hovernet, post_process_batch_hovernet

outputs = model(images)
loss = loss_hovernet(
    outputs=outputs,
    ground_truth=[nucleus_mask, horizontal_vertical_map],
    n_classes=6,
)

instances, classified_instances = post_process_batch_hovernet(
    outputs=outputs,
    n_classes=6,
    small_obj_size_thresh=10,
    kernel_size=21,
    h=0.5,
    k=0.5,
)

Verify tensor shapes from the stable API:

NP logits: (batch, 2, height, width)
HV maps:   (batch, 2, height, width)
NC logits: (batch, n_classes, height, width)

post_process_batch_hovernet returns instance maps with 0 as background and positive object IDs. The classification output uses one channel per class with instance IDs in the selected class channel.

Evaluation mode is not dynamic evaluation

PyTorch's model.eval() method switches module behavior such as dropout and batch normalization to evaluation mode. It is not Python's dangerous built-in expression evaluator and does not execute a string.

To avoid ambiguity in executable examples, the equivalent explicit form is:

import torch

model.train(False)
with torch.inference_mode():
    outputs = model(images)

Never use Python dynamic evaluation or execution to load a model, transform, configuration, metric, or class name. Use an allowlist and normal constructors.

PanNuke training data

from pathml.datasets import PanNukeDataModule

data = PanNukeDataModule(
    data_dir="approved_data/pannuke",
    download=False,
    shuffle=True,
    nucleus_type_labels=True,
    split=1,
    batch_size=8,
    hovernet_preprocess=True,
)

train_loader = data.train_dataloader
validation_loader = data.valid_dataloader
test_loader = data.test_dataloader

The dataloaders are properties, not methods. hovernet_preprocess=True adds the HV target. Set download=True only after explicit consent to the Warwick download, storage estimate, license review, and endpoint disclosure.

Do not assume the published folds satisfy every patient/source-slide grouping claim. Audit the dataset's provenance and duplicates for the intended study.

HACTNet

Stable signature:

from pathml.ml import HACTNet

model = HACTNet(
    cell_params=cell_gnn_parameters,
    tissue_params=tissue_gnn_parameters,
    classifier_params=classifier_parameters,
)

HACTNet consumes a batched HACTPairData object with cell and tissue features, their edge indices, a cell-to-tissue assignment, and a target. Parameter dictionaries configure PathML GNNLayer and its classifier; use the v3.0.5 tutorial/API rather than copying a configuration from another PyG release.

Before training, validate:

pathml.datasets.EntityDataset loads .pt graph objects with unrestricted PyTorch deserialization. Use it only for trusted project-generated artifacts.

Checkpoint trust

Never load an untrusted .pt, .pth, .ckpt, pickle, joblib, or saved pipeline. Such formats can execute code during deserialization.

For a trusted checkpoint:

  1. obtain it from the model owner or an approved registry;
  2. verify exact SHA-256/signature before opening;
  3. record architecture source revision, dependency lock, license, training data, preprocessing, class order, and expected tensor schema;
  4. inspect in a disposable network-disabled environment;
  5. load only the minimal weights-only representation when the producing PyTorch version supports it;
  6. enforce file, tensor, RAM, time, and device limits; and
  7. validate on synthetic tensors before any pathology data.

The bundled planner refuses checkpoint/model extensions and never imports Torch, ONNX, PathML, or a model class.

Local ONNX inference

Stable exports:

from pathml.inference import (
    HaloAIInference,
    Inference,
    check_onnx_clean,
    convert_pytorch_onnx,
    remove_initializer_from_input,
)

For a reviewed local model:

from pathml.core import SlideData
from pathml.inference import Inference
from pathml.preprocessing import Pipeline

inference = Inference(
    model_path="models/reviewed_model.onnx",
    input_name="data",
    num_classes=4,
    model_type="segmentation",
    local=True,
)
pipeline = Pipeline([inference])

slide = SlideData(
    "data/slide-001.ome.tiff",
    backend="bioformats",
    stain="Fluor",
)
slide.run(
    pipeline,
    distributed=False,
    tile_size=256,
    tile_stride=256,
    level=0,
)

Stable Inference.apply() replaces tile.image with model output. If the raw image must be preserved, write a custom reviewed transform that stores predictions separately or use a separate inference loop.

Inference:

remove_initializer_from_input(source, destination) rewrites the model. Do not overwrite the original; verify the destination hash and outputs. ONNX parsing is not a guarantee of safety—malformed models can exploit parser/runtime bugs or request excessive resources.

Source-only ONNX difference after 3.0.5

GitHub v3.0.7 release notes report:

PyPI pathml==3.0.5 instead declares Torch 2.8.0, torch-geometric 2.3.1, ONNX 1.17.0, and ONNX Runtime >=1.17,<1.18. An ONNX file exported with newer source may use operators unsupported by the stable runtime. Validate opset and runtime compatibility explicitly.

Remote model classes

Do not instantiate without explicit network consent:

Stable code downloads model bytes and performs inference locally; it does not upload slide pixels. The GET still discloses connection metadata and lacks a built-in checksum/size/timeout policy. Prefer approved local artifacts.

See multiparametric.md for the full consent template.

Bounded inference planning

Plan without opening a model:

python scripts/plan_inference.py \
  --tile-count 4000 \
  --batch-size 16 \
  --channels 3 \
  --height 256 \
  --width 256 \
  --dtype float32 \
  --activation-multiplier 8 \
  --max-memory-mib 4096

Or supply a bounded strict JSON model card containing only metadata:

{
  "schema_version": "1.0",
  "model_id": "reviewed-hovernet",
  "artifact_sha256": "hex-digest",
  "input_shape": [3, 256, 256],
  "dtype": "float32",
  "output_elements_per_tile": 589824,
  "activation_multiplier": 8.0
}

python scripts/plan_inference.py \
  --model-card models/reviewed_model_card.json \
  --root . \
  --tile-count 4000 \
  --batch-size 16

The estimate is a planning bound, not a GPU profiler. Include model parameters, runtime workspace, framework caches, graph memory, postprocessing, and stitching headroom. Pilot at a smaller batch and monitor actual peak memory.

Batch execution

For local PyTorch architecture code:

import torch

model.train(False)
for tile_images, tile_masks, tile_labels, slide_labels in loader:
    inputs = tile_images.to(device, non_blocking=True)
    with torch.inference_mode():
        outputs = model(inputs)
    # Move bounded outputs to CPU and attach the original slide/tile coordinates.

PathML's label dictionaries may need a custom collate_fn; never lose coordinate keys. Avoid collecting all prediction maps in RAM. Stream bounded batches to a structured local output and flush per slide.

For ONNX, stable Inference operates one PathML tile at a time because its reshape method adds a batch dimension. For true batch inference, build a separate reviewed ONNX Runtime loop around TileDataset, validate the model's dynamic or fixed batch axis, and retain coordinates.

Overlap and stitching

For dense outputs:

PathML includes tile-stitching utilities, but verify their stable signature and output semantics for the exact task rather than assuming average, max, or weighted options from unrelated examples.

Evaluation

PathML 3.0.5 does not export the broad pathml.ml.metrics.dice_coefficient/panoptic_quality API shown in older references. Implement or import metrics from a pinned, validated package and record the exact definition.

For segmentation/classification:

Choose thresholds on training/validation only. Keep the test set sealed until the analysis plan is frozen. Do not treat tiles/nuclei as independent patients.

Model provenance card

Record:

Never include direct patient identifiers or sensitive example tiles in a model card.

Sources, accessed 2026-07-23