diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html index f13aba4e53ca..b84cc6b519fe 100644 --- a/doc/_templates/indexsidebar.html +++ b/doc/_templates/indexsidebar.html @@ -5,7 +5,7 @@

News

to support matplotlib development.

-

matplotlib 1.0.0 is available for download. See what's new and tips on download. See what's new and tips on installing

@@ -64,7 +64,7 @@

Need help?

but it is a good idea to ping us on the mailing list too.

For details on what's new, see the detailed changelog or browse the source code. Anything that could +pathto('_static/CHANGELOG', 1) }}">changelog or browse the source code. Anything that could require changes to your existing codes is logged in the api changes file.

diff --git a/doc/api/afm_api.rst b/doc/api/afm_api.rst index 1d67b557e50b..3bffbd1c30a3 100644 --- a/doc/api/afm_api.rst +++ b/doc/api/afm_api.rst @@ -1,6 +1,6 @@ -************** -matplotlib afm -************** +********************************** +afm (Adobe Font Metrics interface) +********************************** :mod:`matplotlib.afm` diff --git a/doc/api/artist_api.rst b/doc/api/artist_api.rst index 0a84de2798fc..cb662d6c71ca 100644 --- a/doc/api/artist_api.rst +++ b/doc/api/artist_api.rst @@ -1,8 +1,8 @@ .. _artist-api: -******************* -matplotlib artists -******************* +******* +artists +******* .. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text :parts: 2 diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst index 236c62d1bd70..d8b5596c291f 100644 --- a/doc/api/axes_api.rst +++ b/doc/api/axes_api.rst @@ -1,6 +1,6 @@ -*************** -matplotlib axes -*************** +**** +axes +**** :mod:`matplotlib.axes` diff --git a/doc/api/axis_api.rst b/doc/api/axis_api.rst index ca2bf21c2458..426f0c873dfb 100644 --- a/doc/api/axis_api.rst +++ b/doc/api/axis_api.rst @@ -1,6 +1,6 @@ -*************** -matplotlib axis -*************** +**** +axis +**** :mod:`matplotlib.axis` diff --git a/doc/api/cbook_api.rst b/doc/api/cbook_api.rst index 4f262dbceb09..7c133ce8fdd1 100644 --- a/doc/api/cbook_api.rst +++ b/doc/api/cbook_api.rst @@ -1,6 +1,6 @@ -**************** -matplotlib cbook -**************** +***** +cbook +***** :mod:`matplotlib.cbook` diff --git a/doc/api/cm_api.rst b/doc/api/cm_api.rst index 3d1d6940214f..86b87cd4cda7 100644 --- a/doc/api/cm_api.rst +++ b/doc/api/cm_api.rst @@ -1,5 +1,5 @@ ************* -matplotlib cm +cm (colormap) ************* diff --git a/doc/api/collections_api.rst b/doc/api/collections_api.rst index 5d681a6931ab..8f3f92c4e756 100644 --- a/doc/api/collections_api.rst +++ b/doc/api/collections_api.rst @@ -1,6 +1,6 @@ -********************** -matplotlib collections -********************** +*********** +collections +*********** .. inheritance-diagram:: matplotlib.collections :parts: 2 diff --git a/doc/api/colorbar_api.rst b/doc/api/colorbar_api.rst index 55f3f4e769e4..26714dcebd38 100644 --- a/doc/api/colorbar_api.rst +++ b/doc/api/colorbar_api.rst @@ -1,6 +1,6 @@ -******************* -matplotlib colorbar -******************* +******** +colorbar +******** :mod:`matplotlib.colorbar` diff --git a/doc/api/colors_api.rst b/doc/api/colors_api.rst index dc93b275e960..766eb763f612 100644 --- a/doc/api/colors_api.rst +++ b/doc/api/colors_api.rst @@ -1,6 +1,6 @@ -***************** -matplotlib colors -***************** +****** +colors +****** :mod:`matplotlib.colors` diff --git a/doc/api/dates_api.rst b/doc/api/dates_api.rst index b65e87a06f21..6d9d8dd529b6 100644 --- a/doc/api/dates_api.rst +++ b/doc/api/dates_api.rst @@ -1,6 +1,6 @@ -**************** -matplotlib dates -**************** +***** +dates +***** .. inheritance-diagram:: matplotlib.dates :parts: 1 diff --git a/doc/api/figure_api.rst b/doc/api/figure_api.rst index 20c3a83912f2..27e86a1fee14 100644 --- a/doc/api/figure_api.rst +++ b/doc/api/figure_api.rst @@ -1,6 +1,6 @@ -***************** -matplotlib figure -***************** +****** +figure +****** :mod:`matplotlib.figure` diff --git a/doc/api/font_manager_api.rst b/doc/api/font_manager_api.rst index e4f07681ecc5..88d5fb38e5f9 100644 --- a/doc/api/font_manager_api.rst +++ b/doc/api/font_manager_api.rst @@ -1,6 +1,6 @@ -*********************** -matplotlib font_manager -*********************** +************ +font_manager +************ :mod:`matplotlib.font_manager` ============================== diff --git a/doc/api/gridspec_api.rst b/doc/api/gridspec_api.rst index 8f265c8ab9ed..d4771f02ebdd 100644 --- a/doc/api/gridspec_api.rst +++ b/doc/api/gridspec_api.rst @@ -1,6 +1,6 @@ -******************* -matplotlib gridspec -******************* +******** +gridspec +******** :mod:`matplotlib.gridspec` diff --git a/doc/api/index.rst b/doc/api/index.rst index 929c7bf0ac23..640cc82d410b 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -10,6 +10,7 @@ :Date: |today| .. toctree:: + :maxdepth: 1 api_changes.rst matplotlib_configuration_api.rst @@ -31,7 +32,8 @@ path_api.rst pyplot_api.rst nxutils_api.rst - spine_api.rst + spines_api.rst ticker_api.rst units_api.rst index_backend_api.rst + widgets_api.rst diff --git a/doc/api/index_backend_api.rst b/doc/api/index_backend_api.rst index efda381de865..8a3682630279 100644 --- a/doc/api/index_backend_api.rst +++ b/doc/api/index_backend_api.rst @@ -1,6 +1,6 @@ -******************* -matplotlib backends -******************* +******** +backends +******** .. toctree:: diff --git a/doc/api/mathtext_api.rst b/doc/api/mathtext_api.rst index e37b8b0aca19..689c0ade3aa5 100644 --- a/doc/api/mathtext_api.rst +++ b/doc/api/mathtext_api.rst @@ -1,6 +1,6 @@ -******************* -matplotlib mathtext -******************* +******** +mathtext +******** .. inheritance-diagram:: matplotlib.mathtext :parts: 1 diff --git a/doc/api/matplotlib_configuration_api.rst b/doc/api/matplotlib_configuration_api.rst index 19f21392e639..e8788289d162 100644 --- a/doc/api/matplotlib_configuration_api.rst +++ b/doc/api/matplotlib_configuration_api.rst @@ -1,6 +1,6 @@ -************************ -matplotlib configuration -************************ +************* +configuration +************* :mod:`matplotlib` diff --git a/doc/api/mlab_api.rst b/doc/api/mlab_api.rst index 28af7bd1ebfe..4e326b353a50 100644 --- a/doc/api/mlab_api.rst +++ b/doc/api/mlab_api.rst @@ -1,6 +1,6 @@ -**************** -matplotlib mlab -**************** +**** +mlab +**** :mod:`matplotlib.mlab` diff --git a/doc/api/nxutils_api.rst b/doc/api/nxutils_api.rst index 22743a33f3cd..6c17d8341370 100644 --- a/doc/api/nxutils_api.rst +++ b/doc/api/nxutils_api.rst @@ -1,9 +1,12 @@ - -******************* -matplotlib nxutils -******************* +******* +nxutils +******* :mod:`matplotlib.nxutils` =========================== .. automodule:: matplotlib.nxutils + :members: + :undoc-members: + :show-inheritance: + diff --git a/doc/api/path_api.rst b/doc/api/path_api.rst index 964a999a4076..d67bbb2536e4 100644 --- a/doc/api/path_api.rst +++ b/doc/api/path_api.rst @@ -1,6 +1,6 @@ -*************** -matplotlib path -*************** +**** +path +**** :mod:`matplotlib.path` diff --git a/doc/api/pyplot_api.rst b/doc/api/pyplot_api.rst index 9c4e837609e2..fe090eac87af 100644 --- a/doc/api/pyplot_api.rst +++ b/doc/api/pyplot_api.rst @@ -1,6 +1,6 @@ -***************** -matplotlib pyplot -***************** +****** +pyplot +****** :mod:`matplotlib.pyplot` diff --git a/doc/api/spine_api.rst b/doc/api/spines_api.rst similarity index 60% rename from doc/api/spine_api.rst rename to doc/api/spines_api.rst index 062b0aabe1ef..aeab960c0776 100644 --- a/doc/api/spine_api.rst +++ b/doc/api/spines_api.rst @@ -1,9 +1,9 @@ -***************** -matplotlib spine -***************** +****** +spines +****** -:mod:`matplotlib.spine` +:mod:`matplotlib.spines` ======================== .. automodule:: matplotlib.spines diff --git a/doc/api/ticker_api.rst b/doc/api/ticker_api.rst index 544eea10b431..12214161c330 100644 --- a/doc/api/ticker_api.rst +++ b/doc/api/ticker_api.rst @@ -1,6 +1,6 @@ -******************* -matplotlib ticker -******************* +****** +ticker +****** :mod:`matplotlib.ticker` diff --git a/doc/api/units_api.rst b/doc/api/units_api.rst index e7121c406aee..c29596eb3d3c 100644 --- a/doc/api/units_api.rst +++ b/doc/api/units_api.rst @@ -1,6 +1,6 @@ -***************** -matplotlib units -***************** +***** +units +***** :mod:`matplotlib.units` diff --git a/doc/api/widgets_api.rst b/doc/api/widgets_api.rst new file mode 100644 index 000000000000..edc196717988 --- /dev/null +++ b/doc/api/widgets_api.rst @@ -0,0 +1,12 @@ +******* +widgets +******* + + +:mod:`matplotlib.widgets` +========================= + +.. automodule:: matplotlib.widgets + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index 405248c88b7b..61cb232dbce8 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -372,6 +372,22 @@ please ignore it while we consolidate our testing to these locations.) .. _nose: http://somethingaboutorange.com/mrl/projects/nose/ +Requirements +------------ + +The following software is required to run the tests: + + - nose_, version 0.11.1 or later + + - `Python Imaging Library + `_ (to compare image + results) + + - `Ghostscript `_ (to render PDF + files) + + - `Inkscape `_ (to render SVG files) + Running the tests ----------------- diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst index 24f929711d48..dc3277d9b0f2 100644 --- a/doc/faq/installing_faq.rst +++ b/doc/faq/installing_faq.rst @@ -117,12 +117,18 @@ and build and install as usual with:: sudo apt-get build-dep python-matplotlib - This does not build matplotlib, but it does get the install the + If you are on Fedora/RedHat, you can get all the dependencies + required to build matplotlib by first installing ``yum-builddep`` + and then running:: + + su -c "yum-builddep python-matplotlib" + + This does not build matplotlib, but it does get all of the build dependencies, which will make building from source easier. If you want to be able to follow the development branch as it changes just replace -the last step with (Make sure you have **setuptools** installed):: +the last step with (make sure you have **setuptools** installed):: > python setupegg.py develop @@ -138,11 +144,6 @@ setupegg.py develop` command again to compile them. There is more information on :ref:`using git ` in the developer docs. -Install from git -================ - -See :ref:`using-git`. - Backends ======== diff --git a/doc/sphinxext/gen_rst.py b/doc/sphinxext/gen_rst.py index fe600fb776c0..2502076c9f93 100644 --- a/doc/sphinxext/gen_rst.py +++ b/doc/sphinxext/gen_rst.py @@ -111,7 +111,7 @@ def generate_example_rst(app): rstfile = '%s.rst'%basename outrstfile = os.path.join(rstdir, rstfile) - fhsubdirIndex.write(' %s\n'%rstfile) + fhsubdirIndex.write(' %s <%s>\n'%(os.path.basename(basename),rstfile)) if not out_of_date(fullpath, outrstfile): continue diff --git a/doc/users/installing.rst b/doc/users/installing.rst index 9a7c33578e8d..8ecc1f0f87db 100644 --- a/doc/users/installing.rst +++ b/doc/users/installing.rst @@ -9,7 +9,7 @@ way depends on what operating system you are using, what you already have installed, and how you want to use it. To avoid wading through all the details (and potential complications) on this page, the easiest thing for you to do is use one of the pre-packaged python -distributions that already provide matplotlib built in. The Enthought +distributions that already provide matplotlib built-in. The Enthought Python Distribution `(EPD) `_ for Windows, OS X or Redhat is an excellent choice that "just works" out of the box. @@ -17,7 +17,7 @@ Another excellent alternative for Windows users is `Python (x, y) `_ which tends to be updated a bit more frequently. Both of these packages include matplotlib and pylab, and *lots* of other useful tools. matplotlib is also packaged -for pretty much every major linux distribution, so if you are on linux +for almost every major linux distribution. So if you are on linux, your package manager will probably provide matplotlib prebuilt. One single click installer and you are done. @@ -34,7 +34,7 @@ but OS X users please read :ref:`which-python-for-osx`. Once you have python up and running, you will need to install `numpy `_. -numpy provides high performance array data structures and mathematical +numpy provides high-performance array data structures and mathematical functions, and is a requirement for matplotlib. You can test your progress:: @@ -44,9 +44,9 @@ progress:: matplotlib requires numpy version 1.1 or later. Although it is not a requirement to use matplotlib, we strongly encourage you to install `ipython `_, which is an interactive -shell for python that is matplotlib aware. +shell for python that is matplotlib-aware. -Next we need to get matplotlib installed. We provide prebuilt +Next, we need to get matplotlib installed. We provide prebuilt binaries for OS X and Windows on the matplotlib `download `_ page. Click on the latest release of the "matplotlib" package, choose your python @@ -55,7 +55,7 @@ should be good to go. If you have any problems, please check the :ref:`installing-faq`, google around a little bit, and post a question the `mailing list `_. If -you are on debian/unbuntu linux, it suffices to do:: +you are on debian/ubuntu linux, it suffices to do:: > sudo apt-get install python-matplotlib diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index 9c8ef0e34b30..3db1e2835228 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -1292,10 +1292,9 @@ def _initialize_x_y(self, z): Use keyword args to control colors, linewidth, origin, cmap ... see below for more details. - *X*, *Y*, and *Z* must be arrays with the same dimensions. - - *Z* may be a masked array, but filled contouring may not - handle internal masked regions correctly. + *X* and *Y* must both be 2-D with the same shape as *Z*, or they + must both be 1-D such that ``len(X)`` is the number of columns in + *Z* and ``len(Y)`` is the number of rows in *Z*. ``C = contour(...)`` returns a :class:`~matplotlib.contour.QuadContourSet` object. diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 15d53290d3ca..f1dfbe579545 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -129,13 +129,12 @@ class Figure(Artist): the callback will be called with ``func(fig)`` where fig is the :class:`Figure` instance. - The figure patch is drawn by a the attribute - *patch* - a :class:`matplotlib.patches.Rectangle` instance + The figure patch is drawn by a + :class:`matplotlib.patches.Rectangle` instance *suppressComposite* - for multiple figure images, the figure will make composite + For multiple figure images, the figure will make composite images depending on the renderer option_image_nocomposite function. If suppressComposite is True|False, this will override the renderer @@ -165,7 +164,7 @@ def __init__(self, *linewidth* the figure patch edge linewidth; the default linewidth of the frame *frameon* - if False, suppress drawing the figure frame + if ``False``, suppress drawing the figure frame *subplotpars* a :class:`SubplotParams` instance, defaults to rc """ diff --git a/lib/matplotlib/mlab.py b/lib/matplotlib/mlab.py index 5c757bd5a667..37d755f164b2 100644 --- a/lib/matplotlib/mlab.py +++ b/lib/matplotlib/mlab.py @@ -427,7 +427,7 @@ def specgram(x, NFFT=256, Fs=2, detrend=detrend_none, window=window_hanning, noverlap=128, pad_to=None, sides='default', scale_by_freq=None): """ Compute a spectrogram of data in *x*. Data are split into *NFFT* - length segements and the PSD of each section is computed. The + length segments and the PSD of each section is computed. The windowing function *window* is applied to each segment, and the amount of overlap of each segment is specified with *noverlap*. diff --git a/lib/matplotlib/scale.py b/lib/matplotlib/scale.py index 4e85632061b7..b789f463950d 100644 --- a/lib/matplotlib/scale.py +++ b/lib/matplotlib/scale.py @@ -244,9 +244,9 @@ def __init__(self, axis, **kwargs): *subsx*/*subsy*: Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 - scale: ``[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]`` + scale: ``[2, 3, 4, 5, 6, 7, 8, 9]`` - will place 10 logarithmically spaced minor ticks between + will place 8 logarithmically spaced minor ticks between each major tick. """ if axis.axis_name == 'x': @@ -373,9 +373,9 @@ def __init__(self, axis, **kwargs): *subsx*/*subsy*: Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 - scale: ``[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]`` + scale: ``[2, 3, 4, 5, 6, 7, 8, 9]`` - will place 10 logarithmically spaced minor ticks between + will place 8 logarithmically spaced minor ticks between each major tick. """ if axis.axis_name == 'x': diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py index 28aedf0e234b..ae258b4df970 100644 --- a/lib/matplotlib/widgets.py +++ b/lib/matplotlib/widgets.py @@ -1,10 +1,12 @@ """ GUI Neutral widgets +=================== -All of these widgets require you to predefine an Axes instance and -pass that as the first arg. matplotlib doesn't try to be too smart in -layout -- you have to figure out how wide and tall you want your Axes -to be to accommodate your widget. +Widgets that are designed to work for any of the GUI backends. +All of these widgets require you to predefine an :class:`matplotlib.axes.Axes` +instance and pass that as the first arg. matplotlib doesn't try to +be too smart with respect to layout -- you will have to figure out how +wide and tall you want your Axes to be to accommodate your widget. """ import numpy as np @@ -16,17 +18,19 @@ class LockDraw: """ - some widgets, like the cursor, draw onto the canvas, and this is not + Some widgets, like the cursor, draw onto the canvas, and this is not desirable under all circumstaces, like when the toolbar is in zoom-to-rect mode and drawing a rectangle. The module level "lock" allows someone to grab the lock and prevent other widgets from - drawing. Use matplotlib.widgets.lock(someobj) to pr + drawing. Use ``matplotlib.widgets.lock(someobj)`` to pr """ + # FIXME: This docstring ends abruptly without... + def __init__(self): self._owner = None def __call__(self, o): - 'reserve the lock for o' + 'reserve the lock for *o*' if not self.available(o): raise ValueError('already locked') self._owner = o @@ -38,23 +42,22 @@ def release(self, o): self._owner = None def available(self, o): - 'drawing is available to o' + 'drawing is available to *o*' return not self.locked() or self.isowner(o) def isowner(self, o): - 'o owns the lock' + 'Return True if *o* owns this lock' return self._owner is o def locked(self): - 'the lock is held' + 'Return True if the lock is currently held by an owner' return self._owner is not None class Widget: """ - OK, I couldn't resist; abstract base class for mpl GUI neutral - widgets + Abstract base class for GUI neutral widgets """ drawon = True eventson = True @@ -68,30 +71,41 @@ class Button(Widget): The following attributes are accesible - ax - the Axes the button renders into - label - a text.Text instance - color - the color of the button when not hovering - hovercolor - the color of the button when hovering + *ax* + The :class:`matplotlib.axes.Axes` the button renders into. + + *label* + A :class:`matplotlib.text.Text` instance. + + *color* + The color of the button when not hovering. - Call "on_clicked" to connect to the button + *hovercolor* + The color of the button when hovering. + + Call :meth:`on_clicked` to connect to the button """ def __init__(self, ax, label, image=None, color='0.85', hovercolor='0.95'): """ - ax is the Axes instance the button will be placed into - - label is a string which is the button text + *ax* + The :class:`matplotlib.axes.Axes` instance the button + will be placed into. - image if not None, is an image to place in the button -- can - be any legal arg to imshow (numpy array, matplotlib Image - instance, or PIL image) + *label* + The button text. Accepts string. - color is the color of the button when not activated + *image* + The image to place in the button, if not ``None``. + Can be any legal arg to imshow (numpy array, + matplotlib Image instance, or PIL image). - hovercolor is the color of the button when the mouse is over - it + *color* + The color of the button when not activated + *hovercolor* + The color of the button when the mouse is over it """ if image is not None: ax.imshow(image) @@ -148,7 +162,7 @@ def _motion(self, event): def on_clicked(self, func): """ - When the button is clicked, call this func with event + When the button is clicked, call this *func* with event A connection id is returned which can be used to disconnect """ @@ -158,7 +172,7 @@ def on_clicked(self, func): return cid def disconnect(self, cid): - 'remove the observer with connection id cid' + 'remove the observer with connection id *cid*' try: del self.observers[cid] except KeyError: pass @@ -169,42 +183,62 @@ class Slider(Widget): A slider representing a floating point range The following attributes are defined - ax : the slider axes.Axes instance - val : the current slider value - vline : a Line2D instance representing the initial value - poly : A patch.Polygon instance which is the slider - valfmt : the format string for formatting the slider text - label : a text.Text instance, the slider label - closedmin : whether the slider is closed on the minimum - closedmax : whether the slider is closed on the maximum - slidermin : another slider - if not None, this slider must be > slidermin - slidermax : another slider - if not None, this slider must be < slidermax - dragging : allow for mouse dragging on slider - - Call on_changed to connect to the slider event + *ax* : the slider :class:`matplotlib.axes.Axes` instance + + *val* : the current slider value + + *vline* : a :class:`matplotlib.lines.Line2D` instance + representing the initial value of the slider + + *poly* : A :class:`matplotlib.patches.Polygon` instance + which is the slider knob + + *valfmt* : the format string for formatting the slider text + + *label* : a :class:`matplotlib.text.Text` instance + for the slider label + + *closedmin* : whether the slider is closed on the minimum + + *closedmax* : whether the slider is closed on the maximum + + *slidermin* : another slider - if not ``None``, this slider must be + greater than *slidermin* + + *slidermax* : another slider - if not ``None``, this slider must be + less than *slidermax* + + *dragging* : allow for mouse dragging on slider + + Call :meth:`on_changed` to connect to the slider event """ def __init__(self, ax, label, valmin, valmax, valinit=0.5, valfmt='%1.2f', closedmin=True, closedmax=True, slidermin=None, slidermax=None, dragging=True, **kwargs): """ - Create a slider from valmin to valmax in axes ax; + Create a slider from *valmin* to *valmax* in axes *ax* - valinit - the slider initial position + *valinit* + The slider initial position - label - the slider label + *label* + The slider label - valfmt - used to format the slider value + *valfmt* + Used to format the slider value - closedmin and closedmax - indicate whether the slider interval is closed + *closedmin* and *closedmax* + Indicate whether the slider interval is closed - slidermin and slidermax - be used to contrain the value of - this slider to the values of other sliders. + *slidermin* and *slidermax* + Used to contrain the value of this slider to the values + of other sliders. - additional kwargs are passed on to self.poly which is the - matplotlib.patches.Rectangle which draws the slider. See the - matplotlib.patches.Rectangle documentation for legal property - names (eg facecolor, edgecolor, alpha, ...) - """ + additional kwargs are passed on to ``self.poly`` which is the + :class:`matplotlib.patches.Rectangle` which draws the slider + knob. See the :class:`matplotlib.patches.Rectangle` documentation + valid property names (e.g., *facecolor*, *edgecolor*, *alpha*, ...) + """ self.ax = ax self.valmin = valmin @@ -294,7 +328,7 @@ def set_val(self, val): def on_changed(self, func): """ - When the slider valud is changed, call this func with the new + When the slider value is changed, call *func* with the new slider position A connection id is returned which can be used to disconnect @@ -305,7 +339,7 @@ def on_changed(self, func): return cid def disconnect(self, cid): - 'remove the observer with connection id cid' + 'remove the observer with connection id *cid*' try: del self.observers[cid] except KeyError: pass @@ -322,24 +356,33 @@ class CheckButtons(Widget): The following attributes are exposed - ax - the Axes instance the buttons are in - labels - a list of text.Text instances - lines - a list of (line1, line2) tuples for the x's in the check boxes. - These lines exist for each box, but have set_visible(False) when - box is not checked - rectangles - a list of patch.Rectangle instances + *ax* + The :class:`matplotlib.axes.Axes` instance the buttons are + located in + + *labels* + List of :class:`matplotlib.text.Text` instances - Connect to the CheckButtons with the on_clicked method + *lines* + List of (line1, line2) tuples for the x's in the check boxes. + These lines exist for each box, but have ``set_visible(False)`` + when its box is not checked. + + *rectangles* + List of :class:`matplotlib.patches.Rectangle` instances + + Connect to the CheckButtons with the :meth:`on_clicked` method """ def __init__(self, ax, labels, actives): """ - Add check buttons to axes.Axes instance ax - - labels is a len(buttons) list of labels as strings + Add check buttons to :class:`matplotlib.axes.Axes` instance *ax* - actives is a len(buttons) list of booleans indicating whether - the button is active + *labels* + A len(buttons) list of labels as strings + *actives* + A len(buttons) list of booleans indicating whether + the button is active """ ax.set_xticks([]) @@ -420,7 +463,7 @@ def _clicked(self, event): def on_clicked(self, func): """ - When the button is clicked, call this func with button label + When the button is clicked, call *func* with button label A connection id is returned which can be used to disconnect """ @@ -430,7 +473,7 @@ def on_clicked(self, func): return cid def disconnect(self, cid): - 'remove the observer with connection id cid' + 'remove the observer with connection id *cid*' try: del self.observers[cid] except KeyError: pass @@ -441,22 +484,32 @@ class RadioButtons(Widget): The following attributes are exposed - ax - the Axes instance the buttons are in - activecolor - the color of the button when clicked - labels - a list of text.Text instances - circles - a list of patch.Circle instances + *ax* + The :class:`matplotlib.axes.Axes` instance the buttons are in + + *activecolor* + The color of the button when clicked + + *labels* + A list of :class:`matplotlib.text.Text` instances - Connect to the RadioButtons with the on_clicked method + *circles* + A list of :class:`matplotlib.patches.Circle` instances + + Connect to the RadioButtons with the :meth:`on_clicked` method """ def __init__(self, ax, labels, active=0, activecolor='blue'): """ - Add radio buttons to axes.Axes instance ax + Add radio buttons to :class:`matplotlib.axes.Axes` instance *ax* - labels is a len(buttons) list of labels as strings + *labels* + A len(buttons) list of labels as strings - active is the index into labels for the button that is active + *active* + The index into labels for the button that is active - activecolor is the color of the button when clicked + *activecolor* + The color of the button when clicked """ self.activecolor = activecolor @@ -529,7 +582,7 @@ def inside(p): def on_clicked(self, func): """ - When the button is clicked, call this func with button label + When the button is clicked, call *func* with button label A connection id is returned which can be used to disconnect """ @@ -539,7 +592,7 @@ def on_clicked(self, func): return cid def disconnect(self, cid): - 'remove the observer with connection id cid' + 'remove the observer with connection id *cid*' try: del self.observers[cid] except KeyError: pass @@ -547,16 +600,20 @@ def disconnect(self, cid): class SubplotTool(Widget): """ - A tool to adjust to subplot params of fig + A tool to adjust to subplot params of a :class:`matplotlib.figure.Figure` """ def __init__(self, targetfig, toolfig): """ - targetfig is the figure to adjust + *targetfig* + The figure instance to adjust - toolfig is the figure to embed the the subplot tool into. If - None, a default pylab figure will be created. If you are - using this from the GUI + *toolfig* + The figure instance to embed the subplot tool into. If + None, a default figure will be created. If you are using + this from the GUI """ + # FIXME: The docstring seems to just abruptly end without... + self.targetfig = targetfig toolfig.subplots_adjust(left=0.2, right=0.9) @@ -682,18 +739,24 @@ class Cursor: the pointer. You can turn off the hline or vline spectively with the attributes - horizOn =True|False: controls visibility of the horizontal line - vertOn =True|False: controls visibility of the horizontal line + *horizOn* + Controls the visibility of the horizontal line + + *vertOn* + Controls the visibility of the horizontal line - And the visibility of the cursor itself with visible attribute + and the visibility of the cursor itself with the *visible* attribute """ def __init__(self, ax, useblit=False, **lineprops): """ - Add a cursor to ax. If useblit=True, use the backend - dependent blitting features for faster updates (GTKAgg only - now). lineprops is a dictionary of line properties. See - examples/widgets/cursor.py. + Add a cursor to *ax*. If ``useblit=True``, use the backend- + dependent blitting features for faster updates (GTKAgg + only for now). *lineprops* is a dictionary of line properties. + + .. plot :: mpl_examples/widgets/cursor.py """ + # TODO: Is the GTKAgg limitation still true? + self.ax = ax self.canvas = ax.figure.canvas @@ -760,22 +823,24 @@ class MultiCursor: """ Provide a vertical line cursor shared between multiple axes - from matplotlib.widgets import MultiCursor - from pylab import figure, show, nx + Example usage:: - t = nx.arange(0.0, 2.0, 0.01) - s1 = nx.sin(2*nx.pi*t) - s2 = nx.sin(4*nx.pi*t) - fig = figure() - ax1 = fig.add_subplot(211) - ax1.plot(t, s1) + from matplotlib.widgets import MultiCursor + from pylab import figure, show, nx + t = nx.arange(0.0, 2.0, 0.01) + s1 = nx.sin(2*nx.pi*t) + s2 = nx.sin(4*nx.pi*t) + fig = figure() + ax1 = fig.add_subplot(211) + ax1.plot(t, s1) - ax2 = fig.add_subplot(212, sharex=ax1) - ax2.plot(t, s2) - multi = MultiCursor(fig.canvas, (ax1, ax2), color='r', lw=1) - show() + ax2 = fig.add_subplot(212, sharex=ax1) + ax2.plot(t, s2) + + multi = MultiCursor(fig.canvas, (ax1, ax2), color='r', lw=1) + show() """ def __init__(self, canvas, axes, useblit=True, **lineprops): @@ -833,40 +898,39 @@ class SpanSelector: """ Select a min/max range of the x or y axes for a matplotlib Axes - Example usage: + Example usage:: - ax = subplot(111) - ax.plot(x,y) + ax = subplot(111) + ax.plot(x,y) - def onselect(vmin, vmax): - print vmin, vmax - span = SpanSelector(ax, onselect, 'horizontal') + def onselect(vmin, vmax): + print vmin, vmax + span = SpanSelector(ax, onselect, 'horizontal') - onmove_callback is an optional callback that will be called on mouse move - with the span range + *onmove_callback* is an optional callback that is called on mouse + move within the span range """ - def __init__(self, ax, onselect, direction, minspan=None, useblit=False, rectprops=None, onmove_callback=None): + def __init__(self, ax, onselect, direction, minspan=None, useblit=False, + rectprops=None, onmove_callback=None): """ - Create a span selector in ax. When a selection is made, clear - the span and call onselect with + Create a span selector in *ax*. When a selection is made, clear + the span and call *onselect* with:: - onselect(vmin, vmax) + onselect(vmin, vmax) and clear the span. - direction must be 'horizontal' or 'vertical' + *direction* must be 'horizontal' or 'vertical' - If minspan is not None, ignore events smaller than minspan + If *minspan* is not ``None``, ignore events smaller than *minspan* - The span rect is drawn with rectprops; default + The span rectangle is drawn with *rectprops*; default:: rectprops = dict(facecolor='red', alpha=0.5) - set the visible attribute to False if you want to turn off + Set the visible attribute to ``False`` if you want to turn off the functionality of the span selector - - """ if rectprops is None: rectprops = dict(facecolor='red', alpha=0.5) @@ -929,7 +993,7 @@ def update_background(self, event): def ignore(self, event): - 'return True if event should be ignored' + 'return ``True`` if *event* should be ignored' return event.inaxes!=self.ax or not self.visible or event.button !=1 def press(self, event): @@ -966,7 +1030,10 @@ def release(self, event): return False def update(self): - 'draw using newfangled blit or oldfangled draw depending on useblit' + """ + Draw using newfangled blit or oldfangled draw depending + on *useblit* + """ if self.useblit: if self.background is not None: self.canvas.restore_region(self.background) @@ -1057,38 +1124,41 @@ def __init__(self, ax, onselect, drawtype='box', button=None): """ - Create a selector in ax. When a selection is made, clear - the span and call onselect with + Create a selector in *ax*. When a selection is made, clear + the span and call onselect with:: onselect(pos_1, pos_2) - and clear the drawn box/line. There pos_i are arrays of length 2 - containing the x- and y-coordinate. + and clear the drawn box/line. The ``pos_1`` and ``pos_2`` are + arrays of length 2 containing the x- and y-coordinate. + + If *minspanx* is not ``None`` then events smaller than *minspanx* + in x direction are ignored (it's the same for y). - If minspanx is not None then events smaller than minspanx - in x direction are ignored(it's the same for y). + The rectangle is drawn with *rectprops*; default:: - The rect is drawn with rectprops; default rectprops = dict(facecolor='red', edgecolor = 'black', alpha=0.5, fill=False) - The line is drawn with lineprops; default + The line is drawn with *lineprops*; default:: + lineprops = dict(color='black', linestyle='-', linewidth = 2, alpha=0.5) - Use type if you want the mouse to draw a line, a box or nothing - between click and actual position ny setting + Use *drawtype* if you want the mouse to draw a line, + a box or nothing between click and actual position by setting - drawtype = 'line', drawtype='box' or drawtype = 'none'. + ``drawtype = 'line'``, ``drawtype='box'`` or ``drawtype = 'none'``. - spancoords is one of 'data' or 'pixels'. If 'data', minspanx - and minspanx will be interpreted in the same coordinates as - the x and ya axis, if 'pixels', they are in pixels + *spancoords* is one of 'data' or 'pixels'. If 'data', *minspanx* + and *minspanx* will be interpreted in the same coordinates as + the x and y axis. If 'pixels', they are in pixels. - button is a list of integers indicating which mouse buttons should + *button* is a list of integers indicating which mouse buttons should be used for rectangle selection. You can also specify a single - integer if only a single button is desired. Default is None, which - does not limit which button can be used. + integer if only a single button is desired. Default is ``None``, + which does not limit which button can be used. + Note, typically: 1 = left mouse button 2 = center mouse button (scroll wheel) @@ -1151,7 +1221,7 @@ def update_background(self, event): def ignore(self, event): - 'return True if event should be ignored' + 'return ``True`` if *event* should be ignored' # If RectangleSelector is not active : if not self.active: return True @@ -1217,12 +1287,14 @@ def release(self, event): spany = ymax - ymin xproblems = self.minspanx is not None and spanx