New documentation

README.md

@@ -38,6 +38,10 @@ with ND2Reader('my_directory/example.nd2') as images:
 
 After opening the file, all `pims` features are supported. Please refer to the [pims documentation](http://soft-matter.github.io/pims/).
 
+#### Backwards compatibility
+
+Older versions of `nd2reader` do not use the `pims` framework. To provide backwards compatibility, a legacy [Nd2](http://www.lighthacking.nl/nd2reader/docs/nd2reader.html#module-nd2reader.legacy) class is provided.
+
 ### Contributing
 
 If you'd like to help with the development of nd2reader or just have an idea for improvement, please see the [contributing](https://github.com/rbnvrw/nd2reader/blob/master/CONTRIBUTING.md) page

docs

@@ -1 +1 @@
-Subproject commit 1972b012f71a4c65b927ddfef5bf88d66ef521ef
+Subproject commit 6e17cadb9d79143c4e41ababeb309d4e88f9038b

nd2reader/artificial.py

@@ -1,5 +1,4 @@
-"""
-Functions to create artificial nd2 data for testing purposes
+"""Functions to create artificial nd2 data for testing purposes
 """
 import six
 import numpy as np
@@ -7,8 +6,7 @@ import struct
 
 
 class ArtificialND2(object):
-    """
-    Artificial ND2 class (for testing purposes)
+    """Artificial ND2 class (for testing purposes)
     """
 
     def __init__(self, file):
@@ -23,23 +21,22 @@ class ArtificialND2(object):
 
     @property
     def file_handle(self):
-        """
-        The file handle to the binary file
+        """The file handle to the binary file
+
         Returns:
             file: the file handle
+
         """
         return self._fh
 
     def close(self):
-        """
-        Correctly close the file handle
+        """Correctly close the file handle
         """
         if self._fh is not None:
             self._fh.close()
 
     def write_version(self):
-        """
-        Write file header
+        """Write file header
         """
         # write 16 empty bytes
         self._fh.write(bytearray(16))
@@ -50,10 +47,11 @@ class ArtificialND2(object):
 
     @staticmethod
     def create_label_map_bytes():
-        """
-        Construct a binary label map
+        """Construct a binary label map
+
         Returns:
             tuple: (binary data, dictionary data)
+
         """
         raw_text = six.b('')
         labels = {

nd2reader/legacy.py

@@ -8,7 +8,9 @@ from nd2reader import ND2Reader
 
 
 class Nd2(object):
-    """ Legacy Nd2 object for backwards compatibility. """
+    """ Warning: this module is deprecated and only maintained for backwards compatibility with the non-PIMS version of
+    nd2reader.
+    """
 
     def __init__(self, filename):
         warnings.warn(
@@ -41,8 +43,8 @@ class Nd2(object):
         return self.reader[item]
 
     def select(self, fields_of_view=None, channels=None, z_levels=None, start=0, stop=None):
-        """
-        Select images based on criteria.
+        """Select images based on criteria.
+
         Args:
             fields_of_view: the fields of view
             channels: the color channels
@@ -52,6 +54,7 @@ class Nd2(object):
 
         Returns:
             ND2Reader: Sliced ND2Reader which contains the frames
+
         """
         if stop is None:
             stop = len(self.frames)
@@ -59,13 +62,17 @@ class Nd2(object):
         return self.reader[start:stop]
 
     def get_image(self, frame_number, field_of_view, channel_name, z_level):
-        """
-        Deprecated. Returns the specified image from the ND2Reader class.
+        """Deprecated. Returns the specified image from the ND2Reader class.
+
         Args:
             frame_number: the frame number
             field_of_view: the field of view number
             channel_name: the name of the color channel
             z_level: the z level number
+
+        Returns:
+            Frame: the specified image
+
         """
         return self.reader.parser.get_image_by_attributes(frame_number, field_of_view, channel_name, z_level,
                                                           self.height, self.width)
@@ -78,72 +85,80 @@ class Nd2(object):
 
     @property
     def height(self):
-        """
-        Deprecated. Fetches the height of the image.
+        """Deprecated. Fetches the height of the image.
+
         Returns:
             int: the pixel height of the image
+
         """
         return self.reader.metadata["height"]
 
     @property
     def width(self):
-        """
-        Deprecated. Fetches the width of the image.
+        """Deprecated. Fetches the width of the image.
+
         Returns:
             int: the pixel width of the image
+
         """
         return self.reader.metadata["width"]
 
     @property
     def z_levels(self):
-        """
-        Deprecated. Fetches the available z levels.
+        """Deprecated. Fetches the available z levels.
+
         Returns:
             list: z levels.
+
         """
         return self.reader.metadata["z_levels"]
 
     @property
     def fields_of_view(self):
-        """
-        Deprecated. Fetches the fields of view.
+        """Deprecated. Fetches the fields of view.
+
         Returns:
             list: fields of view.
+
         """
         return self.reader.metadata["fields_of_view"]
 
     @property
     def channels(self):
-        """
-        Deprecated. Fetches all color channels.
+        """Deprecated. Fetches all color channels.
+
         Returns:
             list: the color channels.
+
         """
         return self.reader.metadata["channels"]
 
     @property
     def frames(self):
-        """
-        Deprecated. Fetches all frames.
+        """Deprecated. Fetches all frames.
+
         Returns:
             list: list of frames
+
         """
         return self.reader.metadata["frames"]
 
     @property
     def date(self):
-        """
-        Deprecated. Fetches the acquisition date.
+        """Deprecated. Fetches the acquisition date.
+
         Returns:
             string: the date
+
         """
         return self.reader.metadata["date"]
 
     @property
     def pixel_microns(self):
-        """
-        Deprecated. Fetches the amount of microns per pixel.
+        """Deprecated. Fetches the amount of microns per pixel.
+
         Returns:
             float: microns per pixel
+
         """
         return self.reader.metadata["pixel_microns"]

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.
+    This is the main class: use this to process your .nd2 files.
     """
 
     def __init__(self, filename):

sphinx/index.rst

@@ -1,8 +1,3 @@
-.. nd2reader documentation master file, created by
-   sphinx-quickstart on Mon Mar  6 21:17:58 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 ``nd2reader``: a pure-Python package for reading Nikon .nd2 files
 =================================================================
 
@@ -10,11 +5,11 @@
 The reader is written in the `pims <https://github.com/soft-matter/pims>`_ framework, enabling easy access to multidimensional files, lazy slicing, and nice display in IPython. To get started, see the quick start tutorial.
 
 .. toctree::
-   :maxdepth: 4
-   :caption: Contents:
+    :maxdepth: 4
+    :caption: Contents:
 
-   nd2reader quick start tutorial <tutorial>
-   nd2reader API reference <nd2reader>
+        nd2reader quick start tutorial <tutorial>
+        nd2reader API reference <nd2reader>
 
 
 Indices and tables

sphinx/nd2reader.rst

@@ -54,3 +54,19 @@ nd2reader.exceptions module
     :members:
     :undoc-members:
     :show-inheritance:
+
+nd2reader.exceptions artificial
+-------------------------------
+
+.. automodule:: nd2reader.artificial
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+nd2reader.legacy module
+-----------------------
+
+.. automodule:: nd2reader.legacy
+    :members:
+    :undoc-members:
+    :show-inheritance: