⚡ Faster Filtering in Patch Dataset

[measty]

• API Change for PatchExtractor.filter_coordinates. Instead of coordinate_resolution, coordinate_units, & mask_resolution, it takes slide_shape and a callable function func to validate the coordinates as input. New implementation is about ~200 times fast.

I've been using WSIPatchDataset for something recently, and noticed that it uses filter_coordinates method of PatchExtractor, instead of the faster filter_coordinates_fast. I can't see any reason why it shouldn't use the faster version - I am guessing that its just a case of, when the faster version was added, WSIPatchDataset was never updated to use it.

So, this PR updates it to use the faster method, and also includes a few other small improvements like allowing the min_mask_ratio argument to be used in the WSIPatchDataset in the same way it is available for patch extractor, so that behaviour between PatchExtractor and WSIPatchDataset is consistent.

Changes in this PR:

1. WSIPatchDataset now uses filter_coordinates_fast, consistent with PatchExtractor.
2. filter_coordinates_fast now uses the relative scale between the wsi dimensions at the requested patch resolution, and the mask dimensions, as the scale factor. This is units-agnostic and gives consistent results regardless of mode. Also doesn't make an even lower-res thumbnail of an already low-res mask as it did previously, which was unnecessary and could have had some wierd effects with masks which were already very low-res.
3. the documented post_proc argument now exists and will be used if given. Changed the documentation to reflect its functionality (ie its just called as is on the patch before it is returned)
4. Allows min_mask_ratio to be used in WSIPatchDataset, consistent with usage in PatchExtractor.

Rough performance comparison:
~0.6 sec using filter_coordinates_fast
~4 min using filter_coordinates
consistent with what was reported in original PR which added filter_coordinates_fast to PatchExtractor.

The PR also replicates the ability to provide a custom 'filter func' from filter_coordinates into filter_coordinates_fast, so in theory we can now get rid of filter_coordinates as it does nothing filter_coordinates_fast doesn't do.

[codecov]

Codecov Report

Merging #571 (0635e0d) into develop (41b3c66) will decrease coverage by 0.01%.
The diff coverage is 100.00%.

@@             Coverage Diff             @@
##           develop     #571      +/-   ##
===========================================
- Coverage    99.63%   99.63%   -0.01%     
===========================================
  Files           62       62              
  Lines         6626     6609      -17     
  Branches      1081     1073       -8     
===========================================
- Hits          6602     6585      -17     
  Misses          15       15              
  Partials         9        9              

Impacted Files	Coverage Δ
tiatoolbox/models/dataset/classification.py	100.00% <100.00%> (ø)
tiatoolbox/tools/patchextraction.py	100.00% <100.00%> (ø)
tiatoolbox/tools/registration/wsi_registration.py	99.50% <100.00%> (ø)
tiatoolbox/wsicore/wsireader.py	99.42% <100.00%> (ø)

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[blaginin]

It feels like a good idea to mark filter_coordinates as deprecated to remove it in the future versions

[measty]

It feels like a good idea to mark filter_coordinates as deprecated to remove it in the future versions

We were considering just removing it and renaming the current filter_coordinates_fast to be filter_coordinates, though depreciation may be a good option instead. Perhaps @shaneahmed could comment on which approach would be preferable?

[shaneahmed]

It feels like a good idea to mark filter_coordinates as deprecated to remove it in the future versions

We were considering just removing it and renaming the current filter_coordinates_fast to be filter_coordinates, though depreciation may be a good option instead. Perhaps @shaneahmed could comment on which approach would be preferable?

I would suggest to replace it as this was the initial intention. filter_coordinates_fast was not intended for use.

[shaneahmed]

Thanks @measty