<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Transformations Tutorial — Matplotlib v1.1.1 documentation</title>
<link rel="stylesheet" href="../_static/mpl.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.1.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Matplotlib v1.1.1 documentation"
href="../_static/opensearch.xml"/>
<link rel="top" title="Matplotlib v1.1.1 documentation" href="../index.html" />
<link rel="up" title="User’s Guide" href="index.html" />
<link rel="next" title="Path Tutorial" href="path_tutorial.html" />
<link rel="prev" title="Event handling and picking" href="event_handling.html" />
</head>
<body>
<!-- Piwik -->
<script type="text/javascript">
if ("matplotlib.sourceforge.net" == document.location.hostname ||
"matplotlib.sf.net" == document.location.hostname) {
var pkBaseURL = (("https:" == document.location.protocol) ? "https://apps.sourceforge.net/piwik/matplotlib/" : "http://apps.sourceforge.net/piwik/matplotlib/");
document.write(unescape("%3Cscript src='" + pkBaseURL + "piwik.js' type='text/javascript'%3E%3C/script%3E"));
}
</script>
<script type="text/javascript">
if ("matplotlib.sourceforge.net" == document.location.hostname ||
"matplotlib.sf.net" == document.location.hostname) {
piwik_action_name = '';
piwik_idsite = 1;
piwik_url = pkBaseURL + "piwik.php";
piwik_log(piwik_action_name, piwik_idsite, piwik_url);
document.write(unescape('%3Cobject%3E%3Cnoscript%3E%3Cp%3E%3Cimg src="http://apps.sourceforge.net/piwik/matplotlib/piwik.php?idsite=1" alt="piwik"/%3E%3C/p%3E%3C/noscript%3E%3C/object%3E'));
}
</script>
<!-- End Piwik Tag -->
<link rel="shortcut icon" href="_static/favicon.ico">
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="../index.html"><img src="../_static/logo2.png" border="0" alt="matplotlib"/></a>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="path_tutorial.html" title="Path Tutorial"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="event_handling.html" title="Event handling and picking"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">home</a>| </li>
<li><a href="../search.html">search</a>| </li>
<li><a href="../examples/index.html">examples</a>| </li>
<li><a href="../gallery.html">gallery</a>| </li>
<li><a href="../contents.html">docs</a> »</li>
<li><a href="index.html" accesskey="U">User’s Guide</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Transformations Tutorial</a><ul>
<li><a class="reference internal" href="#data-coordinates">Data coordinates</a></li>
<li><a class="reference internal" href="#axes-coordinates">Axes coordinates</a></li>
<li><a class="reference internal" href="#blended-transformations">Blended transformations</a></li>
<li><a class="reference internal" href="#using-offset-transforms-to-create-a-shadow-effect">Using offset transforms to create a shadow effect</a></li>
<li><a class="reference internal" href="#the-transformation-pipeline">The transformation pipeline</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="event_handling.html"
title="previous chapter">Event handling and picking</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="path_tutorial.html"
title="next chapter">Path Tutorial</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/users/transforms_tutorial.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="transformations-tutorial">
<span id="transforms-tutorial"></span><h1>Transformations Tutorial<a class="headerlink" href="#transformations-tutorial" title="Permalink to this headline">¶</a></h1>
<p>Like any graphics packages, matplotlib is built on top of a
transformation framework to easily move between coordinate systems,
the userland <cite>data</cite> coordinate system, the <cite>axes</cite> coordinate system,
the <cite>figure</cite> coordinate system, and the <cite>display</cite> coordinate system.
In 95% of your plotting, you won’t need to think about this, as it
happens under the hood, but as you push the limits of custom figure
generation, it helps to have an understanding of these objects so you
can reuse the existing transformations matplotlib makes available to
you, or create your own (see <a class="reference internal" href="../devel/transformations.html#module-matplotlib.transforms" title="matplotlib.transforms"><tt class="xref py py-mod docutils literal"><span class="pre">matplotlib.transforms</span></tt></a>). The table
below summarizes the existing coordinate systems, the transformation
object you should use to work in that coordinate system, and the
description of that system. In the <cite>Transformation Object</cite> column,
<tt class="docutils literal"><span class="pre">ax</span></tt> is a <a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><tt class="xref py py-class docutils literal"><span class="pre">Axes</span></tt></a> instance, and <tt class="docutils literal"><span class="pre">fig</span></tt> is a
<a class="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><tt class="xref py py-class docutils literal"><span class="pre">Figure</span></tt></a> instance.</p>
<table border="1" class="docutils">
<colgroup>
<col width="5%" />
<col width="11%" />
<col width="84%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Coordinate</th>
<th class="head">Transformation Object</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><cite>data</cite></td>
<td><tt class="docutils literal"><span class="pre">ax.transData</span></tt></td>
<td>The userland data coordinate system, controlled by the xlim and ylim</td>
</tr>
<tr><td><cite>axes</cite></td>
<td><tt class="docutils literal"><span class="pre">ax.transAxes</span></tt></td>
<td>The coordinate system of the <a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><tt class="xref py py-class docutils literal"><span class="pre">Axes</span></tt></a>; (0,0) is bottom left of the axes, and (1,1) is top right of the axes</td>
</tr>
<tr><td><cite>figure</cite></td>
<td><tt class="docutils literal"><span class="pre">fig.transFigure</span></tt></td>
<td>The coordinate system of the <a class="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><tt class="xref py py-class docutils literal"><span class="pre">Figure</span></tt></a>; (0,0) is bottom left of the figure, and (1,1) is top right of the figure</td>
</tr>
<tr><td><cite>display</cite></td>
<td><cite>None</cite></td>
<td>This is the pixel coordinate system of the display; (0,0) is the bottom left of the display, and (width, height) is the top right of the display in pixels</td>
</tr>
</tbody>
</table>
<p>All of the transformation objects in the table above take inputs in
their coordinate system, and transform the input to the <cite>display</cite>
coordinate system. That is why the <cite>display</cite> coordinate system has
<cite>None</cite> for the <cite>Transformation Object</cite> column – it already is in
display coordinates. The transformations also know how to invert
themselves, to go from <cite>display</cite> back to the native coordinate system.
This is particularly useful when processing events from the user
interface, which typically occur in display space, and you want to
know where the mouse click or key-press occurred in your data
coordinate system.</p>
<div class="section" id="data-coordinates">
<span id="data-coords"></span><h2>Data coordinates<a class="headerlink" href="#data-coordinates" title="Permalink to this headline">¶</a></h2>
<p>Let’s start with the most commonly used coordinate, the <cite>data</cite>
coordinate system. Whenever you add data to the axes, matplotlib
updates the datalimits, most commonly updated with the
<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.set_xlim" title="matplotlib.axes.Axes.set_xlim"><tt class="xref py py-meth docutils literal"><span class="pre">set_xlim()</span></tt></a> and
<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.set_ylim" title="matplotlib.axes.Axes.set_ylim"><tt class="xref py py-meth docutils literal"><span class="pre">set_ylim()</span></tt></a> methods. For example, in the
figure below, the data limits stretch from 0 to 10 on the x-axis, and
-1 to 1 on the y-axis.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">numpy</span> <span class="kn">as</span> <span class="nn">np</span>
<span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="kn">as</span> <span class="nn">plt</span>
<span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mf">0.005</span><span class="p">)</span>
<span class="n">y</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">exp</span><span class="p">(</span><span class="o">-</span><span class="n">x</span><span class="o">/</span><span class="mf">2.</span><span class="p">)</span> <span class="o">*</span> <span class="n">np</span><span class="o">.</span><span class="n">sin</span><span class="p">(</span><span class="mi">2</span><span class="o">*</span><span class="n">np</span><span class="o">.</span><span class="n">pi</span><span class="o">*</span><span class="n">x</span><span class="p">)</span>
<span class="n">fig</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">figure</span><span class="p">()</span>
<span class="n">ax</span> <span class="o">=</span> <span class="n">fig</span><span class="o">.</span><span class="n">add_subplot</span><span class="p">(</span><span class="mi">111</span><span class="p">)</span>
<span class="n">ax</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
<span class="n">ax</span><span class="o">.</span><span class="n">set_xlim</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
<span class="n">ax</span><span class="o">.</span><span class="n">set_ylim</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="n">plt</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
<p>(<a class="reference external" href="../users/transforms_tutorial-1.py">Source code</a>, <a class="reference external" href="../users/transforms_tutorial-1.png">png</a>, <a class="reference external" href="../users/transforms_tutorial-1.hires.png">hires.png</a>, <a class="reference external" href="../users/transforms_tutorial-1.pdf">pdf</a>)</p>
<div class="figure">
<img alt="../_images/transforms_tutorial-1.png" src="../_images/transforms_tutorial-1.png" />
</div>
<p>You can use the <tt class="docutils literal"><span class="pre">ax.transData</span></tt> instance to transform from your
<cite>data</cite> to your <cite>display</cite> coordinate system, either a single point or a
sequence of points as shown below:</p>
<div class="highlight-ipython"><div class="highlight"><pre><span class="gp">In [14]: </span><span class="nb">type</span><span class="p">(</span><span class="n">ax</span><span class="o">.</span><span class="n">transData</span><span class="p">)</span>
<span class="gr">Out[14]: </span><span class="o"><</span><span class="k">class</span> <span class="err">'</span><span class="nc">matplotlib</span><span class="o">.</span><span class="n">transforms</span><span class="o">.</span><span class="n">CompositeGenericTransform</span><span class="s">'></span>
<span class="gp">In [15]: </span><span class="n">ax</span><span class="o">.</span><span class="n">transData</span><span class="o">.</span><span class="n">transform</span><span class="p">((</span><span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span>
<span class="gr">Out[15]: </span><span class="n">array</span><span class="p">([</span> <span class="mf">335.175</span><span class="p">,</span> <span class="mf">247.</span> <span class="p">])</span>
<span class="gp">In [16]: </span><span class="n">ax</span><span class="o">.</span><span class="n">transData</span><span class="o">.</span><span class="n">transform</span><span class="p">([(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)])</span>
<span class="go">Out[16]:</span>
<span class="go">array([[ 335.175, 247. ],</span>
<span class="go"> [ 132.435, 642.2 ]])</span>
</pre></div>
</div>
<p>You can use the <a class="reference internal" href="../devel/transformations.html#matplotlib.transforms.Transform.inverted" title="matplotlib.transforms.Transform.inverted"><tt class="xref py py-meth docutils literal"><span class="pre">inverted()</span></tt></a>
method to create a transform which will take you from display to data
coordinates:</p>
<div class="highlight-ipython"><div class="highlight"><pre><span class="gp">In [41]: </span><span class="n">inv</span> <span class="o">=</span> <span class="n">ax</span><span class="o">.</span><span class="n">transData</span><span class="o">.</span><span class="n">inverted</span><span class="p">()</span>
<span class="gp">In [42]: </span><span class="nb">type</span><span class="p">(</span><span class="n">inv</span><span class="p">)</span>
<span class="gr">Out[42]: </span><span class="o"><</span><span class="k">class</span> <span class="err">'</span><span class="nc">matplotlib</span><span class="o">.</span><span class="n">transforms</span><span class="o">.</span><span class="n">CompositeGenericTransform</span><span class="s">'></span>
<span class="gp">In [43]: </span><span class="n">inv</span><span class="o">.</span><span class="n">transform</span><span class="p">((</span><span class="mf">335.175</span><span class="p">,</span> <span class="mf">247.</span><span class="p">))</span>
<span class="gr">Out[43]: </span><span class="n">array</span><span class="p">([</span> <span class="mf">5.</span><span class="p">,</span> <span class="mf">0.</span><span class="p">])</span>
</pre></div>
</div>
<p>If your are typing along with this tutorial, the exact values of the
display coordinates may differ if you have a different window size or
dpi setting. Likewise, in the figure below, the display labeled
points are probably not the same as in the ipython session because the
documentation figure size defaults are different.</p>
<p>(<a class="reference external" href="../pyplots/annotate_transform.py">Source code</a>, <a class="reference external" href="../pyplots/annotate_transform.png">png</a>, <a class="reference external" href="../pyplots/annotate_transform.hires.png">hires.png</a>, <a class="reference external" href="../pyplots/annotate_transform.pdf">pdf</a>)</p>
<div class="figure">
<img alt="../_images/annotate_transform.png" src="../_images/annotate_transform.png" />
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you run the source code in the example above in a GUI backend,
you may also find that the two arrows for the <cite>data</cite> and <cite>display</cite>
annotations do not point to exactly the same point. This is because
the display point was computed before the figure was displayed, and
the GUI backend may slightly resize the figure when it is created.
The effect is more pronounced if you resize the figure yourself.
This is one good reason why you rarely want to work in display
space, but you can connect to the <tt class="docutils literal"><span class="pre">'on_draw'</span></tt>
<a class="reference internal" href="../api/backend_bases_api.html#matplotlib.backend_bases.Event" title="matplotlib.backend_bases.Event"><tt class="xref py py-class docutils literal"><span class="pre">Event</span></tt></a> to update figure
coordinates on figure draws; see <a class="reference internal" href="event_handling.html#event-handling-tutorial"><em>Event handling and picking</em></a>.</p>
</div>
<p>When you change the x or y limits of your axes, the data limits are
updated so the transformation yields a new display point. Note that
when we just change the ylim, only the y-display coordinate is
altered, and when we change the xlim too, both are altered. More on
this later when we talk about the
<a class="reference internal" href="../devel/transformations.html#matplotlib.transforms.Bbox" title="matplotlib.transforms.Bbox"><tt class="xref py py-class docutils literal"><span class="pre">Bbox</span></tt></a>.</p>
<div class="highlight-ipython"><div class="highlight"><pre><span class="gp">In [54]: </span><span class="n">ax</span><span class="o">.</span><span class="n">transData</span><span class="o">.</span><span class="n">transform</span><span class="p">((</span><span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span>
<span class="gr">Out[54]: </span><span class="n">array</span><span class="p">([</span> <span class="mf">335.175</span><span class="p">,</span> <span class="mf">247.</span> <span class="p">])</span>
<span class="gp">In [55]: </span><span class="n">ax</span><span class="o">.</span><span class="n">set_ylim</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span>
<span class="gr">Out[55]: </span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="gp">In [56]: </span><span class="n">ax</span><span class="o">.</span><span class="n">transData</span><span class="o">.</span><span class="n">transform</span><span class="p">((</span><span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span>
<span class="gr">Out[56]: </span><span class="n">array</span><span class="p">([</span> <span class="mf">335.175</span> <span class="p">,</span> <span class="mf">181.13333333</span><span class="p">])</span>
<span class="gp">In [57]: </span><span class="n">ax</span><span class="o">.</span><span class="n">set_xlim</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="mi">20</span><span class="p">)</span>
<span class="gr">Out[57]: </span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">20</span><span class="p">)</span>
<span class="gp">In [58]: </span><span class="n">ax</span><span class="o">.</span><span class="n">transData</span><span class="o">.</span><span class="n">transform</span><span class="p">((</span><span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span>
<span class="gr">Out[58]: </span><span class="n">array</span><span class="p">([</span><span class="o">-</span><span class="mf">171.675</span> <span class="p">,</span> <span class="mf">181.13333333</span><span class="p">])</span>
</pre></div>
</div>
</div>
<div class="section" id="axes-coordinates">
<span id="axes-coords"></span><h2>Axes coordinates<a class="headerlink" href="#axes-coordinates" title="Permalink to this headline">¶</a></h2>
<p>After the <cite>data</cite> coordinate system, <cite>axes</cite> is probably the second most
useful coordinate system. Here the point (0,0) is the bottom left of
your axes or subplot, (0.5, 0.5) is the center, and (1.0, 1.0) is the
top right. You can also refer to points outside the range, so (-0.1,
1.1) is to the left and above your axes. This coordinate system is
extremely useful when placing text in your axes, because you often
want a text bubble in a fixed, location, eg. the upper left of the axes
pane, and have that location remain fixed when you pan or zoom. Here
is a simple example that creates four panels and labels them ‘A’, ‘B’,
‘C’, ‘D’ as you often see in journals.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">numpy</span> <span class="kn">as</span> <span class="nn">np</span>
<span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="kn">as</span> <span class="nn">plt</span>
<span class="n">fig</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">figure</span><span class="p">()</span>
<span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">label</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">((</span><span class="s">'A'</span><span class="p">,</span> <span class="s">'B'</span><span class="p">,</span> <span class="s">'C'</span><span class="p">,</span> <span class="s">'D'</span><span class="p">)):</span>
<span class="n">ax</span> <span class="o">=</span> <span class="n">fig</span><span class="o">.</span><span class="n">add_subplot</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="n">i</span><span class="o">+</span><span class="mi">1</span><span class="p">)</span>
<span class="n">ax</span><span class="o">.</span><span class="n">text</span><span class="p">(</span><span class="mf">0.05</span><span class="p">,</span> <span class="mf">0.95</span><span class="p">,</span> <span class="n">label</span><span class="p">,</span> <span class="n">transform</span><span class="o">=</span><span class="n">ax</span><span class="o">.</span><span class="n">transAxes</span><span class="p">,</span>
<span class="n">fontsize</span><span class="o">=</span><span class="mi">16</span><span class="p">,</span> <span class="n">fontweight</span><span class="o">=</span><span class="s">'bold'</span><span class="p">,</span> <span class="n">va</span><span class="o">=</span><span class="s">'top'</span><span class="p">)</span>
<span class="n">plt</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
<p>(<a class="reference external" href="../users/transforms_tutorial-2.py">Source code</a>, <a class="reference external" href="../users/transforms_tutorial-2.png">png</a>, <a class="reference external" href="../users/transforms_tutorial-2.hires.png">hires.png</a>, <a class="reference external" href="../users/transforms_tutorial-2.pdf">pdf</a>)</p>
<div class="figure">
<img alt="../_images/transforms_tutorial-2.png" src="../_images/transforms_tutorial-2.png" />
</div>
<p>You can also make lines or patches in the axes coordinate system, but
this is less useful in my experience than using <tt class="docutils literal"><span class="pre">ax.transAxes</span></tt> for
placing text. Nonetheless, here is a silly example which plots some
random dots in <cite>data</cite> space, and overlays a semi-transparent
<a class="reference internal" href="../api/artist_api.html#matplotlib.patches.Circle" title="matplotlib.patches.Circle"><tt class="xref py py-class docutils literal"><span class="pre">Circle</span></tt></a> centered in the middle of the axes
with a radius one quarter of the axes – if your axes does not
preserve aspect ratio (see <a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.set_aspect" title="matplotlib.axes.Axes.set_aspect"><tt class="xref py py-meth docutils literal"><span class="pre">set_aspect()</span></tt></a>),
this will look like an ellipse. Use the pan/zoom tool to move around,
or manually change the data xlim and ylim, and you will see the data
move, but the circle will remain fixed because it is not in <cite>data</cite>
coordinates and will always remain at the center of the axes.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">numpy</span> <span class="kn">as</span> <span class="nn">np</span>
<span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="kn">as</span> <span class="nn">plt</span>
<span class="kn">import</span> <span class="nn">matplotlib.patches</span> <span class="kn">as</span> <span class="nn">patches</span>
<span class="n">fig</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">figure</span><span class="p">()</span>
<span class="n">ax</span> <span class="o">=</span> <span class="n">fig</span><span class="o">.</span><span class="n">add_subplot</span><span class="p">(</span><span class="mi">111</span><span class="p">)</span>
<span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="mi">10</span><span class="o">*</span><span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">rand</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span>
<span class="n">ax</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="s">'go'</span><span class="p">)</span> <span class="c"># plot some data in data coordinates</span>
<span class="n">circ</span> <span class="o">=</span> <span class="n">patches</span><span class="o">.</span><span class="n">Circle</span><span class="p">((</span><span class="mf">0.5</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">),</span> <span class="mf">0.25</span><span class="p">,</span> <span class="n">transform</span><span class="o">=</span><span class="n">ax</span><span class="o">.</span><span class="n">transAxes</span><span class="p">,</span>
<span class="n">facecolor</span><span class="o">=</span><span class="s">'yellow'</span><span class="p">,</span> <span class="n">alpha</span><span class="o">=</span><span class="mf">0.5</span><span class="p">)</span>
<span class="n">ax</span><span class="o">.</span><span class="n">add_patch</span><span class="p">(</span><span class="n">circ</span><span class="p">)</span>
<span class="n">plt</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
<p>(<a class="reference external" href="../users/transforms_tutorial-3.py">Source code</a>, <a class="reference external" href="../users/transforms_tutorial-3.png">png</a>, <a class="reference external" href="../users/transforms_tutorial-3.hires.png">hires.png</a>, <a class="reference external" href="../users/transforms_tutorial-3.pdf">pdf</a>)</p>
<div class="figure">
<img alt="../_images/transforms_tutorial-3.png" src="../_images/transforms_tutorial-3.png" />
</div>
</div>
<div class="section" id="blended-transformations">
<h2>Blended transformations<a class="headerlink" href="#blended-transformations" title="Permalink to this headline">¶</a></h2>
<p>Drawing in <cite>blended</cite> coordinate spaces which mix <cite>axes</cite> with <cite>data</cite>
coordinates is extremely useful, for example to create a horizontal
span which highlights some region of the y-data but spans across the
x-axis regardless of the data limits, pan or zoom level, etc. In fact
these blended lines and spans are so useful, we have built in
functions to make them easy to plot (see
<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.axhline" title="matplotlib.axes.Axes.axhline"><tt class="xref py py-meth docutils literal"><span class="pre">axhline()</span></tt></a>,
<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.axvline" title="matplotlib.axes.Axes.axvline"><tt class="xref py py-meth docutils literal"><span class="pre">axvline()</span></tt></a>,
<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.axhspan" title="matplotlib.axes.Axes.axhspan"><tt class="xref py py-meth docutils literal"><span class="pre">axhspan()</span></tt></a>,
<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.axvspan" title="matplotlib.axes.Axes.axvspan"><tt class="xref py py-meth docutils literal"><span class="pre">axvspan()</span></tt></a>) but for didactic purposes we
will implement the horizontal span here using a blended
transformation. This trick only works for separable transformations,
like you see in normal Cartesian coordinate systems, but not on
inseparable transformations like the
<a class="reference internal" href="../devel/add_new_projection.html#matplotlib.projections.polar.PolarAxes.PolarTransform" title="matplotlib.projections.polar.PolarAxes.PolarTransform"><tt class="xref py py-class docutils literal"><span class="pre">PolarTransform</span></tt></a>.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">numpy</span> <span class="kn">as</span> <span class="nn">np</span>
<span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="kn">as</span> <span class="nn">plt</span>
<span class="kn">import</span> <span class="nn">matplotlib.patches</span> <span class="kn">as</span> <span class="nn">patches</span>
<span class="kn">import</span> <span class="nn">matplotlib.transforms</span> <span class="kn">as</span> <span class="nn">transforms</span>
<span class="n">fig</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">figure</span><span class="p">()</span>
<span class="n">ax</span> <span class="o">=</span> <span class="n">fig</span><span class="o">.</span><span class="n">add_subplot</span><span class="p">(</span><span class="mi">111</span><span class="p">)</span>
<span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">randn</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span>
<span class="n">ax</span><span class="o">.</span><span class="n">hist</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="mi">30</span><span class="p">)</span>
<span class="n">ax</span><span class="o">.</span><span class="n">set_title</span><span class="p">(</span><span class="s">r'$\sigma=1 \/ \dots \/ \sigma=2$'</span><span class="p">,</span> <span class="n">fontsize</span><span class="o">=</span><span class="mi">16</span><span class="p">)</span>
<span class="c"># the x coords of this transformation are data, and the</span>
<span class="c"># y coord are axes</span>
<span class="n">trans</span> <span class="o">=</span> <span class="n">transforms</span><span class="o">.</span><span class="n">blended_transform_factory</span><span class="p">(</span>
<span class="n">ax</span><span class="o">.</span><span class="n">transData</span><span class="p">,</span> <span class="n">ax</span><span class="o">.</span><span class="n">transAxes</span><span class="p">)</span>
<span class="c"># highlight the 1..2 stddev region with a span.</span>
<span class="c"># We want x to be in data coordinates and y to</span>
<span class="c"># span from 0..1 in axes coords</span>
<span class="n">rect</span> <span class="o">=</span> <span class="n">patches</span><span class="o">.</span><span class="n">Rectangle</span><span class="p">((</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="n">width</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">height</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>
<span class="n">transform</span><span class="o">=</span><span class="n">trans</span><span class="p">,</span> <span class="n">color</span><span class="o">=</span><span class="s">'yellow'</span><span class="p">,</span>
<span class="n">alpha</span><span class="o">=</span><span class="mf">0.5</span><span class="p">)</span>
<span class="n">ax</span><span class="o">.</span><span class="n">add_patch</span><span class="p">(</span><span class="n">rect</span><span class="p">)</span>
<span class="n">plt</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
<p>(<a class="reference external" href="../users/transforms_tutorial-4.py">Source code</a>, <a class="reference external" href="../users/transforms_tutorial-4.png">png</a>, <a class="reference external" href="../users/transforms_tutorial-4.hires.png">hires.png</a>, <a class="reference external" href="../users/transforms_tutorial-4.pdf">pdf</a>)</p>
<div class="figure">
<img alt="../_images/transforms_tutorial-4.png" src="../_images/transforms_tutorial-4.png" />
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>The blended transformations where x is in data coords and y in axes
coordinates is so useful that we have helper methods to return the
versions mpl uses internally for drawing ticks, ticklabels, etc.
The methods are <a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.get_xaxis_transform" title="matplotlib.axes.Axes.get_xaxis_transform"><tt class="xref py py-meth docutils literal"><span class="pre">matplotlib.axes.Axes.get_xaxis_transform()</span></tt></a> and
<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.get_yaxis_transform" title="matplotlib.axes.Axes.get_yaxis_transform"><tt class="xref py py-meth docutils literal"><span class="pre">matplotlib.axes.Axes.get_yaxis_transform()</span></tt></a>. So in the example
above, the call to
<a class="reference internal" href="../devel/transformations.html#matplotlib.transforms.blended_transform_factory" title="matplotlib.transforms.blended_transform_factory"><tt class="xref py py-meth docutils literal"><span class="pre">blended_transform_factory()</span></tt></a> can be
replaced by <tt class="docutils literal"><span class="pre">get_xaxis_transform</span></tt>:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="n">trans</span> <span class="o">=</span> <span class="n">ax</span><span class="o">.</span><span class="n">get_xaxis_transform</span><span class="p">()</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="using-offset-transforms-to-create-a-shadow-effect">
<h2>Using offset transforms to create a shadow effect<a class="headerlink" href="#using-offset-transforms-to-create-a-shadow-effect" title="Permalink to this headline">¶</a></h2>
<p>One use of transformations is to create a new transformation that is
offset from another transformation, eg to place one object shifted a
bit relative to another object. Typically you want the shift to be in
some physical dimension, like points or inches rather than in data
coordinates, so that the shift effect is constant at different zoom
levels and dpi settings.</p>
<p>One use for an offset is to create a shadow effect, where you draw one
object identical to the first just to the right of it, and just below
it, adjusting the zorder to make sure the shadow is drawn first and
then the object it is shadowing above it. The transforms module has a
helper transformation
<a class="reference internal" href="../devel/transformations.html#matplotlib.transforms.ScaledTranslation" title="matplotlib.transforms.ScaledTranslation"><tt class="xref py py-class docutils literal"><span class="pre">ScaledTranslation</span></tt></a>. It is
instantiated with:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">trans</span> <span class="o">=</span> <span class="n">ScaledTranslation</span><span class="p">(</span><span class="n">xt</span><span class="p">,</span> <span class="n">yt</span><span class="p">,</span> <span class="n">scale_trans</span><span class="p">)</span>
</pre></div>
</div>
<p>where <cite>xt</cite> and <cite>yt</cite> are the translation offsets, and <cite>scale_trans</cite> is
a transformation which scales <cite>xt</cite> and <cite>yt</cite> at transformation time
before applying the offsets. A typical use case is to use the figure
<tt class="docutils literal"><span class="pre">fig.dpi_scale_trans</span></tt> transformation for the <cite>scale_trans</cite> argument,
to first scale <cite>xt</cite> and <cite>yt</cite> specified in points to <cite>display</cite> space
before doing the final offset. The dpi and inches offset is a
common-enough use case that we have a special helper function to
create it in <tt class="xref py py-func docutils literal"><span class="pre">matplotlib.transforms.offset_copy()</span></tt>, which returns
a new transform with an added offset. But in the example below, we’ll
create the offset transform ourselves. Note the use of the plus
operator in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">offset</span> <span class="o">=</span> <span class="n">transforms</span><span class="o">.</span><span class="n">ScaledTranslation</span><span class="p">(</span><span class="n">dx</span><span class="p">,</span> <span class="n">dy</span><span class="p">,</span>
<span class="n">fig</span><span class="o">.</span><span class="n">dpi_scale_trans</span><span class="p">)</span>
<span class="n">shadow_transform</span> <span class="o">=</span> <span class="n">ax</span><span class="o">.</span><span class="n">transData</span> <span class="o">+</span> <span class="n">offset</span>
</pre></div>
</div>
<p>showing that can chain transformations using the addition operator.
This code says: first apply the data transformation <tt class="docutils literal"><span class="pre">ax.transData</span></tt>
and then translate the data by <cite>dx</cite> and <cite>dy</cite> points. In typography,
a`point <<a class="reference external" href="http://en.wikipedia.org/wiki/Point_%28typography%29">http://en.wikipedia.org/wiki/Point_%28typography%29</a>>`_ is
1/72 inches, and by specifying your offsets in points, your figure
will look the same regardless of the dpi resolution it is saved in.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">numpy</span> <span class="kn">as</span> <span class="nn">np</span>
<span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="kn">as</span> <span class="nn">plt</span>
<span class="kn">import</span> <span class="nn">matplotlib.patches</span> <span class="kn">as</span> <span class="nn">patches</span>
<span class="kn">import</span> <span class="nn">matplotlib.transforms</span> <span class="kn">as</span> <span class="nn">transforms</span>
<span class="n">fig</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">figure</span><span class="p">()</span>
<span class="n">ax</span> <span class="o">=</span> <span class="n">fig</span><span class="o">.</span><span class="n">add_subplot</span><span class="p">(</span><span class="mi">111</span><span class="p">)</span>
<span class="c"># make a simple sine wave</span>
<span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mf">0.</span><span class="p">,</span> <span class="mf">2.</span><span class="p">,</span> <span class="mf">0.01</span><span class="p">)</span>
<span class="n">y</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">sin</span><span class="p">(</span><span class="mi">2</span><span class="o">*</span><span class="n">np</span><span class="o">.</span><span class="n">pi</span><span class="o">*</span><span class="n">x</span><span class="p">)</span>
<span class="n">line</span><span class="p">,</span> <span class="o">=</span> <span class="n">ax</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">lw</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">color</span><span class="o">=</span><span class="s">'blue'</span><span class="p">)</span>
<span class="c"># shift the object over 2 points, and down 2 points</span>
<span class="n">dx</span><span class="p">,</span> <span class="n">dy</span> <span class="o">=</span> <span class="mi">2</span><span class="o">/</span><span class="mf">72.</span><span class="p">,</span> <span class="o">-</span><span class="mi">2</span><span class="o">/</span><span class="mf">72.</span>
<span class="n">offset</span> <span class="o">=</span> <span class="n">transforms</span><span class="o">.</span><span class="n">ScaledTranslation</span><span class="p">(</span><span class="n">dx</span><span class="p">,</span> <span class="n">dy</span><span class="p">,</span>
<span class="n">fig</span><span class="o">.</span><span class="n">dpi_scale_trans</span><span class="p">)</span>
<span class="n">shadow_transform</span> <span class="o">=</span> <span class="n">ax</span><span class="o">.</span><span class="n">transData</span> <span class="o">+</span> <span class="n">offset</span>
<span class="c"># now plot the same data with our offset transform;</span>
<span class="c"># use the zorder to make sure we are below the line</span>
<span class="n">ax</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">lw</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">color</span><span class="o">=</span><span class="s">'gray'</span><span class="p">,</span>
<span class="n">transform</span><span class="o">=</span><span class="n">shadow_transform</span><span class="p">,</span>
<span class="n">zorder</span><span class="o">=</span><span class="mf">0.5</span><span class="o">*</span><span class="n">line</span><span class="o">.</span><span class="n">get_zorder</span><span class="p">())</span>
<span class="n">ax</span><span class="o">.</span><span class="n">set_title</span><span class="p">(</span><span class="s">'creating a shadow effect with an offset transform'</span><span class="p">)</span>
<span class="n">plt</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
<p>(<a class="reference external" href="../users/transforms_tutorial-5.py">Source code</a>, <a class="reference external" href="../users/transforms_tutorial-5.png">png</a>, <a class="reference external" href="../users/transforms_tutorial-5.hires.png">hires.png</a>, <a class="reference external" href="../users/transforms_tutorial-5.pdf">pdf</a>)</p>
<div class="figure">
<img alt="../_images/transforms_tutorial-5.png" src="../_images/transforms_tutorial-5.png" />
</div>
</div>
<div class="section" id="the-transformation-pipeline">
<h2>The transformation pipeline<a class="headerlink" href="#the-transformation-pipeline" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">ax.transData</span></tt> transform we have been working with in this
tutorial is a composite of three different transformations that
comprise the transformation pipeline from <cite>data</cite> -> <cite>display</cite>
coordinates. Michael Droettboom implemented the transformations
framework, taking care to provide a clean API that segregated the
nonlinear projections and scales that happen in polar and logarithmic
plots, from the linear affine transformations that happen when you pan
and zoom. There is an efficiency here, because you can pan and zoom
in your axes which affects the affine transformation, but you may not
need to compute the potentially expensive nonlinear scales or
projections on simple navigation events. It is also possible to
multiply affine transformation matrices together, and then apply them
to coordinates in one step. This is not true of all possible
transformations.</p>
<p>Here is how the <tt class="docutils literal"><span class="pre">ax.transData</span></tt> instance is defined in the basic
separable axis <a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><tt class="xref py py-class docutils literal"><span class="pre">Axes</span></tt></a> class:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="bp">self</span><span class="o">.</span><span class="n">transData</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">transScale</span> <span class="o">+</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">transLimits</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">transAxes</span><span class="p">)</span>
</pre></div>
</div>
<p>We’ve been introduced to the <tt class="docutils literal"><span class="pre">transAxes</span></tt> instance above in
<a class="reference internal" href="#axes-coords"><em>Axes coordinates</em></a>, which maps the (0,0), (1,1) corners of the
axes or subplot bounding box to <cite>display</cite> space, so let’s look at
these other two pieces.</p>
<p><tt class="docutils literal"><span class="pre">self.transLimits</span></tt> is the transformation that takes you from
<tt class="docutils literal"><span class="pre">data</span></tt> to <tt class="docutils literal"><span class="pre">axes</span></tt> coordinates; i.e., it maps your view xlim and ylim
to the unit space of the axes (and <tt class="docutils literal"><span class="pre">transAxes</span></tt> then takes that unit
space to display space). We can see this in action here</p>
<div class="highlight-ipython"><div class="highlight"><pre><span class="gp">In [80]: </span><span class="n">ax</span> <span class="o">=</span> <span class="n">subplot</span><span class="p">(</span><span class="mi">111</span><span class="p">)</span>
<span class="gp">In [81]: </span><span class="n">ax</span><span class="o">.</span><span class="n">set_xlim</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
<span class="gr">Out[81]: </span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
<span class="gp">In [82]: </span><span class="n">ax</span><span class="o">.</span><span class="n">set_ylim</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span>
<span class="gr">Out[82]: </span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="gp">In [84]: </span><span class="n">ax</span><span class="o">.</span><span class="n">transLimits</span><span class="o">.</span><span class="n">transform</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span><span class="o">-</span><span class="mi">1</span><span class="p">))</span>
<span class="gr">Out[84]: </span><span class="n">array</span><span class="p">([</span> <span class="mf">0.</span><span class="p">,</span> <span class="mf">0.</span><span class="p">])</span>
<span class="gp">In [85]: </span><span class="n">ax</span><span class="o">.</span><span class="n">transLimits</span><span class="o">.</span><span class="n">transform</span><span class="p">((</span><span class="mi">10</span><span class="p">,</span><span class="o">-</span><span class="mi">1</span><span class="p">))</span>
<span class="gr">Out[85]: </span><span class="n">array</span><span class="p">([</span> <span class="mf">1.</span><span class="p">,</span> <span class="mf">0.</span><span class="p">])</span>
<span class="gp">In [86]: </span><span class="n">ax</span><span class="o">.</span><span class="n">transLimits</span><span class="o">.</span><span class="n">transform</span><span class="p">((</span><span class="mi">10</span><span class="p">,</span><span class="mi">1</span><span class="p">))</span>
<span class="gr">Out[86]: </span><span class="n">array</span><span class="p">([</span> <span class="mf">1.</span><span class="p">,</span> <span class="mf">1.</span><span class="p">])</span>
<span class="gp">In [87]: </span><span class="n">ax</span><span class="o">.</span><span class="n">transLimits</span><span class="o">.</span><span class="n">transform</span><span class="p">((</span><span class="mi">5</span><span class="p">,</span><span class="mi">0</span><span class="p">))</span>
<span class="gr">Out[87]: </span><span class="n">array</span><span class="p">([</span> <span class="mf">0.5</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">])</span>
</pre></div>
</div>
<p>and we can use this same inverted transformation to go from the unit
<cite>axes</cite> coordinates back to <cite>data</cite> coordinates.</p>
<div class="highlight-ipython"><div class="highlight"><pre><span class="gp">In [90]: </span><span class="n">inv</span><span class="o">.</span><span class="n">transform</span><span class="p">((</span><span class="mf">0.25</span><span class="p">,</span> <span class="mf">0.25</span><span class="p">))</span>
<span class="gr">Out[90]: </span><span class="n">array</span><span class="p">([</span> <span class="mf">2.5</span><span class="p">,</span> <span class="o">-</span><span class="mf">0.5</span><span class="p">])</span>
</pre></div>
</div>
<p>The final piece is the <tt class="docutils literal"><span class="pre">self.transScale</span></tt> attribute, which is
responsible for the optional non-linear scaling of the data, eg. for
logarithmic axes. When an Axes is initially setup, this is just set to
the identity transform, since the basic matplotlib axes has linear
scale, but when you call a logarithmic scaling function like
<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.semilogx" title="matplotlib.axes.Axes.semilogx"><tt class="xref py py-meth docutils literal"><span class="pre">semilogx()</span></tt></a> or explicitly set the scale to
logarithmic with <a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.set_xscale" title="matplotlib.axes.Axes.set_xscale"><tt class="xref py py-meth docutils literal"><span class="pre">set_xscale()</span></tt></a>, then the
<tt class="docutils literal"><span class="pre">ax.transScale</span></tt> attribute is set to handle the nonlinear projection.
The scales transforms are properties of the respective <tt class="docutils literal"><span class="pre">xaxis</span></tt> and
<tt class="docutils literal"><span class="pre">yaxis</span></tt> <a class="reference internal" href="../api/axis_api.html#matplotlib.axis.Axis" title="matplotlib.axis.Axis"><tt class="xref py py-class docutils literal"><span class="pre">Axis</span></tt></a> instances. For example, when
you call <tt class="docutils literal"><span class="pre">ax.set_xscale('log')</span></tt>, the xaxis updates its scale to a
<a class="reference internal" href="../devel/add_new_projection.html#matplotlib.scale.LogScale" title="matplotlib.scale.LogScale"><tt class="xref py py-class docutils literal"><span class="pre">matplotlib.scale.LogScale</span></tt></a> instance.</p>
<p>For non-separable axes the PolarAxes, there is one more piece to
consider, the projection transformation. The <tt class="docutils literal"><span class="pre">transData</span></tt>
<a class="reference internal" href="../devel/add_new_projection.html#matplotlib.projections.polar.PolarAxes" title="matplotlib.projections.polar.PolarAxes"><tt class="xref py py-class docutils literal"><span class="pre">matplotlib.projections.polar.PolarAxes</span></tt></a> is similar to that for
the typical separable matplotlib Axes, with one additional piece
<tt class="docutils literal"><span class="pre">transProjection</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="bp">self</span><span class="o">.</span><span class="n">transData</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">transScale</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">transProjection</span> <span class="o">+</span> \
<span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">transProjectionAffine</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">transAxes</span><span class="p">)</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">transProjection</span></tt> handles the projection from the space,
eg. latitude and longitude for map data, or radius and theta for polar
data, to a separable Cartesian coordinate system. There are several
projection examples in the <tt class="docutils literal"><span class="pre">matplotlib.projections</span></tt> package, and the
best way to learn more is to open the source for those packages and
see how to make your own, since matplotlib supports extensible axes
and projections. Michael Droettboom has provided a nice tutorial
example of creating a hammer projection axes; see
<a class="reference internal" href="../examples/api/custom_projection_example.html#api-custom-projection-example"><em>api example code: custom_projection_example.py</em></a>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="path_tutorial.html" title="Path Tutorial"
>next</a> |</li>
<li class="right" >
<a href="event_handling.html" title="Event handling and picking"
>previous</a> |</li>
<li><a href="../index.html">home</a>| </li>
<li><a href="../search.html">search</a>| </li>
<li><a href="../examples/index.html">examples</a>| </li>
<li><a href="../gallery.html">gallery</a>| </li>
<li><a href="../contents.html">docs</a> »</li>
<li><a href="index.html" >User’s Guide</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2008, John Hunter, Darren Dale, Michael Droettboom.
Last updated on Oct 04, 2012.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.2
>
i586
>
media
>
contrib-backports
>
by-pkgid
>
a44f8c7e78ee9c5838c1fb080c9e7630
>
files
>
4775
