Added documentation.

Author: ljosa

.gitignore

@@ -2,3 +2,4 @@
 /build
 /docs/_build
 /python_bioformats.egg-info
+/dist

bioformats/__init__.py

@@ -42,18 +42,43 @@
 ChannelSeparator = _formatreader.make_reader_wrapper_class(
     "loci/formats/ChannelSeparator")
 
+
 from .metadatatools import createOMEXMLMetadata as create_ome_xml_metadata
 from .metadatatools import wrap_imetadata_object
 import metadatatools as _metadatatools
 PixelType = _metadatatools.make_pixel_type_class()
 get_metadata_options = _metadatatools.get_metadata_options
 
+# Reading images
+
+ImageReader = _formatreader.ImageReader
 load_image = _formatreader.load_using_bioformats
 load_image_url = _formatreader.load_using_bioformats_url
+
+# Cached image readers
+
 get_image_reader = _formatreader.get_image_reader
 release_image_reader = _formatreader.release_image_reader
+clear_image_reader_cache = _formatreader.clear_image_reader_cache
+
+# Metadata
+
+from .omexml import OMEXML
 get_omexml_metadata = _formatreader.get_omexml_metadata
 
+# Writing images
+
+write_image = _formatwriter.write_image
+
+from .omexml import PT_UINT16, PT_UINT8, PT_BIT
+
+# Omero
+
+from .formatreader import use_omero_credentials, set_omero_credentials, get_omero_credentials
+from .formatreader import set_omero_login_hook, omero_logout
+from .formatreader import K_OMERO_SERVER, K_OMERO_PORT, K_OMERO_USER, K_OMERO_SESSION_ID,\
+         K_OMERO_PASSWORD, K_OMERO_CONFIG_FILE
+
 from . import omexml
 
 def init_logger():

bioformats/formatreader.py

@@ -357,16 +357,17 @@ def __init__(self, rdr):
 def set_omero_credentials(omero_server, omero_port, omero_username, omero_password):
     '''Set the credentials to be used to connect to the Omero server
     
-    omero_server - DNS name of the server
+    :param omero_server: DNS name of the server
 
-    omero_port - use this port to connect to the server
+    :param omero_port: use this port to connect to the server
 
-    omero_username - log on as this user
+    :param omero_username: log on as this user
 
-    omero_password - log on using this password
+    :param omero_password: log on using this password
     
-    The session ID is valid after this is called. An exception is thrown
-    if the login fails. omero_logout() can be called to log out.
+    The session ID is valid after this function is called. An exception is thrown
+    if the login fails. :func:`bioformats.omero_logout()` can be called to log out.
+
     '''
     global __omero_server
     global __omero_username
@@ -388,9 +389,10 @@ def set_omero_credentials(omero_server, omero_port, omero_username, omero_passwo
     return __omero_session_id
 
 def get_omero_credentials():
-    '''Return a pickleable dictionary representing the Omero credentials
+    '''Return a pickleable dictionary representing the Omero credentials.
     
-    Call use_omero_credentials in some other process to use this.
+    Call :func:`bioformats.use_omero_credentials` in some other process to use this.
+
     '''
     if __omero_session_id is None:
         omero_login()
@@ -427,14 +429,17 @@ def omero_login():
     return __omero_session_id
 
 def omero_logout():
-    '''Abandon any current Omero session'''
+    '''Abandon any current Omero session.
+
+    '''
     global __omero_session_id
     __omero_session_id = None
 
 def use_omero_credentials(credentials):
-    '''Use the session ID from an extant login as credentials
+    '''Use the session ID from an existing login as credentials.
     
-    credentials - credentials from get_omero_credentials
+    :param credentials: credentials from get_omero_credentials.
+
     '''
     global __omero_server
     global __omero_username
@@ -451,12 +456,16 @@ def use_omero_credentials(credentials):
 
 __omero_login_fn = None
 def set_omero_login_hook(fn):
-    '''Set the function to be called when a login to Omero is needed'''
+    '''Set the function to be called when a login to Omero is needed.
+
+    '''
     global __omero_login_fn
     __omero_login_fn = fn
 
 def get_omero_reader():
-    '''Return an loci.ome.io.OMEROReader instance, wrapped as a FormatReader'''
+    '''Return an ``loci.ome.io.OMEROReader`` instance, wrapped as a FormatReader.
+
+    '''
     script = """
     var rdr = new Packages.loci.ome.io.OmeroReader();
     rdr.setServer(server);
@@ -492,18 +501,19 @@ def load_using_bioformats_url(url, c=None, z=0, t=0, series=None, index=None,
 
 
 class ImageReader(object):
-    '''Find the appropriate reader for a file
+    '''Find the appropriate reader for a file.
     
     This class is meant to be harnessed to a scope like this:
     
-    with GetImageReader(path) as rdr:
-        ....
+    >>> with GetImageReader(path) as reader:
+    >>>     ....
         
-    It uses __enter__ and __exit__ to manage the random access stream
+    It uses `__enter__` and `__exit__` to manage the random access stream
     that can be used to cache the file contents in memory.
+
     '''
-    
-    def __init__(self, path = None, url= None, perform_init=True):
+
+    def __init__(self, path=None, url=None, perform_init=True):
         self.stream = None
         file_scheme = "file:"
         self.url = url
@@ -689,17 +699,17 @@ def read(self, c = None, z = 0, t = 0, series = None, index = None,
              rescale = True, wants_max_intensity = False, channel_names = None):
         '''Read a single plane from the image reader file.
         
-        c - read from this channel. None = read color image if multichannel
-            or interleaved RGB
-        z - z-stack index
-        t - time index
-        series - series for .flex and similar multi-stack formats
-        index - if None, fall back to zct, otherwise load the indexed frame
-        rescale - True to rescale the intensity scale to 0 and 1, False to
-                  return the raw values native to the file
-        wants_max_intensity - if False,  only return the image, if True
+        :param c: read from this channel. `None` = read color image if multichannel
+            or interleaved RGB.
+        :param z: z-stack index
+        :param t: time index
+        :param series: series for ``.flex`` and similar multi-stack formats
+        :param index: if `None`, fall back to ``zct``, otherwise load the indexed frame
+        :param rescale: `True` to rescale the intensity scale to 0 and 1; `False` to
+                  return the raw values native to the file.
+        :param wants_max_intensity: if `False`, only return the image; if `True`,
                   return a tuple of image and max intensity
-        channel_names - provide the channel names for the OME metadata
+        :param channel_names: provide the channel names for the OME metadata
         '''
         FormatTools = make_format_tools_class()
         ChannelSeparator = make_reader_wrapper_class(
@@ -888,14 +898,15 @@ def load_using_bioformats(path, c=None, z=0, t=0, series=None, index=None,
                           rescale = True,
                           wants_max_intensity = False,
                           channel_names = None):
-    '''Load the given image file using the Bioformats library
+    '''Load the given image file using the Bioformats library.
     
-    path: path to the file
-    z: the frame index in the z (depth) dimension.
-    t: the frame index in the time dimension.
-    channel_names: None if you don't want them, a list which will be filled if you do
+    :param path: path to the file
+    :param z: the frame index in the `z` (depth) dimension.
+    :param t: the frame index in the time dimension.
+    :param channel_names: `None` if you don't want them, a list which will be filled if you do.
     
-    Returns either a 2-d (grayscale) or 3-d (2-d + 3 RGB planes) image
+    :returns: either a 2-d (grayscale) or 3-d (2-d + 3 RGB planes) image.
+
     '''
 
     with ImageReader(path=path) as rdr:
@@ -905,13 +916,13 @@ def load_using_bioformats(path, c=None, z=0, t=0, series=None, index=None,
 def get_omexml_metadata(path=None, url=None):
     '''Read the OME metadata from a file using Bio-formats
     
-    path - path to the file
+    :param path: path to the file
     
-    allowopenfiles - allow the image reader to open files while looking for
-                     the proper reader class.
-                     
-    groupfiles - utilize the groupfiles option to take the directory structure
+    :param groupfiles: utilize the groupfiles option to take the directory structure
                  into account.
+
+    :returns: the metdata as XML.
+
     '''
     with ImageReader(path=path, url=url, perform_init=False) as rdr:
         #

bioformats/formatwriter.py

@@ -49,28 +49,29 @@ def write_image(pathname, pixels, pixel_type,
                 c = 0, z = 0, t = 0,
                 size_c = 1, size_z = 1, size_t = 1,
                 channel_names = None):
-    """Write the image using bioformats
+    """Write the image using bioformats.
     
-        filename - save to this filename
+    :param filename: save to this filename
         
-        pixels - the image to save
+    :param pixels: the image to save
         
-        pixel_type - save using this pixel type
+    :param pixel_type: save using this pixel type
         
-        c - the image's channel index
+    :param c: the image's channel index
         
-        z - the image's z index
+    :param z: the image's `z` index
         
-        t - the image's t index
+    :param t: the image's `t` index
         
-        sizeC - # of channels in the stack
+    :param sizeC: # of channels in the stack
         
-        sizeZ - # of z stacks
+    :param sizeZ: # of z stacks
         
-        sizeT - # of timepoints in the stack
+    :param sizeT: # of timepoints in the stack
         
-        channel_names - names of the channels (make up names if not present
-        """
+    :param channel_names: names of the channels (make up names if not present).
+
+    """
     omexml = ome.OMEXML()
     omexml.image(0).Name = os.path.split(pathname)[1]
     p = omexml.image(0).Pixels

bioformats/omexml.py

@@ -253,9 +253,9 @@ def make_text_node(parent, namespace, tag_name, text):
     set_text(node, text)
 
 class OMEXML(object):
-    '''The OMEXML class reads and writes OME-XML with methods to get and set it
+    '''Reads and writes OME-XML with methods to get and set it.
     
-    The OMEXML class has four main purposes - to parse OME-XML, to output
+    The OMEXML class has four main purposes: to parse OME-XML, to output
     OME-XML, to provide a structured mechanism for inspecting OME-XML and to
     let the caller create and modify OME-XML.
     
@@ -271,36 +271,33 @@ class OMEXML(object):
     where it's supported is to use properties on OMEXML and on some of its
     derived objects. For instance:
     
-    o = OMEXML()
-    print o.image().AcquiredDate
+    >>> o = OMEXML()
+    >>> print o.image().AcquiredDate
     
     will get you the date that image # 0 was acquired.
     
-    o = OMEXML()
+    >>> o = OMEXML()
+    >>> o.image().Name = "MyImage"
     
-    o.image().Name = "MyImage"
-    
-    will set the image name to "MyImage"
+    will set the image name to "MyImage".
     
     You can add and remove objects using the "count" properties. Each of these
     handles hooking up and removing orphaned elements for you and should be
     less error prone than creating orphaned elements and attaching them. For
     instance, to create a three-color image:
     
-    o = OMEXML()
-    
-    o.image().Pixels.channel_count = 3
-    
-    o.image().Pixels.Channel(0).Name = "Red"
-    
-    o.image().Pixels.Channel(1).Name = "Green"
-    
-    o.image().Pixels.Channel(2).Name = "Blue"
+    >>> o = OMEXML()
+    >>> o.image().Pixels.channel_count = 3
+    >>> o.image().Pixels.Channel(0).Name = "Red"
+    >>> o.image().Pixels.Channel(1).Name = "Green"
+    >>> o.image().Pixels.Channel(2).Name = "Blue"
     
-    You can view the OME-XML schema documentation online at:
-    http://git.openmicroscopy.org/src/develop/components/specification/Documentation/Generated/OME-2011-06/ome.html
+    See the `OME-XML schema documentation <http://git.openmicroscopy.org/src/develop/components/specification/Documentation/Generated/OME-2011-06/ome.html>`_.
+
     '''
-    def __init__(self, xml=default_xml):
+    def __init__(self, xml=None):
+        if xml is None:
+            xml = default_xml
         if isinstance(xml, unicode):
             xml = xml.encode("utf-8")
         self.dom = ElementTree.ElementTree(ElementTree.fromstring(xml))
@@ -416,7 +413,16 @@ def set_AcquiredDate(self, date):
 
         @property
         def Pixels(self):
-            '''The OME/Image/Pixels element'''
+            '''The OME/Image/Pixels element.
+
+            Example:
+            >>> md = bioformats.omexml.OMEXML(xml)
+            >>> pixels = omemetadata.image(i).Pixels
+            >>> channel_count = pixels.SizeC
+            >>> stack_count = pixels.SizeZ
+            >>> timepoint_count = pixels.SizeT
+
+            '''
             return OMEXML.Pixels(self.node.find(qnome("Pixels")))
 
     def image(self, index=0):
@@ -1208,4 +1214,4 @@ def set_ImageRef(self, value):
                 ref = ElementTree.SubElement(self.node, qn(NS_SPW, "ImageRef"))
             ref.set("ID", value)
         ImageRef = property(get_ImageRef, set_ImageRef)
-        
+