## 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: **[seyed.kahaki@fda.hhs.gov](mailto:seyed.kahaki@fda.hhs.gov)**.
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](https://mousavikahaki.github.io/ValidPath/index.html)
Please refer to the code documentation and email **[seyed.kahaki@fda.hhs.gov](mailto:seyed.kahaki@fda.hhs.gov)** if you have any questions.
### Testing Examples
1. [WSI Reader: Read Whole slide Image, Extract WSI Regions](https://github.com/mousavikahaki/ValidPath/blob/main/01_read_wsi.ipynb)
2. [Extract Annotations: Extract annotations and masks from Whole Slide Images](https://github.com/mousavikahaki/ValidPath/blob/main/02_annotation_extraction.ipynb)
3. [Patch Extraction: Extract patch images from annotated regions](https://github.com/mousavikahaki/ValidPath/blob/main/03_patch_extraction.ipynb)
4. [Annotation Generator: Generate Aperio ImageScope Annotation file](https://github.com/mousavikahaki/ValidPath/blob/main/4_annotation_generator.ipynb)
5. [Performance Assessmet: including different methods for assessing the performance of ML models](https://github.com/mousavikahaki/ValidPath/blob/main/05_performance_assessment.ipynb)
## 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](https://mousavikahaki.github.io/ValidPath/installation.html)
To understand better how the programs work, study the jupyter notebooks referred to under the heading [**Examples Taster**](https://github.com/mousavikahaki/ValidPath/blob/main/README.md#testing-examples).
### 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:
```sh
pip install lxml==4.9.1
```
Please follow the same procedure to install these python packages:
```sh
• 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:
```sh
pip freeze | findstr lxml
```
or
```sh
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
```sh
$ cd ValidPath ROOT DIRECTORY
```
4. Download a complete copy of the ** ValidPath **.
```sh
$ git clone https://github.com/mousavikahaki/ValidPath/
```
5. Change directory to ValidPath
```sh
$ cd ValidPath
```
6. Create virtual environment for ** ValidPath** using
```sh
$ conda env create -f requirements.dev.conda.yml
$ conda activate ValidPath-dev
```
or
```sh
$ 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:
```sh
$ 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](https://github.com/mousavikahaki/ValidPath/tree/main/data).
### Contact
For any questions/suggestions/collaborations, please contact Seyed Kahaki either via this GitHub repo or via email (seyed.kahaki@fda.hhs.gov).
### 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.
Raw data
{
"_id": null,
"home_page": "",
"name": "ValidPath",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python,whole slide,image,pathology,WSI,medical image",
"author": "Seyed Mostafa Mousavi Kahaki",
"author_email": "<mousavikahaki@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/db/db/ae3f7b357b2fc7929408480c31744d9c8850c169cb46e795dc5149fb4063/ValidPath-0.0.5.tar.gz",
"platform": null,
"description": "## Getting Started\r\n\r\n### General Information\r\n**`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: **[seyed.kahaki@fda.hhs.gov](mailto:seyed.kahaki@fda.hhs.gov)**.\r\n\r\nWe are continuously working on this toolbox, and we welcome any contributions.\r\n\r\n### Modules\r\nThere are several modules in this package including\r\n1. WSI Handler: Includes functions and classes for general WSI analysis such as reading whole slide images, extract sub region, and visualize thumbnail.\r\n2. Annotation Extraction: Includes several functions for extracting annotated ROIs.\r\n3. Patch Extraction: Assists pathologists and developers in extracting image patches from a whole slide image's region of interest.\r\n4. Annotation File Generator: Maps ROIs back into the image scope visualizer for the pathologist validation process\r\n5. Performance Assessment: Includes different modules for assessing the performance of ML models.\r\n\r\n### Information for Developers\r\nCode Documentation: [Link](https://mousavikahaki.github.io/ValidPath/index.html)\r\nPlease refer to the code documentation and email **[seyed.kahaki@fda.hhs.gov](mailto:seyed.kahaki@fda.hhs.gov)** if you have any questions.\r\n\r\n\r\n### Testing Examples\r\n1. [WSI Reader: Read Whole slide Image, Extract WSI Regions](https://github.com/mousavikahaki/ValidPath/blob/main/01_read_wsi.ipynb)\r\n2. [Extract Annotations: Extract annotations and masks from Whole Slide Images](https://github.com/mousavikahaki/ValidPath/blob/main/02_annotation_extraction.ipynb)\r\n3. [Patch Extraction: Extract patch images from annotated regions](https://github.com/mousavikahaki/ValidPath/blob/main/03_patch_extraction.ipynb)\r\n4. [Annotation Generator: Generate Aperio ImageScope Annotation file](https://github.com/mousavikahaki/ValidPath/blob/main/4_annotation_generator.ipynb)\r\n5. [Performance Assessmet: including different methods for assessing the performance of ML models](https://github.com/mousavikahaki/ValidPath/blob/main/05_performance_assessment.ipynb)\r\n\r\n## Installation\r\nThis section will help you to install the packages needed for ValidPath.\r\n\r\n### Install Python package\r\n\r\nIf 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).\r\n\r\nDetailed installation instructions can be found in the [documentation]([Link to Installation Guide dependencies](https://mousavikahaki.github.io/ValidPath/installation.html)\r\nTo understand better how the programs work, study the jupyter notebooks referred to under the heading [**Examples Taster**](https://github.com/mousavikahaki/ValidPath/blob/main/README.md#testing-examples).\r\n\r\n### Pre-requirements\r\n\r\nIn 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: \r\n- Linux System (Tested on Ubuntu 18.04.3 LTS)\r\n- Python 3.8\r\n \r\nTo install a python package with specific version of a package using pip, you can use the syntax \u201cpip install package==version\u201d 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:\r\n```sh\r\npip install lxml==4.9.1\r\n```\r\nPlease follow the same procedure to install these python packages:\r\n```sh\r\n\u2022 lxml==4.9.1\r\n\u2022 opencv-python==4.8.1.78\r\n\u2022 openslide-python==1.1.2\r\n\u2022 scikit-image==0.18.1\r\n\u2022 Shapely==1.7.1\r\n\u2022 sharepy==2.0.0\r\n\u2022 matplotlib==3.6.2 \r\n\u2022 Pillow==9.3.0\r\n\u2022 tifffile==2022.10.10\r\n\u2022 mpmath==1.2.1\r\n\u2022 random\r\n\u2022 glob\r\n\u2022 pandas\r\n\u2022 numpy\r\n```\r\nFor the full list of the requirements, please see the requirement.txt file in the project root directory \r\n\r\n \r\nIn order to check the current package version installed on you system, you can use \u201cpip freeze\u201d or \u201c.___version___\u201d as follows:\r\n```sh\r\n pip freeze | findstr lxml\r\n```\r\nor \r\n```sh\r\n import lxml\r\n print(lxml.__version__)\r\n```\r\n\r\n\r\n\r\n### Prepare for development (this is optional)\r\n\r\nPrepare a computer as a convenient platform for further development of the Python package ValidPath and related programs as follows.\r\n1.\tInstall the dependencies based on this guide (Link to Installation Guide dependencies)\r\n2.\tOpen a terminal window\r\n```sh\r\n $ cd ValidPath ROOT DIRECTORY\r\n```\r\n4.\tDownload a complete copy of the ** ValidPath **.\r\n```sh\r\n $ git clone https://github.com/mousavikahaki/ValidPath/\r\n```\r\n5.\tChange directory to ValidPath\r\n```sh\r\n $ cd ValidPath\r\n```\r\n6.\tCreate virtual environment for ** ValidPath** using\r\n```sh\r\n $ conda env create -f requirements.dev.conda.yml\r\n $ conda activate ValidPath-dev\r\n```\r\nor\r\n```sh\r\n $ conda create -n ValidPath-dev python=3.8 \r\n $ conda activate ValidPath-dev\r\n $ pip install -r requirements.txt\r\n```\r\n7.\tTo use the packages installed in the environment, run the command:\r\n```sh\r\n$ conda activate ValidPath-dev\r\n```\r\n\r\n\r\n### Cite this repository\r\n\r\nIf you find that ValidPath is useful or if you use it in your project, please consider citing the code:\r\n\r\n```\r\nSeyed Kahaki, Arian Arab, Weijie Chen. (2024) ValidPath [Source Code] https://github.com/mousavikahaki/ValidPath\r\n```\r\n\r\nAnd this pape:\r\n```\r\n@article{\r\n Pocock2022,\r\n 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)},\r\n doi = {TBD},\r\n issn = {TBD},\r\n journal = {SPIE Medical Imaging},\r\n month = {feb},\r\n number = {1},\r\n pages = {1},\r\n publisher = {SPIE Medical Imaging},\r\n title = {{Weakly supervised deep learning for predicting the response to hormonal treatment of women with atypical endometrial hyperplasia: a feasibility study}},\r\n url = {https://spie.org/medical-imaging/presentation/Weakly-supervised-deep-learning-for-predicting-the-response-to-hormonal/12471-31},\r\n volume = {2},\r\n year = {2023}\r\n}\r\n```\r\n\r\n### Auxiliary Files\r\n\r\nExample of input data can be found here: [Link](https://github.com/mousavikahaki/ValidPath/tree/main/data).\r\n\r\n### Contact\r\nFor any questions/suggestions/collaborations, please contact Seyed Kahaki either via this GitHub repo or via email (seyed.kahaki@fda.hhs.gov).\r\n\r\n### Acknowledgment \r\nThis 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.\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Processing Digital Pathology Data",
"version": "0.0.5",
"project_urls": null,
"split_keywords": [
"python",
"whole slide",
"image",
"pathology",
"wsi",
"medical image"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "007d15e8a7ab6ef95fd328b3a6b9dee4b10bde9215b768d3f3c45857cfa78018",
"md5": "1cba4cef94313ad51907648c0570bc65",
"sha256": "027c9c75ee7a4c84d69fd288db0c678a15647b11aebb6bdc6bbf3ef89151d131"
},
"downloads": -1,
"filename": "ValidPath-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1cba4cef94313ad51907648c0570bc65",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 22790,
"upload_time": "2023-12-27T16:13:02",
"upload_time_iso_8601": "2023-12-27T16:13:02.312199Z",
"url": "https://files.pythonhosted.org/packages/00/7d/15e8a7ab6ef95fd328b3a6b9dee4b10bde9215b768d3f3c45857cfa78018/ValidPath-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dbdbae3f7b357b2fc7929408480c31744d9c8850c169cb46e795dc5149fb4063",
"md5": "8ef4b3024d165e40c623bd03638dabfe",
"sha256": "781e4952efe3ea2f55a40d7ac2cd87118e9e1e7eb3226daedf7b43ffcb1e51de"
},
"downloads": -1,
"filename": "ValidPath-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "8ef4b3024d165e40c623bd03638dabfe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22746,
"upload_time": "2023-12-27T16:13:04",
"upload_time_iso_8601": "2023-12-27T16:13:04.005015Z",
"url": "https://files.pythonhosted.org/packages/db/db/ae3f7b357b2fc7929408480c31744d9c8850c169cb46e795dc5149fb4063/ValidPath-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-27 16:13:04",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "validpath"
}
JSON