|
From: <jd...@us...> - 2008-06-09 21:01:35
|
Revision: 5445
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5445&view=rev
Author: jdh2358
Date: 2008-06-09 14:01:33 -0700 (Mon, 09 Jun 2008)
Log Message:
-----------
reorg text users guide, added annotations unit
Modified Paths:
--------------
trunk/matplotlib/doc/devel/outline.rst
trunk/matplotlib/doc/faq/howto_faq.rst
trunk/matplotlib/doc/users/event_handling.rst
trunk/matplotlib/doc/users/index.rst
trunk/matplotlib/doc/users/pyplot_tutorial.rst
trunk/matplotlib/doc/users/usetex.rst
Added Paths:
-----------
trunk/matplotlib/doc/users/annotations.rst
trunk/matplotlib/doc/users/figures/annotation_basic.py
trunk/matplotlib/doc/users/figures/annotation_polar.py
trunk/matplotlib/doc/users/figures/pyplot_annotate.py
Modified: trunk/matplotlib/doc/devel/outline.rst
===================================================================
--- trunk/matplotlib/doc/devel/outline.rst 2008-06-09 20:13:23 UTC (rev 5444)
+++ trunk/matplotlib/doc/devel/outline.rst 2008-06-09 21:01:33 UTC (rev 5445)
@@ -23,15 +23,15 @@
working with data John has author Darren
custom ticking ? no author ?
masked data Eric has author ?
-text ? no author ?
patches ? no author ?
legends ? no author ?
animation John has author ?
collections ? no author ?
-mathtext Michael in review John
+text - mathtext Michael in review John
+text - usetex Darren submitted ?
+text - annotations John submitted ?
fonts et al Michael ? no author Darren
pyplot tut John submitted Eric
-usetex Darren submitted ?
configuration Darren preliminary ?
win32 install Charlie ? no author Darren
os x install Charlie ? no author ?
Modified: trunk/matplotlib/doc/faq/howto_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/howto_faq.rst 2008-06-09 20:13:23 UTC (rev 5444)
+++ trunk/matplotlib/doc/faq/howto_faq.rst 2008-06-09 21:01:33 UTC (rev 5445)
@@ -104,28 +104,28 @@
there is not data. The solution is to pass in some proxy x-data, eg
evenly sampled indicies, and then use a custom formatter to format
these as dates. The example below shows how to use an 'index formatter'
-to achieve the desired plot
+to achieve the desired plot::
- import numpy as np
- import matplotlib.pyplot as plt
- import matplotlib.mlab as mlab
- import matplotlib.ticker as ticker
+ import numpy as np
+ import matplotlib.pyplot as plt
+ import matplotlib.mlab as mlab
+ import matplotlib.ticker as ticker
- r = mlab.csv2rec('../data/aapl.csv')
- r.sort()
- r = r[-30:] # get the last 30 days
+ r = mlab.csv2rec('../data/aapl.csv')
+ r.sort()
+ r = r[-30:] # get the last 30 days
- N = len(r)
- ind = np.arange(N) # the evenly spaced plot indices
+ N = len(r)
+ ind = np.arange(N) # the evenly spaced plot indices
- def format_date(x, pos=None):
- thisind = np.clip(int(x+0.5), 0, N-1)
- return r.date[thisind].strftime('%Y-%m-%d')
+ def format_date(x, pos=None):
+ thisind = np.clip(int(x+0.5), 0, N-1)
+ return r.date[thisind].strftime('%Y-%m-%d')
- fig = plt.figure()
- ax = fig.add_subplot(111)
- ax.plot(ind, r.adj_close, 'o-')
- ax.xaxis.set_major_formatter(ticker.FuncFormatter(format_date))
- fig.autofmt_xdate()
+ fig = plt.figure()
+ ax = fig.add_subplot(111)
+ ax.plot(ind, r.adj_close, 'o-')
+ ax.xaxis.set_major_formatter(ticker.FuncFormatter(format_date))
+ fig.autofmt_xdate()
- plt.show()
+ plt.show()
Added: trunk/matplotlib/doc/users/annotations.rst
===================================================================
--- trunk/matplotlib/doc/users/annotations.rst (rev 0)
+++ trunk/matplotlib/doc/users/annotations.rst 2008-06-09 21:01:33 UTC (rev 5445)
@@ -0,0 +1,83 @@
+.. _annotations-tutorial:
+
+Annotating text
+===============
+
+The uses of the basic :func:`~matplotlib.pyplot.text` command above
+place text at an arbitrary position on the Axes. A common use case of
+text is to annotate some feature of the plot, and the
+:func:`~matplotlib.Axes.annotate` method provides helper functionality
+to make annotations easy. In an annotation, there are two points to
+consider: the location being annotated represented by the argument
+``xy`` and the location of the text ``xytext``. Both of these
+arguments are ``(x,y)`` tuples.
+
+.. literalinclude:: figures/annotation_basic.py
+
+.. image:: figures/annotation_basic.png
+ :scale: 50
+
+In this example, both the ``xy`` (arrow tip) and ``xytext`` locations
+(text location) are in data coordinates. There are a variety of other
+coordinate systems one can choose -- you can specify the coordinate
+system of ``xy`` and ``xytext`` with one of the following strings for
+``xycoords`` and ``textcoords`` (default is 'data')
+
+==================== ====================================================
+argument coordinate system
+==================== ====================================================
+ 'figure points' points from the lower left corner of the figure
+ 'figure pixels' pixels from the lower left corner of the figure
+ 'figure fraction' 0,0 is lower left of figure and 1,1 is upper, right
+ 'axes points' points from lower left corner of axes
+ 'axes pixels' pixels from lower left corner of axes
+ 'axes fraction' 0,1 is lower left of axes and 1,1 is upper right
+ 'data' use the axes data coordinate system
+==================== ====================================================
+
+For example to place the text coordinates in fractional axes
+coordinates, one could do::
+
+ ax.annotate('local max', xy=(3, 1), xycoords='data',
+ xytext=(0.8, 0.95), textcoords='axes fraction',
+ arrowprops=dict(facecolor='black', shrink=0.05),
+ horizontalalignment='right', verticalalignment='top',
+ )
+
+For physical coordinate systems (points or pixels) the origin is the
+(bottom, left) of the figure or axes. If the value is negative,
+however, the origin is from the (right, top) of the figure or axes,
+analogous to negative indexing of sequences.
+
+Optionally, you can specify arrow properties which draws an arrow
+from the text to the annotated point by giving a dictionary of arrow
+properties in the optional keyword argument ``arrowprops``.
+
+
+==================== ===========================================================================
+``arrowprops`` key description
+==================== ===========================================================================
+width the width of the arrow in points
+frac the fraction of the arrow length occupied by the head
+headwidth the width of the base of the arrow head in points
+shrink move the tip and base some percent away from the annotated point and text
+\*\*kwargs any key for :class:`matplotlib.patches.Polygon`, eg ``facecolor``
+==================== ===========================================================================
+
+
+In the example below, the ``xy`` point is in native coordinates
+(``xycoords`` defaults to 'data'). For a polar axes, this is in
+(theta, radius) space. The text in this example is placed in the
+fractional figure coordinate system. :class:`matplotlib.text.Text`
+keyword args like ``horizontalalignment``, ``verticalalignment`` and
+``fontsize are passed from the `~matplotlib.Axes.annotate` to the
+``Text`` instance
+
+.. literalinclude:: figures/annotation_polar.py
+
+.. image:: figures/annotation_polar.png
+ :scale: 50
+
+See the `annotations demo
+<http://matplotlib.sf.net/examples/pylab_examples/annotation_demo.py>`_ for more
+examples.
Modified: trunk/matplotlib/doc/users/event_handling.rst
===================================================================
--- trunk/matplotlib/doc/users/event_handling.rst 2008-06-09 20:13:23 UTC (rev 5444)
+++ trunk/matplotlib/doc/users/event_handling.rst 2008-06-09 21:01:33 UTC (rev 5445)
@@ -1,8 +1,8 @@
.. _event-handling-tutorial:
-***********************************
-Event Handling and Picking Tutorial
-***********************************
+**************************
+Event handling and picking
+**************************
matplotlib works with 5 user interface toolkits (wxpython, tkinter,
qt, gtk and fltk) and in order to support features like interactive
Added: trunk/matplotlib/doc/users/figures/annotation_basic.py
===================================================================
--- trunk/matplotlib/doc/users/figures/annotation_basic.py (rev 0)
+++ trunk/matplotlib/doc/users/figures/annotation_basic.py 2008-06-09 21:01:33 UTC (rev 5445)
@@ -0,0 +1,16 @@
+import numpy as np
+import matplotlib.pyplot as plt
+
+fig = plt.figure()
+ax = fig.add_subplot(111)
+
+t = np.arange(0.0, 5.0, 0.01)
+s = np.cos(2*np.pi*t)
+line, = ax.plot(t, s, lw=2)
+
+ax.annotate('local max', xy=(2, 1), xytext=(3, 1.5),
+ arrowprops=dict(facecolor='black', shrink=0.05),
+ )
+
+ax.set_ylim(-2,2)
+plt.show()
Added: trunk/matplotlib/doc/users/figures/annotation_polar.py
===================================================================
--- trunk/matplotlib/doc/users/figures/annotation_polar.py (rev 0)
+++ trunk/matplotlib/doc/users/figures/annotation_polar.py 2008-06-09 21:01:33 UTC (rev 5445)
@@ -0,0 +1,21 @@
+import numpy as np
+import matplotlib.pyplot as plt
+
+fig = plt.figure()
+ax = fig.add_subplot(111, polar=True)
+r = np.arange(0,1,0.001)
+theta = 2*2*np.pi*r
+line, = ax.plot(theta, r, color='#ee8d18', lw=3)
+
+ind = 800
+thisr, thistheta = r[ind], theta[ind]
+ax.plot([thistheta], [thisr], 'o')
+ax.annotate('a polar annotation',
+ xy=(thistheta, thisr), # theta, radius
+ xytext=(0.05, 0.05), # fraction, fraction
+ textcoords='figure fraction',
+ arrowprops=dict(facecolor='black', shrink=0.05),
+ horizontalalignment='left',
+ verticalalignment='bottom',
+ )
+plt.show()
Added: trunk/matplotlib/doc/users/figures/pyplot_annotate.py
===================================================================
--- trunk/matplotlib/doc/users/figures/pyplot_annotate.py (rev 0)
+++ trunk/matplotlib/doc/users/figures/pyplot_annotate.py 2008-06-09 21:01:33 UTC (rev 5445)
@@ -0,0 +1,15 @@
+import numpy as np
+import matplotlib.pyplot as plt
+
+ax = plt.subplot(111)
+
+t = np.arange(0.0, 5.0, 0.01)
+s = np.cos(2*np.pi*t)
+line, = plt.plot(t, s, lw=2)
+
+plt.annotate('local max', xy=(2, 1), xytext=(3, 1.5),
+ arrowprops=dict(facecolor='black', shrink=0.05),
+ )
+
+plt.ylim(-2,2)
+plt.show()
Modified: trunk/matplotlib/doc/users/index.rst
===================================================================
--- trunk/matplotlib/doc/users/index.rst 2008-06-09 20:13:23 UTC (rev 5444)
+++ trunk/matplotlib/doc/users/index.rst 2008-06-09 21:01:33 UTC (rev 5445)
@@ -11,11 +11,12 @@
intro.rst
pyplot_tutorial.rst
- mathtext.rst
navigation_toolbar.rst
customizing.rst
+ index_text.rst
artists.rst
event_handling.rst
- usetex.rst
+
+
Modified: trunk/matplotlib/doc/users/pyplot_tutorial.rst
===================================================================
--- trunk/matplotlib/doc/users/pyplot_tutorial.rst 2008-06-09 20:13:23 UTC (rev 5444)
+++ trunk/matplotlib/doc/users/pyplot_tutorial.rst 2008-06-09 21:01:33 UTC (rev 5445)
@@ -273,4 +273,46 @@
+Using mathematical expressions in text
+--------------------------------------
+matplotlib accepts TeX equation expressions in any text expression.
+For example to write the expression :math:`\sigma_i=15` in the title,
+you can write a TeX expression surrounded by dollar signs::
+
+ plt.title(r'$\sigma_i=15$')
+
+The ``r`` preceeding the title string is important -- it signifies
+that the string is a *raw* string and not to treate backslashes and
+python escapes. matplotlib has a built-in TeX expression parser and
+layout engine, and ships its own math fonts -- for details see
+:ref:`mathtext-tutorial`. Thus you can use mathematical text across platforms
+without requiring a TeX installation. For those who have LaTeX and
+dvipng installed, you can also use LaTeX to format your text and
+incorporate the output directly into your display figures or saved
+postscript -- see :ref:`usetex-tutorial`.
+
+
+Annotating text
+---------------
+
+The uses of the basic :func:`~matplotlib.pyplot.text` command above
+place text at an arbitrary position on the Axes. A common use case of
+text is to annotate some feature of the plot, and the
+:func:`~matplotlib.pyplot.annotate` method provides helper
+functionality to make annotations easy. In an annotation, there are
+two points to consider: the location being annotated represented by
+the argument ``xy`` and the location of the text ``xytext``. Both of
+these arguments are ``(x,y)`` tuples.
+
+.. literalinclude:: figures/pyplot_annotate.py
+
+.. image:: figures/pyplot_annotate.png
+ :scale: 50
+
+In this basic example, both the ``xy`` (arrow tip) and ``xytext``
+locations (text location) are in data coordinates. There are a
+variety of other coordinate systems one can choose -- see
+:ref:`annotations-tutorial` for details. More examples can be found
+in the `annotations demo
+<http://matplotlib.sf.net/examples/pylab_examples/annotation_demo.py>`_
Modified: trunk/matplotlib/doc/users/usetex.rst
===================================================================
--- trunk/matplotlib/doc/users/usetex.rst 2008-06-09 20:13:23 UTC (rev 5444)
+++ trunk/matplotlib/doc/users/usetex.rst 2008-06-09 21:01:33 UTC (rev 5445)
@@ -1,7 +1,7 @@
.. _usetex-tutorial:
*************************
-Text Rendering With LaTeX
+Text rendering With LaTeX
*************************
Matplotlib has the option to use LaTeX to manage all text layout. This
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|