From 760644d135aec2ded766d825a0b06c320bb64718 Mon Sep 17 00:00:00 2001 From: Ruben Verweij Date: Thu, 16 Mar 2017 10:38:37 +0100 Subject: [PATCH] New documentation --- README.md | 4 +++ docs | 2 +- nd2reader/artificial.py | 22 ++++++++-------- nd2reader/legacy.py | 57 ++++++++++++++++++++++++++--------------- nd2reader/reader.py | 4 +-- sphinx/index.rst | 13 +++------- sphinx/nd2reader.rst | 16 ++++++++++++ 7 files changed, 73 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 553896a..ca8592e 100644 --- a/README.md +++ b/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 diff --git a/docs b/docs index 1972b01..6e17cad 160000 --- a/docs +++ b/docs @@ -1 +1 @@ -Subproject commit 1972b012f71a4c65b927ddfef5bf88d66ef521ef +Subproject commit 6e17cadb9d79143c4e41ababeb309d4e88f9038b diff --git a/nd2reader/artificial.py b/nd2reader/artificial.py index 4510ee0..ec45f4d 100644 --- a/nd2reader/artificial.py +++ b/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 = { diff --git a/nd2reader/legacy.py b/nd2reader/legacy.py index 8764ab0..244ee73 100644 --- a/nd2reader/legacy.py +++ b/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"] diff --git a/nd2reader/reader.py b/nd2reader/reader.py index d48d157..a898e28 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. + This is the main class: use this to process your .nd2 files. """ def __init__(self, filename): diff --git a/sphinx/index.rst b/sphinx/index.rst index cb70957..1220bdb 100644 --- a/sphinx/index.rst +++ b/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 `_ 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 - nd2reader API reference + nd2reader quick start tutorial + nd2reader API reference Indices and tables diff --git a/sphinx/nd2reader.rst b/sphinx/nd2reader.rst index d10be6a..668ad6e 100644 --- a/sphinx/nd2reader.rst +++ b/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: