markowetzlab / pathml

A Python library for deep learning on whole-slide images

PathML: a Python library for deep learning on whole-slide images

PathML is a Python library for performing deep learning image analysis on whole-slide images (WSIs), including deep tissue, artefact, and background filtering, tile extraction, model inference, model evaluation and more.

Please see our tutorial repository to learn how to use PathML on an example problem from start to finish.

Installing PathML and its depedencies

Install PathML by cloning its repository:

git clone https://github.com/markowetzlab/pathml

PathML is best run inside an Anaconda environment. Once you have installed Anaconda, you can create pathml-env, a conda environment containing all of PathML's dependencies, then activate that environment. Make sure to adjust the path to your local path to the pathml repository:

conda env create -f /path/to/pathml/pathml-environment.yml
conda activate pathml-env

Note that pathml-environment.yml installs Python version 3.7, PyTorch version 1.4, Torchvision version 0.5, and CUDA version 10.0. Stable versions above these should also work as long as the versions are cross-compatible. Be sure that the CUDA version matches the version installed on your GPU; if not, either update your GPU's CUDA or change the cudatoolkit line of pathml-environment.yml to match your GPU's version before creating pathml-env.

Some users have run into an error message saying that something from libvips is missing when PathML tries to import pyvips. This is because on some operating systems, the pip install of pyvips performed in the conda env create command leads to a flawed pyvips build. To solve this issue, also install pyvips using conda in pathml-env:

conda install -c conda-forge pyvips

For users who don't wish to use conda, PathML can also be installed via pip. To do so, navigate to to the pathml directory containing setup.py, and run the following command:

pip install -e .

Learning to use PathML

See our extensive tutorial here.

Documentation

The complete documentation for PathML including its API reference can be found here.

Disclaimer

Note that this is prerelease software. Please use accordingly.

pathml's Issues

inferClassifier freezes

Thank you very much for a great development!
The software installed fine and training executes well with gpu support.
However, following training, the slide inference step freezes....
Tried to reduce batch size, but this had no effect.
Presumably this is a pytorch issue?
Many thanks for your help.

start_time = time.time()

class_names = ['metastasis', 'non_metastasis']
means_and_stds = pickle.load(open(os.path.join(analysis_dir_path, 'classification_results', 'trainval_channel_means_and_stds.p'), 'rb'))
modelPath = glob.glob(os.path.join(analysis_dir_path, 'classification_results', 'classification_best_model*'))[0]

dataTransforms = transforms.Compose([
transforms.Resize(224),
transforms.ToTensor(),
transforms.Normalize(means_and_stds['channel_means'], means_and_stds['channel_stds'])])

trainedModel = models.vgg19_bn(pretrained=False)
num_ftrs = trainedModel.classifier[6].in_features
trainedModel.classifier[6] = nn.Linear(num_ftrs, len(class_names))
trainedModel.load_state_dict(torch.load(modelPath))

for case in val_cases + test_cases:
pathml_slide = Slide(os.path.join(analysis_dir_path, 'pathml_slides', case+'.pml'))
######## this step freezes......
pathml_slide.inferClassifier(trainedModel, classNames=class_names, dataTransforms=dataTransforms, tissueLevelThreshold=0.995, foregroundLevelThreshold=88)
pathml_slide.save(folder=pathml_slide_dir_path)

time_elapsed = time.time() - start_time
print('Complete in {:.0f}m {:.0f}s'.format(time_elapsed // 60, time_elapsed % 60))

OUTPUT
Inferring model on GPU
0%| | 0/60 [00:00<?, ?it/s]

SPEC
i9 with 16 CPU and 64GB RAM with GPU
Ubuntu 20.04

GPU allocation:
'|===========================================================================|\n| PyTorch CUDA memory summary, device ID 0 |\n|---------------------------------------------------------------------------|\n| CUDA OOMs: 0 | cudaMalloc retries: 0 |\n|===========================================================================|\n| Metric | Cur Usage | Peak Usage | Tot Alloc | Tot Freed |\n|---------------------------------------------------------------------------|\n| Allocated memory | 2669 MB | 3418 MB | 11114 GB | 11111 GB |\n| from large pool | 2663 MB | 3412 MB | 11086 GB | 11084 GB |\n| from small pool | 5 MB | 6 MB | 27 GB | 27 GB |\n|---------------------------------------------------------------------------|\n| Active memory | 2669 MB | 3418 MB | 11114 GB | 11111 GB |\n| from large pool | 2663 MB | 3412 MB | 11086 GB | 11084 GB |\n| from small pool | 5 MB | 6 MB | 27 GB | 27 GB |\n|---------------------------------------------------------------------------|\n| GPU reserved memory | 2742 MB | 3544 MB | 4022 MB | 1280 MB |\n| from large pool | 2736 MB | 3536 MB | 4012 MB | 1276 MB |\n| from small pool | 6 MB | 8 MB | 10 MB | 4 MB |\n|---------------------------------------------------------------------------|\n| Non-releasable memory | 74728 KB | 218569 KB | 3400 GB | 3400 GB |\n| from large pool | 74416 KB | 217124 KB | 3369 GB | 3369 GB |\n| from small pool | 312 KB | 2924 KB | 31 GB | 31 GB |\n|---------------------------------------------------------------------------|\n| Allocations | 446 | 501 | 1512 K | 1511 K |\n| from large pool | 70 | 115 | 675 K | 675 K |\n| from small pool | 376 | 430 | 837 K | 836 K |\n|---------------------------------------------------------------------------|\n| Active allocs | 446 | 501 | 1512 K | 1511 K |\n| from large pool | 70 | 115 | 675 K | 675 K |\n| from small pool | 376 | 430 | 837 K | 836 K |\n|---------------------------------------------------------------------------|\n| GPU reserved segments | 37 | 61 | 65 | 28 |\n| from large pool | 34 | 57 | 60 | 26 |\n| from small pool | 3 | 4 | 5 | 2 |\n|---------------------------------------------------------------------------|\n| Non-releasable allocs | 18 | 48 | 767 K | 767 K |\n| from large pool | 16 | 36 | 387 K | 387 K |\n| from small pool | 2 | 26 | 380 K | 380 K |\n|---------------------------------------------------------------------------|\n| Oversize allocations | 0 | 0 | 0 | 0 |\n|---------------------------------------------------------------------------|\n| Oversize GPU segments | 0 | 0 | 0 | 0 |\n|===========================================================================|\n'