deepliif 1.1.11__tar.gz → 1.1.12__tar.gz

{deepliif-1.1.11/deepliif.egg-info → deepliif-1.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: deepliif
-Version: 1.1.11
+Version: 1.1.12
 Summary: DeepLIIF: Deep-Learning Inferred Multiplex Immunofluorescence for Immunohistochemical Image Quantification
 Home-page: https://github.com/nadeemlab/DeepLIIF
 Author: Parmida93
@@ -53,7 +53,7 @@ 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)
+![Version](https://img.shields.io/static/v1?label=latest&message=v1.1.12&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 
@@ -101,6 +101,16 @@ Commands:
   train                  General-purpose training script for multi-task...
 ```
 
+**Note:** You might need to install a version of PyTorch that is compatible with your CUDA version. 
+Otherwise, only the CPU will be used. 
+Visit the [PyTorch website](https://pytorch.org/) for details. 
+You can confirm if your installation will run on the GPU by checking if the following returns `True`:
+
+```
+import torch
+torch.cuda.is_available()
+```
+
 ## Training Dataset
 For training, all image sets must be 512x512 and combined together in 3072x512 images (six images of size 512x512 stitched
 together horizontally).
@@ -198,26 +208,49 @@ python test.py --dataroot /path/to/input/images
 * Before running test on images, the model files must be serialized as described above.
 * The serialized model files are expected to be located in `DeepLIIF/model-server/DeepLIIF_Latest_Model`.
 * The test results will be saved to the specified output directory, which defaults to the input directory.
-* The default tile size is 512.
+* The tile size must be specified and is used to split the image into tiles for processing.  The tile size is based on the resolution (scan magnification) of the input image, and the recommended values are a tile size of 512 for 40x images, 256 for 20x, and 128 for 10x.  Note that the smaller the tile size, the longer inference will take.
 * Testing datasets can be downloaded [here](https://zenodo.org/record/4751737#.YKRTS0NKhH4).
 
+**Test Command Options:**  
+In addition to the required parameters given above, the following optional parameters are available for `deepliif test`:
+* `--eager-mode` Run the original model files (instead of serialized model files).
+* `--seg-intermediate` Save the intermediate segmentation maps created for each modality.
+* `--seg-only` Save only the segmentation files, and do not infer images that are not needed.
+* `--color-dapi` Color the inferred DAPI image.
+* `--color-marker` Color the inferred marker image.
+
 **Whole Slide Image (WSI) Inference:**  
 For translation and segmentation of whole slide images, 
-you can simply use the same test command 
-giving path to the directory containing your whole slide images as the input-dir.
+you can simply use the `test-wsi` command 
+giving path to the directory containing your WSI as the input-dir 
+and specifying the filename of the WSI.
 DeepLIIF automatically reads the WSI region by region, 
 and translate and segment each region separately and stitches the regions 
 to create the translation and segmentation for whole slide image, 
 then saves all masks in the format of ome.tiff in the given output-dir. 
-Based on the available GPU resources, the region-size can be changed.
+Based on the available 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
-              --tile-size 512
-              --region-size 20000
+deepliif test-wsi --input-dir /path/to/input/image 
+                  --filename wsiFile.svs
+                  --output-dir /path/to/output/images 
+                  --model-dir /path/to/the/serialized/model
+                  --tile-size 512
 ```
 
+**WSI Inference Options:**  
+In addition to the required parameters given above, the following optional parameters are available for `deepliif test-wsi`:
+* `--region-size` Set the size of each region to read from the WSI (default is 20000).
+* `--seg-intermediate` Save the intermediate segmentation maps created for each modality.
+* `--seg-only` Save only the segmentation files, and do not infer images that are not needed.
+* `--color-dapi` Color the inferred DAPI image.
+* `--color-marker` Color the inferred marker image.
+
+**Reducing Run Time**  
+If you need only the final segmentation and not the inferred multiplex images, 
+it is recommended to run `deepliif test` or `deepliif test-wsi` with the `--seg-only` 
+option.  This will generate only the necessary images, thus reducing the overall run time.
+
+**Torchserve**  
 If you prefer, it is possible to run the models using Torchserve.
 Please see [the documentation](https://nadeemlab.github.io/DeepLIIF/deployment/#deploying-deepliif-with-torchserve)
 on how to deploy the model with Torchserve and for an example of how to run the inference.
@@ -254,9 +287,16 @@ If you don't have access to GPU or appropriate hardware and don't want to instal
 
 ![DeepLIIF Website Demo](images/deepliif-website-demo-04.gif)
 
+Our deployment at [deepliif.org](https://deepliif.org) also provides virtual slide digitization to generate a single stitched image from a 10x video acquired with a microscope and camera.  The video should be captured with the following guidelines to achieve the best results:
+* Brief but complete pauses at every section of the sample to avoid motion artifacts.
+* Significant overlap between pauses so that there is sufficient context for stitching frames together.
+* Methodical and consistent movement over the sample.  For example, start at the top left corner, then go all the way to the right, then down one step, then all the way to the left, down one step, etc., until the end of the sample is reached.  Again, brief overlapping pauses throughout will allow the best quality images to be generated.
+
+![DeepLIIF Website Demo](images/deepliif-stitch-demo-01.gif)
+
 ## 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:
+For small images, 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
@@ -352,6 +392,8 @@ with open(f'{images_dir}/{root}_scoring.json', 'w') as f:
 print(json.dumps(data['scoring'], indent=2))
 ```
 
+Note that since this is a single request to send the image and receive the results, processing must complete within the timeout period (typically about one minute).  If your request is receiving a 504 status code, please try a smaller image or install the `deepliif` package as detailed above to run the process locally.
+
 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:
 
 ```
@@ -504,16 +546,17 @@ DeepLIIF model and release back to the community with full credit to the contrib
 - [x] **Moffitt Cancer Center** [AI-ready multiplex immunofluorescence and multiplex immunohistochemistry dataset](https://wiki.cancerimagingarchive.net/pages/viewpage.action?pageId=70226184) for head-and-neck squamous cell carcinoma (**MICCAI'23**)   
 
 ## Support
-Please use the [Image.sc Forum](https://forum.image.sc/tag/deepliif) for discussion and questions related to DeepLIIF.
-
-Bugs can be reported in the [GitHub Issues](https://github.com/nadeemlab/DeepLIIF/issues) tab.
+Please use the [GitHub Issues](https://github.com/nadeemlab/DeepLIIF/issues) tab for discussion, questions, or to report bugs related to DeepLIIF.
 
 ## License
 © [Nadeem Lab](https://nadeemlab.org/) - DeepLIIF code is distributed under **Apache 2.0 with Commons Clause** license, 
 and is available for non-commercial academic purposes. 
 
 ## Acknowledgments
-* This code is inspired by [CycleGAN and pix2pix in PyTorch](https://github.com/junyanz/pytorch-CycleGAN-and-pix2pix).
+This code is inspired by [CycleGAN and pix2pix in PyTorch](https://github.com/junyanz/pytorch-CycleGAN-and-pix2pix).
+
+## Funding
+This work is funded by the 7-year NIH/NCI R37 MERIT Award ([R37CA295658](https://reporter.nih.gov/search/5dgSOlHosEKepkZEAS5_kQ/project-details/11018883#description)).
 
 ## Reference
 If you find our work useful in your research or if you use parts of this code or our released dataset, please cite the following papers:
@@ -541,6 +584,8 @@ If you find our work useful in your research or if you use parts of this code or
   title={An AI-Ready Multiplex Staining Dataset for Reproducible and Accurate Characterization of Tumor Immune Microenvironment},
   author={Ghahremani, Parmida and Marino, Joseph and Hernandez-Prera, Juan and V. de la Iglesia, Janis and JC Slebos, Robbert and H. Chung, Christine and Nadeem, Saad},
   journal={International Conference on Medical Image Computing and Computer-Assisted Intervention (MICCAI)},
+  volume={14225},
+  pages={704--713},
   year={2023}
 }
 
@@ -548,14 +593,19 @@ If you find our work useful in your research or if you use parts of this code or
   author = {Nadeem, Saad and Hanna, Matthew G and Viswanathan, Kartik and Marino, Joseph and Ahadi, Mahsa and Alzumaili, Bayan and Bani, Mohamed-Amine and Chiarucci, Federico and Chou, Angela and De Leo, Antonio and Fuchs, Talia L and Lubin, Daniel J and Luxford, Catherine and Magliocca, Kelly and Martinez, Germán and Shi, Qiuying and Sidhu, Stan and Al Ghuzlan, Abir and Gill, Anthony J and Tallini, Giovanni and Ghossein, Ronald and Xu, Bin},
   title = {Ki67 proliferation index in medullary thyroid carcinoma: a comparative study of multiple counting methods and validation of image analysis and deep learning platforms},
   journal = {Histopathology},
+  volume = {83},
+  number = {6},
+  pages = {981--988},
   year = {2023},
   doi = {https://doi.org/10.1111/his.15048}
 }
 
 @article{zehra2024deepliifstitch,
-author = {Zehra, Talat and Marino, Joseph and Wang, Wendy and Frantsuzov, Grigoriy and Nadeem, Saad},
-title = {Rethinking Histology Slide Digitization Workflows for Low-Resource Settings},
-journal = {International Conference on Medical Image Computing and Computer-Assisted Intervention (MICCAI)},
-year = {2024}
+  author = {Zehra, Talat and Marino, Joseph and Wang, Wendy and Frantsuzov, Grigoriy and Nadeem, Saad},
+  title = {Rethinking Histology Slide Digitization Workflows for Low-Resource Settings},
+  journal = {International Conference on Medical Image Computing and Computer-Assisted Intervention (MICCAI)},
+  volume = {15004},
+  pages = {427--436},
+  year = {2024}
 }
 ```

{deepliif-1.1.11 → deepliif-1.1.12}/README.md

@@ -42,7 +42,7 @@ 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)
+![Version](https://img.shields.io/static/v1?label=latest&message=v1.1.12&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 
@@ -90,6 +90,16 @@ Commands:
   train                  General-purpose training script for multi-task...
 ```
 
+**Note:** You might need to install a version of PyTorch that is compatible with your CUDA version. 
+Otherwise, only the CPU will be used. 
+Visit the [PyTorch website](https://pytorch.org/) for details. 
+You can confirm if your installation will run on the GPU by checking if the following returns `True`:
+
+```
+import torch
+torch.cuda.is_available()
+```
+
 ## Training Dataset
 For training, all image sets must be 512x512 and combined together in 3072x512 images (six images of size 512x512 stitched
 together horizontally).
@@ -187,26 +197,49 @@ python test.py --dataroot /path/to/input/images
 * Before running test on images, the model files must be serialized as described above.
 * The serialized model files are expected to be located in `DeepLIIF/model-server/DeepLIIF_Latest_Model`.
 * The test results will be saved to the specified output directory, which defaults to the input directory.
-* The default tile size is 512.
+* The tile size must be specified and is used to split the image into tiles for processing.  The tile size is based on the resolution (scan magnification) of the input image, and the recommended values are a tile size of 512 for 40x images, 256 for 20x, and 128 for 10x.  Note that the smaller the tile size, the longer inference will take.
 * Testing datasets can be downloaded [here](https://zenodo.org/record/4751737#.YKRTS0NKhH4).
 
+**Test Command Options:**  
+In addition to the required parameters given above, the following optional parameters are available for `deepliif test`:
+* `--eager-mode` Run the original model files (instead of serialized model files).
+* `--seg-intermediate` Save the intermediate segmentation maps created for each modality.
+* `--seg-only` Save only the segmentation files, and do not infer images that are not needed.
+* `--color-dapi` Color the inferred DAPI image.
+* `--color-marker` Color the inferred marker image.
+
 **Whole Slide Image (WSI) Inference:**  
 For translation and segmentation of whole slide images, 
-you can simply use the same test command 
-giving path to the directory containing your whole slide images as the input-dir.
+you can simply use the `test-wsi` command 
+giving path to the directory containing your WSI as the input-dir 
+and specifying the filename of the WSI.
 DeepLIIF automatically reads the WSI region by region, 
 and translate and segment each region separately and stitches the regions 
 to create the translation and segmentation for whole slide image, 
 then saves all masks in the format of ome.tiff in the given output-dir. 
-Based on the available GPU resources, the region-size can be changed.
+Based on the available 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
-              --tile-size 512
-              --region-size 20000
+deepliif test-wsi --input-dir /path/to/input/image 
+                  --filename wsiFile.svs
+                  --output-dir /path/to/output/images 
+                  --model-dir /path/to/the/serialized/model
+                  --tile-size 512
 ```
 
+**WSI Inference Options:**  
+In addition to the required parameters given above, the following optional parameters are available for `deepliif test-wsi`:
+* `--region-size` Set the size of each region to read from the WSI (default is 20000).
+* `--seg-intermediate` Save the intermediate segmentation maps created for each modality.
+* `--seg-only` Save only the segmentation files, and do not infer images that are not needed.
+* `--color-dapi` Color the inferred DAPI image.
+* `--color-marker` Color the inferred marker image.
+
+**Reducing Run Time**  
+If you need only the final segmentation and not the inferred multiplex images, 
+it is recommended to run `deepliif test` or `deepliif test-wsi` with the `--seg-only` 
+option.  This will generate only the necessary images, thus reducing the overall run time.
+
+**Torchserve**  
 If you prefer, it is possible to run the models using Torchserve.
 Please see [the documentation](https://nadeemlab.github.io/DeepLIIF/deployment/#deploying-deepliif-with-torchserve)
 on how to deploy the model with Torchserve and for an example of how to run the inference.
@@ -243,9 +276,16 @@ If you don't have access to GPU or appropriate hardware and don't want to instal
 
 ![DeepLIIF Website Demo](images/deepliif-website-demo-04.gif)
 
+Our deployment at [deepliif.org](https://deepliif.org) also provides virtual slide digitization to generate a single stitched image from a 10x video acquired with a microscope and camera.  The video should be captured with the following guidelines to achieve the best results:
+* Brief but complete pauses at every section of the sample to avoid motion artifacts.
+* Significant overlap between pauses so that there is sufficient context for stitching frames together.
+* Methodical and consistent movement over the sample.  For example, start at the top left corner, then go all the way to the right, then down one step, then all the way to the left, down one step, etc., until the end of the sample is reached.  Again, brief overlapping pauses throughout will allow the best quality images to be generated.
+
+![DeepLIIF Website Demo](images/deepliif-stitch-demo-01.gif)
+
 ## 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:
+For small images, 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
@@ -341,6 +381,8 @@ with open(f'{images_dir}/{root}_scoring.json', 'w') as f:
 print(json.dumps(data['scoring'], indent=2))
 ```
 
+Note that since this is a single request to send the image and receive the results, processing must complete within the timeout period (typically about one minute).  If your request is receiving a 504 status code, please try a smaller image or install the `deepliif` package as detailed above to run the process locally.
+
 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:
 
 ```
@@ -493,16 +535,17 @@ DeepLIIF model and release back to the community with full credit to the contrib
 - [x] **Moffitt Cancer Center** [AI-ready multiplex immunofluorescence and multiplex immunohistochemistry dataset](https://wiki.cancerimagingarchive.net/pages/viewpage.action?pageId=70226184) for head-and-neck squamous cell carcinoma (**MICCAI'23**)   
 
 ## Support
-Please use the [Image.sc Forum](https://forum.image.sc/tag/deepliif) for discussion and questions related to DeepLIIF.
-
-Bugs can be reported in the [GitHub Issues](https://github.com/nadeemlab/DeepLIIF/issues) tab.
+Please use the [GitHub Issues](https://github.com/nadeemlab/DeepLIIF/issues) tab for discussion, questions, or to report bugs related to DeepLIIF.
 
 ## License
 © [Nadeem Lab](https://nadeemlab.org/) - DeepLIIF code is distributed under **Apache 2.0 with Commons Clause** license, 
 and is available for non-commercial academic purposes. 
 
 ## Acknowledgments
-* This code is inspired by [CycleGAN and pix2pix in PyTorch](https://github.com/junyanz/pytorch-CycleGAN-and-pix2pix).
+This code is inspired by [CycleGAN and pix2pix in PyTorch](https://github.com/junyanz/pytorch-CycleGAN-and-pix2pix).
+
+## Funding
+This work is funded by the 7-year NIH/NCI R37 MERIT Award ([R37CA295658](https://reporter.nih.gov/search/5dgSOlHosEKepkZEAS5_kQ/project-details/11018883#description)).
 
 ## Reference
 If you find our work useful in your research or if you use parts of this code or our released dataset, please cite the following papers:
@@ -530,6 +573,8 @@ If you find our work useful in your research or if you use parts of this code or
   title={An AI-Ready Multiplex Staining Dataset for Reproducible and Accurate Characterization of Tumor Immune Microenvironment},
   author={Ghahremani, Parmida and Marino, Joseph and Hernandez-Prera, Juan and V. de la Iglesia, Janis and JC Slebos, Robbert and H. Chung, Christine and Nadeem, Saad},
   journal={International Conference on Medical Image Computing and Computer-Assisted Intervention (MICCAI)},
+  volume={14225},
+  pages={704--713},
   year={2023}
 }
 
@@ -537,14 +582,19 @@ If you find our work useful in your research or if you use parts of this code or
   author = {Nadeem, Saad and Hanna, Matthew G and Viswanathan, Kartik and Marino, Joseph and Ahadi, Mahsa and Alzumaili, Bayan and Bani, Mohamed-Amine and Chiarucci, Federico and Chou, Angela and De Leo, Antonio and Fuchs, Talia L and Lubin, Daniel J and Luxford, Catherine and Magliocca, Kelly and Martinez, Germán and Shi, Qiuying and Sidhu, Stan and Al Ghuzlan, Abir and Gill, Anthony J and Tallini, Giovanni and Ghossein, Ronald and Xu, Bin},
   title = {Ki67 proliferation index in medullary thyroid carcinoma: a comparative study of multiple counting methods and validation of image analysis and deep learning platforms},
   journal = {Histopathology},
+  volume = {83},
+  number = {6},
+  pages = {981--988},
   year = {2023},
   doi = {https://doi.org/10.1111/his.15048}
 }
 
 @article{zehra2024deepliifstitch,
-author = {Zehra, Talat and Marino, Joseph and Wang, Wendy and Frantsuzov, Grigoriy and Nadeem, Saad},
-title = {Rethinking Histology Slide Digitization Workflows for Low-Resource Settings},
-journal = {International Conference on Medical Image Computing and Computer-Assisted Intervention (MICCAI)},
-year = {2024}
+  author = {Zehra, Talat and Marino, Joseph and Wang, Wendy and Frantsuzov, Grigoriy and Nadeem, Saad},
+  title = {Rethinking Histology Slide Digitization Workflows for Low-Resource Settings},
+  journal = {International Conference on Medical Image Computing and Computer-Assisted Intervention (MICCAI)},
+  volume = {15004},
+  pages = {427--436},
+  year = {2024}
 }
 ```