<!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>FITS Headers — 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="FITS File handling (astropy.io.fits)" href="../index.html" />
<link rel="next" title="Image Data" href="image.html" />
<link rel="prev" title="FITS File handling (astropy.io.fits)" href="../index.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="image.html" title="Image Data">
next »
</a>
</li>
<li class="right">
<a href="../index.html" title="FITS File handling (astropy.io.fits)">
« previous
</a>
|
</li>
<li>
<a href="../../../index.html">Astropy v0.2.4</a>
»
</li>
<li><a href="../index.html" accesskey="U">FITS File handling (<tt class="docutils literal"><span class="pre">astropy.io.fits</span></tt>)</a> »</li>
<li>FITS Headers</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="fits-headers">
<h1>FITS Headers<a class="headerlink" href="#fits-headers" title="Permalink to this headline">¶</a></h1>
<p>In the next three chapters, more detailed information as well as examples will
be explained for manipulating the header, the image data, and the table data
respectively.</p>
<div class="section" id="header-of-an-hdu">
<h2>Header of an HDU<a class="headerlink" href="#header-of-an-hdu" title="Permalink to this headline">¶</a></h2>
<p>Every HDU normally has two components: header and data. In Astropy these two
components are accessed through the two attributes of the HDU,
<tt class="xref py py-attr docutils literal"><span class="pre">header</span></tt> and <tt class="xref py py-attr docutils literal"><span class="pre">data</span></tt>.</p>
<p>While an HDU may have empty data, i.e. the .data attribute is None, any HDU
will always have a header. When an HDU is created with a constructor, e.g.
<tt class="docutils literal"><span class="pre">hdu</span> <span class="pre">=</span> <span class="pre">PrimaryHDU(data,</span> <span class="pre">header)</span></tt>, the user may supply the header value from
an existing HDU’s header and the data value from a numpy array. If the
defaults (<tt class="docutils literal"><span class="pre">None</span></tt>) are used, the new HDU will have the minimal required
keywords for an HDU of that type:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">hdu</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">PrimaryHDU</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">hdu</span><span class="o">.</span><span class="n">header</span> <span class="c"># show the all of the header cards</span>
<span class="go">SIMPLE = T / conforms to FITS standard</span>
<span class="go">BITPIX = 8 / array data type</span>
<span class="go">NAXIS = 0 / number of array dimensions</span>
<span class="go">EXTEND = T</span>
</pre></div>
</div>
<p>A user can use any header and any data to construct a new HDU. Astropy will
strip the required keywords from the input header first and then add back the
required keywords compatible to the new HDU. So, a user can use a table HDU’s
header to construct an image HDU and vice versa. The constructor will also
ensure the data type and dimension information in the header agree with the
data.</p>
</div>
<div class="section" id="the-header-attribute">
<h2>The Header Attribute<a class="headerlink" href="#the-header-attribute" title="Permalink to this headline">¶</a></h2>
<div class="section" id="value-access-updating-and-creating">
<h3>Value Access, Updating, and Creating<a class="headerlink" href="#value-access-updating-and-creating" title="Permalink to this headline">¶</a></h3>
<p>As shown in the Quick Tutorial, keyword values can be accessed via keyword name
or index of an HDU’s header attribute. Here is a quick summary:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">hdulist</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s">'input.fits'</span><span class="p">)</span> <span class="c"># open a FITS file</span>
<span class="gp">>>> </span><span class="n">prihdr</span> <span class="o">=</span> <span class="n">hdulist</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">header</span> <span class="c"># the primary HDU header</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">prihdr</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="c"># get the 4th keyword's value</span>
<span class="go">10</span>
<span class="gp">>>> </span><span class="n">prihdr</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="o">=</span> <span class="mi">20</span> <span class="c"># change its value</span>
<span class="gp">>>> </span><span class="n">prihdr</span><span class="p">[</span><span class="s">'DARKCORR'</span><span class="p">]</span> <span class="c"># get the value of the keyword 'darkcorr'</span>
<span class="go">'OMIT'</span>
<span class="gp">>>> </span><span class="n">prihdr</span><span class="p">[</span><span class="s">'darkcorr'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'PERFORM'</span> <span class="c"># change darkcorr's value</span>
</pre></div>
</div>
<p>Keyword names are case-insenstive except in a few special cases (see the
sections on HIERARCH card and record-valued cards). Thus, <tt class="docutils literal"><span class="pre">prihdr['abc']</span></tt>,
<tt class="docutils literal"><span class="pre">prihdr['ABC']</span></tt>, or <tt class="docutils literal"><span class="pre">prihdr['aBc']</span></tt> are all equivalent.</p>
<p>Like with python <tt class="xref py py-class docutils literal"><span class="pre">dict</span></tt>s, new keywords can also be added to the header
using assignment syntax:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="s">'DARKCORR'</span> <span class="ow">in</span> <span class="n">header</span> <span class="c"># Check for existence</span>
<span class="go">False</span>
<span class="gp">>>> </span><span class="n">header</span><span class="p">[</span><span class="s">'DARKCORR'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'OMIT'</span> <span class="c"># Add a new DARKCORR keyword</span>
</pre></div>
</div>
<p>You can also add a new value <em>and</em> comment by assigning them as a tuple:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">header</span><span class="p">[</span><span class="s">'DARKCORR'</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="s">'OMIT'</span><span class="p">,</span> <span class="s">'Dark Image Subtraction'</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>An important point to note when adding new keywords to a header is that by
default they are not appended <em>immediately</em> to the end of the file.
Rather, they are appended to the last non-commentary keyword. This is in
order to support the common use case of always having all HISTORY keywords
grouped together at the end of a header. A new non-commentary keyword will
be added at the end of the existing keywords, but before any
HISTORY/COMMENT keywords at the end of the header.</p>
<p>There are a couple of ways to override this functionality:</p>
<ul class="last">
<li><p class="first">Use the <a class="reference internal" href="../api/headers.html#astropy.io.fits.Header.append" title="astropy.io.fits.Header.append"><tt class="xref py py-meth docutils literal"><span class="pre">Header.append()</span></tt></a> method with the <tt class="docutils literal"><span class="pre">end=True</span></tt> argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">header</span><span class="o">.</span><span class="n">append</span><span class="p">((</span><span class="s">'DARKCORR'</span><span class="p">,</span> <span class="s">'OMIT'</span><span class="p">,</span> <span class="s">'Dark Image Subtraction'</span><span class="p">),</span>
<span class="go"> end=True)</span>
</pre></div>
</div>
<p>This forces the new keyword to be added at the actual end of the header.</p>
</li>
<li><p class="first">The <a class="reference internal" href="../api/headers.html#astropy.io.fits.Header.insert" title="astropy.io.fits.Header.insert"><tt class="xref py py-meth docutils literal"><span class="pre">Header.insert()</span></tt></a> method will always insert a new keyword exactly
where you ask for it:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">header</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="mi">20</span><span class="p">,</span> <span class="p">(</span><span class="s">'DARKCORR'</span><span class="p">,</span> <span class="s">'OMIT'</span><span class="p">,</span> <span class="s">'Dark Image Subtraction'</span><span class="p">))</span>
</pre></div>
</div>
<p>This inserts the DARKCORR keyword before the 20th keyword in the header
no matter what it is.</p>
</li>
</ul>
</div>
<p>A keyword (and its corresponding card) can be deleted using the same index/name
syntax:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">del</span> <span class="n">prihdr</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="c"># delete the 2nd keyword</span>
<span class="gp">>>> </span><span class="k">del</span> <span class="n">prihdr</span><span class="p">[</span><span class="s">'abc'</span><span class="p">]</span> <span class="c"># get the value of the keyword 'abc'</span>
</pre></div>
</div>
<p>Note that, like a regular Python list, the indexing updates after each delete,
so if <tt class="docutils literal"><span class="pre">del</span> <span class="pre">prihdr[3]</span></tt> is done two times in a row, the 4th and 5th keywords
are removed from the original header. Likewise, <tt class="docutils literal"><span class="pre">del</span> <span class="pre">prihdr[-1]</span></tt> will delete
the last card in the header.</p>
<p>It is also possible to delete an entire range of cards using the slice syntax:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">del</span> <span class="n">prihdr</span><span class="p">[</span><span class="mi">3</span><span class="p">:</span><span class="mi">5</span><span class="p">]</span>
</pre></div>
</div>
<p>The method <a class="reference internal" href="../api/headers.html#astropy.io.fits.Header.set" title="astropy.io.fits.Header.set"><tt class="xref py py-meth docutils literal"><span class="pre">Header.set()</span></tt></a> is another way to update they value or comment
associated with an existing keyword, or to create a new keyword. Most of its
functionality can be duplicated with the dict-like syntax shown above. But in
some cases it might be more clear. It also has the advantage of allowing one
to either move cards within the header, or specify the location of a new card
relative to existing cards:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">prihdr</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s">'target'</span><span class="p">,</span> <span class="s">'NGC1234'</span><span class="p">,</span> <span class="s">'target name'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="c"># place the next new keyword before the 'target' keyword</span>
<span class="gp">>>> </span><span class="n">prihdr</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s">'newkey'</span><span class="p">,</span> <span class="mi">666</span><span class="p">,</span> <span class="n">before</span><span class="o">=</span><span class="s">'target'</span><span class="p">)</span> <span class="c"># comment is optional</span>
<span class="gp">>>> </span><span class="c"># place the next new keyword after the 21st keyword</span>
<span class="gp">>>> </span><span class="n">prihdr</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s">'newkey2'</span><span class="p">,</span> <span class="mf">42.0</span><span class="p">,</span> <span class="s">'another new key'</span><span class="p">,</span> <span class="n">after</span><span class="o">=</span><span class="mi">20</span><span class="p">)</span>
</pre></div>
</div>
<p>In FITS headers, each keyword may also have a comment associated with it
explaining its purpose. The comments associated with each keyword are accessed
through the <a class="reference internal" href="../api/headers.html#astropy.io.fits.Header.comments" title="astropy.io.fits.Header.comments"><tt class="xref py py-attr docutils literal"><span class="pre">comments</span></tt></a> attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">header</span><span class="p">[</span><span class="s">'NAXIS'</span><span class="p">]</span>
<span class="go">2</span>
<span class="gp">>>> </span><span class="n">header</span><span class="o">.</span><span class="n">comments</span><span class="p">[</span><span class="s">'NAXIS'</span><span class="p">]</span>
<span class="go">the number of image axes</span>
<span class="gp">>>> </span><span class="n">header</span><span class="o">.</span><span class="n">comments</span><span class="p">[</span><span class="s">'NAXIS'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'The number of image axes'</span> <span class="c"># Update</span>
</pre></div>
</div>
<p>Comments can be accessed in all the same ways that values are accessed, whether
by keyword name or card index. Slices are also possible. The only difference
is that you go through <tt class="docutils literal"><span class="pre">header.comments</span></tt> instead of just <tt class="docutils literal"><span class="pre">header</span></tt> by
itself.</p>
</div>
<div class="section" id="comment-history-and-blank-keywords">
<h3>COMMENT, HISTORY, and Blank Keywords<a class="headerlink" href="#comment-history-and-blank-keywords" title="Permalink to this headline">¶</a></h3>
<p>Most keywords in a FITS header have unique names. If there are more than two
cards sharing the same name, it is the first one accessed when referred by
name. The duplicates can only be accessed by numeric indexing.</p>
<p>There are three special keywords (their associated cards are sometimes referred
to as commentary cards), which commonly appear in FITS headers more than once.
They are (1) blank keyword, (2) HISTORY, and (3) COMMENT. Unlike other
keywords, when accessing these keywords they are returned as a list:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">prihdr</span><span class="p">[</span><span class="s">'HISTORY'</span><span class="p">]</span>
<span class="go">I updated this file on 02/03/2011</span>
<span class="go">I updated this file on 02/04/2011</span>
<span class="go">....</span>
</pre></div>
</div>
<p>These lists can be sliced like any other list. For example, to diplay just the
last HISTORY entry, use <tt class="docutils literal"><span class="pre">prihdr['history'][-1]</span></tt>. Existing commentary cards
can also be updated by using the appropriate index number for that card.</p>
<p>New commentary cards can be added like any other card by using the dict-like
keyword assignment syntax, or by using the <a class="reference internal" href="../api/headers.html#astropy.io.fits.Header.set" title="astropy.io.fits.Header.set"><tt class="xref py py-meth docutils literal"><span class="pre">Header.set()</span></tt></a> method. However,
unlike with other keywords, a new commentary card is always added and appended
to the last commentary card with the same keyword, rather than to the end of
the header. Here is an example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">hdu</span><span class="o">.</span><span class="n">header</span><span class="p">[</span><span class="s">'HISTORY'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'history 1'</span>
<span class="gp">>>> </span><span class="n">hdu</span><span class="o">.</span><span class="n">header</span><span class="p">[</span><span class="s">''</span><span class="p">]</span> <span class="o">=</span> <span class="s">'blank 1'</span>
<span class="gp">>>> </span><span class="n">hdu</span><span class="o">.</span><span class="n">header</span><span class="p">[</span><span class="s">'COMMENT'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'comment 1'</span>
<span class="gp">>>> </span><span class="n">hdu</span><span class="o">.</span><span class="n">header</span><span class="p">[</span><span class="s">'HISTORY'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'history 2'</span>
<span class="gp">>>> </span><span class="n">hdu</span><span class="o">.</span><span class="n">header</span><span class="p">[</span><span class="s">''</span><span class="p">]</span> <span class="o">=</span> <span class="s">'blank 2'</span>
<span class="gp">>>> </span><span class="n">hdu</span><span class="o">.</span><span class="n">header</span><span class="p">[</span><span class="s">'COMMENT'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'comment 2'</span>
</pre></div>
</div>
<p>and the part in the modified header becomes:</p>
<div class="highlight-python"><pre>HISTORY history 1
HISTORY history 2
blank 1
blank 2
COMMENT comment 1
COMMENT comment 2</pre>
</div>
<p>Users can also directly control exactly where in the header to add a new
commentary card by using the <a class="reference internal" href="../api/headers.html#astropy.io.fits.Header.insert" title="astropy.io.fits.Header.insert"><tt class="xref py py-meth docutils literal"><span class="pre">Header.insert()</span></tt></a> method.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Ironically, there is no comment in a commentary card, only a string
value.</p>
</div>
</div>
</div>
<div class="section" id="card-images">
<h2>Card Images<a class="headerlink" href="#card-images" title="Permalink to this headline">¶</a></h2>
<p>A FITS header consists of card images.</p>
<p>A card image in a FITS header consists of a keyword name, a value, and
optionally a comment. Physically, it takes 80 columns (bytes)–without carriage
return–in a FITS file’s storage format. In Astropy, each card image is
manifested by a <a class="reference internal" href="../api/cards.html#astropy.io.fits.Card" title="astropy.io.fits.Card"><tt class="xref py py-class docutils literal"><span class="pre">Card</span></tt></a> object. There are also special kinds of cards:
commentary cards (see above) and card images taking more than one 80-column
card image. The latter will be discussed later.</p>
<p>Most of the time the details of dealing with cards are handled by the
<a class="reference internal" href="../api/headers.html#astropy.io.fits.Header" title="astropy.io.fits.Header"><tt class="xref py py-class docutils literal"><span class="pre">Header</span></tt></a> object, and it is not necessary to directly manipulate cards.
In fact, most <a class="reference internal" href="../api/headers.html#astropy.io.fits.Header" title="astropy.io.fits.Header"><tt class="xref py py-class docutils literal"><span class="pre">Header</span></tt></a> methods that accept a <tt class="docutils literal"><span class="pre">(keyword,</span> <span class="pre">value)</span></tt> or
<tt class="docutils literal"><span class="pre">(keyword,</span> <span class="pre">value,</span> <span class="pre">comment)</span></tt> tuple as an argument can also take a
<a class="reference internal" href="../api/cards.html#astropy.io.fits.Card" title="astropy.io.fits.Card"><tt class="xref py py-class docutils literal"><span class="pre">Card</span></tt></a> object as an argument. <a class="reference internal" href="../api/cards.html#astropy.io.fits.Card" title="astropy.io.fits.Card"><tt class="xref py py-class docutils literal"><span class="pre">Card</span></tt></a> objects are just wrappers
around such tuples that provide the logic for parsing and formatting individual
cards in a header. But there’s usually nothing gained by manually using a
<a class="reference internal" href="../api/cards.html#astropy.io.fits.Card" title="astropy.io.fits.Card"><tt class="xref py py-class docutils literal"><span class="pre">Card</span></tt></a> object, except to examine how a card might appear in a header
before actually adding it to the header.</p>
<p>A new Card object is created with the <a class="reference internal" href="../api/cards.html#astropy.io.fits.Card" title="astropy.io.fits.Card"><tt class="xref py py-class docutils literal"><span class="pre">Card</span></tt></a> constructor:
<tt class="docutils literal"><span class="pre">Card(key,</span> <span class="pre">value,</span> <span class="pre">comment)</span></tt>. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">c1</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">Card</span><span class="p">(</span><span class="s">'TEMP'</span><span class="p">,</span> <span class="mf">80.0</span><span class="p">,</span> <span class="s">'temperature, floating value'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">c2</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">Card</span><span class="p">(</span><span class="s">'DETECTOR'</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span> <span class="c"># comment is optional</span>
<span class="gp">>>> </span><span class="n">c3</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">Card</span><span class="p">(</span><span class="s">'MIR_REVR'</span><span class="p">,</span> <span class="bp">True</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'mirror reversed? Boolean value'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">c4</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">Card</span><span class="p">(</span><span class="s">'ABC'</span><span class="p">,</span> <span class="mi">2</span><span class="o">+</span><span class="mi">3j</span><span class="p">,</span> <span class="s">'complex value'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">c5</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">Card</span><span class="p">(</span><span class="s">'OBSERVER'</span><span class="p">,</span> <span class="s">'Hubble'</span><span class="p">,</span> <span class="s">'string value'</span><span class="p">)</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span> <span class="n">c1</span><span class="p">;</span> <span class="k">print</span> <span class="n">c2</span><span class="p">;</span> <span class="k">print</span> <span class="n">c3</span><span class="p">;</span> <span class="k">print</span> <span class="n">c4</span><span class="p">;</span> <span class="k">print</span> <span class="n">c5</span> <span class="c"># show the card images</span>
<span class="go">TEMP = 80.0 / temperature, floating value</span>
<span class="go">DETECTOR= 1 /</span>
<span class="go">MIR_REVR= T / mirror reversed? Boolean value</span>
<span class="go">ABC = (2.0, 3.0) / complex value</span>
<span class="go">OBSERVER= 'Hubble ' / string value</span>
</pre></div>
</div>
<p>Cards have the attributes <tt class="docutils literal"><span class="pre">.keyword</span></tt>, <tt class="docutils literal"><span class="pre">.value</span></tt>, and <tt class="docutils literal"><span class="pre">.comment</span></tt>. Both
<tt class="docutils literal"><span class="pre">.value</span></tt> and <tt class="docutils literal"><span class="pre">.comment</span></tt> can be changed but not the <tt class="docutils literal"><span class="pre">.keyword</span></tt> attribute.</p>
<p>The <a class="reference internal" href="../api/cards.html#astropy.io.fits.Card" title="astropy.io.fits.Card"><tt class="xref py py-meth docutils literal"><span class="pre">Card()</span></tt></a> constructor will check if the arguments given are conforming
to the FITS standard and has a fixed card image format. If the user wants to
create a card with a customized format or even a card which is not conforming
to the FITS standard (e.g. for testing purposes), the <a class="reference internal" href="../api/cards.html#astropy.io.fits.Card.fromstring" title="astropy.io.fits.Card.fromstring"><tt class="xref py py-meth docutils literal"><span class="pre">Card.fromstring()</span></tt></a>
class method can be used.</p>
<p>Cards can be verified with <a class="reference internal" href="../api/cards.html#astropy.io.fits.Card.verify" title="astropy.io.fits.Card.verify"><tt class="xref py py-meth docutils literal"><span class="pre">Card.verify()</span></tt></a>. The non-standard card <tt class="docutils literal"><span class="pre">c2</span></tt> in
the example below is flagged by such verification. More about verification in
Astropy will be discussed in a later chapter.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">c1</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">Card</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">'ABC = 3.456D023'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">c2</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">Card</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">"P.I. ='Hubble'"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">c1</span><span class="p">;</span> <span class="k">print</span> <span class="n">c2</span>
<span class="go">ABC = 3.456D023</span>
<span class="go">P.I. ='Hubble'</span>
<span class="gp">>>> </span><span class="n">c2</span><span class="o">.</span><span class="n">verify</span><span class="p">()</span>
<span class="go">Output verification result:</span>
<span class="go">Unfixable error: Illegal keyword name 'P.I.'</span>
</pre></div>
</div>
<p>A list of the <a class="reference internal" href="../api/cards.html#astropy.io.fits.Card" title="astropy.io.fits.Card"><tt class="xref py py-class docutils literal"><span class="pre">Card</span></tt></a> objects underlying a <a class="reference internal" href="../api/headers.html#astropy.io.fits.Header" title="astropy.io.fits.Header"><tt class="xref py py-class docutils literal"><span class="pre">Header</span></tt></a> object can be
accessed with the <a class="reference internal" href="../api/headers.html#astropy.io.fits.Header.cards" title="astropy.io.fits.Header.cards"><tt class="xref py py-attr docutils literal"><span class="pre">Header.cards</span></tt></a> attribute. This list is only meant for
observing, and should not be directly manipulated. In fact, it is only a
copy–modifications to it will not affect the header it came from. Use the
methods provided by the <a class="reference internal" href="../api/headers.html#astropy.io.fits.Header" title="astropy.io.fits.Header"><tt class="xref py py-class docutils literal"><span class="pre">Header</span></tt></a> class instead.</p>
</div>
<div class="section" id="continue-cards">
<h2>CONTINUE Cards<a class="headerlink" href="#continue-cards" title="Permalink to this headline">¶</a></h2>
<p>The fact that the FITS standard only allows up to 8 characters for the keyword
name and 80 characters to contain the keyword, the value, and the comment is
restrictive for certain applications. To allow long string values for keywords,
a proposal was made in:</p>
<blockquote>
<div><a class="reference external" href="http://legacy.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html">http://legacy.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html</a></div></blockquote>
<p>by using the CONTINUE keyword after the regular 80-column containing the
keyword. Astropy does support this convention, even though it is not a FITS
standard. The examples below show the use of CONTINUE is automatic for long
string values.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">header</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">Header</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">header</span><span class="p">[</span><span class="s">'abc'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'abcdefg'</span> <span class="o">*</span> <span class="mi">20</span>
<span class="gp">>>> </span><span class="n">header</span>
<span class="go">ABC = 'abcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcd&'</span>
<span class="go">CONTINUE 'efgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefga&'</span>
<span class="go">CONTINUE 'bcdefg&'</span>
<span class="gp">>>> </span><span class="n">header</span><span class="p">[</span><span class="s">'abc'</span><span class="p">]</span>
<span class="go">'abcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefg'</span>
<span class="gp">>>> </span><span class="c"># both value and comments are long</span>
<span class="gp">>>> </span><span class="n">header</span><span class="p">[</span><span class="s">'abc'</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="s">'abcdefg'</span> <span class="o">*</span> <span class="mi">10</span><span class="p">,</span> <span class="s">'abcdefg'</span> <span class="o">*</span> <span class="mi">10</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">header</span>
<span class="go">ABC = 'abcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcd&'</span>
<span class="go">CONTINUE 'efg&'</span>
<span class="go">CONTINUE '&' / abcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefgabcdefga</span>
<span class="go">CONTINUE '&' / bcdefg</span>
</pre></div>
</div>
<p>Note that when a CONTINUE card is used, at the end of each 80-characters card
image, an ampersand is present. The ampersand is not part of the string value.
Also, there is no “=” at the 9th column after CONTINUE. In the first example,
the entire 240 characters is treated by Astropy as a single card. So, if it is
the nth card in a header, the (n+1)th card refers to the next keyword, not the
next CONTINUE card. As such, CONTINUE cards are transparently handled by
Astropy as a single logical card, and it’s generally not necessary to worry
about the details of the format. Keywords that resolve to a set of CONTINUE
cards can be accessed and updated just like regular keywords.</p>
</div>
<div class="section" id="hierarch-cards">
<h2>HIERARCH Cards<a class="headerlink" href="#hierarch-cards" title="Permalink to this headline">¶</a></h2>
<p>For keywords longer than 8 characters, there is a convention originated at ESO
to facilitate such use. It uses a special keyword HIERARCH with the actual long
keyword following. Astropy supports this convention as well.</p>
<p>If a keyword contains more than 8 characters Astropy will automatically use a
HIERARCH card, but will also issue a warning in case this is in error.
However, one may explicitly request a HIERARCH card by prepending the keyword
with ‘HIERARCH ‘ (just as it would appear in the header). For example,
<tt class="docutils literal"><span class="pre">header['HIERARCH</span> <span class="pre">abcdefghi']</span></tt> will create the keyword <tt class="docutils literal"><span class="pre">abcdefghi</span></tt> without
displaying a warning. Once created, HIERARCH keywords can be accessed like any
other: <tt class="docutils literal"><span class="pre">header['abcdefghi']</span></tt>, without prepending ‘HIERARCH’ to the keyword.
HIEARARCH keywords also differ from normal FITS keywords in that they are
case-sensitive.</p>
<p>Examples follow:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">Card</span><span class="p">(</span><span class="s">'abcdefghi'</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
<span class="go">Keyword name 'abcdefghi' is greater than 8 characters; a HIERARCH card will</span>
<span class="go">be created.</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">c</span>
<span class="go">HIERARCH abcdefghi = 10</span>
<span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">Card</span><span class="p">(</span><span class="s">'hierarch abcdefghi'</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">c</span>
<span class="go">HIERARCH abcdefghi = 10</span>
<span class="gp">>>> </span><span class="n">h</span> <span class="o">=</span> <span class="n">fits</span><span class="o">.</span><span class="n">PrimaryHDU</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">header</span><span class="p">[</span><span class="s">'hierarch abcdefghi'</span><span class="p">]</span> <span class="o">=</span> <span class="mi">99</span>
<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">header</span><span class="p">[</span><span class="s">'abcdefghi'</span><span class="p">]</span>
<span class="go">99</span>
<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">header</span><span class="p">[</span><span class="s">'abcdefghi'</span><span class="p">]</span> <span class="o">=</span> <span class="mi">10</span>
<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">header</span><span class="p">[</span><span class="s">'abcdefghi'</span><span class="p">]</span>
<span class="go">10</span>
<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">header</span><span class="p">[</span><span class="s">'ABCDEFGHI'</span><span class="p">]</span>
<span class="gt">Traceback (most recent call last):</span>
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>, in <span class="n"><module></span>
File <span class="nb">"astropy/io/fits/header.py"</span>, line <span class="m">121</span>, in <span class="n">__getitem__</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_cards</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_cardindex</span><span class="p">(</span><span class="n">key</span><span class="p">)]</span><span class="o">.</span><span class="n">value</span>
File <span class="nb">"astropy/io/fits/header.py"</span>, line <span class="m">1106</span>, in <span class="n">_cardindex</span>
<span class="k">raise</span> <span class="ne">KeyError</span><span class="p">(</span><span class="s">"Keyword </span><span class="si">%r</span><span class="s"> not found."</span> <span class="o">%</span> <span class="n">keyword</span><span class="p">)</span>
<span class="gr">KeyError</span>: <span class="n">"Keyword 'ABCDEFGI.' not found."</span>
<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">header</span>
<span class="go">SIMPLE = T / conforms to FITS standard</span>
<span class="go">BITPIX = 8 / array data type</span>
<span class="go">NAXIS = 0 / number of array dimensions</span>
<span class="go">EXTEND = T</span>
<span class="go">HIERARCH abcdefghi = 1000</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>A final point to keep in mind about the <a class="reference internal" href="../api/headers.html#astropy.io.fits.Header" title="astropy.io.fits.Header"><tt class="xref py py-class docutils literal"><span class="pre">Header</span></tt></a> class is that much
of its design is intended to abstract away quirks about the FITS format.
This is why, for example, it will automatically created CONTINUE and
HIEARARCH cards. The Header is just a data structure, and as user you
shouldn’t have to worry about how it ultimately gets serialized to a header
in a FITS file.</p>
<p class="last">Though there are some areas where it’s almost impossible to hide away the
quirks of the FITS format, Astropy tries to make it so that you have to
think about it as little as possible. If there are any areas where you
have concern yourself unncessarily about how the header is constructed,
then let <a class="reference external" href="mailto:help%40stsci.edu">help<span>@</span>stsci<span>.</span>edu</a> know, as there are probably areas where this can be
improved on even more.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper"><h3>Page Contents</h3>
<ul>
<li><a class="reference internal" href="#">FITS Headers</a><ul>
<li><a class="reference internal" href="#header-of-an-hdu">Header of an HDU</a></li>
<li><a class="reference internal" href="#the-header-attribute">The Header Attribute</a><ul>
<li><a class="reference internal" href="#value-access-updating-and-creating">Value Access, Updating, and Creating</a></li>
<li><a class="reference internal" href="#comment-history-and-blank-keywords">COMMENT, HISTORY, and Blank Keywords</a></li>
</ul>
</li>
<li><a class="reference internal" href="#card-images">Card Images</a></li>
<li><a class="reference internal" href="#continue-cards">CONTINUE Cards</a></li>
<li><a class="reference internal" href="#hierarch-cards">HIERARCH Cards</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/io/fits/usage/headers.rst">Edit This Page on Github</a>
<a href="../../../_sources/io/fits/usage/headers.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>
