\documentstyle[11pt,psfig]{article}

\setlength{\oddsidemargin}{0in}		%  1 inch (0 + 1) from left.
\setlength{\topmargin}{0in}		%  1 inch (1.5 - 0.5) from top.
\setlength{\textwidth}{6.5in}		%  1 inch (8.5 - 1 - 6.5) from right.
\setlength{\textheight}{9.0in}		%  1 inch (11 - 1 - 9) from bottom.

\addtolength{\parskip}{0.5\baselineskip}

%  The environment centerpage centers text vertically on the page.  This is
%  useful within a titlepage environment.

\newenvironment{centerpage}{\mbox{} \protect\vspace*{\fill}}{
	\protect\vspace*{\fill} \mbox{} \protect\\ \mbox{}}

\begin{document}		
\bibliographystyle{plain}		% Define bibliography style.
\thispagestyle{empty}			% Don't number first page.

\begin{titlepage}
\hrule
{\noindent\bf Owens Valley Solar Array}\\
\vspace{-0.7\baselineskip}\\
{\noindent\Huge\bf OVSA}
\vspace{2mm}
\hrule
\vspace{3mm}
\centerline{\bf OVSA SOFTWARE NOTE No. 1}
\vspace{3mm}
\hrule
\noindent Version 1.1 \hfill Last updated 18 December 2000
\vspace{2mm}
\hrule

\begin{centerpage}

\begin{center}
{\Large\bf OVSA SOFTWARE AND DATA}\\
\mbox{}\\
Peter T. Gallagher \& Dale E. Gary\\
Big Bear Solar Observatory/Owens Valley Solar Array\\
New Jersey Institute of Technology\\
Big Bear City, CA 92314\\
U.S.A.\\
\mbox{}\\
ptg@bbso.njit.edu\\
dgary@njit.edu\\
\end{center}

\end{centerpage}

\end{titlepage}

\sloppy{}

\section{Introduction}

This document is meant as a guide to users of calibrated data from the Owens
Valley Solar Array ({\sc ovsa}). There are currently two levels of data
produced, including quicklook data which can be viewed at our web page and
calibrated data in Flexible Image and Transport System ({\sc fits}) format.
Here, we describe the calibrated {\sc fits} data and its associated software
which allows the production of light curves, spectra and dynamic spectra. 
Background subtraction and spectral fitting features have also recently been 
added.

It should also be noted that prior to using this software, you must have 
installed {\sc idl} and the SolarSoftWare ({\sc ssw}) package together with 
the {\sc ovsa} branch of the tree. {\sc ssw} can be downloaded from
{\tt http://www.lmsal.com/ssw/} while further {\sc ovsa} specific 
information can be found at {\tt http://www.ovsa.njit.edu/}.

OVSA instrument details can be found in Hurford et al. (1984) and 
Gary \& Hurford (1998).


\section{OVSA FITS}

The {\sc ovsa} data is written to {\sc fits} files as binary table
extensions which are described in detail in Thompson (1994) and references 
therein. First the primary {\sc fits} header is created with the {\sc fits}
file creation date inserted together with the {\tt EXTEND} keyword set to
true -- this keyword indicates that a {\sc fits} extension will be written.
Next, the binary table extension header is created with the following
standard keywords included.
\begin{verbatim}
XTENSION= 'BINTABLE'           /Written by IDL:  Thu Mar 16 17:34:08 2000
BITPIX  =                    8 /
NAXIS   =                    2 /Binary table
NAXIS1  =              1295135 /Number of bytes per row
NAXIS2  =                    1 /Number of rows
PCOUNT  =                    0 /Random parameter count
GCOUNT  =                    1 /Group count
TFIELDS =                    5 /Number of columns
DATE    = '2000-03-16'         /
EXTNAME = 'OVSA Data'          /Binary table extension
FILENAME= 'ovsa_1-18GHz_sp_19991121_1805.fts'          /
ORIGIN  = 'NJIT    '           /Institute where file was written
TELESCOP= 'OVSA    '           /Owens Valley Solar Array
SEQ_NUM = 'G0281439_07263'     /Unique number for this dataset
DATE_OBS= '1999-11-21T18:05:05.000Z' /Start date/time of observation
DATE_END= '1999-11-21T18:29:55.000Z' /End date/time of observation
OBJ_ID  = 'AR8340  '           /Object ID
XCEN    =                   20 /Antenna pointing in arcsec from Sun centre
YCEN    =                   20 /Antenna pointing in arcsec from Sun centre
FREQMIN =              1.20000 /Min freq in observation (GHz)
FREQMAX =              18.0000 /Max freq in observation (GHz)
TFORM1  = '161250E '           /Real*4 (floating point)
TTYPE1  = 'CHANNEL,FREQ,TIME'  /Label for column 1
TDIM1   = '(25,43,150)'        /Array dimensions for column 1
TFORM2  = '43E     '           /Real*4 (floating point)
TTYPE2  = 'FREQ/GHZ'           /Label for column 2
TFORM3  = '63A     '           /Character string
TTYPE3  = 'FEED NUMBER AND POLARIZATION' /Label for column 3
TDIM3   = '(9,7)   '           /Array dimensions for column 3
TFORM4  = '162325E '           /Real*4 (floating point)
TTYPE4  = 'ERRORS  '           /Label for column 4
TDIM4   = '(25,43,151)'        /Array dimensions for column 4
TFORM5  = '150E    '           /Real*4 (floating point)
TTYPE5  = 'TIME/MSEC'          /Label for column 5      
\end{verbatim}
                              
The binary table header and data units are written to the {\sc fits} file
using {\tt write\_ovsa\_fits}, which is executed using the following syntax:
\begin{verbatim}
IDL> write_ovsa_fits, avg, 'G0281439_07263',f, feedinfo, sigma, $
IDL> 'AR8340', t, avg, tls, xcen, ycen
\end{verbatim}
This routine also writes an {\sc IAU} standard file name which in this case is
{\tt ovsa\_1-18GHz\_sp\_19991121\_1805.fts}. The two characters
{\tt sp} indicate that the file contains spectral data.


\section{Analysis Software}

This section details the {\sc ovso} object class and the methods
associated with it. Specifically, we describe how to create an {\sc ovsa}
object together with the methods for plotting, fitting and saving 
dynamic spectra, light curves and spectra.
\begin{figure}[!ht]
\begin{center}
\leavevmode
\psfig{figure=ovsa_summary.ps,width=1\textwidth}
\caption{OVSA summary plot showing a large microwave burst as observed with each available
antenna and frequency.}
\end{center}
\end{figure}    

\subsection{OVSA Class}

An instance of the {\sc ovsa} class is created using the {\tt obj\_new}
function. This can be achieved using; 
\begin{verbatim}
IDL> obj = obj_new( 'ovsa' )
\end{verbatim}
\noindent
The methods associated with the object together with the various arguments and 
keywords of each method can be accessed by typing:
\begin{verbatim}
IDL> obj -> help
  0) PRO ovsa::help
  1) PRO ovsa::read,filename,data	     
  2) PRO ovsa::plot,ant,gen,tmin,tmax,dynamic=dynamic,light curve=light curve,
     amplitude=amplitude,phase=phase,spectrum=spectrum,interactive=interactive,
     print=print,save=save
\end{verbatim}

An {\sc ovsa} {\sc fits} file can then be read using the {\tt read} method 
associated with the object via
\begin{verbatim}
IDL> obj -> read, 'filename.fits'
\end{verbatim}
\noindent
This method also prints the {\tt filename.fits} binary extension header which contains
information on pointing, start and end times, observed frequencies, campaign IDs and a variety
of other information -- see Section 2 for further details. If the user is interested in
accessing the data directly, a second argument can be included when calling the {\tt
read} method. This second argument then contains the header and data arrays incorporated
within a standard {\sc idl} structure, e.g.
\begin{verbatim}
IDL> obj -> read, 'filename.fits', idl_data_structure
\end{verbatim}
\noindent

The data can then be displayed using the {\tt plot} method which allows us to produce 
dynamic spectra, light curves and spectra. There are a number of keywords associated
with the {\tt plot} method, not all of which are described in the following sections.

\subsection{Getting a General Overview}

Before analysing the data, it is useful to view the data obtained from each antenna and
in each polarization. This can be achieved using the {\tt /Summary} keword with the 
{\tt plot} method.
\begin{verbatim}
IDL> obj -> plot, /Summary
\end{verbatim}
Figure 1 gives an example of the typical output from the above.

\begin{figure}[t]
\begin{center}
\leavevmode
\psfig{figure=ovsa_dynamic.ps,width=1\textwidth}
\caption{A left-circular polarization dynamic spectrum for antenna 1 at 43 frequencies between 1 and 18 GHz.}
\end{center}
\end{figure}    


\subsection{Viewing Dynamic Spectra}

A dynamic spectrum, showing the total power from a chosen antenna as a function of frequency
and time, is create as follows; 
\begin{verbatim}
IDL> AntennaNumber = 1   
IDL> obj -> plot, AntennaNumber, /LCP, /Dynamic 
\end{verbatim}
\noindent
where the the variable, {\tt AntennaNumber}, can take the values 1, 2, 4, 5, 6, or 7 -- antennas 
number 1 and 2 correspond to the two 27--m  dishes, while 4, 5, 6 and 7 refer to the four 2--m
dishes. The polarization must also be specified via the {\tt /LIN, /LCP} or {\tt /RCP} keywords. 
These are given in Table 1. An example of a dynamic spectrum created with the {\tt plot} method 
is given in Figure 1. 

A re-gridded dynamic spectrum can be viewed via:
\begin{verbatim}
IDL> obj -> plot, AntennaNumber, /LCP, /Dynamic, /Mesh
\end{verbatim}
\noindent
The {\tt Mesh} keyword converts the data to a regular grid and fills in missing data
values. As with all interpolation procedures, this should be used cautiously.

A background subtracted dynamic spectrum can be produced using the {\tt Background} keyword.
\begin{verbatim}
IDL> obj -> plot, AntennaNumber, /LCP, /Dynamic, /Background 
\end{verbatim}
\noindent
The user can use the cursor to identify a pre-flare background region, from which 
an average spectrum is created. This average spectrum is then subtracted from the dynamic spectrum.
The {\tt Background} keyword can be used with the {\tt Dynamic}, {\tt Spectrum} and 
{\tt Lightcurve} keywords.

\begin{table}
\begin{center}
  \begin{tabular}{cc}
    \hline
    \hline
    Antenna Number & Polarization    \\
    \hline
     1 & LIN or LCP\\
     2 & LIN or RCP\\
     3 & Not in use\\
     4 & LIN\\
     5 & LIN\\
     6 & LIN\\
     7 & LIN\\
  \hline
  \end{tabular}
 \caption{OVSA antenna numbers and polarization states measured.}
\end{center}
\end{table}

It is also possible to  view the dynamic spectrum between any two times by adding a second and
third argument to the {\tt plot} method. For example,
\begin{verbatim}
IDL> obj -> plot, AntennaNumber, '18:12', '18:24', /LCP, /Dynamic 
\end{verbatim}
\noindent
will plot the dynamic spectrum for antenna 1 between 18:12 U.T. and 18:24 U.T.


\subsection{Creating Light Curves}

A light curve at a particular frequency is again created using the {\tt plot} method, but in
this case the {\tt Lightcurve} rather than the {\tt Dynamic }keyword is used. The left panel
of Figure 2 gives an example of a light curve produced using:
\begin{verbatim}
IDL> AntennaNumber = 1   
IDL> Frequency = 11.0       
IDL> obj -> plot, AntennaNumber, Frequency, /LCP, /Lightcurve 
\end{verbatim}
\noindent
where the variable {\tt Frequency} can take any value between 1.2 and 18.0 GHz. As {\sc ovsa}
records 43 frequencies in the 1.2 to 18 GHz range, the {\tt plot} method will display the
observed frequency closest to the requested value. In this example the closest observed
frequency to the requested frequency of 11.0 GHz was 11.2 GHz which can be seen in Figure 2. 

\begin{figure}
\begin{center}
\leavevmode
\psfig{figure=ovsa_lightcurve.eps,angle=90,width=0.49\textwidth}
\psfig{figure=ovsa_lightcurve2.eps,angle=90,width=0.49\textwidth}
\caption{The left panel shows a left-circular polarization {\sc ovsa} 11.2 GHz total power 
light curve between 18:05 U.T. and 18:29 U.T for antenna 1, while the right panel shows a 
section of the same data extracted between 18:14 U.T. and 18:20 U.T.}
\end{center}
\end{figure}    

Similarly to the option available when producing a dynamic spectrum plot, we can also change
the start and end times used when plotting a light curve. In this case we use,

\begin{verbatim}
IDL> obj -> plot, AntennaNumber, Frequency, '18:14', '18:20', /LCP, /Lightcurve 
\end{verbatim}
\noindent
to plot the 11.2 GHz light curve for antenna 1 between the times 18:14 U.T. and 18:20 U.T.

\begin{figure}[t]
\begin{center}
\leavevmode
\psfig{figure=ovsa_spectrum.ps,width=0.8\textwidth}
\caption{Radio spectrum from 1.2 GHz to 18.0 GHz extracted at 18:14 U.T.}
\end{center}
\end{figure}    

\subsection{Viewing and Fitting Spectra}

A radio spectrum can be extracted using 
the {\tt plot} method together with the {\tt Spectrum} keyword. If for example, we are 
interested in the spectrum at 18:14 U.T. we can type;
\begin{verbatim}
IDL> obj -> plot, AntennaNumber, '18:14', /LCP, /Spectrum
\end{verbatim}
\noindent
which is shown in Figure 3.

The spectrum can be fitted using a function of the form
\begin{equation}
S = A \nu^\alpha(1 - \exp(-B\nu^{-\beta}))
\end{equation}
which expresses the frequency dependence of the flux density (St\"{a}hli et al.,
1989). The parameters $\alpha$ and $\alpha - \beta$ represent the low- and high-frequency
slopes respectively. This equation is derived by combining the radiative transfer 
equation for an isolated source with constant effective temperature 
\begin{equation}
T_b = T_{eff} (1 - \exp(-\tau_nu))
\end{equation}
with $S = \Delta \Omega k T_b nu^2/c^2$ (Dulk \& Marsh, 1982).

In general the microwave spectrum shows multiple peaks so the user must select a
section of the spectrum using the cursor. When this selection has been made, the {\tt
plot} method in conjunction with {\tt Fit} keyword calls the {\tt mpfitexpr}
procedure which performs a Levenberg-Marquardt least-squares fit i.e.,
\begin{verbatim}
IDL> obj -> plot, AntennaNumber, '18:14', /LCP, /Spectrum, /Fit
\end{verbatim}
\noindent


\subsection{Saving And Restoring Your Plots}

In order to save the data plotted in a particular dynamic spectrum, light curve or spectrum,
the {\tt Save} keyword is used with the {\tt plot} method. This feature is particularly
useful when comparing {\sc ovsa} data to data from other instruments. For
example, we can save the time and total power arrays together with the start and end times of
the following

\begin{verbatim}
IDL> obj -> plot, AntennaNumber, Frequency, '18:14', '18:20', /LCP, /Lightcurve, /Save
\end{verbatim}
\noindent
by using the {\tt Save} keyword as shown. The variables and arrays used in the plotting are 
written to {\tt ovsa.sav} within an {\sc idl} structure named {\tt ovsa\_data}.

We can then restore, view and plot the these data outside the {\sc ovro} software using
standard {\sc idl} and {\sc ssw} routines. For example;
\begin{verbatim}
IDL> restore, 'ovsa.sav'
IDL> help, ovsa_data, /Structure
** Structure <8297fe4>, 5 tags, length=1224, refs=1:
   T_SEC           FLOAT     Array[150]
   POWER           FLOAT     Array[150]
   T_START         STRING    '1999-11-21T18:14:00'
   T_END           STRING    '1999-11-21T18:20:00'
   FREQ            STRING    '16.4'  
IDL> utplot, ovsa_data.t_sec, ovsa_data.power, ovsa_data.t_base,$
IDL> timerange = [ ovsa_data.t_start, ovsa_data.t_end ] 
IDL> oplot, other_instrument_time, other_instrument_flux               
\end{verbatim}
\noindent
where the {\tt other\_instrument} arrays are time and flux arrays recorded by another
instrument such as {\sc sxt} or {\sc hessi}.


\subsection{Interactive Mode}

The interactive mode allows the user to point and click on the dynamic spectrum and
view spectra or light curves at a variety of times or frequencies and can be run 
using the {\tt Interactive} keyword combined with either the {\tt Lightcurve} or
{\tt Spectrum} keywords.

For example, light curves for antenna 1 can be selected using the cursor by entering;
\begin{verbatim}
IDL> obj -> plot, 1, /LCP, /Lightcurve, /Interactive
\end{verbatim}
while spectra can be extracted using the following:
\begin{verbatim}
IDL> obj -> plot, 1, /LCP, /Spectrum, /Interactive
\end{verbatim}

\subsection{Movie Mode}

The movie mode can provide an interesting insight into the temporal evolution 
of a flare spectrum using the {\tt movie} method. A movie from antenna 1 in
linear polarization can be viewed by entering the following;
\begin{verbatim}
IDL> obj -> plot, AntennaNumber, /LIN, /Dynamic, /Movie
\end{verbatim}
\noindent


\section{References}

Dulk, G. A. \& Marsh, K. A., 1982, {\it ApJ}, {\bf 259}, 350. \\
St\"{a}hli, M., Gary, D. E. \& Hurford, G. J., 1989, {\it Sol. Phys.}, {\bf 120}, 351.\\
Gary, D. E. \& Hurford, G. J., 1998, in {\it Proceedings of the Nobeyama Symposium},
Eds. T. S. Bastian, N. Gopalswamy and K. Shibasaki, NRO Report No. {\bf 479}, 429.\\ 
Hurford, G. J., Read, R. B., Zirin, H., 1984, {\it Sol. Phys.}, 94, 413.\\
Thompson, W., 1994, {\tt http://orpheus.nascom.nasa.gov/cds/software\_notes.html},
{\sc cds} Software Note No. 4.

\end{document}
