Merge branch 'slice-and-fancy-indexing-for-markevery'

Conflicts:
	CHANGELOG
	doc/api/api_changes.rst
	doc/users/whats_new.rst

Author: tacaswell

CHANGELOG

@@ -48,6 +48,11 @@
 2014-02-27 Implemented separate horizontal/vertical axes padding to the
            ImageGrid in the AxesGrid toolkit
 
+2014-02-27 Allowed markevery property of matplotlib.lines.Line2D to be, an int
+           numpy fancy index, slice object, or float.  The float behaviour
+           turns on markers at approximately equal display-coordinate-distances
+           along the line.
+
 2014-02-25 In backend_qt4agg changed from using update -> repaint under
            windows.  See comment in source near `self._priv_update` for
            longer explaination.

doc/api/api_changes.rst

@@ -160,16 +160,21 @@ original location:
 
 * Added clockwise parameter to control sectors direction in `axes.pie`
 
+* In `matplotlib.lines.Line2D` the `markevery` functionality has been extended.
+  Previously an integer start-index and stride-length could be specified using
+  either a two-element-list or a two-element-tuple.  Now this can only be done
+  using a two-element-tuple.  If a two-element-list is used then it will be
+  treated as numpy fancy indexing and only the two markers corresponding to the
+  given indexes will be shown.
+
+
 Code removal
 ------------
 
 * Removed ``mlab.levypdf``.  The code raised a numpy error (and has for
   a long time) and was not the standard form of the Levy distribution.
   ``scipy.stats.levy`` should be used instead
 
-
-
-
 .. _changes_in_1_3:
 
 

doc/users/whats_new.rst

@@ -46,7 +46,7 @@ New plotting features
 Power-law normalization
 ```````````````````````
 Ben Gamari added a power-law normalization method,
-:class:`~matplotlib.colors.PowerNorm`. This class maps a range of 
+:class:`~matplotlib.colors.PowerNorm`. This class maps a range of
 values to the interval [0,1] with power-law scaling with the exponent
 provided by the constructor's `gamma` argument. Power law normalization
 can be useful for, e.g., emphasizing small populations in a histogram.
@@ -173,6 +173,15 @@ handling on a par with artists, collections, containers, lines, patches,
 and tables.
 
 
+More `markevery` options to show only a subset of markers
+`````````````````````````````````````````````````````````
+Rohan Walker extended the `markevery` property in
+:class:`~matplotlib.lines.Line2D`.  You can now specify a subset of markers to
+show with an int, slice object, numpy fancy indexing, or float. Using a float
+shows markers at approximately equal display-coordinate-distances along the
+line.
+
+
 Date handling
 -------------
 

examples/pylab_examples/markevery_demo.py

@@ -0,0 +1,98 @@
+"""
+This example demonstrates the various options for showing a marker at a
+subset of data points using the `markevery` property of a Line2D object.
+
+Integer arguments are fairly intuitive.  e.g. `markevery`=5 will plot every
+5th marker starting from the first data point.
+
+Float arguments allow markers to be spaced at approximately equal distances
+along the line.  The theoretical distance along the line between markers is
+determined by multiplying the display-coordinate distance of the axes
+bounding-box diagonal by the value of `markevery`.  The data points closest
+to the theoretical distances will be shown.
+
+A slice or list/array can also be used with `markevery` to specify the markers
+to show.
+
+"""
+
+from __future__ import division
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.gridspec as gridspec
+
+#define a list of markevery cases to plot
+cases = [None,
+         8,
+         (30, 8),
+         [16, 24, 30], [0,-1],
+         slice(100,200,3),
+         0.1, 0.3, 1.5,
+         (0.0, 0.1), (0.45, 0.1)]
+
+#define the figure size and grid layout properties
+figsize = (10, 8)
+cols = 3
+gs = gridspec.GridSpec(len(cases) // cols + 1, cols)
+
+#define the data for cartesian plots
+delta = 0.11
+x = np.linspace(0, 10 - 2 * delta, 200) + delta
+y = np.sin(x) + 1.0 + delta
+
+#plot each markevery case for linear x and y scales
+fig1 = plt.figure(num=1, figsize=figsize)
+ax = []
+for i, case in enumerate(cases):
+    row = (i // cols)
+    col = i % cols
+    ax.append(fig1.add_subplot(gs[row, col]))
+    ax[-1].set_title('markevery=%s' % str(case))
+    ax[-1].plot(x, y, 'o', ls='-', ms=4,  markevery=case)
+#fig1.tight_layout()
+
+#plot each markevery case for log x and y scales
+fig2 = plt.figure(num=2, figsize=figsize)
+axlog = []
+for i, case in enumerate(cases):
+    row = (i // cols)
+    col = i % cols
+    axlog.append(fig2.add_subplot(gs[row, col]))
+    axlog[-1].set_title('markevery=%s' % str(case))
+    axlog[-1].set_xscale('log')
+    axlog[-1].set_yscale('log')
+    axlog[-1].plot(x, y, 'o', ls='-', ms=4,  markevery=case)
+fig2.tight_layout()
+
+#plot each markevery case for linear x and y scales but zoomed in
+#note the behaviour when zoomed in.  When a start marker offset is specified
+#it is always interpreted with respect to the first data point which might be
+#different to the first visible data point.
+fig3 = plt.figure(num=3, figsize=figsize)
+axzoom = []
+for i, case in enumerate(cases):
+    row = (i // cols)
+    col = i % cols
+    axzoom.append(fig3.add_subplot(gs[row, col]))
+    axzoom[-1].set_title('markevery=%s' % str(case))
+    axzoom[-1].plot(x, y, 'o', ls='-', ms=4,  markevery=case)
+    axzoom[-1].set_xlim((6, 6.7))
+    axzoom[-1].set_ylim((1.1, 1.7))
+fig3.tight_layout()
+
+#define data for polar plots
+r = np.linspace(0, 3.0, 200)
+theta = 2 * np.pi * r
+
+#plot each markevery case for polar plots
+fig4 = plt.figure(num=4, figsize=figsize)
+axpolar = []
+for i, case in enumerate(cases):
+    row = (i // cols)
+    col = i % cols
+    axpolar.append(fig4.add_subplot(gs[row, col], polar = True))
+    axpolar[-1].set_title('markevery=%s' % str(case))
+    axpolar[-1].plot(theta, r, 'o', ls='-', ms=4,  markevery=case)
+fig4.tight_layout()
+
+plt.show()

lib/matplotlib/lines.py

@@ -73,6 +73,118 @@ def segment_hits(cx, cy, x, y, radius):
     return np.concatenate((points, lines))
 
 
+def _mark_every_path(markevery, tpath, affine, ax_transform):
+    """
+    Helper function that sorts out how to deal the input
+    `markevery` and returns the points where markers should be drawn.
+
+    Takes in the `markevery` value and the line path and returns the
+    sub-sampled path.
+    """
+    # pull out the two bits of data we want from the path
+    codes, verts = tpath.codes, tpath.vertices
+
+    def _slice_or_none(in_v, slc):
+        '''
+        Helper function to cope with `codes` being an
+        ndarray or `None`
+        '''
+        if in_v is None:
+            return None
+        return in_v[slc]
+
+    # if just a float, assume starting at 0.0 and make a tuple
+    if isinstance(markevery, float):
+        markevery = (0.0, markevery)
+    # if just an int, assume starting at 0 and make a tuple
+    elif isinstance(markevery, int):
+        markevery = (0, markevery)
+
+    if isinstance(markevery, tuple):
+        if len(markevery) != 2:
+            raise ValueError('`markevery` is a tuple but its '
+                'len is not 2; '
+                'markevery=%s' % (markevery,))
+        start, step = markevery
+        # if step is an int, old behavior
+        if isinstance(step, int):
+            #tuple of 2 int is for backwards compatibility,
+            if not(isinstance(start, int)):
+                raise ValueError('`markevery` is a tuple with '
+                    'len 2 and second element is an int, but '
+                    'the first element is not an int; '
+                    'markevery=%s' % (markevery,))
+            # just return, we are done here
+
+            return Path(verts[slice(start, None, step)],
+                        _slice_or_none(codes, slice(start, None, step)))
+
+        elif isinstance(step, float):
+            if not (isinstance(start, int) or
+                    isinstance(start, float)):
+                raise ValueError('`markevery` is a tuple with '
+                    'len 2 and second element is a float, but '
+                    'the first element is not a float or an '
+                    'int; '
+                    'markevery=%s' % (markevery,))
+            #calc cumulative distance along path (in display
+            # coords):
+            disp_coords = affine.transform(tpath.vertices)
+            delta = np.empty((len(disp_coords), 2),
+                             dtype=float)
+            delta[0, :] = 0.0
+            delta[1:, :] = (disp_coords[1:, :] -
+                                disp_coords[:-1, :])
+            delta = np.sum(delta**2, axis=1)
+            delta = np.sqrt(delta)
+            delta = np.cumsum(delta)
+            #calc distance between markers along path based on
+            # the axes bounding box diagonal being a distance
+            # of unity:
+            scale = ax_transform.transform(
+                np.array([[0, 0], [1, 1]]))
+            scale = np.diff(scale, axis=0)
+            scale = np.sum(scale**2)
+            scale = np.sqrt(scale)
+            marker_delta = np.arange(start * scale,
+                                     delta[-1],
+                                     step * scale)
+            #find closest actual data point that is closest to
+            # the theoretical distance along the path:
+            inds = np.abs(delta[np.newaxis, :] -
+                            marker_delta[:, np.newaxis])
+            inds = inds.argmin(axis=1)
+            inds = np.unique(inds)
+            # return, we are done here
+            return Path(verts[inds],
+                        _slice_or_none(codes, inds))
+        else:
+            raise ValueError('`markevery` is a tuple with '
+                'len 2, but its second element is not an int '
+                'or a float; '
+                'markevery=%s' % (markevery,))
+
+    elif isinstance(markevery, slice):
+        # mazol tov, it's already a slice, just return
+        return Path(verts[markevery],
+                    _slice_or_none(codes, markevery))
+
+    elif iterable(markevery):
+        #fancy indexing
+        try:
+            return Path(verts[markevery],
+                    _slice_or_none(codes, markevery))
+
+        except (ValueError, IndexError):
+            raise ValueError('`markevery` is iterable but '
+                'not a valid form of numpy fancy indexing; '
+                'markevery=%s' % (markevery,))
+    else:
+        raise ValueError('Value of `markevery` is not '
+            'recognized; '
+            'markevery=%s' % (markevery,))
+
+
 class Line2D(Artist):
     """
     A line - the line can have both a solid linestyle connecting all
@@ -341,24 +453,54 @@ def set_fillstyle(self, fs):
         self._marker.set_fillstyle(fs)
 
     def set_markevery(self, every):
-        """
-        Set the markevery property to subsample the plot when using
-        markers.  e.g., if ``markevery=5``, every 5-th marker will be
-        plotted.  *every* can be
-
-        None
-            Every point will be plotted
+        """Set the markevery property to subsample the plot when using markers.
 
-        an integer N
-            Every N-th marker will be plotted starting with marker 0
+        e.g., if `every=5`, every 5-th marker will be plotted.
 
-        A length-2 tuple of integers
-            every=(start, N) will start at point start and plot every N-th
-            marker
-
-        ACCEPTS: None | integer | (startind, stride)
+        Parameters
+        ----------
+        every: None | int | length-2 tuple of int | slice | list/array of int |
+        float | length-2 tuple of float
+            Which markers to plot.
+
+            - every=None, every point will be plotted.
+            - every=N, every N-th marker will be plotted starting with
+              marker 0.
+            - every=(start, N), every N-th marker, starting at point
+              start, will be plotted.
+            - every=slice(start, end, N), every N-th marker, starting at
+              point start, upto but not including point end, will be plotted.
+            - every=[i, j, m, n], only markers at points i, j, m, and n
+              will be plotted.
+            - every=0.1, (i.e. a float) then markers will be spaced at
+              approximately equal distances along the line; the distance
+              along the line between markers is determined by multiplying the
+              display-coordinate distance of the axes bounding-box diagonal
+              by the value of every.
+            - every=(0.5, 0.1) (i.e. a length-2 tuple of float), the
+              same functionality as every=0.1 is exhibited but the first
+              marker will be 0.5 multiplied by the
+              display-cordinate-diagonal-distance along the line.
+
+        Notes
+        -----
+        Setting the markevery property will only show markers at actual data
+        points.  When using float arguments to set the markevery property
+        on irregularly spaced data, the markers will likely not appear evenly
+        spaced because the actual data points do not coincide with the
+        theoretical spacing between markers.
+
+        When using a start offset to specify the first marker, the offset will
+        be from the first data point which may be different from the first
+        the visible data point if the plot is zoomed in.
+
+        If zooming in on a plot when using float arguments then the actual
+        data points that have markers will change because the distance between
+        markers is always determined from the display-coordinates
+        axes-bounding-box-diagonal regardless of the actual axes data limits.
 
         """
+
         self._markevery = every
 
     def get_markevery(self):
@@ -582,16 +724,8 @@ def draw(self, renderer):
                 # subsample the markers if markevery is not None
                 markevery = self.get_markevery()
                 if markevery is not None:
-                    if iterable(markevery):
-                        startind, stride = markevery
-                    else:
-                        startind, stride = 0, markevery
-                    if tpath.codes is not None:
-                        codes = tpath.codes[startind::stride]
-                    else:
-                        codes = None
-                    vertices = tpath.vertices[startind::stride]
-                    subsampled = Path(vertices, codes)
+                    subsampled = _mark_every_path(markevery, tpath,
+                                                  affine, self.axes.transAxes)
                 else:
                     subsampled = tpath