From 60378ad06f9ae13bcb7c47153ae1a2f80f46a5a1 Mon Sep 17 00:00:00 2001
From: Ruben Verweij <verweij@physics.leidenuniv.nl>
Date: Wed, 8 Mar 2017 10:28:30 +0100
Subject: [PATCH] Cleanup docstrings to use google python docs

---
 docs                      |  2 +-
 nd2reader/common.py       | 57 ++++++++++++------------
 nd2reader/exceptions.py   |  6 ++-
 nd2reader/label_map.py    |  3 +-
 nd2reader/parser.py       | 94 +++++++++------------------------------
 nd2reader/raw_metadata.py | 68 +++++++++-------------------
 nd2reader/reader.py       | 48 ++++++++------------
 sphinx/conf.py            | 25 +----------
 8 files changed, 95 insertions(+), 208 deletions(-)

diff --git a/docs b/docs
index db1df91..3db501b 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit db1df91ec6d52b25ac2a2368fdef6b18277e8961
+Subproject commit 3db501b0c85343425c6e8269dcfce5b0ca28c845
diff --git a/nd2reader/common.py b/nd2reader/common.py
index bd4cfdc..d350d34 100644
--- a/nd2reader/common.py
+++ b/nd2reader/common.py
@@ -7,11 +7,13 @@ from nd2reader.exceptions import InvalidVersionError
 
 
 def get_version(fh):
-    """
-    Determines what version the ND2 is.
+    """Determines what version the ND2 is.
+
+    Args:
+        fh: File handle of the .nd2 file
 
-    :param fh:    an open file handle to the ND2
-    :type fh:     file
+    Returns:
+        tuple: Major and minor version
 
     """
     # the first 16 bytes seem to have no meaning, so we skip them
@@ -23,11 +25,13 @@ def get_version(fh):
 
 
 def parse_version(data):
-    """
-    Parses a string with the version data in it.
+    """Parses a string with the version data in it.
 
-    :param data:    the 19th through 54th byte of the ND2, representing the version
-    :type data:     unicode
+    Args:
+        data (unicode): the 19th through 54th byte of the ND2, representing the version
+
+    Returns:
+        tuple: Major and minor version
 
     """
     match = re.search(r"""^ND2 FILE SIGNATURE CHUNK NAME01!Ver(?P<major>\d)\.(?P<minor>\d)$""", data)
@@ -40,14 +44,14 @@ def parse_version(data):
 
 
 def read_chunk(fh, chunk_location):
-    """
-    Reads a piece of data given the location of its pointer.
+    """Reads a piece of data given the location of its pointer.
 
-    :param fh:    an open file handle to the ND2
-    :param chunk_location:    a pointer
-    :type chunk_location:    int
+    Args:
+        fh: an open file handle to the ND2
+        chunk_location (int): location to read
 
-    :rtype: bytes
+    Returns:
+        bytes: the data at the chunk location
 
     """
     if chunk_location is None:
@@ -106,10 +110,10 @@ def _parse_char_array(data):
 
 
 def parse_date(text_info):
-    """
-    The date and time when acquisition began.
+    """The date and time when acquisition began.
 
-    :rtype: datetime.datetime() or None
+    Returns:
+        datetime: The date and time when acquisition began.
 
     """
     for line in text_info.values():
@@ -127,8 +131,10 @@ def parse_date(text_info):
 
 
 def _parse_metadata_item(data, cursor_position):
-    """
-    Reads hierarchical data, analogous to a Python dict.
+    """Reads hierarchical data, analogous to a Python dict.
+
+    Returns:
+        dict: the metadata item
 
     """
     new_count, length = struct.unpack("<IQ", data.read(12))
@@ -141,8 +147,7 @@ def _parse_metadata_item(data, cursor_position):
 
 
 def _get_value(data, data_type, cursor_position):
-    """
-    ND2s use various codes to indicate different data types, which we translate here.
+    """ND2s use various codes to indicate different data types, which we translate here.
 
     """
     parser = {1: _parse_unsigned_char,
@@ -157,8 +162,7 @@ def _get_value(data, data_type, cursor_position):
 
 
 def read_metadata(data, count):
-    """
-    Iterates over each element some section of the metadata and parses it.
+    """Iterates over each element some section of the metadata and parses it.
 
     """
     if data is None:
@@ -188,12 +192,7 @@ def read_metadata(data, count):
 
 
 def _add_to_metadata(metadata, name, value):
-    """
-    Add the name value pair to the metadata dict
-    :param metadata:
-    :param name:
-    :param value:
-    :return:
+    """Add the name value pair to the metadata dict
     """
     if name not in metadata.keys():
         metadata[name] = value
diff --git a/nd2reader/exceptions.py b/nd2reader/exceptions.py
index f5b55b8..28ed71e 100644
--- a/nd2reader/exceptions.py
+++ b/nd2reader/exceptions.py
@@ -1,5 +1,6 @@
 class InvalidVersionError(Exception):
-    """
+    """Unknown version.
+
     We don't know how to parse the version of ND2 that we were given.
 
     """
@@ -7,7 +8,8 @@ class InvalidVersionError(Exception):
 
 
 class NoImageError(Exception):
-    """
+    """No image found.
+
     Some apparent images in ND2s are just completely blank placeholders. These are used when the number of images per
     cycle are unequal (e.g. if you take fluorescent images every 2 minutes, and bright field images every minute).
 
diff --git a/nd2reader/label_map.py b/nd2reader/label_map.py
index aff8f9f..05d972e 100644
--- a/nd2reader/label_map.py
+++ b/nd2reader/label_map.py
@@ -4,8 +4,7 @@ import re
 
 
 class LabelMap(object):
-    """
-    Contains pointers to metadata. This might only be valid for V3 files.
+    """Contains pointers to metadata. This might only be valid for V3 files.
 
     """
     def __init__(self, raw_binary_data):
diff --git a/nd2reader/parser.py b/nd2reader/parser.py
index 61e45fc..860f27b 100644
--- a/nd2reader/parser.py
+++ b/nd2reader/parser.py
@@ -13,7 +13,9 @@ from nd2reader.raw_metadata import RawMetadata
 
 
 class Parser(object):
-    """ Parses ND2 files and creates a Metadata and driver object. """
+    """Parses ND2 files and creates a Metadata and driver object.
+
+    """
     CHUNK_HEADER = 0xabeceda
     CHUNK_MAP_START = six.b("ND2 FILEMAP SIGNATURE NAME 0001!")
     CHUNK_MAP_END = six.b("ND2 CHUNK MAP SIGNATURE 0000001!")
@@ -21,10 +23,6 @@ class Parser(object):
     supported_file_versions = {(3, None): True}
 
     def __init__(self, fh):
-        """
-        :type fh:    file
-
-        """
         self._fh = fh
         self._label_map = None
         self._raw_metadata = None
@@ -37,10 +35,8 @@ class Parser(object):
         self._parse_metadata()
 
     def calculate_image_properties(self, index):
-        """
-        Calculate FOV, channels and z_levels
-        :param index:
-        :return:
+        """Calculate FOV, channels and z_levels
+
         """
         field_of_view = self._calculate_field_of_view(index)
         channel = self._calculate_channel(index)
@@ -56,9 +52,6 @@ class Parser(object):
         eliminate this possibility in future releases. For now, you'll need to check if your image is None if you're
         doing anything out of the ordinary.
 
-        :type index:    int
-        :rtype:    Image or None
-
         """
         field_of_view, channel, z_level = self.calculate_image_properties(index)
         channel_offset = index % len(self.metadata["channels"])
@@ -73,17 +66,8 @@ class Parser(object):
             return image
 
     def get_image_by_attributes(self, frame_number, field_of_view, channel_name, z_level, height, width):
-        """
-        Attempts to get Image based on attributes alone.
+        """Attempts to get Image based on attributes alone.
 
-        :type frame_number:    int
-        :type field_of_view:    int
-        :type channel_name:    str
-        :type z_level:    int
-        :type height:    int
-        :type width:    int
-
-        :rtype: Image or None
         """
         image_group_number = self._calculate_image_group_number(frame_number, field_of_view, z_level)
         try:
@@ -96,18 +80,17 @@ class Parser(object):
 
     @staticmethod
     def get_dtype_from_metadata():
-        """
-        Determine the data type from the metadata.
+        """Determine the data type from the metadata.
+
         For now, always use float64 to prevent unexpected overflow errors when manipulating the data (calculating sums/
         means/etc.)
-        :return:
+
         """
         return np.float64
 
     def _check_version_supported(self):
-        """
-        Checks if the ND2 file version is supported by this reader.
-        :return:
+        """Checks if the ND2 file version is supported by this reader.
+
         """
         major_version, minor_version = get_version(self._fh)
         supported = self.supported_file_versions.get((major_version, minor_version)) or \
@@ -119,8 +102,7 @@ class Parser(object):
         return supported
 
     def _parse_metadata(self):
-        """
-        Reads all metadata and instantiates the Metadata object.
+        """Reads all metadata and instantiates the Metadata object.
 
         """
         # Retrieve raw metadata from the label mapping
@@ -134,8 +116,6 @@ class Parser(object):
         as some of the bytes contain the value 33, which is the ASCII code for "!". So we iteratively find each label,
         grab the subsequent data (always 16 bytes long), advance to the next label and repeat.
 
-        :rtype: LabelMap
-
         """
         self._fh.seek(-8, 2)
         chunk_map_start_location = struct.unpack("Q", self._fh.read(8))[0]
@@ -144,33 +124,23 @@ class Parser(object):
         return LabelMap(raw_text)
 
     def _calculate_field_of_view(self, index):
-        """
-        Determines what field of view was being imaged for a given image.
-
-        :type index:    int
-        :rtype:    int
+        """Determines what field of view was being imaged for a given image.
 
         """
         images_per_cycle = len(self.metadata["z_levels"]) * len(self.metadata["channels"])
         return int((index - (index % images_per_cycle)) / images_per_cycle) % len(self.metadata["fields_of_view"])
 
     def _calculate_channel(self, index):
-        """
-        Determines what channel a particular image is.
-
-        :type index:    int
-        :rtype:    str
+        """Determines what channel a particular image is.
 
         """
         return self.metadata["channels"][index % len(self.metadata["channels"])]
 
     def _calculate_z_level(self, index):
-        """
-        Determines the plane in the z-axis a given image was taken in. In the future, this will be replaced with the
-        actual offset in micrometers.
+        """Determines the plane in the z-axis a given image was taken in.
+
+        In the future, this will be replaced with the actual offset in micrometers.
 
-        :type index:    int
-        :rtype:    int
         """
         return self.metadata["z_levels"][int(
             ((index - (index % len(self.metadata["channels"]))) / len(self.metadata["channels"])) % len(
@@ -180,12 +150,6 @@ class Parser(object):
         """
         Images are grouped together if they share the same time index, field of view, and z-level.
 
-        :type frame_number: int
-        :type fov: int
-        :type z_level: int
-
-        :rtype: int
-
         """
         return frame_number * len(self.metadata["fields_of_view"]) * len(self.metadata["z_levels"]) + (
             fov * len(self.metadata["z_levels"]) + z_level)
@@ -194,12 +158,6 @@ class Parser(object):
         """
         Images are in the same frame if they share the same group number and field of view and are taken sequentially.
 
-        :type image_group_number:    int
-        :type field_of_view:    int
-        :type z_level:    int
-
-        :rtype:    int
-
         """
         return (image_group_number - (field_of_view * len(self.metadata["z_levels"]) + z_level)) / (
             len(self.metadata["fields_of_view"]) * len(self.metadata["z_levels"]))
@@ -210,22 +168,11 @@ class Parser(object):
         Image data is interleaved for each image set. That is, if there are four images in a set, the first image
         will consist of pixels 1, 5, 9, etc, the second will be pixels 2, 6, 10, and so forth.
 
-        :rtype: dict
-
         """
         return {channel: n for n, channel in enumerate(self.metadata["channels"])}
 
     def _get_raw_image_data(self, image_group_number, channel_offset, height, width):
-        """
-        Reads the raw bytes and the timestamp of an image.
-
-        :param image_group_number: groups are made of images with the same time index, field of view and z-level
-        :type image_group_number: int
-        :param channel_offset: the offset in the array where the bytes for this image are found
-        :type channel_offset: int
-
-        :rtype:    (int, Image)
-        :raises:    NoImageError
+        """Reads the raw bytes and the timestamp of an image.
 
         """
         chunk = self._label_map.get_image_data_location(image_group_number)
@@ -254,8 +201,7 @@ class Parser(object):
         raise NoImageError
 
     def _get_frame_metadata(self):
-        """
-        Get the metadata for one frame
-        :return:
+        """Get the metadata for one frame
+
         """
         return self.metadata
diff --git a/nd2reader/raw_metadata.py b/nd2reader/raw_metadata.py
index e317c8a..7fa070c 100644
--- a/nd2reader/raw_metadata.py
+++ b/nd2reader/raw_metadata.py
@@ -24,16 +24,14 @@ class RawMetadata(object):
 
     @property
     def __dict__(self):
-        """
-        Returns the parsed metadata in dictionary form
-        :return: 
+        """Returns the parsed metadata in dictionary form
+
         """
         return self.get_parsed_metadata()
 
     def get_parsed_metadata(self):
-        """
-        Returns the parsed metadata in dictionary form
-        :return: 
+        """ Returns the parsed metadata in dictionary form
+
         """
 
         if self._metadata_parsed is not None:
@@ -63,8 +61,6 @@ class RawMetadata(object):
         These are labels created by the NIS Elements user. Typically they may a short description of the filter cube
         used (e.g. "bright field", "GFP", etc.)
 
-        :rtype: list
-
         """
         channels = []
         metadata = self.image_metadata_sequence[six.b('SLxPictureMetadata')][six.b('sPicturePlanes')]
@@ -90,25 +86,19 @@ class RawMetadata(object):
         in the image data, so we have to calculate it. There probably is something somewhere, since
         NIS Elements can figure it out, but we haven't found it yet.
 
-        :rtype:    list
-
         """
         return self._parse_dimension(r""".*?XY\((\d+)\).*?""")
 
     def _parse_frames(self):
-        """
-        The number of cycles.
-
-        :rtype:     list
+        """The number of cycles.
 
         """
         return self._parse_dimension(r""".*?T'?\((\d+)\).*?""")
 
     def _parse_z_levels(self):
-        """
-        The different levels in the Z-plane. Just a sequence from 0 to n.
+        """The different levels in the Z-plane.
 
-        :rtype:    list
+        Just a sequence from 0 to n.
 
         """
         return self._parse_dimension(r""".*?Z\((\d+)\).*?""")
@@ -119,8 +109,6 @@ class RawMetadata(object):
         Sometimes certain elements don't exist, or change their data type randomly. However, the human-readable text
         is always there and in the same exact format, so we just parse that instead.
 
-        :rtype:    str
-
         """
         dimension_text = six.b("")
         textinfo = self.image_text_info[six.b('SLxImageTextInfo')].values()
@@ -135,13 +123,6 @@ class RawMetadata(object):
         return dimension_text
 
     def _parse_dimension(self, pattern):
-        """
-        :param pattern:    a valid regex pattern
-        :type pattern:    str
-
-        :rtype:    list of int
-
-        """
         dimension_text = self._parse_dimension_text()
         if six.PY3:
             dimension_text = dimension_text.decode("utf8")
@@ -152,18 +133,16 @@ class RawMetadata(object):
         return list(range(count))
 
     def _parse_total_images_per_channel(self):
-        """
-        The total number of images per channel. Warning: this may be inaccurate as it includes "gap" images.
+        """The total number of images per channel.
 
-        :rtype: int
+        Warning: this may be inaccurate as it includes "gap" images.
 
         """
         return self.image_attributes[six.b('SLxImageAttributes')][six.b('uiSequenceCount')]
 
     def _parse_roi_metadata(self):
-        """
-        Parse the raw ROI metadata.
-        :return:
+        """Parse the raw ROI metadata.
+
         """
         if self.roi_metadata is None or not six.b('RoiMetadata_v1') in self.roi_metadata:
             return
@@ -180,11 +159,10 @@ class RawMetadata(object):
         self._metadata_parsed['rois'] = roi_objects
 
     def _parse_roi(self, raw_roi_dict):
-        """
-        Extract the vector animation parameters from the ROI.
+        """Extract the vector animation parameters from the ROI.
+
         This includes the position and size at the given timepoints.
-        :param raw_roi_dict:
-        :return:
+
         """
         number_of_timepoints = raw_roi_dict[six.b('m_vectAnimParams_Size')]
 
@@ -226,10 +204,9 @@ class RawMetadata(object):
         return None
 
     def _parse_vect_anim(self, roi_dict, animation_dict):
-        """
-        Parses a ROI vector animation object and adds it to the global list of timepoints and positions.
-        :param animation_dict:
-        :return:
+        """Parses a ROI vector animation object and adds it to the global list of timepoints and positions.
+
+
         """
         roi_dict["timepoints"].append(animation_dict[six.b('m_dTimeMs')])
 
@@ -251,9 +228,8 @@ class RawMetadata(object):
         return roi_dict
 
     def _parse_experiment_metadata(self):
-        """
-        Parse the metadata of the ND experiment
-        :return:
+        """Parse the metadata of the ND experiment
+
         """
         if not six.b('SLxExperiment') in self.image_metadata:
             return
@@ -274,10 +250,8 @@ class RawMetadata(object):
         self._metadata_parsed['experiment'] = experimental_data
 
     def _parse_loop_data(self, loop_data):
-        """
-        Parse the experimental loop data
-        :param loop_data:
-        :return:
+        """Parse the experimental loop data
+
         """
         loops = [loop_data]
         if six.b('uiPeriodCount') in loop_data and loop_data[six.b('uiPeriodCount')] > 0:
diff --git a/nd2reader/reader.py b/nd2reader/reader.py
index 0952054..943fb3b 100644
--- a/nd2reader/reader.py
+++ b/nd2reader/reader.py
@@ -4,8 +4,8 @@ import numpy as np
 
 
 class ND2Reader(FramesSequenceND):
-    """
-    PIMS wrapper for the ND2 parser
+    """PIMS wrapper for the ND2 parser
+
     """
 
     def __init__(self, filename):
@@ -26,25 +26,21 @@ class ND2Reader(FramesSequenceND):
 
     @classmethod
     def class_exts(cls):
-        """
-        So PIMS open function can use this reader for opening .nd2 files
-        :return:
+        """Let PIMS open function use this reader for opening .nd2 files
+
         """
         return {'nd2'} | super(ND2Reader, cls).class_exts()
 
     def close(self):
-        """
-        Correctly close the file handle
-        :return:
+        """Correctly close the file handle
+
         """
         if self._fh is not None:
             self._fh.close()
 
     def get_frame(self, i):
-        """
-        Return one frame
-        :param i:
-        :return:
+        """Return one frame
+
         """
         fetch_all_channels = 'c' in self.bundle_axes
 
@@ -54,9 +50,8 @@ class ND2Reader(FramesSequenceND):
             return self.get_frame_2D(self.default_coords['c'], i, self.default_coords['z'])
 
     def _get_frame_all_channels(self, i):
-        """
-        Get all color channels for this frame
-        :return:
+        """Get all color channels for this frame
+
         """
         frames = None
         for c in range(len(self.metadata["channels"])):
@@ -68,28 +63,22 @@ class ND2Reader(FramesSequenceND):
         return frames
 
     def get_frame_2D(self, c, t, z):
-        """
-        Gets a given frame using the parser
-        :param c:
-        :param t:
-        :param z:
-        :return:
+        """Gets a given frame using the parser
+
         """
         c_name = self.metadata["channels"][c]
         return self._parser.get_image_by_attributes(t, 0, c_name, z, self.metadata["height"], self.metadata["width"])
 
     @property
     def pixel_type(self):
-        """
-        Return the pixel data type
-        :return:
+        """Return the pixel data type
+
         """
         return self._dtype
 
     def _setup_axes(self):
-        """
-        Setup the xyctz axes, iterate over t axis by default
-        :return:
+        """Setup the xyctz axes, iterate over t axis by default
+
         """
         self._init_axis('x', self.metadata["width"])
         self._init_axis('y', self.metadata["height"])
@@ -101,9 +90,8 @@ class ND2Reader(FramesSequenceND):
         self.iter_axes = 't'
 
     def get_timesteps(self):
-        """
-        Get the timesteps of the experiment
-        :return:
+        """Get the timesteps of the experiment
+
         """
         timesteps = np.array([])
         current_time = 0.0
diff --git a/sphinx/conf.py b/sphinx/conf.py
index 87896ff..94c5592 100644
--- a/sphinx/conf.py
+++ b/sphinx/conf.py
@@ -3,28 +3,6 @@
 
 from recommonmark.parser import CommonMarkParser
 
-#
-# nd2reader documentation build configuration file, created by
-# sphinx-quickstart on Mon Mar  6 21:17:58 2017.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, '/home/ruben/PycharmProjects/nd2reader/nd2reader')
-
-
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -36,7 +14,8 @@ from recommonmark.parser import CommonMarkParser
 # ones.
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.todo',
-              'sphinx.ext.viewcode']
+              'sphinx.ext.viewcode',
+              'sphinx.ext.napoleon']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []