Restructuring and updating docs

.gitignore

@@ -3,7 +3,7 @@
 # setup.py working directory
 build
 # setup.py dist directory
-./dist
+dist/
 # Documentation build files
 doc/build
 # Editor temporary/working/backup files
@@ -27,3 +27,6 @@ doc/build
 ./.shelf
 # Mac droppings
 .DS_Store
+
+# Build products
+MANIFEST

datarray/LICENSE

@@ -104,9 +104,3 @@ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-
-numpydoc license
-----------------
-
-The numpydoc license is in datarray/doc/sphinxext/LICENSE.txt

doc/Makefile

@@ -11,7 +11,9 @@ PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest all
+
+all: html
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"

doc/source/basic_data_array.rst

@@ -70,7 +70,7 @@ The names and the position have to be the same, and the above example should
 raise an error.  At least for now we will raise an error, and review later.
 
 With "labels"
-------------
+-------------
 
 Constructing a DataArray such that an Axis has labels, for example:
 
@@ -108,55 +108,6 @@ By normal "numpy" slicing:
     >>> narr.axis.a[0].axes == narr[0,:].axes
     True
 
-Through the "axis slicer" ``aix`` attribute:
-
-    >>> narr[ narr.aix.b[:2].c[-1] ]
-    DataArray([[ 0.,  0.]])
-    ('a', 'b')
-    >>> narr[ narr.aix.c[-1].b[:2] ]
-    DataArray([[ 0.,  0.]])
-    ('a', 'b')
-    >>> narr[ narr.aix.c[-1].b[:2] ] == narr[:,:2,-1]
-    DataArray([[ True,  True]], dtype=bool)
-    ('a', 'b')
-
-The Axis Indexing object (it's a stuple)
-----------------------------------------
-
-The ``aix`` attribute is a property which generates a "stuple" (special/slicing tuple)::
-
-    @property
-    def aix(self):
-        # Returns an anonymous slicing tuple that knows
-        # about this array's geometry
-        return stuple( ( slice(None), ) * self.ndim,
-                       axes = self.axes )
-
-
-The stuple should have a reference to a group of Axis objects that describes an
-array's geometry. If the stuple is associated with a specific Axis, then when
-sliced itself, it can create a slicing tuple for the array with the given
-geometry.
-:
-
-    >>> narr.aix
-    (slice(None, None, None), slice(None, None, None), slice(None, None, None))
-    >>> narr.names
-    ('a', 'b', 'c')
-    >>> narr.aix.b[0]
-    (slice(None, None, None), 0, slice(None, None, None))
-
-**Note** -- the ``aix`` attribute provides some shorthand syntax for the following:
-
-    >>> narr.axis.c[-1].axis.b[:2]
-    DataArray([[ 0.,  0.]])
-    ('a', 'b')
-
-The mechanics are slightly different (using ``aix``, a slicing tuple is created
-up-front before ``__getitem__`` is called), but functionality is the same.
-**Question** -- Is it convenient enough to include the ``aix`` slicer? should
-it function differently?
-
 Also, slicing with ``newaxis`` is implemented:
 
     >>> arr = np.arange(24).reshape((3,2,4))
@@ -178,7 +129,7 @@ Axis with length-1 at the original index of the named Axis:
     (3, 1, 2, 4)
 
 Slicing and labels
------------------
+------------------
 
 It is also possible to use labels in any of the slicing syntax above:
 
@@ -516,4 +467,3 @@ a[i] valid cases:
 - i: integer => normal numpy scalar indexing, one less dim than x
 - i: slice: numpy view slicing.  same dims as x, must recover the labels 
 - i: list/array: numpy fancy indexing, as long as the index list is 1d only.
-

doc/source/conf.py

@@ -130,7 +130,8 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
+html_static_path = []
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

doc/source/data_summit_proposal.rst

@@ -18,9 +18,59 @@ behaviour::
     # get the nth axis object (particularly if not named)
     >>> a.axes[n]
     
-    # get an "axes indexer" object for the indicated objects
+    # get an "axes indexer" object for the indicated objects.
     >>> a.axes('stocks', 'date')
+
+This indexer object returns something that is meant to be indexed with as many
+dimensions as it was passed arguments, but that will, upon indexing, return
+arrays with dimensions ordered just like the original underlying array.
 
+The reason that I think that this is more natural is that the information that
+you have is all available at the point where you are constructing the slicer,
+you don't need to go rummaging around the code to find the correct order of the
+axes from where the array was originally defined.  It also potentially permits
+you to use underlying arrays with different axis orders in the same code
+unambiguously.
+
+There was also the thought that with numerical arguments that this would fill a
+hole in the current numpy API for arbitrary re-ordering of axes in a view for
+slicing (essentially a super-generalized transpose-ish sort of thing)
+
+I think that the result of the slicing operation retains the original ordering,
+but the slices provided to a.axes()[] need to match the order of the arguments
+to a.axes.
+
+So in other words, when you do
+
+
+tslicer = a.axes('t')
+
+then
+
+tslicer['a':'z']
+
+returns an array with axes x, y, z, t in that order, but sliced as
+a[:,:,:,'a':'z'] 
+
+When you have:
+
+xyslicer = a.axes('x', 'y')
+yxslicer = a.axes('y', 'x')
+
+then I would expect to do:
+
+xyslicer[x1:x2, y1:y2]
+
+but
+
+yxslicer[y1:y2, x1:x2]
+
+However, these are two equivalent ways of writing a[x1:x2, y1:y2, :, :]
+
+
+
+::
+      
     # actually do the slicing: equivalent to a[100, 0:2, :]
     >>> a.axes('stocks', 'date')['aapl':'goog',100]
     
@@ -35,9 +85,11 @@ have to supply a keyword argument to the axes call::
     >>> date_mapper = DictMapper(...)
     >>> a = DataArray( ..., axes=(('date', date_mapper), ... ))
     
-    # do mapped indexing
+    # do mapped indexing XXX - this might not have been the final decision
     >>> a.axes('stocks', 'date', mapped=True)['aapl':'goog', datetime.date(2011, 1, 1):datetime.date(2011, 5, 14)]
 
+    # For mapped indexing
+    
 The exact semantics of mapping are yet to be determined, but the thought is that
 there would be standard mappers to do things like interpolation, mapped integer
 indexing.