Merge pull request #432 from Dana-Farber-AIOS/dev_graph

Updated digital pathology assistant to include instructions and link

README.md

@@ -5,6 +5,8 @@
 [![codecov](https://codecov.io/gh/Dana-Farber-AIOS/pathml/branch/master/graph/badge.svg?token=UHSQPTM28Y)](https://codecov.io/gh/Dana-Farber-AIOS/pathml)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![PyPI version](https://img.shields.io/pypi/v/pathml)](https://pypi.org/project/pathml/)
+![tests](https://github.com/Dana-Farber-AIOS/pathml/actions/workflows/tests-linux.yml/badge.svg?branch=master)
+![dev-tests](https://github.com/Dana-Farber-AIOS/pathml/actions/workflows/tests-linux.yml/badge.svg?branch=dev)
 
 ⭐ **PathML objective is to lower the barrier to entry to digital pathology**
 
@@ -14,25 +16,45 @@ Imaging datasets in cancer research are growing exponentially in both quantity a
 
     docker pull pathml/pathml && docker run -it -p 8888:8888 pathml/pathml
 
-| Branch | Test status   |
-| ------ | ------------- |
-| master | ![tests](https://github.com/Dana-Farber-AIOS/pathml/actions/workflows/tests-linux.yml/badge.svg?branch=master) |
-| dev    | ![tests](https://github.com/Dana-Farber-AIOS/pathml/actions/workflows/tests-linux.yml/badge.svg?branch=dev) |
+Done, what analyses can I write now? 👉 <kbd> <br> **[🔬🤖 Click here to launch your PathML Digital Pathology Assistant 🎓](https://chat.openai.com/g/g-L1IbnIIVt-digital-pathology-assistant-v3-0)** <br> </kbd>
 
-<img src=https://raw.githubusercontent.com/Dana-Farber-AIOS/pathml/master/docs/source/_static/images/logo.png width="300"> 
+<table> 
+<tr>
+    <td> <img src="https://github.com/Dana-Farber-AIOS/pathml/assets/25375373/7b1b7293-03cd-4ef1-91d3-8f2efde0899a"/> </td>
+    <td>
+        
+This AI will:
+
+- 🤖 write digital pathology analyses for you
+- 🔬 walk you through the code, step-by-step
+- 🎓 be your teacher, as you embark on your digital pathology journey ❤️
+
+More information [here](./ai-digital-pathology-assistant-v3) and usage examples [here](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/talk_to_pathml.ipynb)
+
+</td>
+</tr>
+</table>
 
-<img src=https://raw.githubusercontent.com/Dana-Farber-AIOS/pathml/master/docs/source/_static/images/overview.png width="750">
 
-**View [documentation](https://pathml.readthedocs.io/en/latest/)**
+📖 **Official PathML Documentation**
+
+View the official [PathML Documentation on readthedocs](https://pathml.readthedocs.io/en/latest/)
+
+🔥 **Examples! Examples! Examples!**
+
+[↴ Jump to the gallery of examples below](#3-examples)
+
+<br>
+
+<img src=https://raw.githubusercontent.com/Dana-Farber-AIOS/pathml/master/docs/source/_static/images/logo.png width="300"> 
 
-:construction: the `dev` branch is under active development, with experimental features, bug fixes, and refactors that may happen at any time! 
-Stable versions are available as tagged releases on GitHub, or as versioned releases on PyPI
+<img src=https://raw.githubusercontent.com/Dana-Farber-AIOS/pathml/master/docs/source/_static/images/overview.png width="750">
 
-# Installation
+# 1. Installation
 
 `PathML` is an advanced tool for pathology image analysis. Below are simplified instructions to help you install PathML on your system. Whether you're a user or a developer, follow these steps to get started.
 
-## 1. Prerequisites
+## 1.1 Prerequisites
 
 We recommend using [Conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html#) for managing your environments. 
 
@@ -84,9 +106,9 @@ For Windows users, an alternative to using `vcpkg` is to download and use pre-bu
   - Extract the archive to your desired location, e.g., `C:\OpenSlide\`.
 
 
-## 2. PathML Installation Methods
+## 1.2 PathML Installation Methods
 
-### 2.1 Install with pip (Recommended for Users)
+### 1.2.1 Install with pip (Recommended for Users)
 
 #### Create and Activate Conda Environment
 ````
@@ -103,7 +125,7 @@ conda install -c conda-forge 'openjdk<=18.0'
 pip install pathml
 ````
 
-### 2.2 Install from Source (Recommended for Developers)
+### 1.2.2 Install from Source (Recommended for Developers)
 
 #### Clone repository
 ````
@@ -133,7 +155,7 @@ conda activate pathml
 pip install -e .
 ````
 
-### 2.3 Use Docker Container
+### 1.2.3 Use Docker Container
 
 First, download or build the PathML Docker container:
 
@@ -170,7 +192,7 @@ Note that these instructions assume that there are no other processes using port
 Please refer to the `Docker run` [documentation](https://docs.docker.com/engine/reference/run/) for further instructions
 on accessing the container, e.g. for mounting volumes to access files on a local machine from within the container.
 
-### 2.4 Use Google Colab
+### 1.2.4 Use Google Colab
 
 To get PathML running in a Colab environment:
 
@@ -188,7 +210,7 @@ os.environ["JAVA_HOME"] = "/usr/lib/jvm/java-17-openjdk-amd64"
 *Thanks to all of our open-source collaborators for helping maintain these installation instructions!*  
 *Please open an issue for any bugs or other problems during installation process.*
 
-## 3. Import PathML
+## 1.3. Import PathML
 
 After you have installed all necessary dependencies and PathML itself, import it using the following command:
 
@@ -220,7 +242,7 @@ This code snippet ensures that the OpenSlide DLLs are correctly found by Python
 If you encounter any DLL load failures, verify that the OpenSlide `bin` directory is correctly added to your `PATH`.
 
 
-## CUDA
+## 1.4 CUDA
 
 To use GPU acceleration for model training or other tasks, you must install CUDA. 
 This guide should work, but for the most up-to-date instructions, refer to the [official PyTorch installation instructions](https://pytorch.org/get-started/locally/).
@@ -244,11 +266,11 @@ After installing PyTorch, optionally verify successful PyTorch installation with
 python -c "import torch; print(torch.cuda.is_available())"
 ````
 
-## Using with Jupyter
+# 2. Using with Jupyter (optional)
 
 Jupyter notebooks are a convenient way to work interactively. To use `PathML` in Jupyter notebooks: 
 
-### Set JAVA_HOME environment variable
+## 2.1 Set JAVA_HOME environment variable
 
 PathML relies on Java to enable support for reading a wide range of file formats.
 Before using `PathML` in Jupyter, you may need to manually set the `JAVA_HOME` environment variable 
@@ -261,51 +283,67 @@ specifying the path to Java. To do so:
     os.environ["JAVA_HOME"] = "/opt/conda/envs/pathml" # change path as needed
     ````
 
-### Register environment as an IPython kernel
+## 2.2 Register environment as an IPython kernel
 ````
 conda activate pathml
 conda install ipykernel
 python -m ipykernel install --user --name=pathml
 ````
 This makes the pathml environment available as a kernel in jupyter lab or notebook.
 
+# 3. Examples
+
+Now that you are all set with ``PathML`` installation, let's get started with some analyses you can easily replicate:
+
+<table style="border: 0px !important;">
+    <tr>
+    <td> 
+        
+1. [Load over 160+ different types of pathology images using PathML](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/loading_images_vignette.ipynb)
+2. [H&E Stain Deconvolution and Color Normalization](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/stain_normalization.ipynb)
+3. [Brightfield imaging pipeline: load an image, preprocess it on a local cluster, and get it read for machine learning analyses in PyTorch](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/workflow_HE_vignette.ipynb)
+4. [Multiparametric Imaging: Quickstart & single-cell quantification](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/multiplex_if.ipynb)
+5. [Multiparametric Imaging: CODEX & nuclei quantization](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/codex.ipynb)
+6. [Train HoVer-Net model to perform nucleus detection and classification, using data from PanNuke dataset](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/train_hovernet.ipynb)
+7. [Gallery of PathML preprocessing and transformations](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/pathml_gallery.ipynb)
+8. [Use the new Graph API to construct cell and tissue graphs from pathology images](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/construct_graphs.ipynb)
+9. [Train HACTNet model to perform cancer sub-typing using graphs constructed from the BRACS dataset](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/train_hactnet.ipynb)
+10. [Perform reconstruction of tiles obtained from pathology images using Tile Stitching](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/tile_stitching.ipynb)
+11. [Create an ONNX model in HaloAI or similar software, export it, and run it at scale using PathML](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/InferenceOnnx_tutorial.ipynb)
+12. [Step-by-step process used to analyze the Whole Slide Images (WSIs) of Non-Small Cell Lung Cancer (NSCLC) samples as published in the Journal of Clinical Oncology](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/Graph_Analysis_NSCLC.ipynb)
+13. [Talk to the PathML Digital Pathology Assistant](https://github.com/Dana-Farber-AIOS/pathml/blob/master/examples/talk_to_pathml.ipynb)
 
-# Contributing
-
-``PathML`` is an open source project. Consider contributing to benefit the entire community!
-
-There are many ways to contribute to `PathML`, including:
-
-* Submitting bug reports
-* Submitting feature requests
-* Writing documentation and examples
-* Fixing bugs
-* Writing code for new features
-* Sharing workflows
-* Sharing trained model parameters
-* Sharing ``PathML`` with colleagues, students, etc.
+</td>                                                                                                                             
+        <td>
+<img src="https://github.com/Dana-Farber-AIOS/pathml/assets/25375373/502c9e69-e988-4d61-b50f-0d6bfc8af251" width="1000px" />
 
-See [contributing](https://github.com/Dana-Farber-AIOS/pathml/blob/master/CONTRIBUTING.rst) for more details.
+   </td>
+</tr>
+</table>
 
-# Citing
+# 4. Citing & known uses
 
-If you use `PathML` please cite:
+If you use ``PathML`` please cite:
 
 - [**J. Rosenthal et al., "Building tools for machine learning and artificial intelligence in cancer research: best practices and a case study with the PathML toolkit for computational pathology." Molecular Cancer Research, 2022.**](https://doi.org/10.1158/1541-7786.MCR-21-0665)
 
-So far, PathML was used in the following manuscripts: 
+So far, **PathML** was referenced in 20+ manuscripts:
 
-- [J. Linares et al. **Molecular Cell** 2021](https://www.cell.com/molecular-cell/fulltext/S1097-2765(21)00729-2)
-- [A. Shmatko et al. **Nature Cancer** 2022](https://www.nature.com/articles/s43018-022-00436-4)
-- [J. Pocock et al. **Nature Communications Medicine** 2022](https://www.nature.com/articles/s43856-022-00186-5)
-- [S. Orsulic et al. **Frontiers in Oncology** 2022](https://www.frontiersin.org/articles/10.3389/fonc.2022.924945/full)
-- [D. Brundage et al. **arXiv** 2022](https://arxiv.org/abs/2203.13888)
-- [A. Marcolini et al. **SoftwareX** 2022](https://www.sciencedirect.com/science/article/pii/S2352711022001558)
-- [M. Rahman et al. **Bioengineering** 2022](https://www.mdpi.com/2306-5354/9/8/335)
-- [C. Lama et al. **bioRxiv** 2022](https://www.biorxiv.org/content/10.1101/2022.09.28.509751v1.full)
-- the list continues [**here 🔗 for 2023 and onwards**](https://scholar.google.com/scholar?oi=bibs&hl=en&cites=1157052756975292108)
+-   [H. Pakula et al. **Nature Communications**, 2024](https://www.nature.com/articles/s41467-023-44210-1)
+-   [B. Ricciuti et al. **Journal of Clinical Oncology**, 2024](https://ascopubs.org/doi/full/10.1200/JCO.23.00580)
+-   [A. Song et al. **Nature Reviews Bioengineering**, 2023](https://www.nature.com/articles/s44222-023-00096-8)
+-   [I. Virshup et al. **Nature Bioengineering**, 2023](https://www.nature.com/articles/s41587-023-01733-8)
+-   [A. Karargyris et al. **Nature Machine Intelligence**, 2023](https://www.nature.com/articles/s42256-023-00652-2)
+-   [S. Pati et al. **Nature Communications Engineering**, 2023](https://www.nature.com/articles/s44172-023-00066-3)
+-   [C. Gorman et al. **Nature Communications**, 2023](https://www.nature.com/articles/s41467-023-37224-2)
+-   [J. Nyman et al. **Cell Reports Medicine**, 2023](https://doi.org/10.1016/j.xcrm.2023.101189)
+-   [A. Shmatko et al. **Nature Cancer**, 2022](https://www.nature.com/articles/s43018-022-00436-4)
+-   [J. Pocock et al. **Nature Communications Medicine**, 2022](https://www.nature.com/articles/s43856-022-00186-5)
+-   [S. Orsulic et al. **Frontiers in Oncology**, 2022](https://www.frontiersin.org/articles/10.3389/fonc.2022.924945/full)
+-   [J. Linares et al. **Molecular Cell**, 2021](https://doi.org/10.1016/j.molcel.2021.08.039)
+-   the list continues [**here** **🔗**](https://scholar.google.com/scholar?oi=bibs&hl=en&cites=1157052756975292108)
 
-# Users
+# 5. Users
 
 <table style="border: 0px !important;"><tr><td>This is where in the world our most enthusiastic supporters are located:
    <br/><br/>
@@ -320,17 +358,35 @@ and this is where they work:
 
 Source: https://ossinsight.io/analyze/Dana-Farber-AIOS/pathml#people
 
-# License
+# 6. Contributing
+
+``PathML`` is an open source project. Consider contributing to benefit the entire community!
+
+There are many ways to contribute to `PathML`, including:
+
+* Submitting bug reports
+* Submitting feature requests
+* Writing documentation and examples
+* Fixing bugs
+* Writing code for new features
+* Sharing workflows
+* Sharing trained model parameters
+* Sharing ``PathML`` with colleagues, students, etc.
+
+See [contributing](https://github.com/Dana-Farber-AIOS/pathml/blob/master/CONTRIBUTING.rst) for more details.
+
+
+# 7. License
 
 The GNU GPL v2 version of PathML is made available via Open Source licensing. 
 The user is free to use, modify, and distribute under the terms of the GNU General Public License version 2.
 
 Commercial license options are available also.
 
-# Contact
+# 8. Contact
 
 Questions? Comments? Suggestions? Get in touch!
 
 [[email protected]](mailto:[email protected])
 
-<img src=https://raw.githubusercontent.com/Dana-Farber-AIOS/pathml/master/docs/source/_static/images/dfci_cornell_joint_logos.png width="750"> 
+<img src=https://raw.githubusercontent.com/Dana-Farber-AIOS/pathml/master/docs/source/_static/images/dfci_cornell_joint_logos.png width="750"> 

ai-digital-pathology-assistant-v3/README.md

@@ -0,0 +1,31 @@
+![image](https://github.com/Dana-Farber-AIOS/pathml/assets/25375373/0e1c7adf-6510-4733-bf38-93c7be1c73cc)
+
+# Digital Pathology Assistant v3.0
+
+👋 Say _Hi!_ to your new digital pathology AI
+
+It will help you:
+
+- install PathML
+- write digital pathology analyses
+- will be your teacher as you embark on your digital pathology journey
+
+## Run it!
+
+👉 <kbd> <br> **[🔬🤖 Click here to Launch our AI 🎓 ⤴](https://chat.openai.com/g/g-L1IbnIIVt-digital-pathology-assistant-v3-0)** <br> </kbd>
+
+## Examples
+
+### Use this AI to get started with PathML:
+![Screen Recording 2024-04-06 at 10 47 21 AM](https://github.com/Dana-Farber-AIOS/pathml/assets/25375373/cfc4969b-8000-4fc4-b1b9-19a2279ba980)
+
+### Or to learn how to load your WSI image and count the nuclei in it:
+![Screen Recording 2024-04-06 at 10 53 46 AM](https://github.com/Dana-Farber-AIOS/pathml/assets/25375373/a225fadd-e019-485d-959f-6d0c39218f5b)
+
+## Recreate it
+
+[Here](./src) you will find all material needed to re-create our Digital Pathology Assistant, which is a custom OpenAI GPT available to all ChatGPT Plus users for research purposes. 
+
+## Note 
+
+This AI is **NOT** intended for clinical use.

ai-digital-pathology-assistant-v3/src/DESC.txt

@@ -0,0 +1 @@
+Specify your requirements in plain english and I'll provide PathML and Python code for your use-case