pathml skill

PathML

Scope and safety boundary

Use PathML for local computational pathology research. It is beta research software, not a validated medical device, diagnostic system, clinical decision support tool, or substitute for a pathologist. Do not use outputs to diagnose, grade, stage, or treat a patient.

Pathology files may contain faces, labels, accession numbers, patient identifiers, DICOM tags, filenames, or linked clinical data. Before processing:

analysis workspace.

1. Confirm authorization, consent/waiver, data-use terms, and institutional policy.
2. De-identify pixels and metadata; keep the re-identification key outside the

direct identifiers in filenames, logs, .h5path labels, model cards, or reports.

1. Use pseudonymous patientid, slideid, and specimen_id values. Do not put

1. Keep inputs, intermediates, and outputs on approved local encrypted storage.
2. Split by patient (then slide) before tiling or fitting any preprocessing step.

Version baseline, verified 2026-07-23

PyPI does not declare Requires-Python and still has a stale 3.8 classifier, so use the release statement and test the exact environment.

• Installable stable release: PyPI pathml==3.0.5, published 2026-03-24.
• The v3.0.5 release notes state Python 3.10-3.12 and sunset 3.9.

no artifacts for them as of this review. v3.0.7 updates Torch/TorchVision/ torch-geometric and ONNX export code. Do not mix those source dependencies with the 3.0.5 wheel.

• GitHub releases v3.0.6 (2026-04-14) and v3.0.7 (2026-07-09) exist, but PyPI has

against the v3.0.5 tag and PyPI wheel metadata, not unversioned snippets.

• ReadTheDocs /latest identifies itself as 3.0.5. Examples here were checked

licensing options; review upstream terms before redistribution.

• This skill is MIT-licensed. PathML itself is GPL-2.0 with upstream commercial

Reproducible installation

Use Python 3.11 unless the project has tested another supported interpreter:

uv venv --python 3.11
source .venv/bin/activate
uv pip install "pathml==3.0.5"
python -c "import importlib.metadata as m; print(m.version('pathml'))"

PathML 3.0.5 declares no package extras: do not use pathml[all]. Its base distribution pins a large scientific/ML stack, including Torch 2.8.0, ONNX 1.17.0, ONNX Runtime 1.17.x, OpenSlide Python 1.3.1, python-bioformats 4.1.0, and python-javabridge 4.0.4.

Install native prerequisites before the uv command:

# Debian/Ubuntu
sudo apt-get install openslide-tools gcc g++ libblas-dev liblapack-dev openjdk-17-jdk

# macOS
brew install openslide openjdk@17

# Windows OpenSlide option documented upstream
vcpkg install openslide

Java/Bio-Formats is needed for the broad multidimensional format backend. OpenSlide handles common brightfield WSI formats more efficiently. CUDA is optional and must match the pinned PyTorch build; follow PyTorch's platform selector rather than guessing a CUDA wheel. See references/image_loading.md.

Stable minimal workflow

PathML 3.0.5 uses slide convenience classes and SlideData.run(). It does not provide SlideData.from_slide(), and Pipeline does not have run():

from pathml.core import HESlide
from pathml.preprocessing import BoxBlur, Pipeline, TissueDetectionHE

slide = HESlide("data/pseudonymous_slide.svs", backend="openslide")
pipeline = Pipeline(
    [
        BoxBlur(kernel_size=5),
        TissueDetectionHE(mask_name="tissue", min_region_size=5000),
    ]
)
slide.run(
    pipeline,
    distributed=False,
    tile_size=512,
    tile_stride=512,
    level=0,
    tile_pad=False,
)
slide.write("derived/pseudonymous_slide.h5path")

Start with a bounded manual sample before a full run:

from itertools import islice

for tile in islice(slide.generate_tiles(shape=512, stride=512, level=0), 8):
    pipeline.apply(tile)
    assert tile.masks["tissue"].shape[:2] == tile.image.shape[:2]

Tiles use (i, j) = (row, column) coordinates at the selected pyramid level. For OpenSlide, PathML maps them to level-0 coordinates internally. Record the level and downsample; convert to (x, y) or micrometres explicitly downstream.

Research workflow

allowlisted technical metadata, and remove identifiers.

1. Inventory locally. Validate the manifest, reject URLs/symlinks, inspect only

generating overlapping tiles, graphs, normalization references, or features.

1. Freeze splits. Assign every patient and all their slides to one split before

stain behavior, edge padding, and empty-mask cases on representative training slides. Do not tune from test slides.

1. Plan bounds. Estimate tile count, RAM, output size, and pipeline stages.
2. Pilot preprocessing. Inspect tissue masks, whitespace/artifact labels,

mask names, QC decisions, and failed/skipped tiles.

1. Run and preserve coordinates. Keep tile level, (i, j), downsample, MPP,

instance labels, node-feature alignment, graph edges, and cell-to-tissue assignments.

1. Build spatial data deliberately. Validate channel order, physical units,

loading unknown pickle checkpoints. Keep predictions linked to slide/tile coordinates and stitch overlaps with a documented rule.

1. Infer in bounded batches. Verify model provenance and checksum without

stain, parameters, seeds, split manifest, model card, exclusions, and QC.

1. Report provenance and limits. Include package lock, source hashes, scanner,

No-network default and explicit consent gate

Do not instantiate download-capable classes or set dataset download=True unless the user explicitly opts in after receiving the endpoint and disclosure:

https://huggingface.co/pathml/test/resolve/main/mesmer.onnx at construction, then runs inference locally. Stable source does not upload image pixels. The request still discloses network metadata such as IP address and headers and creates temp.onnx; there is no built-in checksum or offline flag.

• SegmentMIFRemote downloads an ONNX file from

initialization may need separately provisioned weights. It is not a PathML extra and is not the preferred stable API.

• Deprecated SegmentMIF imports local DeepCell Mesmer, but DeepCell model

contacts Zenodo. Both default to download=False.

• RemoteTestHoverNet downloads a model from Hugging Face.
• PanNukeDataModule(download=True) contacts Warwick; DeepFocusDataModule

Before any future hosted prediction call, state the exact destination, pixel channels/regions, metadata, identifiers, retention, legal basis, and safeguards; obtain explicit consent; and never send PHI by default. Prefer reviewed, checksummed local model artifacts and local inference.

Model-code security

dangerous built-in evaluator. Never use Python dynamic evaluation or execution.

• PyTorch model.eval() means evaluation mode for modules; it is not Python's

libraries; shadow modules can silently change imports.

• Do not name local files pathml.py, torch.py, onnx.py, or after standard