Nuclei classification can run without feature / annotation files (#1051)

Author: subinkitware

histomicstk/cli/NucleiClassification/NucleiClassification.py

@@ -3,7 +3,14 @@
 import os
 from pathlib import Path
 
+import dask
+import dask.dataframe as dd
+import large_image
 import numpy as np
+import pandas as pd
+
+import histomicstk.segmentation.label as htk_seg_label
+import histomicstk.segmentation.nuclear as htk_nuclear
 
 try:
     import joblib
@@ -20,6 +27,48 @@
 logging.basicConfig(level=logging.CRITICAL)
 
 
+def set_reference_values(args):
+    """
+    Set reference values and configuration parameters for feature extraction.
+
+    Args:
+        args (dict): Configuration parameters for feature extraction.
+
+    Returns:
+        dict: Updated configuration parameters with reference values set.
+    """
+    args.reference_mu_lab = [8.63234435, -0.11501964, 0.03868433]
+    args.reference_std_lab = [0.57506023, 0.10403329, 0.01364062]
+    args.foreground_threshold = 60
+    args.min_radius = 6
+    args.max_radius = 20
+    args.min_nucleus_area = 80
+    args.local_max_search_radius = 10
+    args.nuclei_annotation_format = "boundary"
+    args.stain_1 = "hematoxylin"
+    args.stain_1_vector = [-1.0, -1.0, -1.0]
+    args.stain_2 = "eosin"
+    args.stain_2_vector = [-1.0, -1.0, -1.0]
+    args.stain_3 = "null"
+    args.stain_3_vector = [-1.0, -1.0, -1.0]
+    args.ignore_border_nuclei = False
+    args.cyto_width = 8
+    args.cytoplasm_features = True
+    args.fsd_bnd_pts = 128
+    args.fsd_features = True
+    args.fsd_freq_bins = 6
+    args.gradient_features = True
+    args.haralick_features = True
+    args.morphometry_features = True
+    args.intensity_features = True
+    args.gradient_features = True
+    args.fsd_features = True
+    args.num_glcm_levels = 32
+    args.min_fgnd_frac = .25
+    args.analysis_roi = None
+    return args
+
+
 def gen_distinct_rgb_colors(n, seed=None):
     """
     Generates N visually distinct RGB colors
@@ -57,8 +106,94 @@ def gen_distinct_rgb_colors(n, seed=None):
     return color_list
 
 
+def process_feature_and_annotation(args):
+    """
+    Process nuclei feature extraction and annotation from an input image.
+
+    Args:
+        args (dict): Configuration parameters for feature extraction.
+
+    Returns:
+        tuple: A tuple containing nuclei annotations (list) and feature data (Dask DataFrame).
+    """
+
+    print('>> Generating features and annotation')
+
+    #
+    # Set arguments required for nuclei feature extraction
+    #
+    args = set_reference_values(args)
+    tile_overlap = (args.max_radius + 1) * 4
+    it_kwargs = {'tile_overlap': {'x': tile_overlap, 'y': tile_overlap}}
+
+    #
+    # Read Input Image
+    #
+    print('\n>> Reading input image ... \n')
+
+    ts = large_image.getTileSource(args.inputImageFile)
+
+    ts_metadata = ts.getMetadata()
+
+    print(json.dumps(ts_metadata, indent=2))
+
+    src_mu_lab = None
+    src_sigma_lab = None
+
+    #
+    # Detect and compute nuclei features in parallel using Dask
+    #
+    print('\n>> Detecting nuclei and computing features ...\n')
+
+    tile_result_list = []
+
+    for tile in ts.tileIterator(**it_kwargs):
+
+        # detect nuclei
+        cur_result = dask.delayed(htk_nuclear.detect_tile_nuclei)(
+            tile,
+            args,
+            src_mu_lab, src_sigma_lab,
+            return_fdata=True
+        )
+
+        # append result to list
+        tile_result_list.append(cur_result)
+
+    tile_result_list = dask.delayed(tile_result_list).compute()
+
+    nuclei_annot_list = [annot
+                         for annot_list, fdata in tile_result_list
+                         for annot in annot_list]
+
+    # remove overlapping nuclei
+    nuclei_annot_list = htk_seg_label.remove_overlap_nuclei(
+        nuclei_annot_list, args.nuclei_annotation_format)
+
+    nuclei_fdata = pd.DataFrame()
+
+    if len(nuclei_annot_list) > 0:
+
+        nuclei_fdata = pd.concat([
+            fdata
+            for annot_list, fdata in tile_result_list if fdata is not None],
+            ignore_index=True
+        )
+    # Fill any instances with NaN as zero
+    df = pd.DataFrame(nuclei_fdata).fillna(0)
+    return nuclei_annot_list, dd.from_pandas(df, npartitions=1)
+
+
 def read_feature_file(args):
-    import dask.dataframe as dd
+    """
+    Read nuclei feature data from a specified file.
+
+    Args:
+        args (dict): Configuration parameters including the input feature file path.
+
+    Returns:
+        dask.dataframe.DataFrame: A Dask DataFrame containing the nuclei feature data.
+    """
 
     fname, feature_file_format = os.path.splitext(args.inputNucleiFeatureFile)
 
@@ -73,20 +208,11 @@ def read_feature_file(args):
     else:
         raise ValueError('Extension of output feature file must be .csv or .h5')
 
-    return ddf
-
-
-def check_args(args):
-
-    if not os.path.isfile(args.inputImageFile):
-        raise OSError('Input image file does not exist.')
-
-    if not os.path.isfile(args.inputModelFile):
-        raise OSError('Input model file does not exist.')
+    # Fill any instances with NaN as zero
+    return ddf.fillna(0)
 
 
 def main(args):
-    import pandas as pd
 
     print('\n>> CLI Parameters ...\n')
 
@@ -105,37 +231,38 @@ def main(args):
     # read model file
     #
     print('\n>> Loading classification model ...\n')
-
     clf_model = joblib.load(args.inputModelFile)
 
-    #
-    # read feature file
-    #
-    print('\n>> Loading nuclei feature file ...\n')
+    if args.inputNucleiFeatureFile and args.inputNucleiAnnotationFile:
 
-    ddf = read_feature_file(args)
+        # read feature file
+        print('\n>> Loading nuclei feature file ...\n')
 
-    if len(ddf.columns) != clf_model.n_features_in_:
+        ddf = read_feature_file(args)
 
-        raise ValueError('The number of features of the classification model '
-                         'and the input feature file do not match.')
+        if len(ddf.columns) != clf_model.n_features_in_:
 
-    #
-    # read nuclei annotation file
-    #
-    print('\n>> Loading nuclei annotation file ...\n')
+            raise ValueError('The number of features of the classification model '
+                             'and the input feature file do not match.')
+
+        #
+        # read nuclei annotation file
+        #
+        print('\n>> Loading nuclei annotation file ...\n')
 
-    with open(args.inputNucleiAnnotationFile) as f:
+        with open(args.inputNucleiAnnotationFile) as f:
 
-        annotation_data = json.load(f)
-        nuclei_annot_list = annotation_data.get(
-            'elements', annotation_data.get(
-                'annotation', {}).get('elements'))
+            annotation_data = json.load(f)
+            nuclei_annot_list = annotation_data.get(
+                'elements', annotation_data.get(
+                    'annotation', {}).get('elements'))
 
-    if len(nuclei_annot_list) != len(ddf.index):
+        if len(nuclei_annot_list) != len(ddf.index):
 
-        raise ValueError('The number of nuclei in the feature file and the '
-                         'annotation file do not match')
+            raise ValueError('The number of nuclei in the feature file and the '
+                             'annotation file do not match')
+    else:
+        nuclei_annot_list, ddf = process_feature_and_annotation(args)
 
     #
     # Perform nuclei classification

histomicstk/cli/NucleiClassification/NucleiClassification.xml

@@ -6,7 +6,7 @@
   <version>0.1.0</version>
   <documentation-url>https://digitalslidearchive.github.io/HistomicsTK/</documentation-url>
   <license>Apache 2.0</license>
-  <contributor>Deepak Roy Chittajallu (Kitware), Neal Siekierski (Kitware)</contributor>
+  <contributor>Deepak Roy Chittajallu (Kitware), Neal Siekierski (Kitware), Subin Erattakulangara (Kitware)</contributor>
   <acknowledgements>This work is part of the HistomicsTK project.</acknowledgements>
   <parameters>
     <label>IO</label>
@@ -29,21 +29,21 @@
       <name>inputNucleiFeatureFile</name>
       <label>Input Nuclei Feature File</label>
       <channel>input</channel>
-      <index>2</index>
+      <longflag>feature-file</longflag>
       <description>Input nuclei feature file (*.csv, *.h5) containing the features of all nuclei to be classified</description>
     </file>
     <file fileExtensions=".anot">
       <name>inputNucleiAnnotationFile</name>
       <label>Input Nuclei Annotation File</label>
       <channel>input</channel>
-      <index>3</index>
+      <longflag>annotation-file</longflag>
       <description>Input nuclei annotation file (*.anot) containing nuclei annotations in the same order as their features in the feature file</description>
     </file>
     <file fileExtensions=".anot" reference="inputImageFile">
       <name>outputNucleiAnnotationFile</name>
       <label>Output Nuclei Annotation File</label>
       <channel>output</channel>
-      <index>4</index>
+      <index>2</index>
       <description>Output nuclei annotation file (*.anot) with the same nuclei in input nuclei annotation file if provided) with nuclei sorted into groups based on class and accompanied by heatmaps of the classification probabilities</description>
     </file>
   </parameters>