Coder Social home page Coder Social logo

tddough98 / pathml Goto Github PK

View Code? Open in Web Editor NEW

This project forked from dana-farber-aios/pathml

0.0 0.0 0.0 112.71 MB

Tools for computational pathology

Home Page: https://pathml.org

License: GNU General Public License v2.0

Python 99.50% Dockerfile 0.50%

pathml's Introduction

Documentation Status Code style: black PyPI version Downloads codecov

Branch Test status
master tests
dev tests

An open-source toolkit for computational pathology and machine learning.

View documentation

๐Ÿšง 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

Installation

There are several ways to install PathML:

  1. pip install from PyPI (recommended for users)
  2. Clone repo to local machine and install from source (recommended for developers/contributors)
  3. Use the PathML Docker container

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 from PyPI:

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 from source:

pip install -e .

Installation option 3: Docker

First, download or build the PathML Docker container:

pathml-docker-installation

  • Option A: download PathML container from Docker Hub

    docker pull pathml/pathml:latest
    

    Optionally specify a tag for a particular version, e.g. docker pull pathml/pathml:2.0.2. To view possible tags, please refer to the PathML DockerHub page.

  • Option B: build docker container from source

    git 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/pathml

The 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 with http://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 the token= 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 the Docker run documentation for further instructions on accessing the container, e.g. for mounting volumes to access files on a local machine from within the container.

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:

  1. Get the path to Java by running echo $JAVA_HOME in the terminal in your pathml conda environment (outside of Jupyter)
  2. 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!

[email protected]

pathml's People

Contributors

jacob-rosenthal avatar ryanccarelli avatar beegass avatar mohamedomar2020 avatar dana-farber avatar karenxzr avatar ella-dfci avatar dmbrundage avatar surya-narayanan avatar yu-anchen avatar dependabot[bot] avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.