Skip to content

Commit

Permalink
Merge pull request #149 from Dana-Farber-AIOS/readthedocs
Browse files Browse the repository at this point in the history 
Update docs
  • Loading branch information
@jacob-rosenthal
jacob-rosenthal committed Jul 30, 2021
2 parents 9443765 + 52df05d commit fc33254
Show file tree
Hide file tree
Showing 4 changed files with 113 additions and 116 deletions.
87 changes: 56 additions & 31 deletions CONTRIBUTING.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@ Contributing

``PathML`` is an open source project. Consider contributing to benefit the entire community!

Ways to Contribute
==================
There are many ways to contribute to PathML, including:

* Submitting bug reports
Expand Down Expand Up @@ -35,28 +33,61 @@ Request a new feature by filing an issue on GitHub. Make sure to include the fol
* Pseudocode of how the feature might work (if applicable)
* Any other useful information

Writing code and/or documentation
==============================================
Here's how to contribute code, documentation, etc.
For developers
==============

1. Create a new GitHub issue for what you will be working on, if one does not already exist
2. Create a new fork of the ``PathML`` repository
3. Clone your fork to your local machine
4. Set up the PathML environment: ``conda env create -f environment.yml``
Setting up a local development environment
-------------------------------------------

1. Create a new fork of the ``PathML`` repository
2. Clone your fork to your local machine
3. Set up the PathML environment: ``conda env create -f environment.yml; conda activate pathml``
4. Install PathML: ``pip install -e .``
5. Install pre-commit hooks: ``pre-commit install``
6. Ensure that your environment is properly configured and that all tests pass
7. Implement your changes
8. Write new tests as needed to maintain code coverage
9. Ensure that all tests still pass
10. Commit your changes and submit a pull request referencing the corresponding issue
11. Respond to discussion/feedback about the pull request. Make changes as necessary.

Code Standards
==============
Running tests
-------------

.. code-block::
python -m pytest
Building documentation locally
------------------------------

.. code-block::
cd docs # enter docs directory
make html # build docs in html format
Then use your favorite web browser to open ``pathml/docs/build/html/index.html``

Checking code coverage
----------------------

.. code-block::
conda install coverage # install coverage package for code coverage
coverage run # run tests and calculate code coverage
coverage report # view coverage report
coverage html # optionally generate HTML coverage report
How to contribute code, documentation, etc.
-------------------------------------------

1. Create a new GitHub issue for what you will be working on, if one does not already exist
2. Create a local development environment (see above)
3. Implement your changes
4. Write new tests as needed to maintain code coverage
5. Ensure that all tests pass
6. Commit your changes and submit a pull request referencing the corresponding issue
7. Respond to discussion/feedback about the pull request, make changes as necessary

Code Standards
--------------

Code Quality
------------
^^^^^^^^^^^^

We want PathML to be built on high-quality code. However, the idea of "code quality" is somewhat subjective.
If the code works perfectly but cannot be read and understood by someone else, then it can't be maintained,
Expand All @@ -77,7 +108,7 @@ All code should be reviewed by someone else before merging.
We use `Black`_ to enforce consistency of code style.

Documentation Standards
-----------------------
^^^^^^^^^^^^^^^^^^^^^^^^

All code should be documented, including docstrings for users AND inline comments for
other developers whenever possible! Both are crucial for ensuring long-term usability and maintainability.
Expand All @@ -86,19 +117,8 @@ properly formatted Google-style docstrings.
All documentation (including docstrings) is written in `reStructuredText`_ format.
See this `docstring example`_ to get started.

To build documentation:

.. code-block::
# first install packages for generating docs
pip install ipython sphinx nbsphinx nbsphinx-link sphinx-rtd-theme
cd docs # enter docs directory
make html # build docs in html format
Then use your favorite web browser to open ``pathml/docs/build/html/index.html``

Testing Standards
-----------------
^^^^^^^^^^^^^^^^^^

All code should be accompanied by tests, whenever possible, to ensure that everything is working as intended.

Expand All @@ -121,9 +141,14 @@ To run the test suite and check code coverage:
coverage report # view coverage report
coverage html # optionally generate HTML coverage report
We suggest using test-driven development when applicable. I.e., if you're fixing a bug or adding new features,
write the tests first! (they should all fail). Then, write the actual code. When all tests pass, you know
that your implementation is working. This helps ensure that all code is tested and that the tests are testing
what we want them to.

Thank You!
==========

Thank you for helping make ``PathML`` better!


Expand Down
118 changes: 36 additions & 82 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,103 +1,57 @@
<img src=https://raw.githubusercontent.com/Dana-Farber-AIOS/pathml/master/docs/source/_static/images/logo.png width="300">

<img src=https://raw.githubusercontent.com/Dana-Farber-AIOS/pathml/master/docs/source/_static/images/overview.png width="750">

A toolkit for computational pathology and machine learning.
<img src=https://raw.githubusercontent.com/Dana-Farber-AIOS/pathml/master/docs/source/_static/images/overview.png width="750">

![tests](https://github.com/Dana-Farber-AIOS/pathml/actions/workflows/tests-conda.yml/badge.svg)
[![Documentation Status](https://readthedocs.org/projects/pathml/badge/?version=latest)](https://pathml.readthedocs.io/en/latest/?badge=latest)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![PyPI version](https://img.shields.io/pypi/v/pathml)](https://pypi.org/project/pathml/)

A toolkit for computational pathology and machine learning.

* [Installing](#installing)
* [Requirements](#requirements)
* [Installation](#installation)
* [Generate Documentation](#generate-documentation)
* [Tests and Code Coverage](#tests-and-code-coverage)
* [Getting Started](#getting-started)
* [Contributing](#contributing)
* [Contact](#contact)
**View [documentation](https://pathml.readthedocs.io/en/latest/)**

# Installing
# Installation

*Note: these instructions are for Linux. Commands may be different for other platforms.*

0. Requirements
* Set up Conda environment
* Download Miniconda [here](https://docs.conda.io/en/latest/miniconda.html)
* Create conda environment
````
conda create --name pathml python=3.8 numpy=1.8.15
conda activate pathml
````
* Install external dependencies
## Requirements

* Set up Conda environment
* Download Miniconda [here](https://docs.conda.io/en/latest/miniconda.html)
* Create conda environment
````
sudo apt-get install openslide-tools g++ gcc libblas-dev liblapack-dev
conda create --name pathml python=3.8 numpy=1.8.15
conda activate pathml
````
* Install conda dependencies [OpenJDK](https://openjdk.java.net/)
* Install external dependencies
````
sudo apt-get install openslide-tools g++ gcc libblas-dev liblapack-dev
````
* Install [OpenJDK 8](https://openjdk.java.net/)
````
conda install openjdk==8.0.152
````
* [Optional]: Install CUDA. This step only applies if you want to use GPU acceleration for model training or other tasks. This guide should work, but for the most up-to-date instructions, refer to the [official PyTorch installation instructions](https://pytorch.org/get-started/locally/).
- Check the version of CUDA:
````
nvidia-smi
````
conda install openjdk==8.0.152
- Install correct version of `cudatoolkit`:
````
# update this command with your CUDA version number
conda install cudatoolkit=11.0
````
* [Optional]: Install CUDA. This step only applies if you want to use GPU acceleration for model training or other tasks. This guide should work, but for the most up-to-date instructions, refer to the [official PyTorch installation instructions](https://pytorch.org/get-started/locally/).
- 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
````

1. Install PathML:
````
pip install pathml
````

2. Optionally verify PyTorch installation with GPU support:
````
python -c "import torch; print(torch.cuda.is_available())"
````


## Generate Documentation

This repo is not yet open to the public. Once we open source it, we will host documentation online.
Until then, you must build a local copy of the documentation yourself.

````
# first install packages for generating docs
pip install ipython sphinx nbsphinx nbsphinx-link sphinx-rtd-theme
cd docs # enter docs directory
make html # build docs in html format
## Install PathML
````
pip install pathml
````

Then use your favorite web browser to open ``pathml/docs/build/html/index.html``

## Tests and Code Coverage

You may optionally run the test suite to verify installation.

To run tests:
[Optional]: If using GPUs, verify successful PyTorch installation with CUDA support:
````
conda install pytest # first install pytest package
python -m pytest # run test suite
python -c "import torch; print(torch.cuda.is_available())"
````
Note that because the testing suite tests all parts of the code base,
this may require installing additional packages as well.
(e.g. installation of java is required for some functionality).

You may also optionally measure code coverage, i.e. what percentage of code is covered in the testing suite.

To run tests and check code coverage, install all dependencies (including dependencies for multiparametric images), then:
```
conda install coverage # install coverage package for code coverage
coverage run # run tests and calculate code coverage
coverage report # view coverage report
coverage html # optionally generate HTML coverage report
```

# Getting Started

The [example notebooks](examples) are a good place start with `PathML`.

# Contributing

Expand All @@ -114,7 +68,7 @@ There are many ways to contribute to PathML, including:
* Sharing trained model parameters
* Sharing ``PathML`` with colleagues, students, etc.

See [contributing](CONTRIBUTING.rst) for more details.
See [contributing](https://github.com/Dana-Farber-AIOS/pathml/blob/master/CONTRIBUTING.rst) for more details.

# Contact

Expand Down
7 changes: 7 additions & 0 deletions pathml/core/utils.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
def writedataframeh5(h5, name, df):
"""
Write dataframe as h5 dataset.
Args:
h5(h5py.Dataset): root of h5 object that df will be written into
name(str): name of dataset to be created
Expand All @@ -37,6 +38,7 @@ def writedataframeh5(h5, name, df):
def writestringh5(h5, name, st):
"""
Write string as h5 attribute.
Args:
h5(h5py.Dataset): root of h5 object that st will be written into
name(str): name of dataset to be created
Expand All @@ -49,6 +51,7 @@ def writestringh5(h5, name, st):
def writedicth5(h5, name, dic):
"""
Write dict as attributes of h5py.Group.
Args:
h5(h5py.Dataset): root of h5 object that dic will be written into
name(str): name of dataset to be created
Expand All @@ -62,6 +65,7 @@ def writedicth5(h5, name, dic):
def writetupleh5(h5, name, tup):
"""
Write tuple as h5 attribute.
Args:
h5(h5py.Dataset): root of h5 object that tup will be written into
name(str): name of dataset to be created
Expand All @@ -74,6 +78,7 @@ def writetupleh5(h5, name, tup):
def readtupleh5(h5, key):
"""
Read tuple from h5.
Args:
h5(h5py.Dataset or h5py.Group): h5 object that will be read from
key(str): key where data to read is stored
Expand All @@ -84,6 +89,7 @@ def readtupleh5(h5, key):
def writecounts(h5, counts):
"""
Write counts using anndata h5py.
Args:
h5(h5py.Dataset): root of h5 object that counts will be written into
name(str): name of dataset to be created
Expand All @@ -97,6 +103,7 @@ def writecounts(h5, counts):
def readcounts(h5):
"""
Read counts using anndata h5py.
Args:
h5(h5py.Dataset): h5 object that will be read
"""
Expand Down
17 changes: 14 additions & 3 deletions pathml/preprocessing/transforms.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,13 @@
import pathml.core
import pathml.core.slide_data
import spams
from pathml.utils import (RGB_to_GREY, RGB_to_HSI, RGB_to_HSV, RGB_to_OD,
normalize_matrix_cols)
from pathml.utils import (
RGB_to_GREY,
RGB_to_HSI,
RGB_to_HSV,
RGB_to_OD,
normalize_matrix_cols,
)
from skimage import restoration
from skimage.measure import regionprops_table

Expand Down Expand Up @@ -1157,6 +1162,13 @@ class SegmentMIF(Transform):
Model outputs predictions for centroid and boundary of every nucleus and cell, then centroid and boundary
predictions are used as inputs to a watershed algorithm that creates segmentation masks.
.. warning::
Mesmer model requires installation of deepcell dependency: ``pip install deepcell``
.. warning::
Mesmer model is incompatible with dask.distributed. Pipelines containing Mesmer model must be run with
``distributed=False``. See: https://github.com/Dana-Farber-AIOS/pathml/issues/130
Args:
model(str): string indicating which segmentation model to use. Currently only 'mesmer' is supported.
nuclear_channel(int): channel that defines cell nucleus
Expand Down Expand Up @@ -1260,7 +1272,6 @@ def apply(self, tile):
class QuantifyMIF(Transform):
"""
Convert segmented image into anndata.AnnData counts object.
This function requires deepcell dependency ``pip install deepcell ``
Args:
segmentation_mask (str): key indicating which mask to use as label image
Expand Down

0 comments on commit fc33254

Please sign in to comment.