Feature slide info

.travis.yml

@@ -7,7 +7,7 @@ python:
   - 3.6
 
 before_install:
-  - sudo apt-get -y install python3-openslide
+  - sudo apt-get -y install openslide-tools
 
 # Command to install dependencies, e.g. pip install -r requirements.txt --use-mirrors
 install: pip install -U tox-travis

README.rst

@@ -1,7 +1,7 @@
 .. raw:: html
 
    <p align="center">
-     <img width="450" height="200" src=docs/tialab_logo.png>
+     <img width="450" height="200" src=https://warwick.ac.uk/fac/sci/dcs/research/tia/models/tialab_logo.png>
    </p>
 
 ===========
@@ -22,6 +22,15 @@ Getting Started
 First, install OpenSlide `here <https://openslide.org/download/>`__. Then, create and
 activate the conda environment:
 
+pip
+----
+
+::
+
+    pip install -r requirements_dev.txt
+
+conda
+-----
 ::
 
     conda env create --name tiatoolbox --file requirements.conda.yml
@@ -42,6 +51,6 @@ tiatoolbox --help
 
     optional arguments:
       -h, --help            show this help message and exit
-      --version             show program's version number and exit
+      --version             show program`s version number and exit
       --verbose VERBOSE
 

docs/conf.py

@@ -32,7 +32,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx.ext.napoleon"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/index.rst

@@ -1,5 +1,5 @@
 Welcome to TIA Toolbox's documentation!
-======================================
+=======================================
 
 .. toctree::
    :maxdepth: 2

docs/usage.rst

@@ -5,3 +5,47 @@ Usage
 To use TIA Toolbox in a project::
 
     import tiatoolbox
+
+
+----------
+Dataloader
+----------
+.. automodule:: tiatoolbox.dataloader
+
+^^^^^^^^^^^^^^^^^^^^
+dataloader.wsireader
+^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: tiatoolbox.dataloader.wsireader
+    :members: WSIReader
+    :special-members: __init__
+
+^^^^^^^^^^^^^^^^^^^^^
+dataloader.slide_info
+^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: tiatoolbox.dataloader.slide_info
+    :members: slide_info
+
+----------
+Decorators
+----------
+.. automodule:: tiatoolbox.decorators
+
+^^^^^^^^^^^^^^^^^^^^
+decorators.multiproc
+^^^^^^^^^^^^^^^^^^^^
+.. automodule:: tiatoolbox.decorators.multiproc
+    :members: TIAMultiProcess
+    :special-members: __init__, __call__
+
+------
+Utils
+------
+.. automodule:: tiatoolbox.utils
+
+^^^^^^^^^^
+utils.misc
+^^^^^^^^^^
+.. automodule:: tiatoolbox.utils.misc
+    :members: save_yaml, split_path_name_ext, grab_files_from_dir

tests/test_tiatoolbox.py

@@ -4,7 +4,7 @@
 import pytest
 
 from tiatoolbox.dataloader.slide_info import slide_info
-from tiatoolbox.utils import misc_utils as misc
+from tiatoolbox import utils
 from tiatoolbox import cli
 from tiatoolbox import __version__
 
@@ -62,13 +62,14 @@ def test_slide_info(response_ndpi, response_svs):
     """
     pytest for slide_info as a python function
     """
-    # from bs4 import BeautifulSoup
-    # assert 'GitHub' in BeautifulSoup(response.content).title.string
     file_types = ("*.ndpi", "*.svs", "*.mrxs")
-    files_all = misc.grab_files_from_dir(
+    files_all = utils.misc.grab_files_from_dir(
         input_path=str(pathlib.Path(r".")), file_types=file_types,
     )
-    _ = slide_info(input_path=files_all, workers=2, mode="save")
+    slide_params = slide_info(input_path=files_all, workers=2, mode="save")
+
+    for slide_param in slide_params:
+        utils.misc.save_yaml(slide_param, slide_param["file_name"] + ".yaml")
 
 
 def test_command_line_help_interface():

tiatoolbox/__init__.py

@@ -7,3 +7,6 @@
 __author__ = """TIA Lab"""
 __email__ = "[email protected]"
 __version__ = "0.1.1"
+
+if __name__ == "__main__":
+    pass

tiatoolbox/cli.py

@@ -1,7 +1,7 @@
 """Console script for tiatoolbox."""
 from tiatoolbox import __version__
 from tiatoolbox import dataloader
-from tiatoolbox.utils import misc_utils as misc
+from tiatoolbox import utils
 import sys
 import click
 import os
@@ -52,7 +52,7 @@ def slide_info(wsi_input, output_dir, file_types, mode, workers=None):
     """
     file_types = tuple(file_types.split(", "))
     if os.path.isdir(wsi_input):
-        files_all = misc.grab_files_from_dir(
+        files_all = utils.misc.grab_files_from_dir(
             input_path=wsi_input, file_types=file_types
         )
     elif os.path.isfile(wsi_input):

tiatoolbox/dataloader/__init__.py

@@ -1,2 +1,5 @@
-from tiatoolbox.dataloader import slide_info
-from tiatoolbox.dataloader import wsireader
+"""
+Package to read whole slide images
+"""
+
+from tiatoolbox.dataloader import slide_info, wsireader

tiatoolbox/dataloader/slide_info.py

@@ -1,5 +1,5 @@
 """
-This file contains code to output or save slide information using python multiprocessing
+Get Slide Meta Data information
 """
 from tiatoolbox.dataloader import wsireader
 from tiatoolbox.decorators.multiproc import TIAMultiProcess
@@ -8,43 +8,39 @@
 
 
 @TIAMultiProcess(iter_on="input_path")
-def slide_info(input_path, output_dir=None, mode="show"):
+def slide_info(input_path, output_dir=None):
     """
+    slide_info()
     Single file run to output or save WSI meta data. Multiprocessing uses this function to run slide_info in parallel
     Args:
         input_path: Path to whole slide image
         output_dir: Path to output directory to save the output
-        mode: "show" to display meta information only or "save" to save the meta information
-
     Returns:
         displays or saves WSI meta information
 
+    Examples:
+        >>> from tiatoolbox.dataloader.slide_info import slide_info
+        >>> from tiatoolbox import utils
+        >>> file_types = ("*.ndpi", "*.svs", "*.mrxs")
+        >>> files_all = utils.misc.grab_files_from_dir(input_path, file_types=file_types)
+        >>> slide_params = slide_info(input_path=files_all, workers=2)
+        >>> for slide_param in slide_params:
+        >>>        utils.misc.save_yaml(slide_param, slide_param["file_name"] + ".yaml")
+        >>>        print(type(slide_param))
+
     """
 
     input_dir, file_name = os.path.split(input_path)
 
-    if output_dir is None:
-        output_dir = os.path.join(input_dir, "..", "meta")
-
-    if mode is None:
-        mode = "show"
-
-    if not os.path.isdir(output_dir) and mode == "save":
-        os.makedirs(output_dir, exist_ok=True)
-
     print(file_name, flush=True)
     _, file_type = os.path.splitext(file_name)
 
     if file_type == ".svs" or file_type == ".ndpi" or file_type == ".mrxs":
         wsi_reader = wsireader.WSIReader(
             input_dir=input_dir, file_name=file_name, output_dir=output_dir
         )
-        if mode == "show":
-            info = wsi_reader.slide_info(save_mode=False)
-            print(info)
-            return info
-        else:
-            wsi_reader.slide_info(
-                output_dir=output_dir, output_name=file_name + ".yaml"
-            )
-            return os.path.join(output_dir, file_name + ".yaml")
+        info = wsi_reader.slide_info()
+        return info
+    else:
+        print("File type not supported")
+        return None

tiatoolbox/dataloader/wsireader.py

@@ -1,33 +1,50 @@
 """
 WSIReader for WSI reading or extracting metadata information from WSIs
+
 """
 import pathlib
 import numpy as np
-import yaml
 from PIL import Image
 
 import openslide
 
 
 class WSIReader:
+    """
+    WSI Reader class to read WSI images
+
+    Attributes:
+        input_dir (pathlib.Path): input path to WSI directory
+        file_name (str): file name of the WSI
+        output_dir (pathlib.Path): output directory to save the output
+        openslide_obj (:obj:`openslide.OpenSlide`)
+        tile_objective_value (int): objective value at which tile is generated
+        tile_read_size (int): [tile width, tile height]
+        objective_power (int): objective value at which whole slide image is scanned
+        level_count (int): The number of pyramid levels in the slide
+        level_dimensions = A list of `(width, height)` tuples, one for each level of the slide
+        level_downsamples = A list of down sample factors for each level of the slide
+
+    """
+
     def __init__(
         self,
-        input_dir=pathlib.Path.cwd(),
+        input_dir=".",
         file_name=None,
-        output_dir=pathlib.Path(pathlib.Path.cwd(), "output"),
+        output_dir="./output",
         tile_objective_value=20,
         tile_read_size_w=5000,
         tile_read_size_h=5000,
     ):
         """
-        WSI Reader class to read WSI images
         Args:
-            input_dir: input path to WSI directory
-            file_name: file name of the WSI
-            output_dir: output directory to save the output, default=os.getcwd()/output
-            tile_objective_value: objective value at which tile is generated, default=20
-            tile_read_size_w: tile width, default=5000
-            tile_read_size_h: tile height, default=5000
+            input_dir (str, pathlib.Path): input path to WSI directory
+            file_name (str): file name of the WSI
+            output_dir (str, pathlib.Path): output directory to save the output, default=os.getcwd()/output
+            tile_objective_value (int): objective value at which tile is generated, default=20
+            tile_read_size_w (int): tile width, default=5000
+            tile_read_size_h (int): tile height, default=5000
+
         """
 
         self.input_dir = pathlib.Path(input_dir)
@@ -50,23 +67,16 @@ def __init__(
     def __exit__(self):
         self.openslide_obj.close()
 
-    def slide_info(self, save_mode=True, output_dir=None, output_name=None):
+    def slide_info(self):
         """
         WSI meta data reader
         Args:
-            save_mode: save meta information as yaml file
-            output_dir: output directory to save the meta information
-            output_name: output file name
 
         Returns:
-            displays or saves WSI meta information
+            param (dict): dictionary containing meta information
 
         """
         input_dir = self.input_dir
-        if output_dir is None:
-            self.output_dir = output_dir
-        if output_name is None:
-            output_name = "param.yaml"
         if self.objective_power == 0:
             self.objective_power = np.int(
                 self.openslide_obj.properties[openslide.PROPERTY_NAME_OBJECTIVE_POWER]
@@ -80,10 +90,10 @@ def slide_info(self, save_mode=True, output_dir=None, output_name=None):
         level_count = self.level_count
         level_dimensions = self.level_dimensions
         level_downsamples = self.level_downsamples
+        file_name = self.file_name
 
         param = {
             "input_dir": input_dir,
-            "output_dir": output_dir,
             "objective_power": objective_power,
             "slide_dimension": slide_dimension,
             "rescale": rescale,
@@ -93,9 +103,7 @@ def slide_info(self, save_mode=True, output_dir=None, output_name=None):
             "level_count": level_count,
             "level_dimensions": level_dimensions,
             "level_downsamples": level_downsamples,
+            "file_name": file_name,
         }
-        if save_mode:
-            with open(pathlib.Path(output_dir, output_name), "w") as yaml_file:
-                yaml.dump(param, yaml_file)
-        else:
-            return param
+
+        return param

tiatoolbox/decorators/__init__.py

@@ -1,4 +1,4 @@
 """
-Decorators init file
+Package defines decorators for the toolbox
 """
 from tiatoolbox.decorators import multiproc