pathml

Files (13)

• SKILL.md
• data_management.md · references/
• graphs.md · references/
• image_loading.md · references/
• machine_learning.md · references/
• multiparametric.md · references/
• preprocessing.md · references/
• _common.py · scripts/
• image_qc.py · scripts/
• plan_inference.py · scripts/
• plan_pipeline.py · scripts/
• slide_manifest.py · scripts/
• validate_spatial_schema.py · scripts/

SKILL.md (first lines)

# 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:

1. Confirm authorization, consent/waiver, data-use terms, and institutional policy.
2. De-identify pixels and metadata; keep the re-identification key outside the
   analysis workspace.
3. Use pseudonymous `patient_id`, `slide_id`, and `specimen_id` values. Do not put
   direct identifiers in filenames, logs, `.h5path` labels, model cards, or reports.
4. Keep inputs, intermediates, and outputs on approved local encrypted storage.
5. Split by patient (then slide) before tiling or fitting any preprocessing step.

## Version baseline, reviewed 2026-10-01

- **Published stable release:** PyPI `pathml==3.0.8`, published 2026-08-14,
  source tag `v3.0.8` (`fa49ffb66757ed8a8265756c92b6290834eddecb`).
- The v3.0.5 release notes state Python **3.10-3.12** and sunset 3.9.
  PyPI does not declare `Requires-Python` and still has a stale 3.8 classifier, so
  use the release statement and test the exact environment.
- The current wheel incorporates the Torch/PyG dependency updates and explicit
  legacy ONNX export (`dynamo=False`). ReadTheDocs pages/search caches can show
  different versions; the 3.0.8 wheel and tagged source determine these APIs.
- Bundled CLIs are tested with synthetic data. PathML examples and installation
  commands are **illustrative, source-checked**, not a full native-stack or
  pathology-model execution claim. No slides, model weights, or datasets were
  downloaded for this review.
- This skill is MIT-licensed. PathML itself is GPL-2.0 with upstream commercial
  licensing options; review upstream terms before redistribution.

## Reproducible installation

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

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

PathML 3.0.8 declares no package extras: do **not** use `pathml[all]`. Its base
distribution pins a large scientific/ML stack, including Torch 2.12.0, ONNX 1.22.0,
ONNX Runtime 1.17.x, OpenSlide Python 1.3.1, python-bioformats 4.1.0, and
python-javabridge 4.0.4, torch-geometric 2.8.0, and onnxscript 0.7.1. It also pins
NumPy below 2 and several older binary packages; do not upgrade them independently.

Install native prerequisites before the uv command:

```bash
# 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
```

`python-javabridge==4.0.4` is source-only on PyPI and needs a **JDK** (including
`javac`/JNI headers), not just a JRE. Set `JAVA_HOME` to that JDK before building.
PathML imports the Java bridge/Bio-Formats in its shared backend module even when
the requested reader is OpenSlide; selecting OpenSlide does not avoid those
installation dependencies. Old import-error advice mentioning Java 8 and
`javabridge==1.0.19` does not match the released wheel requirements.

Java/Bio-Formats provides 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.8 uses slide convenience classes and `SlideData.run()`. It does not
provide `SlideData.from_slide()`, and `Pipeline` does not have `run()`:

```python
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:

```python
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.
PathML 3.0.8 truncates OpenSlide's downsample to an integer when locating a region.
Use level 0 or an exactly integral downsample; a fractional downsample can shift

From K-Dense-AI/scientific-agent-skills, MIT.

More from K-Dense-AI/scientific-agent-skills