Merge pull request #310 from Dana-Farber-AIOS/v2.1.0

v2.1.0

Author: jacob-rosenthal

README.md

@@ -24,24 +24,13 @@ Stable versions are available as tagged releases on GitHub, or as versioned rele
 
 There are several ways to install `PathML`:
 
-1. `pip install` from PyPI
-2. Clone repo to local machine and install from source
+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
 
-Option (1) is recommended for most users. It will install the latest versions of most packages. 
-Option (2) is a deterministic environment setup, meaning that all package versions are pinned and it will install the
-pinned version of a package even if it is not the newest. The automated testing suite is run in this environment. This
-is the suggested installation method for users wanting to interface with the Mesmer model for IF workflows, and for
-contributors/developers. Option (3) uses the same environment from (2), but in a Docker 
-container.
-
-Options (1) and (2) require that you first install all external dependencies (namelt, JDK-8 and system libraries used
-by OpenSlide and OpenCV):
-
-* Install external dependencies (Linux) with [Apt](https://ubuntu.com/server/docs/package-management):
-    ````
-    sudo apt-get update && sudo apt-get install openslide-tools g++ gcc libblas-dev liblapack-dev python3-opencv
-    ````
+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](https://docs.conda.io/en/latest/miniconda.html)
@@ -50,12 +39,27 @@ Download Miniconda [here](https://docs.conda.io/en/latest/miniconda.html)
 
 ## Installation option 1: pip install
 
-Create conda environment with dependencies:
+Create conda environment:
 ````
-conda create --name pathml python=3.8 numpy=1.19.5 openjdk==8.0.152 -c conda-forge
+conda create --name pathml python=3.8
 conda activate pathml
 ````
 
+Install external dependencies (Linux) with [Apt](https://ubuntu.com/server/docs/package-management):
+````
+sudo apt-get install openslide-tools g++ gcc libblas-dev liblapack-dev
+````
+
+Install external dependencies (MacOS) with [Brew](www.brew.sh):
+````
+brew install openslide
+````
+
+Install [OpenJDK 8](https://openjdk.java.net/):
+````
+conda install openjdk==8.0.152
+````
+
 Optionally install CUDA (instructions [here](#CUDA))
 
 Install `PathML` from PyPI:
@@ -140,17 +144,6 @@ After installing PyTorch, optionally verify successful PyTorch installation with
 python -c "import torch; print(torch.cuda.is_available())"
 ````
 
-## Troubleshooting installation
-
-Installation can be fragile at times due to external dependencies. 
-If having difficulty installing, try the following:
-
-* Look through the GitHub issues to see if someone else has run into the same problem before
-* Ensure that the correct versions of all dependencies are installed
-* Make sure to use a fresh conda environment  
-* Use pip's `--no-cache-dir` to prevent using cached files
-* Use deterministic environment specifications such as those used in installation options (2) and (3)
-
 # Using with Jupyter
 
 Jupyter notebooks are a convenient way to work interactively. To use `PathML` in Jupyter notebooks: 

docs/source/api_utils_reference.rst

@@ -3,6 +3,11 @@ Utilities API
 
 Documentation for various utilities from all modules.
 
+Logging Utils
+-------------
+
+.. autoapiclass:: pathml.PathMLLogger
+
 Core Utils
 ----------
 

environment.yml

@@ -29,3 +29,4 @@ dependencies:
         - scanpy==1.8.2
         - anndata==0.7.8
         - tqdm==4.62.3
+        - loguru==0.5.3

pathml/__init__.py

@@ -7,4 +7,5 @@
 from . import datasets as ds
 from . import ml
 from . import preprocessing as pp
+from ._logging import PathMLLogger
 from ._version import __version__

pathml/_logging.py

@@ -0,0 +1,96 @@
+"""
+Copyright 2021, Dana-Farber Cancer Institute and Weill Cornell Medicine
+License: GNU GPL 2.0
+"""
+
+from loguru import logger
+import functools
+import sys
+
+
+class PathMLLogger:
+    """
+    Convenience methods for turning on or off and configuring logging for PathML.
+    Note that this can also be achieved by interfacing with loguru directly
+
+    Example::
+
+        from pathml import PathMLLogger as pml
+
+        # turn on logging for PathML
+        pml.enable()
+
+        # turn off logging for PathML
+        pml.disable()
+
+        # turn on logging and output logs to a file named 'logs.txt', with colorization enabled
+        pml.enable(sink="logs.txt", colorize=True)
+    """
+
+    logger.disable("pathml")
+    logger.disable(__name__)
+
+    @staticmethod
+    def disable():
+        """
+        Turn off logging for PathML
+        """
+        logger.disable("pathml")
+        logger.disable(__name__)
+        logger.info(
+            "Disabled Logging For PathML! If you are seeing this, there is a problem"
+        )
+
+    @staticmethod
+    def enable(
+        sink=sys.stderr,
+        level="DEBUG",
+        fmt="PathML:{level}:{time:HH:mm:ss} | {module}:{function}:{line} | {message}",
+        **kwargs
+    ):
+        """
+        Turn on and configure logging for PathML
+
+        Args:
+            sink (str or io._io.TextIOWrapper, optional):
+                Destination sink for log messages. Defaults to ``sys.stderr``.
+            level (str):
+                level of logs to capture. Defaults to 'DEBUG'.
+            fmt (str):
+                Formatting for the log message. Defaults to: 'PathML:{level}:{time:HH:mm:ss} | {module}:{function}:{line} | {message}'
+            **kwargs (dict, optional):
+                additional options passed to configure logger. See:
+                `loguru documentation <https://loguru.readthedocs.io/en/stable/api/logger.html#loguru._logger.Logger.add>`_
+        """
+        logger.enable("pathml")
+        logger.enable(__name__)
+        # remove pre-configured logger (https://github.com/Delgan/loguru/issues/208#issuecomment-581002215)
+        logger.remove(0)
+        handler_id = logger.add(sink=sink, level=level, format=fmt, **kwargs)
+        logger.info("Enabled Logging For PathML!")
+        return handler_id
+
+
+# courtesy of the people at loguru
+# https://loguru.readthedocs.io/en/stable/resources/recipes.html#:~:text=or%20fallback%20policy.-,Logging%20entry%20and%20exit%20of%20functions%20with%20a%20decorator,-%EF%83%81
+def logger_wraps(*, entry=True, exit=True, level="DEBUG"):
+    def wrapper(func):
+        name = func.__name__
+
+        @functools.wraps(func)
+        def wrapped(*args, **kwargs):
+            logger_ = logger.opt(depth=1)
+            if entry:
+                logger_.bind(enter_exit=True).log(
+                    level, "Entering '{}' (args={}, kwargs={})", name, args, kwargs
+                )
+            result = func(*args, **kwargs)
+            if exit:
+                logger_.bind(enter_exit=True).log(
+                    level, "Exiting '{}' (result={})", name, result
+                )
+            return result
+
+        return wrapped
+
+    return wrapper

pathml/_version.py

@@ -3,4 +3,4 @@
 License: GNU GPL 2.0
 """
 
-__version__ = "2.0.4"
+__version__ = "2.1.0"

pathml/core/h5managers.py

@@ -9,6 +9,7 @@
 from collections import OrderedDict
 
 import anndata
+from loguru import logger
 import h5py
 import numpy as np
 import pathml.core
@@ -95,7 +96,7 @@ def add_tile(self, tile):
             tile(pathml.core.tile.Tile): Tile object
         """
         if str(tile.coords) in self.h5["tiles"].keys():
-            print(f"Tile is already in tiles. Overwriting {tile.coords} inplace.")
+            logger.info(f"Tile is already in tiles. Overwriting {tile.coords} inplace.")
             # remove old cells from self.counts so they do not duplicate
             if tile.counts:
                 if "tile" in self.counts.obs.keys():
@@ -114,7 +115,6 @@ def add_tile(self, tile):
             raise ValueError(
                 f"cannot add tile of shape {tile.image.shape}. Must match shape of existing tiles: {existing_shape}"
             )
-
         if self.slide_type and tile.slide_type:
             # check that slide types match
             if tile.slide_type != self.slide_type:
@@ -127,7 +127,7 @@ def add_tile(self, tile):
 
         # create a group for tile and write tile
         if str(tile.coords) in self.h5["tiles"]:
-            print(f"overwriting tile at {str(tile.coords)}")
+            logger.info(f"overwriting tile at {str(tile.coords)}")
             del self.h5["tiles"][str(tile.coords)]
         self.h5["tiles"].create_group(str(tile.coords))
         self.h5["tiles"][str(tile.coords)].create_dataset(
@@ -155,7 +155,9 @@ def add_tile(self, tile):
             # add tile-level masks
             for key, mask in tile.masks.items():
                 self.h5["tiles"][str(tile.coords)]["masks"].create_dataset(
-                    str(key), data=mask, dtype="float16",
+                    str(key),
+                    data=mask,
+                    dtype="float16",
                 )
 
         # add coords
@@ -209,8 +211,7 @@ def get_tile(self, item):
             item = list(self.h5["tiles"].keys())[item]
         else:
             raise KeyError(
-                f"invalid item type: {type(item)}. must getitem by coord (type tuple[int]),"
-                f"index (type int), or name (type str)"
+                f"invalid item type: {type(item)}. must getitem by coord (type tuple[int]), index (type int), or name (type str)"
             )
         tile = self.h5["tiles"][item]["array"][:]
 
@@ -339,7 +340,7 @@ def remove_mask(self, key):
                 f"masks keys must be of type(str) but key was passed of type {type(key)}"
             )
         if key not in self.h5["masks"].keys():
-            raise KeyError("key is not in Masks")
+            raise KeyError(f"key is not in Masks")
         del self.h5["masks"][key]
 
     def get_slidetype(self):

pathml/core/masks.py

@@ -9,6 +9,7 @@
 from collections import OrderedDict
 import h5py
 import reprlib
+from loguru import logger
 
 import pathml.core.h5managers
 
@@ -31,7 +32,7 @@ def __init__(self, h5manager, masks=None):
         if masks:
             if not isinstance(masks, dict):
                 raise ValueError(
-                    f"masks must be passed as dicts of the form key1:mask1,key2:mask2,..."
+                    "masks must be passed as dicts of the form {key1:mask1, key2:mask2, ...}"
                 )
             for val in masks.values():
                 if not isinstance(val, np.ndarray):