Menu
▾
▴
SF.net SVN: matplotlib: [5222] trunk/matplotlib/doc/users_guide
|
From: <ds...@us...> - 2008-05-23 13:49:22
|
Revision: 5222
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5222&view=rev
Author: dsdale
Date: 2008-05-23 06:49:20 -0700 (Fri, 23 May 2008)
Log Message:
-----------
moved users_guide sources out of sources, into parent directory
for flat rather than nested structure
Modified Paths:
--------------
trunk/matplotlib/doc/users_guide/make.py
Added Paths:
-----------
trunk/matplotlib/doc/users_guide/_static/
trunk/matplotlib/doc/users_guide/_templates/
trunk/matplotlib/doc/users_guide/add_new_projection.txt
trunk/matplotlib/doc/users_guide/artist_api_tut.txt
trunk/matplotlib/doc/users_guide/coding_guide.txt
trunk/matplotlib/doc/users_guide/conf.py
trunk/matplotlib/doc/users_guide/developerguide.txt
trunk/matplotlib/doc/users_guide/documenting_mpl.txt
trunk/matplotlib/doc/users_guide/event_handling_tut.txt
trunk/matplotlib/doc/users_guide/figures/
trunk/matplotlib/doc/users_guide/index.txt
trunk/matplotlib/doc/users_guide/introduction.txt
trunk/matplotlib/doc/users_guide/userguide.txt
Removed Paths:
-------------
trunk/matplotlib/doc/users_guide/source/_static/
trunk/matplotlib/doc/users_guide/source/_templates/
trunk/matplotlib/doc/users_guide/source/add_new_projection.txt
trunk/matplotlib/doc/users_guide/source/artist_api_tut.txt
trunk/matplotlib/doc/users_guide/source/coding_guide.txt
trunk/matplotlib/doc/users_guide/source/conf.py
trunk/matplotlib/doc/users_guide/source/developerguide.txt
trunk/matplotlib/doc/users_guide/source/documenting_mpl.txt
trunk/matplotlib/doc/users_guide/source/event_handling_tut.txt
trunk/matplotlib/doc/users_guide/source/figures/dollar_ticks.py
trunk/matplotlib/doc/users_guide/source/figures/fig_axes_customize_simple.py
trunk/matplotlib/doc/users_guide/source/figures/fig_axes_labels_simple.py
trunk/matplotlib/doc/users_guide/source/figures/fig_x.py
trunk/matplotlib/doc/users_guide/source/figures/make.py
trunk/matplotlib/doc/users_guide/source/figures/matplotlibrc
trunk/matplotlib/doc/users_guide/source/index.txt
trunk/matplotlib/doc/users_guide/source/introduction.txt
trunk/matplotlib/doc/users_guide/source/userguide.txt
Copied: trunk/matplotlib/doc/users_guide/_static (from rev 5221, trunk/matplotlib/doc/users_guide/source/_static)
Property changes on: trunk/matplotlib/doc/users_guide/_static
___________________________________________________________________
Name: svn:mergeinfo
+
Copied: trunk/matplotlib/doc/users_guide/_templates (from rev 5221, trunk/matplotlib/doc/users_guide/source/_templates)
Property changes on: trunk/matplotlib/doc/users_guide/_templates
___________________________________________________________________
Name: svn:mergeinfo
+
Copied: trunk/matplotlib/doc/users_guide/add_new_projection.txt (from rev 5220, trunk/matplotlib/doc/users_guide/source/add_new_projection.txt)
===================================================================
--- trunk/matplotlib/doc/users_guide/add_new_projection.txt (rev 0)
+++ trunk/matplotlib/doc/users_guide/add_new_projection.txt 2008-05-23 13:49:20 UTC (rev 5222)
@@ -0,0 +1,102 @@
+***********************************************
+Adding new scales and projections to matplotlib
+***********************************************
+
+.. ::author Michael Droettboom
+
+Matplotlib supports the addition of custom procedures that transform
+the data before it is displayed.
+
+There is an important distinction between two kinds of
+transformations. Separable transformations, working on a single
+dimension, are called "scales", and non-separable transformations,
+that handle data in two or more dimensions at a time, are called
+"projections".
+
+From the user's perspective, the scale of a plot can be set with
+``set_xscale()`` and ``set_yscale()``. Projections can be chosen using
+the ``projection`` keyword argument to the ``plot()`` or ``subplot()``
+functions::
+
+ plot(x, y, projection="custom")
+
+This document is intended for developers and advanced users who need
+to create new scales and projections for matplotlib. The necessary
+code for scales and projections can be included anywhere: directly
+within a plot script, in third-party code, or in the matplotlib source
+tree itself.
+
+
+Creating a new scale
+====================
+
+Adding a new scale consists of defining a subclass of ``ScaleBase``
+(in the ``matplotlib.scale`` module), that includes the following
+elements:
+
+ - A transformation from data coordinates into display coordinates.
+
+ - An inverse of that transformation. This is used, for example, to
+ convert mouse positions from screen space back into data space.
+
+ - A function to limit the range of the axis to acceptable values
+ (``limit_range_for_scale()``). A log scale, for instance, would
+ prevent the range from including values less than or equal to
+ zero.
+
+ - Locators (major and minor) that determine where to place ticks in
+ the plot, and optionally, how to adjust the limits of the plot to
+ some "good" values. Unlike ``limit_range_for_scale()``, which is
+ always enforced, the range setting here is only used when
+ automatically setting the range of the plot.
+
+ - Formatters (major and minor) that specify how the tick labels
+ should be drawn.
+
+Once the class is defined, it must be registered with ``matplotlib``
+so that the user can select it.
+
+A full-fledged and heavily annotated example is in
+``examples/custom_scale_example.py``. There are also some ``Scale``
+classes in ``scale.py`` that may be used as starting points.
+
+
+Creating a new projection
+=========================
+
+Adding a new projection consists of defining a subclass of ``Axes``
+(in the ``matplotlib.axes`` module), that includes the following
+elements:
+
+ - A transformation from data coordinates into display coordinates.
+
+ - An inverse of that transformation. This is used, for example, to
+ convert mouse positions from screen space back into data space.
+
+ - Transformations for the gridlines, ticks and ticklabels. Custom
+ projections will often need to place these elements in special
+ locations, and ``matplotlib`` has a facility to help with doing so.
+
+ - Setting up default values (overriding ``cla()``), since the
+ defaults for a rectilinear axes may not be appropriate.
+
+ - Defining the shape of the axes, for example, an elliptical axes,
+ that will be used to draw the background of the plot and for
+ clipping any data elements.
+
+ - Defining custom locators and formatters for the projection. For
+ example, in a geographic projection, it may be more convenient to
+ display the grid in degrees, even if the data is in radians.
+
+ - Set up interactive panning and zooming. This is left as an
+ "advanced" feature left to the reader, but there is an example of
+ this for polar plots in ``polar.py``.
+
+ - Any additional methods for additional convenience or features.
+
+Once the class is defined, it must be registered with ``matplotlib``
+so that the user can select it.
+
+A full-fledged and heavily annotated example is in
+``examples/custom_projection_example.py``. The polar plot
+functionality in ``polar.py`` may also be of interest.
Property changes on: trunk/matplotlib/doc/users_guide/add_new_projection.txt
___________________________________________________________________
Name: svn:mergeinfo
+
Name: svn:eol-style
+ CRLF
Copied: trunk/matplotlib/doc/users_guide/artist_api_tut.txt (from rev 5220, trunk/matplotlib/doc/users_guide/source/artist_api_tut.txt)
===================================================================
--- trunk/matplotlib/doc/users_guide/artist_api_tut.txt (rev 0)
+++ trunk/matplotlib/doc/users_guide/artist_api_tut.txt 2008-05-23 13:49:20 UTC (rev 5222)
@@ -0,0 +1,598 @@
+**********************************
+The matplotlib Artist API tutorial
+**********************************
+
+There are three layers to the matplotlib API. The FigureCanvas is the
+area onto which the figure is drawn, the Renderer is the object which
+knows how to draw on the FigureCanvas, and the Artist is the object
+that knows how to use a renderer to paint onto the canvas. The
+FigureCanvas and Renderer handle all the details of talking to user
+interface toolkits like wxpython or drawing languages like postscript,
+and the Artist handles all the high level constructs like
+representing and laying out the figure, text, and lines. The typical
+user will spend 95% of his time working with the Artists.
+
+There are two types Artists: primitives and containers. The
+primitives represent the standard graphical objects we want to paint
+onto our canvas: Line2D, Rectangle, Text, AxesImage, etc, and the
+containers are places to put them (Axis, Axes and Figure). The
+standard use is to create a Figure instance, use the Figure to create
+one or more Axes or Subplot instances, and use the Axes instance
+helper methods to create the primitives. In the example below, we
+create a Figure instance using pyplot.figure, which is a convenience
+method for instantiating Figure instances and connecting them with
+your user interface or drawing toolkit FigureCanvas. As we will
+discuss below, this is not necessary, and you can work directly with
+postscript, pdf gtk, or wxpython FigureCanvas es, instantiate your
+Figures directly and connect them yourselves, but since we are
+focusing here on the Artist API we'll let pyplot handle some of those
+details for us::
+
+ import matplotlib.pyplot as plt
+ fig = plt.figure()
+ ax = fig.add_subplot(2,1,1) # two rows, one column, first plot
+
+The Axes is probably the most important class in the matplotlib API,
+and the one you will be working with most of the time. This is
+because the Axes is the plotting area into which most of the objects
+go, and the Axes has many special helper methods (ax.plot, ax.text,
+ax.hist, ax.imshow) to create the most common graphics primitives
+(Line2D, Text, Rectangle, Image, respectively). These helper methods
+will take your data (eg numpy arrays and strings) create primitive
+Artist instances as needed (eg Line2D), add them to the relevant
+containers, and draw them when requested. Most of you are probably
+familiar with the Subplot, which is just a special case of an Axes
+that lives on a regular rows by columns grid of Subplot instances. If
+you want to create an Axes at an arbitrary location, simply use the
+add_axes method which takes a list of [left, bottom, width, height]
+values in 0-1 relative figure coordinates::
+
+ ax2 = fig.add_axes([0.15, 0.1, 0.7, 0.3])
+
+Continuing with our example::
+
+ import numpy as np
+ t = np.arange(0.0, 1.0, 0.01)
+ s = np.sin(2*np.pi*t)
+ line, = ax1.plot(t, s, color='blue', lw=2)
+
+In this example, ax is the Axes instance created by the
+fig.add_subplot call above (remember Subplot is just a subclass of
+Axes) and when you call ax.plot, it creates a Line2D instance and adds
+it the the Axes.lines list. In the interactive ipython session below,
+you can see that Axes.lines list is length one and contains the same
+line that was returned by the "line, ax.plot(x, y, 'o')" call::
+
+ In [101]: ax.lines[0]
+ Out[101]: <matplotlib.lines.Line2D instance at 0x19a95710>
+
+ In [102]: line
+ Out[102]: <matplotlib.lines.Line2D instance at 0x19a95710>
+
+If you make subsequent calls to ax.plot (and the hold state is "on"
+which is the default) then additional lines will be added to the list.
+You can remove lines later simply by calling the list methods; either
+of these will work::
+
+ del ax.lines[0]
+ ax.lines.remove(line) # one or the other, not both!
+
+The Axes also has helper methods to configure and decorate the xaxis
+and yaxis tick, ticklabels and axis labels::
+
+ xtext = ax.set_xlabel('my xdata') # returns a Text instance
+ ytext = ax.set_ylabel('my xdata')
+
+When you call ax.set_xlabel, it passes the information on the Text
+instance of the XAxis. Each Axes instance contains an xaxis and a
+yaxis instance, which handle the layout and drawing of the ticks, tick
+labels and axis labels.
+
+Here are the most important matplotlib modules that contain the
+classes referenced above
+
+=============== ==================
+Artist Module
+=============== ==================
+Artist matplotlib.artist
+Rectangle matplotlib.patches
+Line2D matplotlib.lines
+Axes matplotlib.axes
+XAxis and YAxis matplotlib.axis
+Figure matplotlib.figure
+Text matplotlib.text
+=============== ==================
+
+Try creating the figure below
+
+.. image:: figures/fig_axes_labels_simple.png
+ :scale: 75
+
+Customizing your objects
+========================
+
+Every element in the figure is represented by a matplotlib Artist, and
+each has an extensive list of properties to configure its appearance.
+The figure itself contains a Rectangle exactly the size of the figure,
+which you can use to set the background color and transparency of the
+figures. Likewise, each Axes bounding box (the standard white box
+with black edges in the typical matplotlib plot, has a Rectangle
+instance that determines the color, transparency, and other properties
+of the Axes. These instances are stored as member variables
+Figure.figurePatch and Axes.axesPatch ("Patch" is a name inherited
+from Matlab, and is a 2D "patch" of color on the figure, eg
+rectangles, circles and polygons). Every matplotlib Artist has the
+following properties
+
+========== ======================================================================
+Property Description
+========== ======================================================================
+alpha The transparency - a scalar from 0-1
+animated A boolean that is used to facilitate animated drawing
+axes The axes that the Artist lives in, possibly None
+clip_box The bounding box that clips the Artist
+clip_on Whether clipping is enabled
+clip_path The path the artist is clipped to
+contains A picking function to test whether the artist contains the pick point
+figure The figure instance the aritst lives in, possibly None
+label A text label (eg for auto-labeling)
+picker A python object that controls object picking
+transform The transformation
+visible A boolean whether the artist should be drawn
+zorder A number which determines the drawing order
+========== ======================================================================
+
+Each of the properties is accessed with an old-fashioned setter or
+getter (yes we know this irritates pythonistas and we plan to support
+direct access via properties or traits but it hasn't been done yet).
+For example, to multiply the current alpha by a half::
+
+ a = o.get_alpha()
+ o.set_alpha(0.5*a)
+
+If you want to set a number of properties at once, you can also use
+the "set" method with keyword arguments. For example::
+
+ o.set(alpha=0.5, zorder=2)
+
+If you are working interactively at the python shell, a handy way to
+inspect the artist properties is to use the matplotlib.artist.getp
+method, which lists the properties and their values (simply "getp") in
+pylab. This works for classes derived from Artist as well, eg Figure
+and Rectangle. Here are the Figure rectangle properties mentioned above::
+
+
+ In [149]: matplotlib.artist.getp(fig.figurePatch)
+ alpha = 1.0
+ animated = False
+ antialiased or aa = True
+ axes = None
+ clip_box = None
+ clip_on = False
+ clip_path = None
+ contains = None
+ edgecolor or ec = w
+ facecolor or fc = 0.75
+ figure = Figure(8.125x6.125)
+ fill = 1
+ hatch = None
+ height = 1
+ label =
+ linewidth or lw = 1.0
+ picker = None
+ transform = <Affine object at 0x134cca84>
+ verts = ((0, 0), (0, 1), (1, 1), (1, 0))
+ visible = True
+ width = 1
+ window_extent = <Bbox object at 0x134acbcc>
+ x = 0
+ y = 0
+ zorder = 1
+
+The docstrings for all of the classes also contain the artist
+properties, so you can consult the interactive "help", the online html
+docs at http://matplotlib.sourceforge.net/classdocs.html or PDF documentation
+at http://matplotlib.sourceforge.net/api.pdf for a listing of
+properties for a give object.
+
+Getting at the objects to customize them
+========================================
+
+Now that we know how to inspect set the properties of a given
+object we want to configure, we need to now how to get at that
+object. As mentioned in the introduction, there are two kinds of
+objects: primitives and containers. The primitives are usually the
+things you want to configure (the font of a Text instance, the width
+of a Line2D) although the containers also have some properties as
+well -- for example the Axes Artist is a container that contains many
+of the primitives in your plot, but it also has properties like the
+xscale to control whether the xaxis is 'linear' or 'log'. In this
+section we'll review where the various container objects store the
+Artists that you want to get at.
+
+The Figure container
+--------------------
+
+The top level container Artist is the matplotlib.figure.Figure, and it
+contains everything in the figure. The background of the figure is a
+Rectangle which is stored in fig.figurePatch (where fig is your Figure
+instance). As you add subplots (fig.add_subplot) and axes
+(ax.add_axes)to the figure these will be appended to the fig.axes
+list. These are also returned by the methods that create them::
+
+ In [156]: fig = plt.figure()
+
+ In [157]: ax1 = fig.add_subplot(211)
+
+ In [158]: ax2 = fig.add_axes([0.1, 0.1, 0.7, 0.3])
+
+ In [159]: ax1
+ Out[159]: <matplotlib.axes.Subplot instance at 0xd54b26c>
+
+ In [160]: print fig.axes
+ [<matplotlib.axes.Subplot instance at 0xd54b26c>, <matplotlib.axes.Axes instance at 0xd3f0b2c>]
+
+
+Because the figure maintains the concept of the "current axes" (see
+Figure.gca and Figure.sca) to support the pylab/pyplot state machine,
+you should not insert or remove axes directly from the axes list, but
+rather use the Figure.add_axes and Figure.add_subplot method to
+insert, and the Figure.delaxes methods to delete. You are free
+however, to iterate over the list of axes or index into it to get
+access to Axes instances you want to customize. Here is an example
+which turns all the axes grids on::
+
+ for ax in fig.axes:
+ ax.grid(True)
+
+
+The figure also has its own text, lines, patches and images, which you
+can use to add primitives directly. The default coordinate system for
+the Figure will simply be in pixels (which is not usually what you
+want) but you can control this by setting the transform property of
+the Artist you are adding to the figure. More useful is "figure
+coordinates" where 0,0 is the bottom, left of the figure and 1,1 is
+the top, right of the figure which you can obtain by setting the
+Artist transform to fig.transFigure::
+
+ In [191]: fig = plt.figure()
+
+ In [192]: l1 = matplotlib.lines.Line2D([0, 1], [0, 1], transform=fig.transFigure, figure=fig)
+
+ In [193]: l2 = matplotlib.lines.Line2D([0, 1], [1, 0], transform=fig.transFigure, figure=fig)
+
+ In [194]: fig.lines.extend([l1, l2])
+
+ In [195]: fig.canvas.draw()
+
+.. image:: figures/fig_x.png
+ :scale: 75
+
+
+Here is a summary of the Artists the figure contains
+
+================ ===============================================================
+Figure attribute Description
+================ ===============================================================
+axes A list of Axes instances (includes Subplot)
+figurePatch The Rectangle background
+images A list of FigureImages patches - useful for raw pixel display
+legends A list of Figure Legend instances (different from Axes.legends)
+lines A list of Figure Line2D instances (rarely used, see Axes.lines)
+patches A list of Figure patches (rarely used, see Axes.patches)
+texts A list Figure Text instances
+================ ===============================================================
+
+
+The Axes container
+------------------
+
+The matplotlib.axes.Axes is the center of the matplotlib universe --
+it contains the vast majority of all the Artists used in a figure with
+many helper methods to create and these Artists to itself, as well as
+helper methods to access and customize the Artists it contains. Like
+the Figure, it contains a Patch ax.axesPatch which is Rectangle for
+Cartesian coordinates and a Circle for polar coordinates; this patch
+determines the shape, background and border of the plotting region::
+
+ ax = fig.add_subplot(111)
+ rect = ax.axesPatch # a Rectangle instance
+ rect.set_facecolor('green')
+
+When you call a plotting method, eg the canonical "ax.plot" and pass
+in arrays or list of values, the method will a matplotlib.lines.Line2D
+instance, update the line with all the Line2D properties passed as
+keyword arguments, add the line to the Axes.lines container, and
+returns it to you::
+
+ In [213]: x, y = np.random.rand(2, 100)
+
+ In [214]: line, = ax.plot(x, y, '-', color='blue', linewidth=2)
+
+ax.plot returns a list of lines because you can pass in multiple x, y
+pairs to plot, and we are unpacking the first element of the length
+one list into the line variable. The line has been added to the
+ax.lines list::
+
+
+ In [229]: print ax.lines
+ [<matplotlib.lines.Line2D instance at 0xd378b0c>]
+
+Similarly, methods that create patches, like ax.bar creates a list of
+rectangles, will add the patches to the ax.patches list::
+
+ In [233]: n, bins, rectangles = ax.hist(np.random.randn(1000), 50, facecolor='yellow')
+
+ In [234]: rectangles
+ Out[234]: <a list of 50 Patch objects>
+
+ In [235]: print len(ax.patches)
+
+You should not add objects directly to the ax.lines or ax.patches
+unless you know exactly what you are doing, because the Axes needs to
+do a few things when it creates and adds an object. It sets the figure
+and axes property of the Artist, as well as the default Axes
+transformation (unless a transformation is set). It also inspects the
+data contained in the Artist to update the data structures controlling
+auto-scaling, so that the view limits can be adjusted to contain the
+plotted data. You can, nonetheless, create objects yourself and add
+them directly to the Axes using helper methods like ax.add_line and
+ax.add_patch. Here is an annotated interactive session illustrating
+what is going on::
+
+ In [261]: fig = plt.figure()
+
+ In [262]: ax = fig.add_subplot(111)
+
+ # create a rectangle instance
+ In [263]: rect = matplotlib.patches.Rectangle( (1,1), width=5, height=12)
+
+ # by default the axes instance is None
+ In [264]: print rect.get_axes()
+ None
+
+ # and the transformation instance is set to the "identity transform"
+ In [265]: print rect.get_transform()
+ <Affine object at 0x13695544>
+
+ # now we add the Rectangle to the Axes
+ In [266]: ax.add_patch(rect)
+
+ # and notice that the ax.add_patch method has set the axes
+ # instance
+ In [267]: print rect.get_axes()
+ Subplot(49,81.25)
+
+ # and the transformation has been set too
+ In [268]: print rect.get_transform()
+ <Affine object at 0x15009ca4>
+
+ # the default axes transformation is ax.transData
+ In [269]: print ax.transData
+ <Affine object at 0x15009ca4>
+
+ # notice that the xlimits of the Axes have not been changed
+ In [270]: print ax.get_xlim()
+ (0.0, 1.0)
+
+ # but the data limits have been updated to encompass the rectangle
+ In [271]: print ax.dataLim.get_bounds()
+ (1.0, 1.0, 5.0, 12.0)
+
+ # we can manually invoke the auto-scaling machinery
+ In [272]: ax.autoscale_view()
+
+ # and now the xlim are updated to encompass the rectangle
+ In [273]: print ax.get_xlim()
+ (1.0, 6.0)
+
+ # we have to manually force a figure draw
+ In [274]: ax.figure.canvas.draw()
+
+
+There are many, many Axes helper methods for creating primitive
+Artists and adding them to their respective containers. The table
+below summarizes a small sampling of them, the kinds of Artist they
+create, and where they store them
+
+============================== ==================== =======================
+Helper method Artist Container
+============================== ==================== =======================
+ax.annotate - text annotations Annotate ax.texts
+ax.bar - bar charts Rectangle ax.patches
+ax.errorbar - error bar plots Line2D and Rectangle ax.lines and ax.patches
+ax.fill - shared area Polygon ax.patches
+ax.hist - histograms Rectangle ax.patches
+ax.imshow - image data AxesImage ax.images
+ax.legend - axes legends Legend ax.legends
+ax.plot - xy plots Line2D ax.lines
+ax.scatter - scatter charts PolygonCollection ax.collections
+ax.text - text Text ax.texts
+============================== ==================== =======================
+
+
+In addition to all of these Artists, the Axes contains two important
+Artist containers: the XAxis and YAxis, which handle the drawing of
+the ticks and labels. These are stored as instance variables xaxis
+and yaxis. The XAxis and YAxis containers will be detailed below, but
+note that the Axes contains many helper methods which forward calls on
+to the Axis instances so you often do not need to work with them
+directly unless you want to. For example, you can set the fontsize of
+the XAxis ticklabels using the Axes helper method::
+
+ for label in ax.get_xticklabels():
+ label.set_color('orange')
+
+Below is a summary of the Artists that the Axes contains
+
+============== ======================================
+Axes attribute Description
+============== ======================================
+artists A list of Artist instances
+axesPatch Rectangle instance for Axes background
+collections A list of Collection instances
+images A list of AxesImage
+legends A list of Legend instances
+lines A list of Line2D instances
+patches A list of Patch instances
+texts A list of Text instances
+xaxis matplotlib.axis.XAxis instance
+yaxis matplotlib.axis.YAxis instance
+============== ======================================
+
+The Axis containers
+-------------------
+
+The matplotlib.axis.Axis instances handle the drawing of the tick lines, the grid
+lines, the tick labels and the axis label. You can configure the left
+and right ticks separately for the y axis, and the upper and lower
+ticks separately for the x axis. The axis also stores the data and view
+intervals used in auto-scaling, panning and zooming, as well as the
+locator and formatter instances which control where the ticks are
+placed and how they are represented as strings.
+
+Each axis object contains a label attribute (this is what the pylab
+calls to xlabel and ylabel set) as well as a list of major and minor
+ticks. The ticks are XTick and YTick instances, which contain the
+actual line and text primitives that render the ticks and ticklabels.
+Because the ticks are dynamically created as needed (eg when panning
+and zooming), you should access the lists of major and minor ticks
+through their accessor methods axis.get_major_ticks() and
+axis.get_minor_ticks(). Although the ticks contain all the primitives
+and will be covered below, the Axis methods contain accessor methods
+to return the tick lines, tick labels, tick locations etc....::
+
+ In [285]: axis = ax.xaxis
+
+ In [286]: axis.get_ticklocs()
+ Out[286]: array([ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])
+
+ In [287]: axis.get_ticklabels()
+ Out[287]: <a list of 10 Text major ticklabel objects>
+
+ # note there are twice as many ticklines as labels because by
+ # default there are tick lines at the top and bottom but only tick
+ # labels below the xaxis; this can be customized
+ In [288]: axis.get_ticklines()
+ Out[288]: <a list of 20 Line2D ticklines objects>
+
+ # by default you get the major ticks back
+ In [291]: axis.get_ticklines()
+ Out[291]: <a list of 20 Line2D ticklines objects>
+
+ # but you can also ask for the minor ticks
+ In [292]: axis.get_ticklines(minor=True)
+ Out[292]: <a list of 0 Line2D ticklines objects>
+
+Here is a summary of some of the useful accessor methods of the Axis
+(these have corresponding setters where useful, such as
+set_major_formatter)
+
+====================== =========================================================
+Accessor method Description
+====================== =========================================================
+get_scale The scale of the axis, eg 'log' or 'linear'
+get_view_interval The interval instance of the axis view limits
+get_data_interval The interval instance of the axis data limits
+get_gridlines A list of grid lines for the Axis
+get_label The axis label - a Text instance
+get_ticklabels A list of Text instances - keyword minor=True|False
+get_ticklines A list of Line2D instances - keyword minor=True|False
+get_ticklocs A list of Tick locations - keyword minor=True|False
+get_major_locator The matplotlib.ticker.Locator instance for major ticks
+get_major_formatter The matplotlib.ticker.Formatter instance for major ticks
+get_minor_locator The matplotlib.ticker.Locator instance for minor ticks
+get_minor_formatter The matplotlib.ticker.Formatter instance for minor ticks
+get_major_ticks A list of Tick instances for major ticks
+get_minor_ticks A list of Tick instances for minor ticks
+grid Turn the grid on or off for the major or minor ticks
+====================== =========================================================
+
+Try creating the figure below
+
+.. image:: figures/fig_axes_customize_simple.png
+ :scale: 75
+
+Exercise solution::
+
+ import numpy as np
+ import matplotlib.pyplot as plt
+
+ # plt.figure creates a matplotlib.figure.Figure instance
+ fig = plt.figure()
+ rect = fig.figurePatch # a rectangle instance
+ rect.set_facecolor('lightgoldenrodyellow')
+
+ ax1 = fig.add_axes([0.1, 0.3, 0.4, 0.4])
+ rect = ax1.axesPatch
+ rect.set_facecolor('lightslategray')
+
+
+ for label in ax1.xaxis.get_ticklabels():
+ # label is a Text instance
+ label.set_color('red')
+ label.set_rotation(45)
+ label.set_fontsize(16)
+
+ for line in ax1.yaxis.get_ticklines():
+ # line is a Line2D instance
+ line.set_color('green')
+ line.set_markersize(25)
+ line.set_markeredgewidth(3)
+
+ fig.savefig('figures/fig_axes_customize_simple.png', dpi=150)
+ fig.savefig('figures/fig_axes_customize_simple.eps')
+ plt.show()
+
+
+
+The Tick containers
+-------------------
+
+The matplotlib.axis.Tick is the final container object in our descent
+from the Figure to the Axes to the Axis to the Tick. The Tick
+contains the tick and grid line instances, as well as the label
+instances for the upper and lower ticks. Each of these is accessible
+directly as an attribute of the Tick. In addition, there are boolean
+variables that determine whether the upper labels and ticks are on for
+the xaxis and whether the right labels and ticks are on for the yaxis.
+
+============== ==========================================================
+Tick attribute Description
+============== ==========================================================
+tick1line Line2D instance
+tick2line Line2D instance
+gridline Line2D instance
+label1 Text instance
+label2 Text instance
+gridOn boolean which determines whether to draw the tickline
+tick1On boolean which determines whether to draw the 1st tickline
+tick2On boolean which determines whether to draw the 2nd tickline
+label1On boolean which determines whether to draw tick label
+label2On boolean which determines whether to draw tick label
+============== ==========================================================
+
+Here is an example which sets the formatter for the upper ticks with
+dollar signs and colors them green on the right side of the yaxis::
+
+ import numpy as np
+ import matplotlib.pyplot as plt
+ import matplotlib.ticker as ticker
+
+ fig = plt.figure()
+ ax = fig.add_subplot(111)
+ ax.plot(100*np.random.rand(20))
+
+ formatter = ticker.FormatStrFormatter('$%1.2f')
+ ax.yaxis.set_major_formatter(formatter)
+
+ for tick in ax.yaxis.get_major_ticks():
+ tick.label1On = False
+ tick.label2On = True
+ tick.label2.set_color('green')
+
+ plt.show()
+
+
+.. image:: figures/dollar_ticks.png
+ :scale: 75
Property changes on: trunk/matplotlib/doc/users_guide/artist_api_tut.txt
___________________________________________________________________
Name: svn:mergeinfo
+
Name: svn:eol-style
+ CRLF
Copied: trunk/matplotlib/doc/users_guide/coding_guide.txt (from rev 5220, trunk/matplotlib/doc/users_guide/source/coding_guide.txt)
===================================================================
--- trunk/matplotlib/doc/users_guide/coding_guide.txt (rev 0)
+++ trunk/matplotlib/doc/users_guide/coding_guide.txt 2008-05-23 13:49:20 UTC (rev 5222)
@@ -0,0 +1,3 @@
+
+.. include:: ../../CODING_GUIDE
+
Property changes on: trunk/matplotlib/doc/users_guide/coding_guide.txt
___________________________________________________________________
Name: svn:mergeinfo
+
Name: svn:eol-style
+ CRLF
Copied: trunk/matplotlib/doc/users_guide/conf.py (from rev 5220, trunk/matplotlib/doc/users_guide/source/conf.py)
===================================================================
--- trunk/matplotlib/doc/users_guide/conf.py (rev 0)
+++ trunk/matplotlib/doc/users_guide/conf.py 2008-05-23 13:49:20 UTC (rev 5222)
@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-
+#
+# Matplotlib documentation build configuration file, created by
+# sphinx-quickstart on Fri May 2 12:33:25 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import sys, os
+
+# If your extensions are in another directory, add it here. If the directory
+# is relative to the documentation root, use os.path.abspath to make it
+# absolute, like shown here.
+sys.path.append(os.path.abspath('../sphinxext'))
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['mathml', 'sphinx.ext.autodoc']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.txt'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'Matplotlib'
+copyright = '2008, John Hunter, Darren Dale'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = '0.98'
+# The full version, including alpha/beta/rc tags.
+release = '0.98pre'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# The name of an image file (within the static path) to place at the top of
+# the sidebar.
+#html_logo = None
+
+# 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']
+
+# If nonempty, this is the file name suffix for generated HTML files. The
+# default is ``".html"``.
+html_file_suffix = '.xml'
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.
+html_use_opensearch = 'False'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Matplotlibdoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+latex_font_size = '11pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', 'Matplotlib_Users_Guide.tex', 'Matplotlib Users Guide', 'John Hunter, Darren Dale', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+latex_logo = None
+
+# Additional stuff for the LaTeX preamble.
+latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+latex_appendices = []
+
+# If false, no module index is generated.
+latex_use_modindex = True
+
+latex_use_parts = True
Property changes on: trunk/matplotlib/doc/users_guide/conf.py
___________________________________________________________________
Name: svn:mergeinfo
+
Name: svn:eol-style
+ native
Copied: trunk/matplotlib/doc/users_guide/developerguide.txt (from rev 5220, trunk/matplotlib/doc/users_guide/source/developerguide.txt)
===================================================================
--- trunk/matplotlib/doc/users_guide/developerguide.txt (rev 0)
+++ trunk/matplotlib/doc/users_guide/developerguide.txt 2008-05-23 13:49:20 UTC (rev 5222)
@@ -0,0 +1,12 @@
+############################
+Matplotlib Developers Guide
+############################
+
+.. _contents:
+
+.. toctree::
+ :maxdepth: 3
+
+ coding_guide
+ documenting_mpl
+ add_new_projection
Property changes on: trunk/matplotlib/doc/users_guide/developerguide.txt
___________________________________________________________________
Name: svn:mergeinfo
+
Name: svn:eol-style
+ CRLF
Copied: trunk/matplotlib/doc/users_guide/documenting_mpl.txt (from rev 5220, trunk/matplotlib/doc/users_guide/source/documenting_mpl.txt)
===================================================================
--- trunk/matplotlib/doc/users_guide/documenting_mpl.txt (rev 0)
+++ trunk/matplotlib/doc/users_guide/documenting_mpl.txt 2008-05-23 13:49:20 UTC (rev 5222)
@@ -0,0 +1,43 @@
+**********************
+Documenting Matplotlib
+**********************
+
+The documentation for matplotlib is generated from ReStructured Text
+using the Sphinx_ documentation generation tool. Sphinx-0.4 or later
+is required to generate xml files to render mathematical expressions
+with mathml. Currently this means we need to install from the svn
+repository by doing::
+
+ svn co http://svn.python.org/projects/doctools/trunk sphinx
+ cd sphinx
+ python setup.py install
+
+.. _Sphinx: http://sphinx.pocoo.org/
+
+The documentation sources are found in the doc/ directory in the trunk.
+To build the users guid in html format, cd into doc/users_guide and do::
+
+ python make.py html
+
+you can also pass a ``latex`` flag to make.py to build a pdf, or pass no
+arguments to build everything. The same procedure can be followed for
+the sources in doc/api_reference.
+
+The actual ReStructured Text files are kept in doc/users_guide/source
+and doc/api_reference/source. The main entry point is index.txt.
+Additional files can be added by including their base file name
+(dropping the .txt extension) in the table of contents. It is also
+possible to include other documents through the use of an include
+statement. For example, in the Developers Guide, index.txt lists
+coding_guide, which automatically inserts coding_guide.txt.
+coding_guide.txt is just a placeholder, it contains one line only to
+gets its contents from the CODING_GUIDE file in the trunk:
+``.. include:: ../../CODING_GUIDE``.
+
+The output produced by Sphinx can be configured by editing the conf.py
+files located in the documentation source directories.
+
+The Sphinx website contains plenty of documentation_ concerning ReST
+markup and working with Sphinx in general.
+
+.. _documentation: http://sphinx.pocoo.org/contents.html
\ No newline at end of file
Property changes on: trunk/matplotlib/doc/users_guide/documenting_mpl.txt
___________________________________________________________________
Name: svn:mergeinfo
+
Copied: trunk/matplotlib/doc/users_guide/event_handling_tut.txt (from rev 5220, trunk/matplotlib/doc/users_guide/source/event_handling_tut.txt)
===================================================================
--- trunk/matplotlib/doc/users_guide/event_handling_tut.txt (rev 0)
+++ trunk/matplotlib/doc/users_guide/event_handling_tut.txt 2008-05-23 13:49:20 UTC (rev 5222)
@@ -0,0 +1,471 @@
+***********************************
+Event Handling and Picking Tutorial
+***********************************
+
+matplotlib works with 5 user interface toolkits (wxpython, tkinter,
+qt, gtk and fltk) and in order to support features like interactive
+panning and zooming of figures, it is helpful to the developers to
+have an API for interacting with the figure via key presses and mouse
+movements that is "GUI neutral" so we don't have to repeat a lot of
+code across the different user interfaces. Although the event
+handling API is GUI neutral, it is based on the GTK model, which was
+the first user interface matplotlib supported. The events that are
+triggered are also a bit richer vis-a-vis matplotlib than standard GUI
+events, including information like which Axes the event occurred in.
+The events also understand the matplotlib coordinate system, and
+report event locations in both pixel and data coordinates.
+
+
+Event connections
+=================
+
+To receive events, you need to write a callback function and then
+connect your function to the event manager, which is part of the
+FigureCanvas. Here is a simple example that prints the location of
+the mouse click and which button was pressed::
+
+ fig = plt.figure()
+ ax = fig.add_subplot(111)
+ ax.plot(np.random.rand(10))
+
+ def onclick(event):
+ print 'button=%d, x=%d, y=%d, xdata=%f, ydata=%f'%(
+ event.button, event.x, event.y, event.xdata, event.ydata)
+
+ cid = fig.canvas.mpl_connect('button_press_event', onclick)
+
+The FigureCanvas method mpl_connect returns a connection id which is
+simply an integer. When you want to disconnect the callback, just
+call::
+
+ fig.canvas.mpl_disconnect(cid)
+
+Here are the events that you can connect to, the class instances that
+are sent back to you when the event occurs, and the event descriptions
+
+
+===================== =========== ===================================
+Event name Class Description
+===================== =========== ===================================
+button_press_event MouseEvent mouse button is pressed
+button_release_event MouseEvent mouse button is released
+draw_event DrawEvent canvas draw
+key_press_event KeyEvent key is pressed
+key_release_event KeyEvent key is released
+motion_notify_event MouseEvent mouse motion
+pick_event PickEvent an object in the canvas is selected
+resize_event ResizeEvent figure canvas is resized
+scroll_event MouseEvent mouse scroll wheel is rolled
+===================== =========== ===================================
+
+
+Event attributes
+================
+
+All matplotlib events inherit from the base class
+matplotlib.backend_bases.Event, which store the attributes
+
+=============== =================================================
+Event attribute Description
+=============== =================================================
+name the event name
+canvas the FigureCanvas instance generating the event
+guiEvent the GUI event that triggered the matplotlib event
+=============== =================================================
+
+The most common events that are the bread and butter of event handling
+are key press/release events and mouse press/release and movement
+events. The KeyEvent and MouseEvent classes that handle these events
+are both derived from the LocationEvent, which has the following
+attributes
+
+======================= ========================================
+LocationEvent attribute Description
+======================= ========================================
+x x position - pixels from left of canvas
+y y position - pixels from right of canvas
+button button pressed None, 1, 2, 3
+inaxes the Axes instance if mouse us over axes
+xdata x coord of mouse in data coords
+ydata y coord of mouse in data coords
+======================= ========================================
+
+Let's look a simple example of a canvas, where a simple line segment
+is created every time a mouse is pressed::
+
+ class LineBuilder:
+ def __init__(self, line):
+ self.line = line
+ self.xs = list(line.get_xdata())
+ self.ys = list(line.get_ydata())
+ self.cid = line.figure.canvas.mpl_connect('button_press_event', self)
+
+ def __call__(self, event):
+ print 'click', event
+ if event.inaxes!=self.line.axes: return
+ self.xs.append(event.xdata)
+ self.ys.append(event.ydata)
+ self.line.set_data(self.xs, self.ys)
+ self.line.figure.canvas.draw()
+
+ fig = plt.figure()
+ ax = fig.add_subplot(111)
+ ax.set_title('click to build line segments')
+ line, = ax.plot([0], [0]) # empty line
+ linebuilder = LineBuilder(line)
+
+
+
+The MouseEvent that we just used is a LocationEvent, so we have access
+to the data and pixel coordinates in event.x and event.xdata. In
+addition to the LocationEvent attributes, it has
+
+==================== ==============================================================
+MouseEvent attribute Description
+==================== ==============================================================
+button button pressed None, 1, 2, 3
+key the key pressed: None, chr(range(255)), shift, win, or control
+==================== ==============================================================
+
+Draggable Rectangle Exercise
+----------------------------
+
+Write draggable rectangle class that is initialized with a Rectangle
+instance but will move its x,y location when dragged. Hint: you will
+need to store the orginal xy location of the rectangle which is stored
+as rect.xy and connect to the press, motion and release mouse events.
+When the mouse is pressed, check to see if the click occurs over your
+rectangle (see rect.contains) and if it does, store the rectangle xy
+and the location of the mouse click in data coords. In the motion
+event callback, compute the deltax and deltay of the mouse movement,
+and add those deltas to the origin of the rectangle you stored. The
+redraw the figure. On the button release event, just reset all the
+button press data you stored as None.
+
+Here is the solution::
+
+ import numpy as np
+ import matplotlib.pyplot as plt
+
+ class DraggableRectangle:
+ def __init__(self, rect):
+ self.rect = rect
+ self.press = None
+
+ def connect(self):
+ 'connect to all the events we need'
+ self.cidpress = self.rect.figure.canvas.mpl_connect(
+ 'button_press_event', self.on_press)
+ self.cidrelease = self.rect.figure.canvas.mpl_connect(
+ 'button_release_event', self.on_release)
+ self.cidmotion = self.rect.figure.canvas.mpl_connect(
+ 'motion_notify_event', self.on_motion)
+
+ def on_press(self, event):
+ 'on button press we will see if the mouse is over us and store some data'
+ if event.inaxes != self.rect.axes: return
+
+ contains, attrd = self.rect.contains(event)
+ if not contains: return
+ print 'event contains', self.rect.xy
+ x0, y0 = self.rect.xy
+ self.press = x0, y0, event.xdata, event.ydata
+
+ def on_motion(self, event):
+ 'on motion we will move the rect if the mouse is over us'
+ if self.press is None: return
+ if event.inaxes != self.rect.axes: return
+ x0, y0, xpress, ypress = self.press
+ dx = event.xdata - xpress
+ dy = event.ydata - ypress
+ #print 'x0=%f, xpress=%f, event.xdata=%f, dx=%f, x0+dx=%f'%(x0, xpress, event.xdata, dx, x0+dx)
+ self.rect.set_x(x0+dx)
+ self.rect.set_y(y0+dy)
+
+ self.rect.figure.canvas.draw()
+
+
+ def on_release(self, event):
+ 'on release we reset the press data'
+ self.press = None
+ self.rect.figure.canvas.draw()
+
+ def disconnect(self):
+ 'disconnect all the stored connection ids'
+ self.rect.figure.canvas.mpl_disconnect(self.cidpress)
+ self.rect.figure.canvas.mpl_disconnect(self.cidrelease)
+ self.rect.figure.canvas.mpl_disconnect(self.cidmotion)
+
+ fig = plt.figure()
+ ax = fig.add_subplot(111)
+ rects = ax.bar(range(10), 20*np.random.rand(10))
+ drs = []
+ for rect in rects:
+ dr = DraggableRectangle(rect)
+ dr.connect()
+ drs.append(dr)
+
+ plt.show()
+
+
+**Extra credit**: use the animation blit techniques discussed at
+http://www.scipy.org/Cookbook/Matplotlib/Animations to make the
+animated drawing faster and smoother.
+
+Extra credit solution::
+
+ # draggable rectangle with the animation blit techniques; see
+ # http://www.scipy.org/Cookbook/Matplotlib/Animations
+ import numpy as np
+ import matplotlib.pyplot as plt
+
+ class DraggableRectangle:
+ lock = None # only one can be animated at a time
+ def __init__(self, rect):
+ self.rect = rect
+ self.press = None
+ self.background = None
+
+ def connect(self):
+ 'connect to all the events we need'
+ self.cidpress = self.rect.figure.canvas.mpl_connect(
+ 'button_press_event', self.on_press)
+ self.cidrelease = self.rect.figure.canvas.mpl_connect(
+ 'button_release_event', self.on_release)
+ self.cidmotion = self.rect.figure.canvas.mpl_connect(
+ 'motion_notify_event', self.on_motion)
+
+ def on_press(self, event):
+ 'on button press we will see if the mouse is over us and store some data'
+ if event.inaxes != self.rect.axes: return
+ if DraggableRectangle.lock is not None: return
+ contains, attrd = self.rect.contains(event)
+ if not contains: return
+ print 'event contains', self.rect.xy
+ x0, y0 = self.rect.xy
+ self.press = x0, y0, event.xdata, event.ydata
+ DraggableRectangle.lock = self
+
+ # draw everything but the selected rectangle and store the pixel buffer
+ canvas = self.rect.figure.canvas
+ axes = self.rect.axes
+ self.rect.set_animated(True)
+ canvas.draw()
+ self.background = canvas.copy_from_bbox(self.rect.axes.bbox)
+
+ # now redraw just the rectangle
+ axes.draw_artist(self.rect)
+
+ # and blit just the redrawn area
+ canvas.blit(axes.bbox)
+
+ def on_motion(self, event):
+ 'on motion we will move the rect if the mouse is over us'
+ if DraggableRectangle.lock is not self:
+ return
+ if event.inaxes != self.rect.axes: return
+ x0, y0, xpress, ypress = self.press
+ dx = event.xdata - xpress
+ dy = event.ydata - ypress
+ self.rect.set_x(x0+dx)
+ self.rect.set_y(y0+dy)
+
+
+ canvas = self.rect.figure.canvas
+ axes = self.rect.axes
+ # restore the background region
+ canvas.restore_region(self.background)
+
+ # redraw just the current rectangle
+ axes.draw_artist(self.rect)
+
+ # blit just the redrawn area
+ canvas.blit(axes.bbox)
+
+
+
+ def on_release(self, event):
+ 'on release we reset the press data'
+ if DraggableRectangle.lock is not self:
+ return
+
+ self.press = None
+ DraggableRectangle.lock = None
+
+ # turn off the rect animation property and reset the background
+ self.rect.set_animated(False)
+ self.background = None
+
+ # redraw the full figure
+ self.rect.figure.canvas.draw()
+ def disconnect(self):
+ 'disconnect all the stored connection ids'
+ self.rect.figure.canvas.mpl_disconnect(self.cidpress)
+ self.rect.figure.canvas.mpl_disconnect(self.cidrelease)
+ self.rect.figure.canvas.mpl_disconnect(self.cidmotion)
+
+ fig = plt.figure()
+ ax = fig.add_subplot(111)
+ rects = ax.bar(range(10), 20*np.random.rand(10))
+ drs = []
+ for rect in rects:
+ dr = DraggableRectangle(rect)
+ dr.connect()
+ drs.append(dr)
+
+ plt.show()
+
+
+Object Picking
+==============
+
+You can enable picking by setting the ``picker`` property of an Artist
+(eg a matplotlib Line2D, Text, Patch, Polygon, AxesImage,
+etc...)
+
+There are a variety of meanings of the picker property:
+
+- None : picking is disabled for this artist (default)
+
+- boolean : if True then picking will be enabled and the artist will
+ fire a pick event if the mouse event is over the artist
+
+- float : if picker is a number it is interpreted as an epsilon
+ tolerance in points and the the artist will fire off an event if its
+ data is within epsilon of the mouse event. For some artists like
+ lines and patch collections, the artist may provide additional data
+ to the pick event that is generated, eg the indices of the data
+ within epsilon of the pick event.
+
+- function : if picker is callable, it is a user supplied function
+ which determines whether the artist is hit by the mouse event. The
+ signature is ``hit, props = picker(artist, mouseevent)`` to
+ determine the hit test. If the mouse event is over the artist,
+ return hit=True and props is a dictionary of properties you want
+ added to the PickEvent attributes
+
+
+After you have enabled an artist for picking by setting the ``picker``
+property, you need to connect to the figure canvas pick_event to get
+pick callbacks on mouse press events. Eg::
+
+ def pick_handler(event):
+ mouseevent = event.mouseevent
+ artist = event.artist
+ # now do something with this...
+
+
+The pick event (matplotlib.backend_bases.PickEvent) which is passed to
+your callback is always fired with two attributes:
+
+- mouseevent : the mouse event that generate the pick event. The
+ mouse event in turn has attributes like x and y (the coords in
+ display space, eg pixels from left, bottom) and xdata, ydata (the
+ coords in data space). Additionally, you can get information about
+ which buttons were pressed, which keys were pressed, which Axes the
+ mouse is over, etc. See matplotlib.backend_bases.MouseEvent for
+ details.
+
+- artist : the matplotlib.artist that generated the pick event.
+
+Additionally, certain artists like Line2D and PatchCollection may
+attach additional meta data like the indices into the data that meet
+the picker criteria (eg all the points in the line that are within the
+specified epsilon tolerance)
+
+Simple picking example
+----------------------
+
+In the example below, we set the line picker property to a scalar, so
+it represents a tolerance in points (72 points per inch). The onpick
+callback function will be called when the pick event it within the
+tolerance distance from the line, and has the indices of the data
+vertices that are within the pick distance tolerance. Our onpick
+callback function simply prints the data that are under the pick
+location. Different matplotlib Artists can attach different data to
+the PickEvent. For example, Line2D attaches the ind property, which
+are the indices into the line data under the pick point. See
+Line2D.pick for details on the PickEvent properties of the line. Here
+is the code::
+
+ import numpy as np
+ import matplotlib.pyplot as plt
+
+ fig = plt.figure()
+ ax = fig.add_subplot(111)
+ ax.set_title('click on points')
+
+ line, = ax.plot(np.random.rand(100), 'o', picker=5) # 5 points tolerance
+
+ def onpick(event):
+ thisline = event.artist
+ xdata = thisline.get_xdata()
+ ydata = thisline.get_ydata()
+ ind = event.ind
+ print 'onpick points:', zip(xdata[ind], ydata[ind])
+
+ fig.canvas.mpl_connect('pick_event', onpick)
+
+ plt.show()
+
+
+Picking Exercise
+----------------
+
+Create a data set of 100 arrays of 1000 Gaussian random numbers and
+compute the sample mean and standard deviation of each of them (hint:
+numpy arrays have a mean and std method) and make a xy marker plot of
+the 100 means vs the 100 standard deviations. Connect the line
+created by the plot command to the pick event, and plot the original
+time series of the data that generated the clicked on points. If more
+than one point is within the tolerance of the clicked on point, you
+can use multiple subplots to plot the multiple time series.
+
+Exercise solution::
+
+ """
+ compute the mean and stddev of 100 data sets and plot mean vs stddev.
+ When you click on one of the mu, sigma points, plot the raw data from
+ the dataset that generated the mean and stddev
+ """
+ import numpy as np
+ import ma...
[truncated message content] |
