<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

<title>units &mdash; Matplotlib 2.2.4 documentation</title>

<link rel="stylesheet" href="../_static/mpl.css"

type="text/css" />

<link rel="stylesheet" href="../_static/pygments.css"

type="text/css" />

<link rel="stylesheet" href="../_static/graphviz.css" type="text/css" />

<link rel="stylesheet" href="../_static/gallery.css" type="text/css" />

<script type="text/javascript">

var DOCUMENTATION_OPTIONS = {

URL_ROOT: '../',

VERSION: '2.2.4',

COLLAPSE_INDEX: false,

FILE_SUFFIX: '.html',

HAS_SOURCE: true,

SOURCELINK_SUFFIX: '.txt'

};

</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>

<script type="text/javascript" src="../_static/language_data.js"></script>

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>

<link rel="search" type="application/opensearchdescription+xml"

title="Search within Matplotlib 2.2.4 documentation"

href="../_static/opensearch.xml"/>

<link rel="shortcut icon" href="../_static/favicon.ico"/>

<link rel="index" title="Index" href="../genindex.html"

<link rel="search" title="Search" href="../search.html"

<link rel="top" title="Matplotlib 2.2.4 documentation" href="../index.html" />

<link rel="up" title="The Matplotlib API" href="index.html" />

<link rel="next" title="widgets" href="widgets_api.html" />

<link rel="prev" title="type1font" href="type1font.html" />

<link rel="canonical" href="https://matplotlib.org/stable/api/units_api.html" />

<script data-domain="matplotlib.org" defer="defer" src="https://views.scientific-python.org/js/script.js"></script>

</head>

<body>

<div id="unreleased-message"> You are reading an old version of the documentation (v2.2.4). For the latest version see <a href="https://matplotlib.org/stable/api/units_api.html">https://matplotlib.org/stable/api/units_api.html</a></div>

<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px; position: relative;">

<a href="../index.html">

<div style="float: left; position: absolute; width: 496px; bottom: 0; padding-bottom: 24px"><span style="float: right; color: #789; background: white">Version 2.2.4</span></div>

<img src="../_static/logo2.png" height="125px" border="0" alt="matplotlib"/></a>

<div id="forkongithub"><a href="https://github.com/matplotlib/matplotlib">Fork me on GitHub</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="widgets_api.html" title="widgets"

accesskey="N">next</a> |</li>

<li class="right" >

<a href="type1font.html" title="type1font"

accesskey="P">previous</a> |</li>

<li><a href="../index.html">home</a>|&nbsp;</li>

<li><a href="../gallery/index.html">examples</a>|&nbsp;</li>

<li><a href="../tutorials/index.html">tutorials</a>|&nbsp;</li>

<li><a href="pyplot_summary.html">pyplot</a>|&nbsp;</li>

<li><a href="../contents.html">docs</a> &raquo;</li>

<li><a href="index.html" accesskey="U">The Matplotlib API</a> &raquo;</li>

</ul>

</div>

<div class="sphinxsidebar">

<div class="sphinxsidebarwrapper">

<div id="searchbox" style="display: none" role="search">

<h3>Quick search</h3>

<div class="searchformwrapper">

<form class="search" action="../search.html" method="get">

<input type="text" name="q" />

<input type="submit" value="Go" />

<input type="hidden" name="check_keywords" value="yes" />

<input type="hidden" name="area" value="default" />

</form>

</div>

<script type="text/javascript">$('#searchbox').show(0);</script>

<h3><a href="../contents.html">Table of Contents</a></h3>

<ul>

<li><a class="reference internal" href="#">units</a><ul>

<li><a class="reference internal" href="#module-matplotlib.units"><code class="docutils literal notranslate"><span class="pre">matplotlib.units</span></code></a></li>

<div class="relations">

<h3>Related Topics</h3>

<li><a href="../contents.html">Documentation overview</a><ul>

<li><a href="index.html">The Matplotlib API</a><ul>

<li>Previous: <a href="type1font.html" title="previous chapter">type1font</a></li>

<li>Next: <a href="widgets_api.html" title="next chapter">widgets</a></li>

</ul></li>

</ul></li>

<div id="sidebar-pagesource" role="note" aria-label="source link"

style="margin-top: 1.5em; padding-top: 0.1em; border-top: 1px solid #86989b">

<a href="../_sources/api/units_api.rst.txt"

style="color: #c0c0c0" rel="nofollow">Show Page Source</a>

</div>

</div>

</div>

<div class="document">

<div class="documentwrapper">

<div class="bodywrapper">

<div class="body">

<div class="section" id="units">

<h1>units<a class="headerlink" href="#units" title="Permalink to this headline">¶</a></h1>

<div class="section" id="module-matplotlib.units">

<span id="matplotlib-units"></span><h2><a class="reference internal" href="#module-matplotlib.units" title="matplotlib.units"><code class="xref py py-mod docutils literal notranslate"><span class="pre">matplotlib.units</span></code></a><a class="headerlink" href="#module-matplotlib.units" title="Permalink to this headline">¶</a></h2>

<p>The classes here provide support for using custom classes with

Matplotlib, e.g., those that do not expose the array interface but know

how to convert themselves to arrays. It also supports classes with

units and units conversion. Use cases include converters for custom

objects, e.g., a list of datetime objects, as well as for objects that

are unit aware. We don't assume any particular units implementation;

rather a units implementation must provide the register with the Registry

converter dictionary and a <a class="reference internal" href="#matplotlib.units.ConversionInterface" title="matplotlib.units.ConversionInterface"><code class="xref py py-obj docutils literal notranslate"><span class="pre">ConversionInterface</span></code></a>. For example,

here is a complete implementation which supports plotting with native

datetime objects:</p>

<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">matplotlib.units</span> <span class="k">as</span> <span class="nn">units</span>

<span class="kn">import</span> <span class="nn">matplotlib.dates</span> <span class="k">as</span> <span class="nn">dates</span>

<span class="kn">import</span> <span class="nn">matplotlib.ticker</span> <span class="k">as</span> <span class="nn">ticker</span>

<span class="kn">import</span> <span class="nn">datetime</span>

<span class="k">class</span> <span class="nc">DateConverter</span><span class="p">(</span><span class="n">units</span><span class="o">.</span><span class="n">ConversionInterface</span><span class="p">):</span>

<span class="nd">@staticmethod</span>

<span class="k">def</span> <span class="nf">convert</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">unit</span><span class="p">,</span> <span class="n">axis</span><span class="p">):</span>

<span class="s1">&#39;Convert a datetime value to a scalar or array&#39;</span>

<span class="k">return</span> <span class="n">dates</span><span class="o">.</span><span class="n">date2num</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>

<span class="nd">@staticmethod</span>

<span class="k">def</span> <span class="nf">axisinfo</span><span class="p">(</span><span class="n">unit</span><span class="p">,</span> <span class="n">axis</span><span class="p">):</span>

<span class="s1">&#39;Return major and minor tick locators and formatters&#39;</span>

<span class="k">if</span> <span class="n">unit</span><span class="o">!=</span><span class="s1">&#39;date&#39;</span><span class="p">:</span> <span class="k">return</span> <span class="kc">None</span>

<span class="n">majloc</span> <span class="o">=</span> <span class="n">dates</span><span class="o">.</span><span class="n">AutoDateLocator</span><span class="p">()</span>

<span class="n">majfmt</span> <span class="o">=</span> <span class="n">dates</span><span class="o">.</span><span class="n">AutoDateFormatter</span><span class="p">(</span><span class="n">majloc</span><span class="p">)</span>

<span class="k">return</span> <span class="n">AxisInfo</span><span class="p">(</span><span class="n">majloc</span><span class="o">=</span><span class="n">majloc</span><span class="p">,</span>

<span class="n">majfmt</span><span class="o">=</span><span class="n">majfmt</span><span class="p">,</span>

<span class="n">label</span><span class="o">=</span><span class="s1">&#39;date&#39;</span><span class="p">)</span>

<span class="nd">@staticmethod</span>

<span class="k">def</span> <span class="nf">default_units</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">axis</span><span class="p">):</span>

<span class="s1">&#39;Return the default unit for x or None&#39;</span>

<span class="k">return</span> <span class="s1">&#39;date&#39;</span>

<span class="c1"># Finally we register our object type with the Matplotlib units registry.</span>

<span class="n">units</span><span class="o">.</span><span class="n">registry</span><span class="p">[</span><span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="p">]</span> <span class="o">=</span> <span class="n">DateConverter</span><span class="p">()</span>

<dl class="class">

<dt id="matplotlib.units.AxisInfo">

<em class="property">class </em><code class="descclassname">matplotlib.units.</code><code class="descname">AxisInfo</code><span class="sig-paren">(</span><em>majloc=None</em>, <em>minloc=None</em>, <em>majfmt=None</em>, <em>minfmt=None</em>, <em>label=None</em>, <em>default_limits=None</em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/matplotlib/units.html#AxisInfo"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#matplotlib.units.AxisInfo" title="Permalink to this definition">¶</a></dt>

<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.7)"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a></p>

<p>Information to support default axis labeling, tick labeling, and

default limits. An instance of this class must be returned by

<a class="reference internal" href="#matplotlib.units.ConversionInterface.axisinfo" title="matplotlib.units.ConversionInterface.axisinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConversionInterface.axisinfo()</span></code></a>.</p>

<table class="docutils field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><dl class="first last docutils">

<dt><strong>majloc, minloc</strong> <span class="classifier-delimiter">:</span> <span class="classifier">Locator, optional</span></dt>

<dd><p class="first last">Tick locators for the major and minor ticks.</p>

<dt><strong>majfmt, minfmt</strong> <span class="classifier-delimiter">:</span> <span class="classifier">Formatter, optional</span></dt>

<dd><p class="first last">Tick formatters for the major and minor ticks.</p>

<dt><strong>label</strong> <span class="classifier-delimiter">:</span> <span class="classifier">str, optional</span></dt>

<dd><p class="first last">The default axis label.</p>

<dt><strong>default_limits</strong> <span class="classifier-delimiter">:</span> <span class="classifier">optional</span></dt>

<dd><p class="first last">The default min and max limits of the axis if no data has

been plotted.</p>

<p class="rubric">Notes</p>

<p>If any of the above are <code class="docutils literal notranslate"><span class="pre">None</span></code>, the axis will simply use the

default value.</p>

<dl class="class">

<dt id="matplotlib.units.ConversionInterface">

<em class="property">class </em><code class="descclassname">matplotlib.units.</code><code class="descname">ConversionInterface</code><a class="reference internal" href="../_modules/matplotlib/units.html#ConversionInterface"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#matplotlib.units.ConversionInterface" title="Permalink to this definition">¶</a></dt>

<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.7)"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a></p>

<p>The minimal interface for a converter to take custom data types (or

sequences) and convert them to values Matplotlib can use.</p>

<dl class="staticmethod">

<dt id="matplotlib.units.ConversionInterface.axisinfo">

<em class="property">static </em><code class="descname">axisinfo</code><span class="sig-paren">(</span><em>unit</em>, <em>axis</em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/matplotlib/units.html#ConversionInterface.axisinfo"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#matplotlib.units.ConversionInterface.axisinfo" title="Permalink to this definition">¶</a></dt>

<dd><p>Return an <code class="xref py py-obj docutils literal notranslate"><span class="pre">AxisInfo</span></code> instance for the axis with the

specified units.</p>

<dl class="staticmethod">

<dt id="matplotlib.units.ConversionInterface.convert">

<em class="property">static </em><code class="descname">convert</code><span class="sig-paren">(</span><em>obj</em>, <em>unit</em>, <em>axis</em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/matplotlib/units.html#ConversionInterface.convert"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#matplotlib.units.ConversionInterface.convert" title="Permalink to this definition">¶</a></dt>

<dd><p>Convert <em>obj</em> using <em>unit</em> for the specified <em>axis</em>.

If <em>obj</em> is a sequence, return the converted sequence.

The output must be a sequence of scalars that can be used by the numpy

array layer.</p>

<dl class="staticmethod">

<dt id="matplotlib.units.ConversionInterface.default_units">

<em class="property">static </em><code class="descname">default_units</code><span class="sig-paren">(</span><em>x</em>, <em>axis</em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/matplotlib/units.html#ConversionInterface.default_units"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#matplotlib.units.ConversionInterface.default_units" title="Permalink to this definition">¶</a></dt>

<dd><p>Return the default unit for <em>x</em> or <code class="docutils literal notranslate"><span class="pre">None</span></code> for the given axis.</p>

<dl class="staticmethod">

<dt id="matplotlib.units.ConversionInterface.is_numlike">

<em class="property">static </em><code class="descname">is_numlike</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/matplotlib/units.html#ConversionInterface.is_numlike"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#matplotlib.units.ConversionInterface.is_numlike" title="Permalink to this definition">¶</a></dt>

<dd><p>The Matplotlib datalim, autoscaling, locators etc work with

scalars which are the units converted to floats given the

current unit. The converter may be passed these floats, or

arrays of them, even when units are set.</p>

<dl class="class">

<dt id="matplotlib.units.Registry">

<em class="property">class </em><code class="descclassname">matplotlib.units.</code><code class="descname">Registry</code><a class="reference internal" href="../_modules/matplotlib/units.html#Registry"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#matplotlib.units.Registry" title="Permalink to this definition">¶</a></dt>

<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.7)"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a></p>

<p>A register that maps types to conversion interfaces.</p>

<dl class="method">

<dt id="matplotlib.units.Registry.get_converter">

<code class="descname">get_converter</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/matplotlib/units.html#Registry.get_converter"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#matplotlib.units.Registry.get_converter" title="Permalink to this definition">¶</a></dt>

<dd><p>Get the converter for data that has the same type as <em>x</em>. If no

converters are registered for <em>x</em>, returns <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>

</div>

</div>

</div>

<div class="clearer"></div>

</div>

<div class="footer">

&copy; Copyright 2002 - 2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the Matplotlib development team; 2012 - 2018 The Matplotlib development team.

<br />

Last updated on Feb 28, 2019.

Created using

<ahref="http://sphinx-doc.org/">Sphinx</a> 1.8.4.

Doc version v2.2.4-2-g38a93e9a0-dirty.

</div>