Faster slide reading with cuCIM
This release adds [cuCIM](https://github.com/rapidsai/cucim) as a slide reading backend, which is now used by default if available. cuCIM is 2-3x faster for whole-slide image reading, with lighter CPU utilization and about half the memory footprint. It is also much easier to install, requiring only pip:
pip install slideflow[cucim] cupy-cuda11x
cuCIM only supports SVS and TIFF images, however, so users working with other slide formats may opt to continue using Libvips. The Libvips backend can be manually enabled by setting the environmental variable `SF_SLIDE_BACKEND=libvips`.
New QC functionality
Slide quality control (QC) methods are now customizable, and can be used during training by passing any Callable or list of Callables to `sf.WSI.qc()`. Example QC functions (Otsu and Gaussian) are available in `sf.slide.qc`, and would be applied as so:
python
from slideflow.slide import qc
wsi = sf.WSI(...)
wsi.qc([qc.Otsu(), qc.Gaussian(sigma=3)]
Additionally, QC masks can now be saved to disk for reproducibility and efficiency. To automatically save a QC mask after generation, use the `sf.slide.qc.Save` and `sf.slide.qc.Load` functions. The former accepts an optional path argument in which the masks will be saved; if not supplied, masks will be saved in the same directory as the slides.
python
from slideflow.slide import qc
Save QC masks after generation
wsi = sf.WSI(...)
wsi.qc([qc.Otsu(), qc.Save('/path/to/directory')])
...
Load any previously saved QC masks
wsi = sf.WSI(...)
wsi.qc([qc.Load('/path/to/directory')])
This same interface can be used when using the project-level function `Project.extract_tiles()`:
python
P.extract_tiles(..., qc=[qc.Otsu()])
Easier dataset reproduction
It is now much easier to setup and reproduce an existing project, particularly if the slides are available at the [Genomic Data Commons](https://portal.gdc.cancer.gov/) (GDC). The new `sf.project.create()` function uses a project configuration file and an internal GDC manifest to automatically setup a project from a given annotations file, download slides, and verify integrity with MD5 hashing.
Several example datasets are now provided in `datasets/` to assist with easy initial setup. Setting up a new project, including automatic slide downloads, is as easy as:
python
import slideflow as sf
P = sf.project.create(
'/home/project',
cfg='slideflow/datasets/thyroid_brs/thyroid_brs.json')
download=True
Custom training loss
Models can now be trained with custom loss functions by supplying a dictionary to the `loss` argument in `sf.ModelParams`, with the keys `type` and `fn`. `type` must be either `'categorical'`, `'linear'`, or `'cph'`, and 'fn' is a callable loss function.
Tensorflow/Keras
For Tensorflow/Keras, the loss function must accept arguments `y_true, y_pred`. `y_true` will not be one-hot encoded. For linear losses, `y_true` may need to be cast to `tf.float32`. An example custom linear loss is given below:
python
def custom_linear_loss(y_true, y_pred):
y_true = tf.cast(y_true, tf.float32)
squared_difference = tf.square(y_true - y_pred)
return tf.reduce_mean(squared_difference, axis=-1)
This loss would be applied as follows:
python
hp = sf.ModelParams(..., loss={'type': 'linear', 'fn': custom_linear_loss})
PyTorch
For PyTorch, the loss function must return a nested loss function with arguments `output, target`. An example linear loss is given below:
python
def custom_linear_loss():
def loss_fn(output, target):
return torch.mean((target - output) ** 2)
return loss_fn
This would be applied as follow:
python
hp = sf.ModelParams(..., loss={'type': 'linear', 'fn': custom_linear_loss})
Optimizations
- Tile extraction now saves a CSV report of all extraction parameters, QC methods, image format, and backend/version in the same folder as the PDF report.
- Decreased memory utilization when training from whole-slide images (`from_wsi=True`)
- Change default `roi_method` from `'inside'` to `'auto'` for `Project.generate_heatmaps()`
Bug fixes
- Fixes `numeric_only` futurewarning for Pandas
- Fixes `StopIteration` error when training models using `from_wsi=True` in the PyTorch backend
- Specifies supported `tensorflow_probability` version in setup.py to match Tensorflow compatibility
- Renames `sf.header()` -> `sf.about()`
- Add `requests` to package requirements