deepliif 1.1.9__tar.gz → 1.1.10__tar.gz

{deepliif-1.1.9/deepliif.egg-info → deepliif-1.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: deepliif
-Version: 1.1.9
+Version: 1.1.10
 Summary: DeepLIIF: Deep-Learning Inferred Multiplex Immunofluorescence for Immunohistochemical Image Quantification
 Home-page: https://github.com/nadeemlab/DeepLIIF
 Author: Parmida93
@@ -51,6 +51,9 @@ segmentation.*
 
 © This code is made available for non-commercial academic purposes.
 
+![Version](https://img.shields.io/static/v1?label=latest&message=v1.1.9&color=darkgreen)
+[![Total Downloads](https://static.pepy.tech/personalized-badge/deepliif?period=total&units=international_system&left_color=grey&right_color=blue&left_text=total%20downloads)](https://pepy.tech/project/deepliif?&left_text=totalusers)
+
 ![overview_image](./images/overview.png)*Overview of DeepLIIF pipeline and sample input IHCs (different 
 brown/DAB markers -- BCL2, BCL6, CD10, CD3/CD8, Ki67) with corresponding DeepLIIF-generated hematoxylin/mpIF modalities 
 and classified (positive (red) and negative (blue) cell) segmentation masks. (a) Overview of DeepLIIF. Given an IHC 
@@ -122,7 +125,7 @@ deepliif prepare-training-data --input-dir /path/to/input/images
 To train a model:
 ```
 deepliif train --dataroot /path/to/input/images 
-                --name Model_Name 
+               --name Model_Name 
 ```
 or
 ```
@@ -168,7 +171,7 @@ The installed `deepliif` uses Dask to perform inference on the input IHC images.
 Before running the `test` command, the model files must be serialized using Torchscript.
 To serialize the model files:
 ```
-deepliif serialize --models-dir /path/to/input/model/files
+deepliif serialize --model-dir /path/to/input/model/files
                    --output-dir /path/to/output/model/files
 ```
 * By default, the model files are expected to be located in `DeepLIIF/model-server/DeepLIIF_Latest_Model`.
@@ -177,15 +180,17 @@ deepliif serialize --models-dir /path/to/input/model/files
 ## Testing
 To test the model:
 ```
-deepliif test --input-dir /path/to/input/images 
-              --output-dir /path/to/output/images 
-              --model-dir path/to/the/serialized/model
+deepliif test --input-dir /path/to/input/images
+              --output-dir /path/to/output/images
+              --model-dir /path/to/the/serialized/model
               --tile-size 512
 ```
 or
 ```
-python test.py --dataroot /path/to/input/images 
-               --name Model_Name  
+python test.py --dataroot /path/to/input/images
+               --results_dir /path/to/output/images
+               --checkpoints_dir /path/to/model/files
+               --name Model_Name
 ```
 * The latest version of the pretrained models can be downloaded [here](https://zenodo.org/record/4751737#.YKRTS0NKhH4).
 * Before running test on images, the model files must be serialized as described above.
@@ -206,7 +211,7 @@ Based on the available GPU resources, the region-size can be changed.
 ```
 deepliif test --input-dir /path/to/input/images 
               --output-dir /path/to/output/images 
-              --model-dir path/to/the/serialized/model
+              --model-dir /path/to/the/serialized/model
               --tile-size 512
               --region-size 20000
 ```
@@ -247,25 +252,61 @@ If you don't have access to GPU or appropriate hardware and don't want to instal
 
 ![DeepLIIF Website Demo](images/deepliif-website-demo-03.gif)
 
-DeepLIIF can also be accessed programmatically through an endpoint by posting a multipart-encoded request
-containing the original image file:
+## Cloud API Endpoints
+
+DeepLIIF can also be accessed programmatically through an endpoint by posting a multipart-encoded request containing the original image file, along with optional parameters including postprocessing thresholds:
 
 ```
 POST /api/infer
 
-Parameters
+File Parameter:
+
+  img (required)
+    Image on which to run DeepLIIF.
+
+Query String Parameters:
+
+  resolution
+    Resolution used to scan the slide (10x, 20x, 40x). Default is 40x.
 
-img (required)
-file: image to run the models on
+  pil
+    If present, use Pillow to load the image instead of Bio-Formats. Pillow is
+    faster, but works only on common image types (png, jpeg, etc.).
 
-resolution
-string: resolution used to scan the slide (10x, 20x, 40x), defaults to 40x 
+  slim
+    If present, return only the refined segmentation result image.
 
-pil
-boolean: if true, use PIL.Image.open() to load the image, instead of python-bioformats
+  nopost
+    If present, do not perform postprocessing (returns only inferred images).
 
-slim
-boolean: if true, return only the segmentation result image
+  prob_thresh
+    Probability threshold used in postprocessing the inferred segmentation map
+    image. The segmentation map value must be above this value in order for a
+    pixel to be included in the final cell segmentation. Valid values are an
+    integer in the range 0-254. Default is 150.
+
+  size_thresh
+    Lower threshold for size gating the cells in postprocessing. Segmented
+    cells must have more pixels than this value in order to be included in the
+    final cell segmentation. Valid values are 0, a positive integer, or 'auto'.
+    'Auto' will try to automatically determine this lower bound for size gating
+    based on the distribution of detected cell sizes. Default is 'auto'.
+
+  size_thresh_upper
+    Upper threshold for size gating the cells in postprocessing.  Segmented
+    cells must have less pixels that this value in order to be included in the
+    final cell segmentation. Valid values are a positive integer or 'none'.
+    'None' will use no upper threshold in size gating. Default is 'none'.
+
+  marker_thresh
+    Threshold for the effect that the inferred marker image will have on the
+    postprocessing classification of cells as positive.  If any corresponding
+    pixel in the marker image for a cell is above this threshold, the cell will
+    be classified as being positive regardless of the values from the inferred
+    segmentation image. Valid values are an integer in the range 0-255, 'none',
+    or 'auto'. 'None' will not use the marker image during classification.
+    'Auto' will automatically determine a threshold from the marker image.
+    Default is 'auto'.
 ```
 
 For example, in Python:
@@ -283,15 +324,118 @@ from PIL import Image
 images_dir = './Sample_Large_Tissues'
 filename = 'ROI_1.png'
 
+root = os.path.splitext(filename)[0]
+
 res = requests.post(
     url='https://deepliif.org/api/infer',
     files={
-        'img': open(f'{images_dir}/{filename}', 'rb')
+        'img': open(f'{images_dir}/{filename}', 'rb'),
     },
-    # optional param that can be 10x, 20x, or 40x (default)
     params={
-        'resolution': '40x'
-    }
+        'resolution': '40x',
+    },
+)
+
+data = res.json()
+
+def b64_to_pil(b):
+    return Image.open(BytesIO(base64.b64decode(b.encode())))
+
+for name, img in data['images'].items():
+    with open(f'{images_dir}/{root}_{name}.png', 'wb') as f:
+        b64_to_pil(img).save(f, format='PNG')
+
+with open(f'{images_dir}/{root}_scoring.json', 'w') as f:
+    json.dump(data['scoring'], f, indent=2)
+print(json.dumps(data['scoring'], indent=2))
+```
+
+If you have previously run DeepLIIF on an image and want to postprocess it with different thresholds, the postprocessing routine can be called directly using the previously inferred results:
+
+```
+POST /api/postprocess
+
+File Parameters:
+
+  img (required)
+    Image on which DeepLIIF was run.
+
+  seg_img (required)
+    Inferred segmentation image previously generated by DeepLIIF.
+
+  marker_img (optional)
+    Inferred marker image previously generated by DeepLIIF.  If this is
+    omitted, then the marker image will not be used in classification.
+
+Query String Parameters:
+
+  resolution
+    Resolution used to scan the slide (10x, 20x, 40x). Default is 40x.
+
+  pil
+    If present, use Pillow to load the original image instead of Bio-Formats.
+    Pillow is faster, but works only on common image types (png, jpeg, etc.).
+    Pillow is always used to open the seg_img and marker_img files.
+
+  prob_thresh
+    Probability threshold used in postprocessing the inferred segmentation map
+    image. The segmentation map value must be above this value in order for a
+    pixel to be included in the final cell segmentation. Valid values are an
+    integer in the range 0-254. Default is 150.
+
+  size_thresh
+    Lower threshold for size gating the cells in postprocessing. Segmented
+    cells must have more pixels than this value in order to be included in the
+    final cell segmentation. Valid values are 0, a positive integer, or 'auto'.
+    'Auto' will try to automatically determine this lower bound for size gating
+    based on the distribution of detected cell sizes. Default is 'auto'.
+
+  size_thresh_upper
+    Upper threshold for size gating the cells in postprocessing.  Segmented
+    cells must have less pixels that this value in order to be included in the
+    final cell segmentation. Valid values are a positive integer or 'none'.
+    'None' will use no upper threshold in size gating. Default is 'none'.
+
+  marker_thresh
+    Threshold for the effect that the inferred marker image will have on the
+    postprocessing classification of cells as positive.  If any corresponding
+    pixel in the marker image for a cell is above this threshold, the cell will
+    be classified as being positive regardless of the values from the inferred
+    segmentation image. Valid values are an integer in the range 0-255, 'none',
+    or 'auto'. 'None' will not use the marker image during classification.
+    'Auto' will automatically determine a threshold from the marker image.
+    Default is 'auto'. (If marker_img is not supplied, this has no effect.)
+```
+
+For example, in Python:
+
+```python
+import os
+import json
+import base64
+from io import BytesIO
+
+import requests
+from PIL import Image
+
+# Use the sample images from the main DeepLIIF repo
+images_dir = './Sample_Large_Tissues'
+filename = 'ROI_1.png'
+
+root = os.path.splitext(filename)[0]
+
+res = requests.post(
+    url='https://deepliif.org/api/infer',
+    files={
+        'img': open(f'{images_dir}/{filename}', 'rb'),
+        'seg_img': open(f'{images_dir}/{root}_Seg.png', 'rb'),
+        'marker_img': open(f'{images_dir}/{root}_Marker.png', 'rb'),
+    },
+    params={
+        'resolution': '40x',
+        'pil': True,
+        'size_thresh': 250,
+    },
 )
 
 data = res.json()
@@ -300,10 +444,11 @@ def b64_to_pil(b):
     return Image.open(BytesIO(base64.b64decode(b.encode())))
 
 for name, img in data['images'].items():
-    output_filepath = f'{images_dir}/{os.path.splitext(filename)[0]}_{name}.png'
-    with open(output_filepath, 'wb') as f:
+    with open(f'{images_dir}/{root}_{name}.png', 'wb') as f:
         b64_to_pil(img).save(f, format='PNG')
 
+with open(f'{images_dir}/{root}_scoring.json', 'w') as f:
+    json.dump(data['scoring'], f, indent=2)
 print(json.dumps(data['scoring'], indent=2))
 ```
 

{deepliif-1.1.9 → deepliif-1.1.10}/README.md

@@ -40,6 +40,9 @@ segmentation.*
 
 © This code is made available for non-commercial academic purposes.
 
+![Version](https://img.shields.io/static/v1?label=latest&message=v1.1.9&color=darkgreen)
+[![Total Downloads](https://static.pepy.tech/personalized-badge/deepliif?period=total&units=international_system&left_color=grey&right_color=blue&left_text=total%20downloads)](https://pepy.tech/project/deepliif?&left_text=totalusers)
+
 ![overview_image](./images/overview.png)*Overview of DeepLIIF pipeline and sample input IHCs (different 
 brown/DAB markers -- BCL2, BCL6, CD10, CD3/CD8, Ki67) with corresponding DeepLIIF-generated hematoxylin/mpIF modalities 
 and classified (positive (red) and negative (blue) cell) segmentation masks. (a) Overview of DeepLIIF. Given an IHC 
@@ -111,7 +114,7 @@ deepliif prepare-training-data --input-dir /path/to/input/images
 To train a model:
 ```
 deepliif train --dataroot /path/to/input/images 
-                --name Model_Name 
+               --name Model_Name 
 ```
 or
 ```
@@ -157,7 +160,7 @@ The installed `deepliif` uses Dask to perform inference on the input IHC images.
 Before running the `test` command, the model files must be serialized using Torchscript.
 To serialize the model files:
 ```
-deepliif serialize --models-dir /path/to/input/model/files
+deepliif serialize --model-dir /path/to/input/model/files
                    --output-dir /path/to/output/model/files
 ```
 * By default, the model files are expected to be located in `DeepLIIF/model-server/DeepLIIF_Latest_Model`.
@@ -166,15 +169,17 @@ deepliif serialize --models-dir /path/to/input/model/files
 ## Testing
 To test the model:
 ```
-deepliif test --input-dir /path/to/input/images 
-              --output-dir /path/to/output/images 
-              --model-dir path/to/the/serialized/model
+deepliif test --input-dir /path/to/input/images
+              --output-dir /path/to/output/images
+              --model-dir /path/to/the/serialized/model
               --tile-size 512
 ```
 or
 ```
-python test.py --dataroot /path/to/input/images 
-               --name Model_Name  
+python test.py --dataroot /path/to/input/images
+               --results_dir /path/to/output/images
+               --checkpoints_dir /path/to/model/files
+               --name Model_Name
 ```
 * The latest version of the pretrained models can be downloaded [here](https://zenodo.org/record/4751737#.YKRTS0NKhH4).
 * Before running test on images, the model files must be serialized as described above.
@@ -195,7 +200,7 @@ Based on the available GPU resources, the region-size can be changed.
 ```
 deepliif test --input-dir /path/to/input/images 
               --output-dir /path/to/output/images 
-              --model-dir path/to/the/serialized/model
+              --model-dir /path/to/the/serialized/model
               --tile-size 512
               --region-size 20000
 ```
@@ -236,25 +241,61 @@ If you don't have access to GPU or appropriate hardware and don't want to instal
 
 ![DeepLIIF Website Demo](images/deepliif-website-demo-03.gif)
 
-DeepLIIF can also be accessed programmatically through an endpoint by posting a multipart-encoded request
-containing the original image file:
+## Cloud API Endpoints
+
+DeepLIIF can also be accessed programmatically through an endpoint by posting a multipart-encoded request containing the original image file, along with optional parameters including postprocessing thresholds:
 
 ```
 POST /api/infer
 
-Parameters
+File Parameter:
+
+  img (required)
+    Image on which to run DeepLIIF.
+
+Query String Parameters:
+
+  resolution
+    Resolution used to scan the slide (10x, 20x, 40x). Default is 40x.
 
-img (required)
-file: image to run the models on
+  pil
+    If present, use Pillow to load the image instead of Bio-Formats. Pillow is
+    faster, but works only on common image types (png, jpeg, etc.).
 
-resolution
-string: resolution used to scan the slide (10x, 20x, 40x), defaults to 40x 
+  slim
+    If present, return only the refined segmentation result image.
 
-pil
-boolean: if true, use PIL.Image.open() to load the image, instead of python-bioformats
+  nopost
+    If present, do not perform postprocessing (returns only inferred images).
 
-slim
-boolean: if true, return only the segmentation result image
+  prob_thresh
+    Probability threshold used in postprocessing the inferred segmentation map
+    image. The segmentation map value must be above this value in order for a
+    pixel to be included in the final cell segmentation. Valid values are an
+    integer in the range 0-254. Default is 150.
+
+  size_thresh
+    Lower threshold for size gating the cells in postprocessing. Segmented
+    cells must have more pixels than this value in order to be included in the
+    final cell segmentation. Valid values are 0, a positive integer, or 'auto'.
+    'Auto' will try to automatically determine this lower bound for size gating
+    based on the distribution of detected cell sizes. Default is 'auto'.
+
+  size_thresh_upper
+    Upper threshold for size gating the cells in postprocessing.  Segmented
+    cells must have less pixels that this value in order to be included in the
+    final cell segmentation. Valid values are a positive integer or 'none'.
+    'None' will use no upper threshold in size gating. Default is 'none'.
+
+  marker_thresh
+    Threshold for the effect that the inferred marker image will have on the
+    postprocessing classification of cells as positive.  If any corresponding
+    pixel in the marker image for a cell is above this threshold, the cell will
+    be classified as being positive regardless of the values from the inferred
+    segmentation image. Valid values are an integer in the range 0-255, 'none',
+    or 'auto'. 'None' will not use the marker image during classification.
+    'Auto' will automatically determine a threshold from the marker image.
+    Default is 'auto'.
 ```
 
 For example, in Python:
@@ -272,15 +313,118 @@ from PIL import Image
 images_dir = './Sample_Large_Tissues'
 filename = 'ROI_1.png'
 
+root = os.path.splitext(filename)[0]
+
 res = requests.post(
     url='https://deepliif.org/api/infer',
     files={
-        'img': open(f'{images_dir}/{filename}', 'rb')
+        'img': open(f'{images_dir}/{filename}', 'rb'),
     },
-    # optional param that can be 10x, 20x, or 40x (default)
     params={
-        'resolution': '40x'
-    }
+        'resolution': '40x',
+    },
+)
+
+data = res.json()
+
+def b64_to_pil(b):
+    return Image.open(BytesIO(base64.b64decode(b.encode())))
+
+for name, img in data['images'].items():
+    with open(f'{images_dir}/{root}_{name}.png', 'wb') as f:
+        b64_to_pil(img).save(f, format='PNG')
+
+with open(f'{images_dir}/{root}_scoring.json', 'w') as f:
+    json.dump(data['scoring'], f, indent=2)
+print(json.dumps(data['scoring'], indent=2))
+```
+
+If you have previously run DeepLIIF on an image and want to postprocess it with different thresholds, the postprocessing routine can be called directly using the previously inferred results:
+
+```
+POST /api/postprocess
+
+File Parameters:
+
+  img (required)
+    Image on which DeepLIIF was run.
+
+  seg_img (required)
+    Inferred segmentation image previously generated by DeepLIIF.
+
+  marker_img (optional)
+    Inferred marker image previously generated by DeepLIIF.  If this is
+    omitted, then the marker image will not be used in classification.
+
+Query String Parameters:
+
+  resolution
+    Resolution used to scan the slide (10x, 20x, 40x). Default is 40x.
+
+  pil
+    If present, use Pillow to load the original image instead of Bio-Formats.
+    Pillow is faster, but works only on common image types (png, jpeg, etc.).
+    Pillow is always used to open the seg_img and marker_img files.
+
+  prob_thresh
+    Probability threshold used in postprocessing the inferred segmentation map
+    image. The segmentation map value must be above this value in order for a
+    pixel to be included in the final cell segmentation. Valid values are an
+    integer in the range 0-254. Default is 150.
+
+  size_thresh
+    Lower threshold for size gating the cells in postprocessing. Segmented
+    cells must have more pixels than this value in order to be included in the
+    final cell segmentation. Valid values are 0, a positive integer, or 'auto'.
+    'Auto' will try to automatically determine this lower bound for size gating
+    based on the distribution of detected cell sizes. Default is 'auto'.
+
+  size_thresh_upper
+    Upper threshold for size gating the cells in postprocessing.  Segmented
+    cells must have less pixels that this value in order to be included in the
+    final cell segmentation. Valid values are a positive integer or 'none'.
+    'None' will use no upper threshold in size gating. Default is 'none'.
+
+  marker_thresh
+    Threshold for the effect that the inferred marker image will have on the
+    postprocessing classification of cells as positive.  If any corresponding
+    pixel in the marker image for a cell is above this threshold, the cell will
+    be classified as being positive regardless of the values from the inferred
+    segmentation image. Valid values are an integer in the range 0-255, 'none',
+    or 'auto'. 'None' will not use the marker image during classification.
+    'Auto' will automatically determine a threshold from the marker image.
+    Default is 'auto'. (If marker_img is not supplied, this has no effect.)
+```
+
+For example, in Python:
+
+```python
+import os
+import json
+import base64
+from io import BytesIO
+
+import requests
+from PIL import Image
+
+# Use the sample images from the main DeepLIIF repo
+images_dir = './Sample_Large_Tissues'
+filename = 'ROI_1.png'
+
+root = os.path.splitext(filename)[0]
+
+res = requests.post(
+    url='https://deepliif.org/api/infer',
+    files={
+        'img': open(f'{images_dir}/{filename}', 'rb'),
+        'seg_img': open(f'{images_dir}/{root}_Seg.png', 'rb'),
+        'marker_img': open(f'{images_dir}/{root}_Marker.png', 'rb'),
+    },
+    params={
+        'resolution': '40x',
+        'pil': True,
+        'size_thresh': 250,
+    },
 )
 
 data = res.json()
@@ -289,10 +433,11 @@ def b64_to_pil(b):
     return Image.open(BytesIO(base64.b64decode(b.encode())))
 
 for name, img in data['images'].items():
-    output_filepath = f'{images_dir}/{os.path.splitext(filename)[0]}_{name}.png'
-    with open(output_filepath, 'wb') as f:
+    with open(f'{images_dir}/{root}_{name}.png', 'wb') as f:
         b64_to_pil(img).save(f, format='PNG')
 
+with open(f'{images_dir}/{root}_scoring.json', 'w') as f:
+    json.dump(data['scoring'], f, indent=2)
 print(json.dumps(data['scoring'], indent=2))
 ```