%ADASS_PROCEEDINGS_FORM%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% SAMPLE1.TEX -- ADASS XII (2002) ASP Conference Proceedings sample
% paper with minimal markup. Based on the sample from ADASS XI (01).
%
% This is a simple example.  If you want to see a more comprehensive
% sample paper,  take a look at sample2.tex.
%
% Much of the input will be enclosed by braces (i.e., { }).  The
% percent sign, "%", denotes the start of a comment; text after it
% will be ignored by LaTeX.  You might also notice in some of the
% examples below the use of "\ " after a period; this prevents LaTeX
% from interpreting the period as the end of a sentence and putting
% extra space after it.   
% 
% You should check your paper by processing it with LaTeX.  For
% details about how to run LaTeX as well as how to print out the User
% Guide, consult the README file.  
%
% If you do not have access to the LaTeX software or a laser printer
% at your site, you can still prepare your paper following the
% instructions in the User Guide.  In such cases, the editors will
% process the file and make any necessary editorial adjustments.
% 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 
\documentclass[11pt,twoside]{article}  % Leave intact
\usepackage{adassconf}

% If you have the old LaTeX 2.09, and not the current LaTeX2e, comment
% out the \documentclass and \usepackage lines above and uncomment
% the following:

%\documentstyle[11pt,twoside,adassconf]{article}

\begin{document}   % Leave intact

%-----------------------------------------------------------------------
%			    Paper ID Code
%-----------------------------------------------------------------------
% Enter the proper paper identification code.  The ID code for your
% paper is the session number associated with your presentation as
% published in the official conference proceedings.  You can
% find this number locating your abstract in the printed proceedings
% that you received at the meeting or on-line at the conference web
% site; the ID code is the letter/number sequence proceeding the title 
% of your presentation.  
%
% This will not appear in your paper; however, it allows different
% papers in the proceedings to cross-reference each other.  Note that
% you should only have one \paperID, and it should not include a
% trailing period.
%

\paperID{D4}
%%%% ID=D4

%-----------------------------------------------------------------------
%		            Paper Title 
%-----------------------------------------------------------------------
% Enter the title of the paper.
%
% EXAMPLE: \title{A Breakthrough in Astronomical Software Development}
%
% If your title is so long as to fill the page header when you print it,
% then please supply a short form as a \titlemark.
%
% EXAMPLE:
%  \title{Rapid Development for Distributed Computing, with Implications
%         for the Virtual Observatory}
%  \titlemark{Rapid Development for Distributed Computing}
%

\title{Demo of numarray, PyFITS, and related software}
%\titlemark{ }

%-----------------------------------------------------------------------
%		          Authors of Paper
%-----------------------------------------------------------------------
% Enter the authors followed by their affiliations.  The \author and
% \affil commands may appear multiple times as necessary.  List each
% author by giving the first name or initials first followed by the
% last name.  Authors with the same affiliations should grouped
% together. 
%
% Try to limit the front matter to no more than three \author
% commands.  Group authors with the same affiliations.  Too many
% \author commands fills the first page of the paper with little
% actual text.

\author{Jin-chung\ Hsu and Philip E.\ Hodge}
\affil{Space Telescope Science Institute, Baltimore, MD
       21218}
%-----------------------------------------------------------------------
%			 Contact Information
%-----------------------------------------------------------------------
% This information will not appear in the paper but will be used by
% the editors in case you need to be contacted concerning your
% submission.  Enter your name as the contact along with your email
% address.

\contact{J.-C. Hsu}
\email{hsu@stsci.edu }

%-----------------------------------------------------------------------
%		      Author Index Specification
%-----------------------------------------------------------------------
% Specify how each author name should appear in the author index.  The 
% \paindex{ } should be used to indicate the primary author, and the
% \aindex for all other co-authors.  You MUST use the following
% syntax: 
%
% SYNTAX:  \aindex{LASTNAME, F. M.}
% 
% where F is the first initial and M is the second initial (if
% used).  This guarantees that authors that appear in multiple papers
% will appear only once in the author index.  
%
% EXAMPLE: \paindex{Crabtree, D.}
%          \aindex{Manset, N.}
%          \aindex{Veillet, C.}
%
% NOTE: this information is also used to build the author list that
% appears in the table of contents.  Authors will be listed in the order
% of the \paindex and \aindex commmands.
%

\paindex{Hsu, J.-C.}
\aindex{Hodge, P. E.}     

%-----------------------------------------------------------------------
%                     Author list for page header
%-----------------------------------------------------------------------
% Please supply a list of author last names for the page header. in
% one of these formats:
%
% EXAMPLES:
% \authormark{LASTNAME}
% \authormark{LASTNAME1 \& LASTNAME2}
% \authormark{LASTNAME1, LASTNAME2, ... \& LASTNAMEn}
% \authormark{LASTNAME et al.}
%
% Use the "et al." form in the case of seven or more authors, or if
% the preferred form is too long to fit in the header.

\authormark{Hsu \& Hodge}

%-----------------------------------------------------------------------
%			Subject Index keywords
%-----------------------------------------------------------------------
% Enter up to 6 keywords describing your paper.  These will NOT be
% printed as part of your paper; however, they will be used to
% generate the subject index for the proceedings.  There is no
% standard list; however, you can consult the indices for past ADASS
% proceedings (http://adass.org/adass/proceedings/).

\keywords{Python, FITS, PyFITS, numarray, readgeis, fitsdiff}

%-----------------------------------------------------------------------
%			       Abstract
%-----------------------------------------------------------------------
% Type abstract in the space below.  Consult the User Guide and Latex
% Information file for a list of supported macros (e.g. for typesetting 
% special symbols). Do not leave a blank line between \begin{abstract} 
% and the start of your text.

\begin{abstract}          % Leave intact
PyFITS is a Python module developed for FITS file I/O.  We demonstrated
its use for FITS images and tables, illustrating the PyFITS classes and
methods, as well as the array manipulation capabilities of numarray.  PyFITS
is convenient for interactive use, and we also showed two utility programs,
\bf fitsdiff \rm and \bf readgeis\rm, as examples of its use in 
astronomical applications.
The task \bf fitsdiff \rm compares two FITS files and reports their 
differences, \bf readgeis \rm reads the STScI-style GEIS format files 
and converts them to FITS files or FITS objects.  
These two Python modules were showcased not only
because they are useful astronomical tools but to demonstrate the ease of
writing such applications using PyFITS and numarray.  PyFITS can also make
use of memory mapping, which significantly enhances its performance on large
FITS files, both images and tables.
At STScI, we are also applying numarray and PyFITS for larger projects such
as pydrizzle and the pipeline software for the new HST instrument COS (Cosmic
Origins Spectrograph).
\end{abstract}

%-----------------------------------------------------------------------
%			      Main Body
%-----------------------------------------------------------------------
% Place the text for the main body of the paper here.  You should use
% the \section command to label the various sections; use of
% \subsection is optional.  Significant words in section titles should
% be capitalized.  Sections and subsections will be numbered
% automatically. 

\section{Introduction}

The Python package numarray is an efficient array handling
tool (it is a replacement for the Numeric Python extension).
In addition to the existing Numeric functionalities for numeric arrays,
arrays of character strings can be created and manipulated,
and tables can be represented using record arrays which are 1-D arrays of 
structures with mixed data types within a row but are homogeneous within 
each column.
The contents of a record array can be accessed by row or by column,
or both at the same time.
A column is a numarray (or numarray.strings) object, with attributes that 
include an offset from one element to another, which allows accessing 
the column data without copying from the table to a temporary array.

PyFITS is a Python module for working with FITS files.
For an image, the data block is a numarray object.
For a table, the data block is a record array.
Images and tables may be read, updated in-place,
or they may be created from scratch.
Header keywords may be read, modified, deleted, or inserted at any location.

Memory mapping is supported in PyFITS to improve performance for large files.
If the native byte order differs from that of a FITS file (big-endian),
byte swapping is done on-the-fly within numarray when accessing data.
This avoids the need for temporary storage space, and it can save time if 
only a portion of the data will be read or modified.
Verification of objects to adhere to the FITS standards can also be performed 
automatically or manually.

If the data in the FITS file is scaled, i.e. BSCALE $\neq$ 1 or BZERO $\neq$ 0, 
PyFITS handles this in a transparent way so the user only needs to interact 
with the scaled objects.  On the other hand, this usually entails extra 
memory space for the scaled arrays; this may be of consideration for very 
large data files.

\section{PyFITS Examples}

In order to access an existing FITS file, we need to use the PyFITS 
\bf open \rm function which will 
return a Python list-like object (called HDUList object) which can 
only contain FITS HDU (header-data unit) objects as its elements.  
\begin{verbatim}
>>> import numarray, pyfits
>>> fd = pyfits.open ("abc.fits", "update", memmap=1)
\end{verbatim}
The \bf info \rm method is useful to find out what is in the HDUList:
\begin{verbatim}
>>> fd.info()
Filename: (No file associated with this HDUList)
No.   Name     Type     Cards Dimensions Format
0   PRIMARY PrimaryHDU      4 ()
1   sci     ImageHDU       61 (512, 512) Int16
2   eng     BinTableHDU    16 100R x 4C  [1D, 1J, 1J, 1I]
\end{verbatim}
Thus the primary HDU is fd[0], the first extension HDU is fd[1], 
etc.  The two most important attributes of each HDU object are 
\bf header \rm and \bf data\rm.
Header keyword values can be accessed by name or index, i.e. 
the header object behaves like a list as well as a dictionary.
\begin{verbatim}
>>> fd[0].header['detector']
'CCD1'
>>> fd[0].header[0]
TRUE

# update an existing keyword's value and add a new keyword
>>> fd[0].header['targname']='new_name'
>>> fd[0].header.update('newkey', 42)

# add a HISTORY, and delete a keyword
>>> fd[0].header.add_history('test')
>>> del fd[0].header['newkey']
\end{verbatim}
To access the image data is straightforward, since the data attribute of 
an image HDU is just 
a numarray object.  We can use the familiar slicing and striding notations, 
as well as all the mathematical operations provided in numarray.
\begin{verbatim}
>>> x=f[1].data[:2,:2]; print x
[[313 312]
 [314 314]]
>>> f[1].data[:2,:2] > 313
array([[0, 0],
       [1, 1]], type=Bool)
\end{verbatim}
Table data can be accessed by rows, using slicing or indexing,
\begin{verbatim}
>>> print fd[2].data[:3]
RecArray[ 
(6056.1279296875, 3626, 470, 0),
(6056.1279296875, 2735, 472, 0),
(6056.1279296875, 8410, 470, 0)
]
>>> print fd[2].data[0]
(6056.1279296875, 3626, 470, 0)
\end{verbatim}
or by columns, by referencing the column name or index, via the \bf field \rm 
method.
\begin{verbatim}
# access the x and y columns 
>>> x = fd[2].data.field ("x")
>>> y = fd[2].data.field ("y")

# apply a linear mapping to x and y
# (x and y are numarray objects)
>>> x = xscale * x + xzero
>>> y = yscale * y + yzero

# flag out-of-bounds in the data quality column
>>> dq = fd[2].data.field ("dq")
>>> dq |= where (logical_or (x < 0, x >= nx), 1, 0)
>>> dq |= where (logical_or (y > 0, y >= ny), 1, 0)
>>> fd.close()

# create a table from scratch
>>> col = []
>>> col.append (pyfits.Column (name="w", format="5A", \
...     array=numarray.strings.array (["one", "two", \
...     "three", "four"])))
>>> col.append (pyfits.Column (name="x", format="3E", \
...     array=array (([1.,2.,3.],[7.,8.,9.],[13.,14.,15.]))))
>>> col.append (pyfits.Column (name="y", format="J", \
...     array=array ([1,2,3,4])))
>>> col.append (pyfits.Column (name="z", format="C", \
...     array=array ([1+2j,3+4j,5+6j])))
>>> tb_hdu = pyfits.new_table (col)
>>> fd = pyfits.HDUList (tb_hdu)

# check for problems
>>> fd.verify()                         
Output verification result:
HDUList's 0th element is not a primary HDU.

# insert missing primary HDU
>>> fd.insert (0, pyfits.PrimaryHDU())  
>>> fd.info()
Filename: (No file associated with this HDUList)
No.   Name     Type     Cards Dimensions Format
0   PRIMARY PrimaryHDU      4 ()
1   None    BinTableHDU    16 4R x 4C    ['a5','3f4','i4','c8']

# write to a disk file
>>> fd.writeto ("example.fits")         
\end{verbatim}
For more details please visit:
\begin{verbatim}
http://www.stsci.edu/resources/software_hardware/numarray
http://www.stsci.edu/resources/software_hardware/pyfits
\end{verbatim}


\section{Some applications which use PyFITS or/and numarray}

\begin{verbatim}
PyTables  -- a hierarchical database package designed to
             efficently manage very large amounts of data
PyDrizzle -- a Python-based interface for combining
             overlapping images
readgeis  -- converts STScI-format images to FITS
fitsdiff  -- compares FITS images and tables
calcos    -- pipeline calibration program for COS
\end{verbatim}

The two applications, \bf readgeis \rm and \bf fitsdiff\rm, are examples 
of applying numarray and PyFITS to do useful work.  Both are entirely 
written in Python and can be run as a shell command or loaded in as a module 
inside Python.  The task \bf fitsdiff \rm is a tool to compare two FITS 
files and generate customizable reports.  Users can, for example, specify 
the relative difference level to be flagged for floating point numbers 
and exclude selected keywords or columns for comparison.

The task \bf readgeis \rm is a tool to read the GEIS file format used by some 
older HST instruments.  The tool will read the GEIS file's contents into 
PyFITS's HDUList structure.  Thus the header keywords will be in the primary 
HDU, the group parameters and data in each group will be in the extension 
HDU.  Users can then either write it out as a FITS file or do mathematical 
operations with the data in the images or the headers.

% You can also add an acknowledgments section as indicated below.

%-----------------------------------------------------------------------
%			      References
%-----------------------------------------------------------------------
% List your references below within the reference environment
% (i.e. between the \begin{references} and \end{references} tags).
% Each new reference should begin with a \reference command which sets
% up the proper indentation.  Observe the following order when listing
% bibliographical information for each reference:  author name(s),
% publication year, journal name, volume, and page number for
% articles.  Note that many journal names are available as macros; see
% the User Guide for a listing "macro-ized" journals.   
%
% Note the following are some of the tricks that can be used:
%
%   o  \& is used to format an ampersand symbol (&).
%   o  \'e puts an accent grave over the letter e.  See the User Guide
%      for details on formatting special characters.  
%   o  "\ " after a period prevents LaTeX from interpreting the period 
%      as an end of a sentence.
%   o  \aj is a macro that expands to "Astron. J."  See the User Guide
%      for a full list of journal macros
%   o  \adassvii is a macro that expands to the full title, editor,
%      and publishing information for the ADASS VII conference
%      proceedings.  Such macros are defined for ADASS conferences I
%      through IX.
%   o  When referencing a paper in the current volume, use the
%      \adassix and \paperref macros.  The argument to \paperref is
%      the paper ID code for the paper you are referencing.  See the 
%      note in the "Paper ID Code" section above for details on how to 
%      determine the paper ID code for the paper you reference.  
%
%\begin{references}
%\end{references}

% Do not place any material after the references section

\end{document}  % Leave intact
