Added some basic usage doc for neighbourhoodFromImages

theano/sandbox/neighbourhoods.py

@@ -9,6 +9,55 @@ import __builtin__
 class NeighbourhoodsFromImages(Op):
     def __init__(self, n_dims_before, dims_neighbourhoods, strides=None, ignore_border=False):
         """
+        This extracts neighbourhoods from "images", but in a
+        dimension-generic manner.
+
+        In the 2D case, this is similar to downsampling, but instead of reducing
+        a group of 2x2 pixels (for example) to a single new pixel in the output,
+        you place those 4 pixels in a row.
+
+        For example, say you have this 2x4 image::
+
+            [ [ 0.5, 0.6, 0.7, 0.8 ],
+              [ 0.1, 0.2, 0.3, 0.4 ] ]
+
+        and you want to extract 2x2 neighbourhoods. This op would then produce::
+
+            [ [ [ 0.5, 0.6, 0.1, 0.2 ] ], # the first 2x2 group of pixels
+              [ [ 0.7, 0.8, 0.3, 0.4 ] ] ] # the second one
+
+        so think of a 2D downsampling where each pixel of the resulting array
+        is replaced by an array containing the (flattened) pixels of the
+        corresponding neighbourhood.
+
+        If you provide a stack of 2D image, or multiple stacks, each image
+        will be treated independently, and the first dimensions of the array
+        will be preserved as such.
+
+        This also makes sense in the 1D or 3D case. Below I'll still be calling
+        those "images", by analogy.
+
+        In the 1D case, you're
+        extracting subsequences from the original sequence. In the 3D case,
+        you're extracting cuboids. If you ever find a 4D use, tell me! It
+        should be possible, anyhow.
+
+        Parameters
+        ----------
+        n_dims_before : int
+            Number of dimensions preceding the "images".
+        dims_neighbourhoods : tuple of ints
+            Exact shape of windows to be extracted (e.g. (2,2) in the case above).
+            n_dims_before + len(dims_neighbourhoods) should be equal to the
+            number of dimensions in the input given to the op.
+        strides : tuple of int
+            Number of elements to skip when moving to the next neighbourhood,
+            for each dimension of dims_neighbourhoods. There can be overlap
+            between neighbourhoods, or gaps.
+        ignore_border : bool
+            If the dimensions of the neighbourhoods don't exactly divide the
+            dimensions of the "images", you can either fill the last
+            neighbourhood with zeros (False) or drop it entirely (True).
         """
         self.n_dims_before = n_dims_before
         self.dims_neighbourhoods = dims_neighbourhoods