4-Util.tex

\section{Additional Functionality}\label{sec:util}
SunPy is meant to provide a consistent environment for solar data analysis. In 
order to achieve this goal SunPy provides a number of additional functions and packages which 
are used by the other SunPy modules and are made available to the user. This section 
briefly describes some of these functions.
	
\subsection{World Coordinate System (WCS) Coordinates}\label{ssec:util:wcs}
Coordinate transformations are frequently a necessary task within the solar 
data analysis workflow. An often used transformation is from 
observer coordinates (e.g., sky coordinates) to a coordinate system that is 
mapped onto the solar surface (e.g., latitude and longitude). This 
transformation is necessary to compare the true physical distance between 
different solar features. This type of transformation is not unique
to solar observations, but is not often considered by astronomical packages
such as the Astropy 
\texttt{coordinates} package. The \texttt{wcs} package in SunPy implements the World Coordinate 
System (WCS) for solar coordinates as described by \cite{thompson2006}. The 
transformations currently implemented are some of the most commonly used in solar data analysis, namely converting from Helioprojective-Cartesian 
(HPC) to Heliographic (HG) coordinates. HPC describes the positions on 
the Sun as angles measured from the center of the solar disk (usually in 
arcseconds) using Cartesian coordinates (X, Y). This is the coordinate system 
most often defined in solar imaging data (see for example, images from 
\textit{SDO}/AIA, \textit{SOHO}/EIT, and \textit{TRACE}). 
HG coordinates express positions on the Sun using longitude and latitude on 
the solar sphere. There are two standards for this coordinate system:
Stonyhurst-Heliographic, where the origin is at the intersection of the solar 
equator and the central meridian as seen from Earth, and 
Carrington-Heliographic, which is fixed to the Sun and does not depend on Earth. The 
implementation of these transformations pass through a common coordinate system 
called Heliocentric-Cartesian (HCC), where positions are expressed in true 
(de-projected) physical distances instead of angles on the celestial sphere.
These transformations require some knowledge of the location of the observer, 
which is usually provided by the image header. In the cases where it is 
not provided, the observer is assumed to be at Earth. Listing \ref{code:wcs_code} shows 
some examples of coordinate transforms carried out in SunPy using the 
\texttt{wcs} utilities. This will form the foundation for transformations functions
to be used on \texttt{Map} objects.

\begin{listing}[H]
\pythoncode{pycode_util1.txt}
\caption{Using the \texttt{wcs} subpackage.}
\label{code:wcs_code}
\end{listing}

\subsection{Solar Constants and units}\label{ssec:util:sun}
Physical quantities (i.e. a number associated with a unit) are an important part
of scientific data analysis. SunPy makes use of the \texttt{Quantity} object provided by 
Astropy \texttt{units} sub-package. This object maintains the relationship between 
a number and its unit and makes it easy to convert between units. 
As these objects inherit from 
NumPy's \texttt{ndarray}, they work well with standard representations of numbers. Using proper
quantities inside of the code base also makes it easier to catch errors in calculations.
SunPy is currently working on integrating quantities throughout the code base.
In order to encourage the use of units and to enable consistency SunPy provides
the \texttt{sun} subpackage which includes solar-specific data such as ephemerides and
solar constants. The main namespace contains a number of functions that provide solar
ephemerides such as the Sun-to-Earth distance, solar-cycle number, mean 
anomaly, etc.
All of these functions take a time as their input, which can be provided in a format
compatible with \texttt{sunpy.time.parse\_time()}. 

The \texttt{sunpy.sun.constants} module provides a number of solar-related 
constants in order to enable the calculation of derived solar 
values within SunPy, but also to the user. All solar 
constants are provided as \texttt{Constant} objects as defined in the Astropy \texttt{units} package. Each 
\texttt{Constant} object defines a \texttt{Quantity}, along with 
the constant's provenance (i.e., reference) and its uncertainty. The use of this package
is shown in Listing~\ref{code:constants_code}.
For convenience, a number of shortcuts to frequently used constants are provided 
directly when importing the module. A larger list of constants can be 
accessed through an interface modeled on that provided by the SciPy \texttt{constants}
package and is available as a dictionary called \texttt{physical\_constants}. 
To view them all quickly, a \texttt{print\_all()} function is available.

\begin{listing}[H]
\pythoncode{pycode_util2.txt}
\caption{Using the \texttt{sun.constants} module.}
\label{code:constants_code}
\end{listing}
	
\subsection{Instruments}\label{ssec:util:inst}
In addition to providing support for instrument-specific solar data via the main data 
classes \texttt{Map}, \texttt{LightCurve}, and \texttt{Spectrum}, 
some instrument-specific functions may be found within the \texttt{instr} subpackage. 
These functions are generally those that are unique to one particular solar instrument, 
rather than of general use, such as a function to construct a \textit{GOES} flare event list 
or a function to query the \textit{LYRA} timeline annotation file. Currently, some support is included
for the \textit{GOES}, \textit{LYRA}, \textit{RHESSI} and \textit{IRIS} instruments, while future developments 
will include support for additional missions. Ultimately, it is anticipated that solar
missions requiring a large suite of software tools will each be supported via a separately 
maintained package that is affiliated with SunPy.