Tools for computational pathology
Project description
Branch | Test status |
---|---|
master | |
dev |
A toolkit for computational pathology and machine learning.
View documentation
: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 commits on the master
branch, or as versioned releases on PyPI
Installation
There are several ways to install PathML
:
- pip install (recommended for users)
- clone repo to local machine and install from source (recommended for developers/contributors)
Options (1) and (2) require that you first install all external dependencies:
- openslide
- JDK 8
We recommend using conda for environment management. Download Miniconda here
Note: these instructions are for Linux. Commands may be different for other platforms.
Installation option 1: pip install
Create conda environment
conda create --name pathml python=3.8
conda activate pathml
Install external dependencies (Linux) with Apt
sudo apt-get install openslide-tools g++ gcc libblas-dev liblapack-dev
Install external dependencies (MacOS) with Brew
brew install openslide
Install OpenJDK 8
conda install openjdk==8.0.152
Optionally install CUDA (instructions here)
Install PathML
pip install pathml
Installation option 2: clone repo and install from source
Clone repo
git clone https://github.com/Dana-Farber-AIOS/pathml.git
cd pathml
Create conda environment
conda env create -f environment.yml
conda activate pathml
Optionally install CUDA (instructions here)
Install PathML
:
pip install -e .
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.
Check the version of CUDA:
nvidia-smi
Install correct version of cudatoolkit
:
# update this command with your CUDA version number
conda install cudatoolkit=11.0
After installing PyTorch, optionally verify successful PyTorch installation with CUDA support:
python -c "import torch; print(torch.cuda.is_available())"
Using with Jupyter
Jupyter notebooks are a convenient way to work interactively. To use PathML
in Jupyter notebooks:
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
specifying the path to Java. To do so:
- Get the path to Java by running
echo $JAVA_HOME
in the terminal in your pathml conda environment (outside of Jupyter) - Set that path as the
JAVA_HOME
environment variable in Jupyter:import os os.environ["JAVA_HOME"] = "/opt/conda/envs/pathml" # change path as needed
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.
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 for more details.
Citing
If you use PathML
in your work, please cite our paper:
Rosenthal J, Carelli R, Omar M, Brundage D, Halbert E, Nyman J, Hari SN, Van Allen EM, Marchionni L, Umeton R, Loda M. 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, 2021. DOI: 10.1158/1541-7786.MCR-21-0665
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
Questions? Comments? Suggestions? Get in touch!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.