Automated Machine Learning for Image Classification in Whole-Slide Imaging with Multiple Instance Learning.
AutoMIL is a flexible, open-source, end-to-end pipeline for training and evaluating Multiple Instance Learning (MIL) models for image classification on whole-slide images (WSIs). It provides a modular command-line interface (CLI) that enables straightforward usage and adaptation to diverse WSI datasets. In addition to the CLI, AutoMIL exposes a Python API for programmatic use, allowing users to build their own custom workflows.
automil run-pipeline ./slides ./annotations.csv ./project -v
Documentation · Installation · Quickstart
- End-to-end CLI: The command
run-pipelinecovers everything from raw slides to an evaluation report.train,evaluateandpredictrun individual stages, whilecreate-splithandles dataset splitting. - Memory-aware batch sizing: the largest batch size that fits the available GPU memory is found automatically (see How it works).
- Multiple MIL architectures: Attention-MIL, TransMIL and a Bistro transformer, selectable with
-m. - Resolution presets: tile size and magnification are chosen from named presets (
Ultra_LowtoUltra) and models can be trained can be trained on several presets in one run. - Flexible input: standard WSI formats (
.svs,.tiff, OME-TIFF, …), PNG slides via automatic TIFF conversion, and pretiled datasets. - Evaluation and interpretability: metrics, ROC curves, model comparison plots, ensemble predictions and attention heatmaps.
- Python API: every CLI stage is backed by a class (
Project,Dataset,Trainer,Evaluator, …) for custom workflows.
AutoMIL builds on Slideflow for slide I/O and tile extraction, and on fastai for training. AutoMIL adds automation around these components, handling tasks such as resource-aware hyperparameter selection, feature extraction, and end-to-end pipeline management.
1. Project and dataset setup. Annotations are validated and normalised, so custom patient, slide and label column names are supported. The average Microns-Per-Pixel (MPP) is read from the slides, and each resolution preset is translated into a physical tile size in µm, which keeps tiling consistent across scanners.
2. Slide backend selection. Slideflow reads slides with cuCIM by default. AutoMIL checks the input and switches to libvips when it is needed (OME-TIFF files, or PNG slides that must be converted to TIFF).
3. Feature bags. Tiles are embedded with a pretrained pathology foundation model (CTransPath) and stored as one feature bag per slide.
4. Resource-aware hyperparameters. Choosing a batch size for MIL is awkward because each sample is a bag of hundreds to thousands of tiles. AutoMIL's ResourceOptimizer:
- instantiates the selected model and runs a real forward and backward pass on dummy bags of the dataset's average bag size, to measure peak GPU memory (
MemoryEstimator); - doubles the batch size until the measured peak exceeds 90% of free memory, then binary-searches the boundary;
- rejects candidates that break dataset or model constraints (a batch larger than the dataset, too few steps per epoch, model-specific limits) using a cheap feasibility check before any GPU work is done;
- caches measurements, so repeated probes are free.
Training runs with automatic mixed precision and early stopping. On CPU-only machines it falls back to safe defaults.
5. Training and evaluation. Models are trained with k-fold cross-validation. The Evaluator then computes Accuracy, AUC, AP and F1 per model and for the ensemble, and writes comparison plots and attention heatmaps.
Example of an evaluation plot generated by automil evaluate (quickstart demo run on a 100-slide TCGA lung subset).
Requirements: Linux, Python 3.11+ and a CUDA-capable GPU or CPU are required. AutoMIL depends on Slideflow and cuCIM, which are developed for Linux. libvips (pip install .[vips]) is optional and needed only for OME-TIFF or PNG input.
git clone https://github.com/frankkramer-lab/AutoMIL.git
cd AutoMIL
pip install .See the installation guide for details.
AutoMIL can be installed directly from its public GitHub repository. To download the source code, open a terminal, navigate to any directory and run:
git clone https://github.com/frankkramer-lab/AutoMILThis will clone the projects source code inside a new directory called ./automil. Navigate to this directory and install AutoMIL in your current python environment:
pip install .A dataset is a directory of slides plus a CSV file with one label per slide:
dataset/
├── slides/
│ ├── case_001.svs
│ ├── case_002.svs
│ └── case_003.svs
└── annotations.csv
patient,slide,label
001,case_001,0
002,case_002,0
003,case_003,1Train (5-fold cross-validation, TransMIL):
automil train ./dataset/slides ./dataset/annotations.csv ./project -m TransMIL -k 5 -vEvaluate the trained models:
automil evaluate ./dataset/slides ./dataset/annotations.csv ./project/bags ./project/models -o ./project/evaluation -vOr do both in one step with automil run-pipeline. Run automil <command> --help for all options, including custom column names (-pc, -lc, -sc), multi-resolution runs (-r "Low,High") and predefined train/test splits (--split-file).
The quickstart guide walks through a full run on a public TCGA lung cancer subset.
automil/
├── cli.py # Click-based command line interface
├── project.py # Project scaffolding and annotation handling
├── dataset.py # Resolution presets, tiling and feature bag generation
├── model.py # Model registry and model-specific constraints
├── trainer.py # k-fold training on top of fastai
├── resource_optimizer.py # Memory-aware batch size search
├── memory.py # Empirical peak-memory measurement
├── feasibility.py # Dataset and model constraint checks
├── runtime.py # Device and mixed-precision handling
├── evaluation.py # Metrics, ensembles and plots
└── util/ # Slide backends, pretiled input, TIFF conversion, logging
AutoMIL is licensed under the GNU General Public License v3.0.