Permalink
Browse files

Restructuring and updating docs

  • Loading branch information...
1 parent 72fb979 commit a35305be70fe1a80b45e088bff5637e2b3b107c0 @fperez fperez committed May 29, 2011
View
@@ -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
View
@@ -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
View
@@ -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"
@@ -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.
-
View
@@ -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.
@@ -1,86 +0,0 @@
-(my thoughts on) What Is The DataArray?
-=======================================
-
-* 1st and foremost, **an ndarray**, in N dimensions, with any dtype
-* has means to locate data more descriptively (IE, with custom names
- for dimensions/axes, and custom names for indices along any axis)
-
-::
-
- >>> darr = DataArray(np.random.randn(2,3,4), ('ex', 'why', 'zee'))
- >>> darr.sum(axis='ex')
- DataArray([[-0.39052695, -2.07493873, 1.19664474, 0.36681094],
- [-1.04287781, 0.5767191 , -0.35425298, 1.10468356],
- [ 0.08331866, -0.36532857, 0.12905265, -1.94559672]])
- ('why', 'zee')
- >>> for subarr in darr.axis.why:
- ... print subarr.shape, subarr.labels
- ...
- (2, 4) ('ex', 'zee')
- (2, 4) ('ex', 'zee')
- (2, 4) ('ex', 'zee')
-
-* An axis "label" can always stand in for an axis number; an index
- "tick" can (in some TBD sense) stand in for an integer index
-* if anything is **more restrictive** in operations, for example
-
-::
-
- >>> ndarr_ones = np.ones((10,10,10))
- >>> ndarr_twos = np.ones((10,10,10))*2
- >>> ndarr_3s = ndarr_ones + ndarr_twos # OK!
- >>> darr_abc = DataArray(ndarr_ones, ('a', 'b', 'c'))
- >>> darr_bac = DataArray(ndarr_twos, ('b', 'a', 'c'))
- >>> darr_wtf = darr_abc + darr_bac # BAD! frames are rotated
-
-(and my very own thoughts on) What The DataArray Is Not
-=======================================================
-
-Unions And Intersections
-------------------------
-
-DataArray may broadcast with certain union rules for adapting
-metadata, but it does not do any data union/intersection rule for
-operations. For example, the result of adding an array with axes ('a', 'c') with an
-array with axis 'c' takes on information from the "superset" of
-axes. This is analogous to ndarray taking on shape information from
-the superset of shapes.
-
-::
-
- >>> darr_abc[:,0,:]
- DataArray([[ 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.],
- ...
- [ 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.]])
- ('a', 'c')
- >>> darr_bac[0,0]
- DataArray([ 2., 2., 2., 2., 2., 2., 2., 2., 2., 2.])
- ('c',)
- >>> darr_abc[:,0,:] + darr_bac[0,0]
- DataArray([[ 3., 3., 3., 3., 3., 3., 3., 3., 3., 3.],
- ...
- [ 3., 3., 3., 3., 3., 3., 3., 3., 3., 3.]])
- ('a', 'c')
-
-But it will not fill or trim any dimension to fit the shape of a
-fellow operand's array (it seems this violation is simply caught at the C-level of an ndarray)::
-
- >>> darr_abc[:,0,:] + darr_bac[0,0,:5]
- ------------------------------------------------------------
- Traceback (most recent call last):
- File "<ipython console>", line 1, in <module>
- ValueError: shape mismatch: objects cannot be broadcast to a single shape
-
-For me, this looks like the **domain of utility functions** (or
-possibly utility methods that yield new DataArrays).
-
-Namespace
----------
-
-It would be good practice to keep all the dynamically generated
-DataArray attributes (eg, Axis labels) removed from the top-level
-array attribute list. This is what we currently have as "axis".
-
-It might(?) be a good idea to put all future special purpose methods
-under that object too.
-
@@ -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.
Oops, something went wrong.

0 comments on commit a35305b

Please sign in to comment.