Package: pathml
🤖🔬PathML: Tools for computational pathology⭐PathML objective is to lower the barrier to entry to digital pathologyImaging datasets in cancer research are growing exponentially in both quantity and information density. These massive datasets may enable derivation of insights for cancer research and clinical care, but only if researchers are equipped with the tools to leverage advanced computational analysis approaches such as machine learning and artificial intelligence. In this work, we highlight three themes to guide development of such computational tools: scalability, standardization, and ease of use. We then apply these principles to develop PathML, a general-purpose research toolkit for computational pathology. We describe the design of the PathML framework and demonstrate applications in diverse use cases.🚀The fastest way to get started?docker pull pathml/pathml && docker run -it -p 8888:8888 pathml/pathmlBranchTest statusmasterdevViewdocumentation:construction: thedevbranch 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 PyPIInstallationThere are several ways to installPathML:pip installfrom PyPI (recommended for users)Clone repo to local machine and install from source (recommended for developers/contributors)Use the PathML Docker containerOptions (1) and (2) require that you first install all external dependencies:openslideJDK 8We recommend using conda for environment management.
Download MinicondahereNote: these instructions are for Linux. Commands may be different for other platforms.Installation option 1: pip installCreate conda environment:conda create --name pathml python=3.8
conda activate pathmlInstall external dependencies (Linux) withApt:sudo apt-get install openslide-tools g++ gcc libblas-dev liblapack-devInstall external dependencies (MacOS) withBrew:brew install openslideInstallOpenJDK 8:conda install openjdk==8.0.152Optionally install CUDA (instructionshere)InstallPathMLfrom PyPI:pip install pathmlInstallation option 2: clone repo and install from sourceClone repo:git clone https://github.com/Dana-Farber-AIOS/pathml.git
cd pathmlCreate conda environment:conda env create -f environment.yml
conda activate pathmlOptionally install CUDA (instructionshere)InstallPathMLfrom source:pip install -e .Installation option 3: DockerFirst, download or build the PathML Docker container:Option A: download PathML container from Docker Hubdocker pull pathml/pathml:latestOptionally specify a tag for a particular version, e.g.docker pull pathml/pathml:2.0.2. To view possible tags,
please refer to thePathML DockerHub page.Option B: build docker container from sourcegit clone https://github.com/Dana-Farber-AIOS/pathml.git
cd pathml
docker build -t pathml/pathml .Then connect to the container:docker run -it -p 8888:8888 pathml/pathmlThe above command runs the container, which is configured to spin up a jupyter lab session and expose it on port 8888.
The terminal should display a URL to the jupyter lab session starting withhttp://127.0.0.1:8888/lab?token=<.....>.
Navigate to that page and you should connect to the jupyter lab session running on the container with the pathml
environment fully configured. If a password is requested, copy the string of characters following thetoken=in the
url.Note that the docker container requires extra configurations to use with GPU.Note that these instructions assume that there are no other processes using port 8888.Please refer to theDocker rundocumentationfor further instructions
on accessing the container, e.g. for mounting volumes to access files on a local machine from within the container.Option 4: Google ColabTo get PathML running in a Colab environment:!pip install openslide-python
!apt-get install openslide-tools
!apt-get install openjdk-8-jdk-headless -qq > /dev/null
os.environ["JAVA_HOME"] = "/usr/lib/jvm/java-8-openjdk-amd64"
!update-alternatives --set java /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java
!java -version
!pip install pathmlThanks 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.CUDATo 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 theofficial PyTorch installation instructions.Check the version of CUDA:nvidia-smiInstall correct version ofcudatoolkit:# update this command with your CUDA version number
conda install cudatoolkit=11.0After installing PyTorch, optionally verify successful PyTorch installation with CUDA support:python -c "import torch; print(torch.cuda.is_available())"Using with JupyterJupyter notebooks are a convenient way to work interactively. To usePathMLin Jupyter notebooks:Set JAVA_HOME environment variablePathML relies on Java to enable support for reading a wide range of file formats.
Before usingPathMLin Jupyter, you may need to manually set theJAVA_HOMEenvironment variable
specifying the path to Java. To do so:Get the path to Java by runningecho $JAVA_HOMEin the terminal in your pathml conda environment (outside of Jupyter)Set that path as theJAVA_HOMEenvironment variable in Jupyter:import os
os.environ["JAVA_HOME"] = "/opt/conda/envs/pathml" # change path as neededRegister environment as an IPython kernelconda activate pathml
conda install ipykernel
python -m ipykernel install --user --name=pathmlThis makes the pathml environment available as a kernel in jupyter lab or notebook.ContributingPathMLis an open source project. Consider contributing to benefit the entire community!There are many ways to contribute toPathML, including:Submitting bug reportsSubmitting feature requestsWriting documentation and examplesFixing bugsWriting code for new featuresSharing workflowsSharing trained model parametersSharingPathMLwith colleagues, students, etc.Seecontributingfor more details.CitingIf you usePathMLplease 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.So far, PathML was used in the following manuscripts:J. Linares et al.Molecular Cell2021A. Shmatko et al.Nature Cancer2022J. Pocock et al.Nature Communications Medicine2022S. Orsulic et al.Frontiers in Oncology2022D. Brundage et al.arXiv2022A. Marcolini et al.SoftwareX2022M. Rahman et al.Bioengineering2022C. Lama et al.bioRxiv2022the list continueshere 🔗 for 2023 and onwardsUsersThis is where in the world our most enthusiastic supporters are located:and this is where they work:Source:https://ossinsight.io/analyze/Dana-Farber-AIOS/pathml#peopleLicenseThe 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.ContactQuestions? Comments? Suggestions? Get in touch!pathml@dfci.harvard.edu