idl_stsdas.tex

basic median filter simulation

\item {\bf access}---This is an {\it optional} input parameter if opening a 
file for reading ({\bf access='R'}), and a {\it necessary} one if creating a 
new header ({\bf access='W'}).  {\bf Note:} R, W must be uppercase. 

\end{itemize}

\noindent
For example, to open one of the FOC Point Spread Function images:\\

\begin{tabular}{ll}
GHRS$>${\bf sxopen}, {\it 1, 'zfoc:f96f210m\_gc', HEADER, HISTORY} & \\ 
\end{tabular}

%\index{SDAS image - creating}
%
%\noindent
%To create a blank header file:\\
%
%\begin{tabular}{ll}
%GHRS$>${\bf header=}{\it strarr(10)} & \\
%GHRS$>${\bf sxopen}, {\it 1, 'filename', header, '', 'W'} & \\ 
%\end{tabular}\\
%
%\noindent
%Here, {\bf header} is an {\it input} parameter ({\bf header} must be 
%supplied).  {\bf SXOPEN} then uses information
%contained in these vectors to create a new header file {\it
%filename.hhh} containing (in this example) ten blank 80 byte
%(character) ASCII records. If {\bf header} does not contain the FITS
%keyword {\bf END} as its last record ({\bf header(9)}), one is added. 
\end{description}

\subsection{\bf Creating Image Files}
\begin{description}
\item [SXMAKE, {\it unit, filename, data, par, groups $[$, header$]$} :] 
\index{SXMAKE}
\index{SDAS images - opening}

This
procedure is used to create new FITS header and data files. By
default, these two files will have extensions {\bf .hhh} (header) and
{\bf .hhd} (data).  Once these files are created, the routine {\bf
SXWRITE} can be used to populate the data {\bf .hhd} file. 

\begin{itemize}

\item {\bf unit}---An IDL logical unit number from 1 to 9. 

\item {\bf filename}---The file name (without extension) given to the
new files. 

\item {\bf data}---A sample data array having the same size,
dimension, and data type as the data to be stored in the new binary
data file. {\bf Note:} this array is only used by {\bf SXMAKE} as a
template; its contents are not written to either the header or data
file. 

\item {\bf par}---The number of group parameters (parameter blocks) to
be written. 

\item {\bf groups}---The expected number of data groups to be stored
in the data file. {\bf Note:} it is recommended that {\bf par=}{\it 0}
since no group parameters will be written in this mode. 

\item {\bf header}--- An optional string vector containing an STSDAS
FITS header file.  If {\bf header} is omitted, a basic FITS
header is constructed.  {\bf Note:} the {\bf END} keyword must be the
last element in {\bf header}. 

\end{itemize}
\newpage
For example, 
to create STSDAS image files to contain one (1) 10$\times$10
data array with no group parameters, one group, and no input header
vector, use:\\ 

\begin{tabular}{ll}
GHRS$>$ {\bf data=}{\it fltarr(10,10)} & \\
GHRS$>${\bf sxmake,} {\it 1, 'myfile', data, 0, 1} & \\
\end{tabular}\\

\noindent
the files {\it myfile.hhh} and {\it myfile.hhd} are then created with
the former containing the default header information listed below: 

\begin{scriptsize}
\begin{center}
\begin{verbatim}
SIMPLE  =                    F /Written by IDL:   7-Dec-1992 14:21:07.00
BITPIX  =                   32 /
NAXIS   =                    2 /
NAXIS1  =                   10 /
NAXIS2  =                   10 /
DATATYPE= 'REAL*4'             /Type of data
GROUPS  =                    T /
PCOUNT  =                    0 /
GCOUNT  =                    1 /
PSIZE   =                    0 /# of bits in parm blk
END
\end{verbatim}
\end{center}
\end{scriptsize}
\end{description}

\subsection{\bf Getting Information From Image Files}
\begin{description}
\item [RESULT=SXREAD({\it unit $[$, group, PAR$]$}{\bf )} :] 
\index{SXREAD}
\index{SDAS image - reading data}

A function for reading data from the image files. The function must be
preceeded by a call to {\bf SXOPEN} or {\bf SXMAKE}.

\begin{itemize}

\item {\bf unit}---The IDL logical unit number specified in the call to 
{\bf SXOPEN} or {\bf SXMAKE}. 

\item {\bf group}---The group number to be read from the image file.  It can
range from zero (0) (first group) to the number of groups minus 1. 
If {\bf group} is not specified, then the first group (group zero) is assumed.

\item {\bf PAR}---An optional output variable containing the parameter values 
from the group parameter block.  {\bf PAR} is a {\it byte} array which may 
contain multiple data types and is therefore not in a readable form.  The 
function {\bf SXGPAR} can be used to retrieve values from it.

\item {\bf RESULT}---An IDL vector or array containing data from the 
requested {\bf group}.

\end{itemize}

\noindent
For example:\\

\begin{small}
\begin{tabular}{ll}
Open FOS data file & \\
& \\
GHRS$>${\bf sxopen}, {\it 1, 'hrs8:[hrsdata.fos.0ya002]y0ya0201t.d0h', header} & \\
GHRS$>${\bf print}, {\bf sxpar(}{\it header, 'gcount'}{\bf )} & ; gcount=8\\
GHRS$>${\bf result=sxread(}{\it 1, 2}{\bf )} & \\
GHRS$>${\bf help}, {\it result} & ; result=float(64)\\
\end{tabular}
\end{small}\\

\noindent
In 
this example, an FOS file is opened, the number of data groups are
identified, and the third of these groups is read.  What is returned to 
{\bf RESULT} is a floating point vector with 500 elements.

\item [SXHREAD, {\it filename, HEADER} : ] 
\index{SDAS image - reading header}
\index{SXHREAD}

This function reads the contents of the image header.  It does not
require the user to first open the file with {\bf SXOPEN}. {\bf SXHREAD} 
therefore offers a simple method for obtaining a header vector that can then 
be used by other routines (such as {\bf SXMAKE}).

\begin{itemize}

\item {\bf filename}---The filename of the header file (an {\bf .hhh} extension is
appended if not given).  {\bf SXHREAD} is capable of reading 
three (3) different types of header files which are listed below:

\begin{enumerate}

\item VMS Fixed record length 80 byte files.

\item Unix stream files with a {\it carriage return} after every 80 bytes.

\item Variable length record files.

\end{enumerate}

\item {\bf HEADER}---Contains the returned FITS header.
\end{itemize}

\noindent
For example:\\

\begin{tabular}{ll}
GHRS$>${\bf sxhread}, {\it 'zman:z0gy011st.shh', HEADER} & \\
GHRS$>${\bf print}, {\it HEADER} & \\
\end{tabular}\\

\noindent

will print the contents of the {\bf .shh} header file for this 
observation to the screen.

\item [RESULT=SXPAR({\it header, keywordname $[$, abort, count=count\_val$]$}) :] 

This function extracts the {\it value} field of a given FITS keyword from an image 
header which was previously opened using {\bf SXOPEN}.

\begin{itemize}

\item {\bf header}---The header vector to be searched for a given keyword.

\item {\bf keywordname}---The keyword name to search the header for.

\item {\bf abort}--An optional input string which specifies that {\bf SXPAR} 
should perform an IDL {\bf RETALL} if the keyword assigned to {\bf name} is 
not found in {\bf hdr}.  The string assigned to {\bf abort} can either be 
blank or can contain a message to be appended to the standard error message 
that is printed if a keyword is not found.  If {\bf abort} is not supplied, 
{\bf SXPAR}  returns a negative {\bf $!$ERR} if a keyword is not 
found.

\item {\bf count=count\_val}---An optional IDL keyword set to the number of 
FITS keyword values for keywords found by {\bf SXPAR}.
\newpage
\item {\bf RESULT}---Contains 
the value assigned to the given FITS 
keyword, if one is found.  {\bf Note:} If {\bf RESULT} is of type 
{\it logical}, a value of {\it 1} is returned 
for {\bf T}, and {\it 0} for {\bf F}.  If a keyword occurs more 
than once in a header, a warning message is printed and the first occurrence 
of the keyword value is assigned to {\bf RESULT}.
\end{itemize}

\noindent
Examples:\\

\begin{small}
\begin{tabular}{ll}
GHRS$>${\bf sxopen}, {\it 1, 'zcal:sf\_g2\_01', header} & \\
GHRS$>${\bf result=sxpar(}{\it header, 'instrume'}{\bf )} & \\
GHRS$>${\bf print}, {\it result} & ; prints HRS, no apostrophes\\
 & \\
GHRS$>${\bf result=sxpar(}{\it header, 'groups'}{\bf )} & \\
GHRS$>${\bf print}, {\it result} & ; prints 1\\
& \\
GHRS$>${\bf result=sxpar(}{\it header, 'gcount',count=cnt}{\bf )} & \\
GHRS$>${\bf print}, {\it result} & ; prints 2, two groups present\\
& ; cnt=1, one keyword found\\
& \\
GHRS$>${\bf result=sxpar(}{\it header, 'dummy'}{\bf )} & \\
GHRS$>${\bf print},{\it $!$err} & ; prints -1, keyword not found\\
& \\
GHRS$>${\bf abort=}{\it 'sf\_g2\_01'} & ; append to abort msg\\
GHRS$>${\bf result=sxpar(}{\it header, 'dummy', abort}{\bf )} & \\
SXPAR: keyword DUMMY not found in sf\_g2\_01 & ; appends {\bf abort} to msg\\
\end{tabular}\\
\end{small}

\item [RESULT=SXGPAR({\it header, par, groupname $[$, type, sbyte, nbytes$]$}) : ] 
\index{SXGPAR}
\index{SDAS image - read keyword values}

This function reads keyword values from the group header.  It must be preceded 
by a call to {\bf SXREAD} (the group header is assigned to the parameter 
{\bf PAR} and is of type {\it byte}).

\begin{itemize}

\item {\bf header}---The STSDAS FITS image header.

\item {\bf par}---The STSDAS image group parameter header.

\item {\bf groupname}---The group parameter name (i.e., those names 
associated with the group parameter keywords {\bf PTYPE}{\it n}, 
{\it n=1,$\cdots$,PCOUNT}), or simply the integer {\bf n}.

\item {\bf type}---An optional output for the 
data type of the requested group parameter (if not supplied or null string, 
the header is searched for type, sbyte, and nbytes).

\item {\bf sbyte}---An optional parameter containing the starting byte 
in parameter block for data.
\newpage

\item {\bf nbytes}---An 
optional input parameter containing the 
number of bytes in parameter block for data.
\end{itemize}

{\bf Note:} supplying the {\bf type}, {\bf sbyte} and {\bf nbytes} parameters 
greatly speeds up the execution of {\bf SXGPAR}.  The best way to get 
these parameters is to pass the three parameters as undefined 
(or set {\bf type=}{\it ' '}).  {\bf SXGPAR} then returns their values for 
use in subsequent calls.  For example:\\

\begin{small}
\begin{tabular}{ll}
GHRS$>${\bf sxopen}, {\it 1, 'hrs8:[hrsdata.fos.0ya002]y0ya0201t.d0h',} & \\
\hspace{1.1in}{\it  header} & ; open FOS data file\\
GHRS$>${\bf print, sxpar(}{\it header, 'gcount'}{\bf )} & ; gcount=8 \\
GHRS$>${\bf print, sxpar(}{\it header, 'pcount'}{\bf )} & ; pcount=25\\
GHRS$>${\bf result1=sxread(}{\it 1, 2, PAR}{\bf )} & ; read group 3 params.\\
GHRS$>${\bf result2=sxgpar(}{\it header, par, 1, type, sbyte, nbytes}{\bf )} & \\
GHRS$>${\bf print}, {\it result2} & ; result2=214.49820 \\
GHRS$>${\bf print}, {\it type, sbyte, nbytes} & ; REAL$*$8, 0, 8\\
GHRS$>${\bf print, sxpar(}{\it header, 'ptype1'}{\bf )} & ; prints CRVAL1\\
\end{tabular}\\
\end{small}

\noindent
In this example, the header file is opened and {\bf SXPAR} is used to get the
number of groups {\bf gcount} and the group parameters per group {\bf pcount}.  
{\bf SXREAD} is then used to read group 3.  Next, using the group 
parameter header vector {\bf PAR}, {\bf SXGPAR} is used to get the value, 
type, starting byte, and byte length of group parameter 1.  Finally, 
{\bf SXPAR} is again used to get the group parameter name of the first 
group parameter.
\end{description}

\subsection{\bf Modifying Image Files}

\begin{description}
\item [SXWRITE, {\it unit, data $[$, par$]$} :] 
\index{SXWRITE}
\index{SDAS image - writing in data}

This procedure writes a data array to a binary image data file. This must be preceded by 
a call to {\bf SXOPEN} or {\bf SXMAKE}.

\begin{itemize}
\item {\bf unit}---The IDL logical unit number from 1 to 9 specified in the
call to {\bf SXOPEN} or {\bf SXMAKE}.

\item {\bf data}---The array of data to be written.  The dimensions of 
{\bf data} must agree with those supplied to {\bf SXOPEN} and written into 
the STSDAS image header.  The type is converted if necessary.

\item {\bf par}---An optional input parameter that contains the group parameter 
block.  The size of this array must agree with the {\bf PSIZE} group 
parameter keyword found in the header.

\end{itemize}
\newpage
\noindent
In this 
example, the goal is to create a new STSDAS FITS image file to
contain a portion of the contents of an existing FITS file:\\ 

\begin{small}
\begin{tabular}{ll}
GHRS$>${\bf sxopen}, {\it 1, 'zcal:sf\_g2\_01', header} & ; open existing file\\
GHRS$>${\bf print, sxpar(}{\it header, 'naxis'}{\bf )} & ; naxis=1 no. of axes\\
GHRS$>${\bf print, sxpar(}{\it header, 'naxis1'}{\bf )} & ; naxis1=203 size axis 1\\
GHRS$>${\bf print, sxpar(}{\it header, 'datatype'}{\bf )} & ; datatype=REAL$*$8 datatype of data\\
& \\
GHRS$>${\bf data=}{\it dblarr(203)} & REAL$*$8 vector\\
GHRS$>${\bf print, sxpar(}{\it header, 'gcount'}{\bf )} & ; gcount=2\\
GHRS$>${\bf sxmake}, {\it 2, 'myfile', data, 0, 1} & ; make new file\\
& \\
GHRS$>${\bf newdata=sxread(}{\it 1, 0}{\bf )} & ; read group 1\\
GHRS$>${\bf sxwrite}, {\it 2, newdata} & \\
\end{tabular}\\
\end{small}