ValidPath 0.0.5

Processing Digital Pathology Data

Getting Started

General Information

ValidPath is a python-based package for developers and scientists who are interested in digital pathology. The main goal of developing this tool is to help stakeholders, graduate students, and pathologists to speed up their projects. For more information please contact: [e-mail].

We are continuously working on this toolbox, and we welcome any contributions.

Modules

There are several modules in this package including

1. WSI Handler: Includes functions and classes for general WSI analysis such as reading whole slide images, extract sub region, and visualize thumbnail.
2. Annotation Extraction: Includes several functions for extracting annotated ROIs.
3. Patch Extraction: Assists pathologists and developers in extracting image patches from a whole slide image's region of interest.
4. Annotation File Generator: Maps ROIs back into the image scope visualizer for the pathologist validation process
5. Performance Assessment: Includes different modules for assessing the performance of ML models.

Information for Developers

Code Documentation: Link Please refer to the code documentation and email [e-mail] if you have any questions.

Testing Examples

1. WSI Reader: Read Whole slide Image, Extract WSI Regions
2. Extract Annotations: Extract annotations and masks from Whole Slide Images
3. Patch Extraction: Extract patch images from annotated regions
4. Annotation Generator: Generate Aperio ImageScope Annotation file
5. Performance Assessmet: including different methods for assessing the performance of ML models

Installation

This section will help you to install the packages needed for ValidPath.

Install Python package

If you wish to use our python package, perhaps without developing them further, run the command pip install ValidPath or pip install --ignore-installed --upgrade ValidPath to upgrade from an existing installation (This will be enabled when the first version is ready and submitted to pypi).

Detailed installation instructions can be found in the [documentation](Link to Installation Guide dependencies To understand better how the programs work, study the jupyter notebooks referred to under the heading Examples Taster.

Pre-requirements

In order to use ValidPath, you need to install some additional python packages. It is recommended to install the same version specified in this section (and in the requirement.txt). ValidPath was tested on the following environment:

• Linux System (Tested on Ubuntu 18.04.3 LTS)
• Python 3.8

To install a python package with specific version of a package using pip, you can use the syntax “pip install package==version” in the command line. For example in ValidPath we are using lxml which is one of the fastest and feature-rich libraries for processing XML and HTML in Python. To install lxml version 4.9.1, run the following command:

pip install lxml==4.9.1

Please follow the same procedure to install these python packages:

• lxml==4.9.1
• opencv-python==4.8.1.78
• openslide-python==1.1.2
• scikit-image==0.18.1
• Shapely==1.7.1
• sharepy==2.0.0
• matplotlib==3.6.2 
• Pillow==9.3.0
• tifffile==2022.10.10
• mpmath==1.2.1
• random
• glob
• pandas
• numpy

For the full list of the requirements, please see the requirement.txt file in the project root directory

In order to check the current package version installed on you system, you can use “pip freeze” or “.version” as follows:

  pip freeze | findstr lxml

or

  import lxml
  print(lxml.__version__)

Prepare for development (this is optional)

Prepare a computer as a convenient platform for further development of the Python package ValidPath and related programs as follows.

1. Install the dependencies based on this guide (Link to Installation Guide dependencies)
2. Open a terminal window

    $ cd ValidPath ROOT DIRECTORY

4. Download a complete copy of the ** ValidPath **.

  $ git clone https://github.com/mousavikahaki/ValidPath/

5. Change directory to ValidPath

  $ cd ValidPath

6. Create virtual environment for ** ValidPath** using

  $ conda env create -f requirements.dev.conda.yml
  $ conda activate ValidPath-dev

or

  $ conda create -n ValidPath-dev python=3.8 
  $ conda activate ValidPath-dev
  $ pip install -r requirements.txt

7. To use the packages installed in the environment, run the command:

$ conda activate ValidPath-dev

Cite this repository

If you find that ValidPath is useful or if you use it in your project, please consider citing the code:

Seyed Kahaki, Arian Arab, Weijie Chen. (2024) ValidPath [Source Code] https://github.com/mousavikahaki/ValidPath

And this pape:

@article{
    Pocock2022,
    author = {Seyed M. M. Kahaki, U.S. Food and Drug Administration (United States); Ian S. Hagemann, Washington Univ. School of Medicine in St. Louis (United States); Kenny Cha, Christopher J. Trindade, Nicholas Petrick, Weijie Chen, U.S. Food and Drug Administration (United States)},
    doi = {TBD},
    issn = {TBD},
    journal = {SPIE Medical Imaging},
    month = {feb},
    number = {1},
    pages = {1},
    publisher = {SPIE Medical Imaging},
    title = {{Weakly supervised deep learning for predicting the response to hormonal treatment of women with atypical endometrial hyperplasia: a feasibility study}},
    url = {https://spie.org/medical-imaging/presentation/Weakly-supervised-deep-learning-for-predicting-the-response-to-hormonal/12471-31},
    volume = {2},
    year = {2023}
}

Auxiliary Files

Example of input data can be found here: Link.

Contact

For any questions/suggestions/collaborations, please contact Seyed Kahaki either via this GitHub repo or via email ([e-mail]).

Acknowledgment

This project was supported in part by an appointment to the ORISE Research Participation Program at the Center for Devices and Radiological Health, U.S. Food and Drug Administration, administered by the Oak Ridge Institute for Science and Education through an interagency agreement between the U.S. Department of Energy and FDA/CDRH.