<!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>Unit formats — Astropy v0.2.4</title>
<link rel="stylesheet" href="../_static/bootstrap-astropy.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.2.4',
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>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="shortcut icon" href="../_static/astropy_logo.ico"/>
<link rel="top" title="Astropy v0.2.4" href="../index.html" />
<link rel="up" title="Units (astropy.units)" href="index.html" />
<link rel="next" title="Equivalencies" href="equivalencies.html" />
<link rel="prev" title="Unit Conversion" href="conversion.html" />
</head>
<body>
<div class="topbar">
<a class="brand" title="Documentation Home" href="../index.html"></a>
<ul>
<li><a class="homelink" title="AstroPy Homepage" href="http://www.astropy.org"></a></li>
<li><a title="General Index" href="../genindex.html">Index</a></li>
<li><a title="Python Module Index" href="../py-modindex.html">Modules</a></li>
<li>
<form action="../search.html" method="get">
<input type="text" name="q" placeholder="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</li>
</ul>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right">
<a href="equivalencies.html" title="Equivalencies">
next »
</a>
</li>
<li class="right">
<a href="conversion.html" title="Unit Conversion">
« previous
</a>
|
</li>
<li>
<a href="../index.html">Astropy v0.2.4</a>
»
</li>
<li><a href="index.html" accesskey="U">Units (<tt class="docutils literal"><span class="pre">astropy.units</span></tt>)</a> »</li>
<li>Unit formats</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="unit-formats">
<h1>Unit formats<a class="headerlink" href="#unit-formats" title="Permalink to this headline">¶</a></h1>
<p>Units can be created from strings using the <a class="reference internal" href="../_generated/astropy.units.core.Unit.html#astropy.units.core.Unit" title="astropy.units.core.Unit"><tt class="xref py py-obj docutils literal"><span class="pre">Unit</span></tt></a>
class:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">astropy</span> <span class="kn">import</span> <span class="n">units</span> <span class="k">as</span> <span class="n">u</span>
<span class="gp">>>> </span><span class="n">u</span><span class="o">.</span><span class="n">Unit</span><span class="p">(</span><span class="s">"m"</span><span class="p">)</span>
<span class="go">Unit("m")</span>
<span class="gp">>>> </span><span class="n">u</span><span class="o">.</span><span class="n">Unit</span><span class="p">(</span><span class="s">"erg / (s cm2)"</span><span class="p">)</span>
<span class="go">Unit("erg / (s cm2)")</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Creating units from strings requires the use of a specialized
parser for the unit language, which results in a performance
penalty if units are created using strings. Thus, it is much
faster to use unit objects directly (e.g., <tt class="docutils literal"><span class="pre">unit</span> <span class="pre">=</span> <span class="pre">u.degree</span> <span class="pre">/</span>
<span class="pre">u.minute</span></tt>) instead of via string parsing (<tt class="docutils literal"><span class="pre">unit</span> <span class="pre">=</span>
<span class="pre">u.Unit('deg/min')</span></tt>).</p>
</div>
<p>Units can be converted to strings using the
<a class="reference internal" href="../_generated/astropy.units.core.UnitBase.html#astropy.units.core.UnitBase.to_string" title="astropy.units.core.UnitBase.to_string"><tt class="xref py py-obj docutils literal"><span class="pre">to_string</span></tt></a> method:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">fluxunit</span> <span class="o">=</span> <span class="n">u</span><span class="o">.</span><span class="n">erg</span> <span class="o">/</span> <span class="p">(</span><span class="n">u</span><span class="o">.</span><span class="n">cm</span> <span class="o">**</span> <span class="mi">2</span> <span class="o">*</span> <span class="n">u</span><span class="o">.</span><span class="n">s</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">fluxunit</span><span class="o">.</span><span class="n">to_string</span><span class="p">()</span>
<span class="go">u'erg / (cm2 s)'</span>
</pre></div>
</div>
<p>By default, the string format used is referred to as the “generic”
format, which is based on syntax of the FITS standard’s format for
representing units, but supports all of the units defined within the
<tt class="xref py py-obj docutils literal"><span class="pre">astropy.units</span></tt> framework, including user-defined units. The
<a class="reference internal" href="../_generated/astropy.units.core.Unit.html#astropy.units.core.Unit" title="astropy.units.core.Unit"><tt class="xref py py-obj docutils literal"><span class="pre">Unit</span></tt></a> and
<a class="reference internal" href="../_generated/astropy.units.core.UnitBase.html#astropy.units.core.UnitBase.to_string" title="astropy.units.core.UnitBase.to_string"><tt class="xref py py-obj docutils literal"><span class="pre">to_string</span></tt></a> functions also take an
optional <tt class="xref py py-obj docutils literal"><span class="pre">format</span></tt> parameter to select a different format.</p>
<div class="section" id="built-in-formats">
<h2>Built-in formats<a class="headerlink" href="#built-in-formats" title="Permalink to this headline">¶</a></h2>
<p><tt class="xref py py-obj docutils literal"><span class="pre">astropy.units</span></tt> includes support for parsing and writing the following
formats:</p>
<blockquote>
<div><ul class="simple">
<li><tt class="docutils literal"><span class="pre">"fits"</span></tt>: This is the format defined in the Units section of the
<a class="reference external" href="http://fits.gsfc.nasa.gov/fits_standard.html">FITS Standard</a>.
Unlike the “generic” string format, this will only accept or
generate units defined in the FITS standard.</li>
<li><tt class="docutils literal"><span class="pre">"vounit"</span></tt>: The <a class="reference external" href="http://www.ivoa.net/Documents/VOUnits/">proposed IVOA standard</a> for representing units
in the VO. Again, based on the FITS syntax, but the collection of
supported units is different.</li>
<li><tt class="docutils literal"><span class="pre">"cds"</span></tt>: <a class="reference external" href="http://cds.u-strasbg.fr/doc/catstd-3.2.htx">Standards for astronomical catalogues from Centre de
Données astronomiques de Strasbourg</a>: This is the
standard used, for example, by VOTable versions 1.2 and earlier.</li>
</ul>
</div></blockquote>
<p><tt class="xref py py-obj docutils literal"><span class="pre">astropy.units</span></tt> is also able to write, but not read, units in the
following formats:</p>
<blockquote>
<div><ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">"latex"</span></tt>: Writes units out using LaTeX math syntax using the
<a class="reference external" href="http://www.iau.org/static/publications/stylemanual1989.pdf">IAU Style Manual</a>
recommendations for unit presentation. This format is
automatically used when printing a unit in the IPython notebook:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">fluxunit</span>
</pre></div>
</div>
<div class="math">
<p><span class="math">\mathrm{\frac{erg}{s\ cm^{2}}}</span></p>
</div></li>
<li><p class="first"><tt class="docutils literal"><span class="pre">"console"</span></tt>: Writes a multi-line representation of the unit
useful for display in a text console:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span> <span class="n">fluxunit</span><span class="o">.</span><span class="n">to_string</span><span class="p">(</span><span class="s">'console'</span><span class="p">)</span>
<span class="go"> erg</span>
<span class="go">------</span>
<span class="go">s cm^2</span>
</pre></div>
</div>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">"unicode"</span></tt>: Same as <tt class="docutils literal"><span class="pre">"console"</span></tt>, except uses Unicode
characters:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span> <span class="n">u</span><span class="o">.</span><span class="n">Ry</span><span class="o">.</span><span class="n">decompose</span><span class="p">()</span><span class="o">.</span><span class="n">to_string</span><span class="p">(</span><span class="s">'unicode'</span><span class="p">)</span>
<span class="go"> m² kg</span>
<span class="go">2.18×10-¹⁸ ─────</span>
<span class="go"> s²</span>
</pre></div>
</div>
</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="unrecognized-units">
<h2>Unrecognized Units<a class="headerlink" href="#unrecognized-units" title="Permalink to this headline">¶</a></h2>
<p>Since many files in found in the wild have unit strings that do not
correspond to any given standard, <tt class="xref py py-obj docutils literal"><span class="pre">astropy.units</span></tt> also has a
consistent way to store and pass around unit strings that did not
parse.</p>
<p>Normally, passing an unrecognized unit string raises an exception:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">u</span><span class="o">.</span><span class="n">Unit</span><span class="p">(</span><span class="s">"m/s/s"</span><span class="p">)</span> <span class="c"># The FITS standard only allows one '/'</span>
<span class="go">ValueError: Expected end of text (at char 3) in 'm/s/s'</span>
</pre></div>
</div>
<p>However, the <a class="reference internal" href="../_generated/astropy.units.core.Unit.html#astropy.units.core.Unit" title="astropy.units.core.Unit"><tt class="xref py py-obj docutils literal"><span class="pre">Unit</span></tt></a> constructor has the keyword
argument <tt class="xref py py-obj docutils literal"><span class="pre">parse_strict</span></tt> that can take one of three values to control
this behavior:</p>
<blockquote>
<div><ul class="simple">
<li><tt class="docutils literal"><span class="pre">'raise'</span></tt>: (default) raise a ValueError exception.</li>
<li><tt class="docutils literal"><span class="pre">'warn'</span></tt>: emit a Warning, and return an
<a class="reference internal" href="../_generated/astropy.units.core.UnrecognizedUnit.html#astropy.units.core.UnrecognizedUnit" title="astropy.units.core.UnrecognizedUnit"><tt class="xref py py-obj docutils literal"><span class="pre">UnrecognizedUnit</span></tt></a> instance.</li>
<li><tt class="docutils literal"><span class="pre">'silent'</span></tt>: return an <a class="reference internal" href="../_generated/astropy.units.core.UnrecognizedUnit.html#astropy.units.core.UnrecognizedUnit" title="astropy.units.core.UnrecognizedUnit"><tt class="xref py py-obj docutils literal"><span class="pre">UnrecognizedUnit</span></tt></a>
instance.</li>
</ul>
</div></blockquote>
<p>So, for example, one can do:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">x</span> <span class="o">=</span> <span class="n">u</span><span class="o">.</span><span class="n">Unit</span><span class="p">(</span><span class="s">"m/s/s"</span><span class="p">,</span> <span class="n">parse_strict</span><span class="o">=</span><span class="s">"warn"</span><span class="p">)</span>
<span class="go">WARNING: UnitsWarning: 'm/s/s' did not parse using format 'generic'.</span>
<span class="go">Expected end of text (at char 3) in 'm/s/s' [astropy.units.core]</span>
</pre></div>
</div>
<p>This <a class="reference internal" href="../_generated/astropy.units.core.UnrecognizedUnit.html#astropy.units.core.UnrecognizedUnit" title="astropy.units.core.UnrecognizedUnit"><tt class="xref py py-obj docutils literal"><span class="pre">UnrecognizedUnit</span></tt></a> object remembers the
original string it was created with, so it can be written back out,
but any meaningful operations on it, such as converting to another
unit or composing with other units, will fail.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">x</span><span class="o">.</span><span class="n">to_string</span><span class="p">()</span>
<span class="go">'m/s/s'</span>
<span class="gp">>>> </span><span class="n">x</span><span class="o">.</span><span class="n">to</span><span class="p">(</span><span class="n">u</span><span class="o">.</span><span class="n">km</span> <span class="o">/</span> <span class="n">u</span><span class="o">.</span><span class="n">s</span> <span class="o">/</span> <span class="n">u</span><span class="o">.</span><span class="n">s</span><span class="p">)</span>
<span class="go">ValueError: The unit 'm/s/s' is unrecognized. It can not be converted to</span>
<span class="go">other units.</span>
<span class="gp">>>> </span><span class="n">x</span> <span class="o">/</span> <span class="n">u</span><span class="o">.</span><span class="n">m</span>
<span class="go">ValueError: The unit 'm/s/s' is unrecognized, so all arithmetic operations</span>
<span class="go">with it are invalid.</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper"><h3>Page Contents</h3>
<ul>
<li><a class="reference internal" href="#">Unit formats</a><ul>
<li><a class="reference internal" href="#built-in-formats">Built-in formats</a></li>
<li><a class="reference internal" href="#unrecognized-units">Unrecognized Units</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<footer class="footer">
<p class="pull-right">
<a href="http://github.com/astropy/astropy/tree/v0.2.4/docs/units/format.rst">Edit This Page on Github</a>
<a href="../_sources/units/format.txt"
rel="nofollow">Page Source</a>
<a href="#">Back to Top</a></p>
<p>
© Copyright 2011-2013, The Astropy Developers.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
Last built 22 Oct 2013. <br/>
</p>
</footer>
</body>
</html>
