Merged documentation with docstrings

doc/library/tensor/nnet/neighbours.txt

@@ -12,99 +12,8 @@
 
 - Functions
 
-    - Function :func:`images2neibs <theano.sandbox.neighbours.images2neibs>`
-      allows to apply a sliding window operation to a tensor containing images 
-      or other two-dimensional objects. The sliding window operation loops 
-      over points in input data and stores a rectangular neighbourhood of each 
-      point. The input `ten4` is a 4-dimensional array which represents a list 
-      of lists of images. The first two dimensions can be 
-      useful to store different channels and batches.
+    .. autofunction:: theano.tensor.nnet.neighbours.images2neibs
 
-      The second input of the function `neib_shape` is a tuple containing two 
-      values: height and width of the neighbourhood.
-
-      It is possible to assign a step of selecting patches (parameter 
-      `neib_step`). The parameter should be a tuple of two elements: number of
-      rows and number of columns to skip each iteration. Basically, when the 
-      step is 1, the neighbourhood of every first element is taken and every 
-      possible rectangular subset is returned. By default it is equal to 
-      `neib_shape` in other words, the 
-      patches are disjoint. When the step is greater than `neib_shape`, some
-      elements are omitted. 
-
-      .. note:: Currently the step size should be chosen in the way that the 
-         corresponding dimension :math:`i` (width or height) is equal to 
-         :math:`n * step\_size_i + neib\_shape_i` for some :math:`n`
-
-      The output can be defined using the following pseudo-code
-
-      .. code-block:: python
-
-         idx = 0
-         for i in xrange(list 1 dim):
-             for j in xrange(list 2 dim):
-                 for k in <image column coordinates>:
-                     for l in <image row coordinates>:
-                         output[idx,:]
-                              = flattened version of ten4[i,j,l:l+r,k:k+c]
-                         idx += 1
-
-      .. note:: The operation isn't necessarily implemented internally with 
-         these for loops, they're just the easiest way to describe the output
-         pattern.
-
-
-      Example:
-
-      .. code-block:: python
-
-          # Defining variables
-          images = T.tensor4('images')
-          neibs = images2neibs(images, neib_shape=(5, 5))
-
-          # Constructing theano function 
-          window_function = theano.function([images], neibs)
-
-          # Input tensor (one image 10x10)
-          im_val = np.arange(100.).reshape((1, 1, 10, 10))
-
-          # Function application
-          neibs_val = window_function(im_val)
-
-      .. note:: The underlying code will construct a 2D tensor of disjoint 
-         patches 5x5. The output has shape 4x25. 
-
-
-    - Function :func:`neibs2images <theano.sandbox.neighbours.neibs2images>`
-      performs the inverse operation of 
-      :func:`images2neibs <theano.sandbox.neigbours.neibs2images>`. It inputs
-      the output of :func:`images2neibs <theano.sandbox.neigbours.neibs2images>`,
-      `neib_shape` -- `neib_shape` that was used in 
-      :func:`images2neibs <theano.sandbox.neigbours.neibs2images>`, 
-      `original_shape` -- original shape of 4d tensor given to 
-      :func:`images2neibs <theano.sandbox.neigbours.neibs2images>`
-     
-       and reconstructs its input.
-
-        .. note:: Currently, the function doesn't support tensors created with
-           `neib_step` different from default value. This means that it may be
-           impossible to compute the gradient of a variable gained by 
-           :func:`images2neibs <theano.sandbox.neigbours.neibs2images>` w.r.t. 
-           its inputs in this case because it uses 
-           :func:`images2neibs <theano.sandbox.neigbours.neibs2images>` for 
-           gradient computation.
-
-
-        Example:
-
-        .. code-block:: python
-
-            im_new = neibs2images(neibs, (5, 5), im_val.shape)
-            # Theano function definition
-            inv_window = theano.function([neibs], im_new)
-            # Function application
-            im_new_val = inv_window(neibs_val)
-
-        .. note:: The code will output the initial image array.
+    .. autofunction:: theano.tensor.nnet.neighbours.neibs2images
 
 - See also: :ref:`indexing`, :ref:`lib_scan`

theano/tensor/nnet/neighbours.py

@@ -402,58 +402,101 @@ class Images2Neibs(Op):
 
 
 def images2neibs(ten4, neib_shape, neib_step=None, mode='valid'):
-    """
-        :param ten4:     a list of lists of images
-                         ten4 is of shape (list 1 dim, list 2 dim,
-                         row, col)
-        :type ten4:      A 4d tensor-like.
-        :param neib_shape: (r,c) where r is the height of the neighborhood
-                        in rows and c is the width of the neighborhood
-                        in columns
-        :type neib_shape: A 1d tensor-like of 2 values.
-        :param neib_step: (dr,dc) where dr is the number of rows to
-                          skip between patch and dc is the number of
-                          columns. When None, this is the same as
-                          neib_shape(patch are disjoint)
-        :type neib_step: A 1d tensor-like of 2 values.
-        :param mode:
-            Possible values:
-
-            ``valid``
-               Requires an input that is a multiple of the
-               pooling factor (in each direction)
-
-            ``ignore_borders``
-               Same as valid, but will ignore the borders
-               if the shape(s) of the input
-               is not a multiple of the pooling factor(s)
-
-            ``wrap_centered``
-               ?? TODO comment
-
-        :type mode: str
-        :return:
-            Reshapes the input as a 2D tensor where each row is an
-            pooling example. Pseudo-code of the output:
-
-              .. code-block:: python
-
-                 idx = 0
-                 for i in xrange(list 1 dim):
-                     for j in xrange(list 2 dim):
-                         for k in <image column coordinates>:
-                             for l in <image row coordinates>:
-                                 output[idx,:]
-                                      = flattened version of ten4[i,j,l:l+r,k:k+c]
-                                 idx += 1
-
-              .. note:: The operation isn't necessarily implemented internally with 
-                 these for loops, they're just the easiest way to describe the output
-                 pattern.
-                 
-        .. note:: Currently the step size should be chosen in the way that the 
-           corresponding dimension :math:`i` (width or height) is equal to 
-           :math:`n * step\_size_i + neib\_shape_i` for some :math:`n`
+    """ 
+    :param ten4:     a list of lists of images
+                     ten4 is of shape (list 1 dim, list 2 dim,
+                     row, col)
+    :type ten4:      A 4d tensor-like.
+    :param neib_shape: (r,c) where r is the height of the neighborhood
+                    in rows and c is the width of the neighborhood
+                    in columns
+    :type neib_shape: A 1d tensor-like of 2 values.
+    :param neib_step: (dr,dc) where dr is the number of rows to
+                      skip between patch and dc is the number of
+                      columns. When None, this is the same as
+                      neib_shape(patch are disjoint)
+    :type neib_step: A 1d tensor-like of 2 values.
+    :param mode:
+        Possible values:
+
+        ``valid``
+           Requires an input that is a multiple of the
+           pooling factor (in each direction)
+
+        ``ignore_borders``
+           Same as valid, but will ignore the borders
+           if the shape(s) of the input
+           is not a multiple of the pooling factor(s)
+
+        ``wrap_centered``
+           ?? TODO comment
+
+    :type mode: str
+    :return:
+        Reshapes the input as a 2D tensor where each row is an
+        pooling example. Pseudo-code of the output:
+
+          .. code-block:: python
+
+             idx = 0
+             for i in xrange(list 1 dim):
+                 for j in xrange(list 2 dim):
+                     for k in <image column coordinates>:
+                         for l in <image row coordinates>:
+                             output[idx,:]
+                                  = flattened version of ten4[i,j,l:l+r,k:k+c]
+                             idx += 1
+
+          .. note:: The operation isn't necessarily implemented internally with 
+             these for loops, they're just the easiest way to describe the 
+             output pattern.
+
+    Function :func:`images2neibs <theano.sandbox.neighbours.images2neibs>`
+    allows to apply a sliding window operation to a tensor containing 
+    images
+    or other two-dimensional objects. 
+    
+    The sliding window operation loops 
+    over points in input data and stores a rectangular neighbourhood of 
+    each point. The input `ten4` is a 4-dimensional array which represents 
+    a list of lists of images. The first two dimensions can be 
+    useful to store different channels and batches.
+
+    The second input of the function `neib_shape` is a tuple containing two
+    values: height and width of the neighbourhood.
+
+    It is possible to assign a step of selecting patches (parameter 
+    `neib_step`). The parameter should be a tuple of two elements: number of
+    rows and number of columns to skip each iteration. Basically, when the 
+    step is 1, the neighbourhood of every first element is taken and every
+    possible rectangular subset is returned. By default it is equal to
+    `neib_shape` in other words, the
+    patches are disjoint. When the step is greater than `neib_shape`, some
+    elements are omitted.
+             
+    .. note:: Currently the step size should be chosen in the way that the 
+       corresponding dimension :math:`i` (width or height) is equal to 
+       :math:`n * step\_size_i + neib\_shape_i` for some :math:`n`
+
+    Example:
+  
+    .. code-block:: python
+  
+        # Defining variables
+        images = T.tensor4('images')
+        neibs = images2neibs(images, neib_shape=(5, 5))
+  
+        # Constructing theano function 
+        window_function = theano.function([images], neibs)
+  
+        # Input tensor (one image 10x10)
+        im_val = np.arange(100.).reshape((1, 1, 10, 10))
+  
+        # Function application
+        neibs_val = window_function(im_val)
+  
+    .. note:: The underlying code will construct a 2D tensor of disjoint 
+       patches 5x5. The output has shape 4x25. 
     """
     return Images2Neibs(mode)(ten4, neib_shape, neib_step)
 
@@ -475,6 +518,28 @@ def neibs2images(neibs, neib_shape, original_shape, mode='valid'):
        its inputs in this case because it uses 
        :func:`images2neibs <theano.sandbox.neigbours.neibs2images>` for 
        gradient computation.
+    
+    Function :func:`neibs2images <theano.sandbox.neighbours.neibs2images>`
+    performs the inverse operation of 
+    :func:`images2neibs <theano.sandbox.neigbours.neibs2images>`. It inputs
+    the output of :func:`images2neibs <theano.sandbox.neigbours.neibs2images>`,
+    `neib_shape` -- `neib_shape` that was used in 
+    :func:`images2neibs <theano.sandbox.neigbours.neibs2images>`, 
+    `original_shape` -- original shape of 4d tensor given to 
+    :func:`images2neibs <theano.sandbox.neigbours.neibs2images>`
+    and reconstructs its input.
+
+    Example:
+
+    .. code-block:: python
+
+        im_new = neibs2images(neibs, (5, 5), im_val.shape)
+        # Theano function definition
+        inv_window = theano.function([neibs], im_new)
+        # Function application
+        im_new_val = inv_window(neibs_val)
+
+    .. note:: The code will output the initial image array.
     """
     neibs = T.as_tensor_variable(neibs)
     neib_shape = T.as_tensor_variable(neib_shape)