Infer ROI Module

This module contains functions to perform nuclei detection on Regions of Interest (ROIs).

Infer ROI Parser

The infer_roi parser allows you to configure various parameters for nuclei detection. Below are the details of each argument:

  • slide_folder (positional argument): Input filename pattern.

  • -o, –outdir: Output directory. Default is ./output/.

  • -m, –model_path: Path to the pre-trained model. Default is ./hoverfast_crosstissue_best_model.pth.

  • -p, –poly_simplify: Float representing the tolerance for simplifying the polygons. Default is 6.

  • -s, –size_threshold: Minimum size threshold for nuclei area in square micrometers. Default is 85.

  • -st –stain: Staining type, choose between he and ihc_dab, default he.

  • -r, –batch_mem: Maximum batches saved in memory (RAM). Default is 500.

  • -g, –batch_gpu: Target batch size for GPU. Default is calculated based on available GPU VRAM.

  • -n, –n_process: Number of workers for multiprocessing. Default is os.cpu_count().

  • -w, –width: Width of the cells border shown in the overlay. Default is 2.

  • -c, –color: Color of polygon shown on the overlay. Refer to Matplotlib colors for more information. Default is limegreen.

Usage Examples

Basic Usage

This example demonstrates the basic usage of the infer_roi command with minimal arguments, processing a batch of ROIs using default settings. This assumes that the default pretrained model is in the current working directory

HoverFast infer_roi /path/to/rois/*.png -o /path/to/output/

Explanation:

  • Input: ROIs located at /path/to/rois/ with the .png extension.

  • Output: Results saved in the directory /path/to/output/.

  • Uses default values for all other parameters.

Custom Model Path

In this example, we specify a custom path for the pre-trained model.

HoverFast infer_roi /path/to/rois/*.png -m /path/to/custom_model.pth -o /path/to/output/

Explanation:

  • Input: ROIs located at /path/to/rois/.

  • Model: Custom model located at /path/to/custom_model.pth.

  • Output: Results saved in /path/to/output/.

Adjusting Polygon Simplification

Adjusting the polygon simplification tolerance to reduce output file size and speed up file writing. This can be useful if you do not require detailed nuclei contours.

HoverFast infer_roi /path/to/rois/*.png -p 8 -o /path/to/output/

Explanation:

  • Input: ROIs located at /path/to/rois/.

  • Polygon Simplification: Set the tolerance to 8 for simplifying the contour of polygons.

  • Output: Results saved in /path/to/output/.

Thresholding Nuclei Size

Setting a minimum size threshold for detected nuclei to filter out small detections. This can be adjusted according to your analysis requirements.

HoverFast infer_roi /path/to/rois/*.png -s 10 -o /path/to/output/

Explanation:

  • Input: ROIs located at /path/to/rois/.

  • Size Threshold: Minimum nuclei area of 10 square micrometers.

  • Output: Results saved in /path/to/output/.

Custom GPU Batch Sizes

Setting custom sizes for GPU batches to optimize VRAM consumption. By default, HoverFast tries to maximize VRAM usage, but sometimes, using less VRAM can be useful.

HoverFast infer_roi /path/to/rois/*.png -g 3 -o /path/to/output/

Explanation:

  • Input: ROIs located at /path/to/rois/.

  • GPU Batch Size: GPU processes 3 batches at a time.

  • Output: Results saved in /path/to/output/.

Using Multiprocessing

Utilizing multiple CPU cores for faster processing. HoverFast can highly benefit from using more CPU threads.

HoverFast infer_roi /path/to/rois/*.png -n 20 -o /path/to/output/

Explanation:

  • Input: ROIs located at /path/to/rois/.

  • CPU Cores: Use 20 threads for multiprocessing.

  • Output: Results saved in /path/to/output/.

Adjusting Overlay Width and Color

Customizing the width and color of the cells border shown in the overlay. This can be useful for better visual representation of detected nuclei.

HoverFast infer_roi /path/to/rois/*.png -w 3 -c red -o /path/to/output/

Explanation:

  • Input: ROIs located at /path/to/rois/.

  • Width: Set the border width to 3 pixels.

  • Color: Set the border color to red.

  • Output: Results saved in /path/to/output/.

Segmenting Cells with Nuclear DAB Stain

Using the new -st flag to specify the type of staining for segmentation. This example demonstrates the use of the ihc_dab option. This should be used when the DAB stain is nuclear. If the dab stain is cytoplasmic, regular H&E segmentation might be a better option.

HoverFast infer_roi /path/to/rois/*.png -st ihc_dab -o /path/to/output/

Explanation:

  • Input: Slides located at /path/to/slides/.

  • Stain: Specifies the type of staining as ihc_dab.

  • Output: Results saved in /path/to/output/.