idl_stsdas.tex

basic median filter simulation

\noindent

The first steps open the existing file and extract header keyword values
useful in determining the type, size, and dimension of a data group.  This 
information is then used to create a {\it template} group array {\bf data}.
In addition, {\bf SXPAR} is used to determine how many groups are in the
existing file which is useful just in case the last group was to be extracted.\\

Next, {\bf SXMAKE} is used to create the header and binary data files.
The STSDAS FITS image file {\it myfile} is designed to contain a single group
of size, dimension, and type {\bf data} with no group parameters.  In
addition, a new header is created.\\

Once the STSDAS image file {\it myfile} has been created, the first group array
is extracted from the existing FITS file.  This group is then written to 
{\it myfile} by {\bf SXWRITE}.

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

This procedure is used to write image header information to a {\it new} 
header file {\it without} changing the data ({\bf .hhd}) file.

\begin{itemize}

\item {\bf filename}--- The name of the header file to write to.  
If an extension is supplied, it must only be three (3) characters in 
length (default is {\bf .hhh}).

\item {\bf HEADER}---The image header vector to write. {\bf Note:} {\bf SXHWRITE} 
modifies the {\bf HEADER} vector in the following ways, if necessary.

\begin{enumerate}

\item If not already present, the FITS {\bf END} keyword is added as the last 
header file record.   Records after an existing {\bf END} keyword are deleted.

\item Spaces are appended to force each record to be 80 characters in length.

\end{enumerate}
\end{itemize}
\newpage

\noindent
{\bf Note:} this 
routine functions like the {\bf access=}{\it 'W'}
option used in {\bf SXOPEN} (see Section~\ref{sxopen}).  It does not append 
the header information to an existing header but rather creates a new header
file.\\

\noindent
For example:\\

\begin{tabular}{ll}
GHRS$>${\bf sxhread}, {\it 'z0gy011st.shh', HEADER} & \\
GHRS$>${\bf sxhwrite}, {\it 'myfile', header} & \\
\end{tabular}\\

\noindent
writes the contents of the {\bf .shh} FITS header to {\it myfile.hhh}.

\item [SXADDPAR, {\it header, keywordname, value $[$, comment, location, 
format=fmt\_string$]$} :] 
\index{SXADDPAR}
\index{SDAS image - modifying header}

This procedure adds or modifies the value of a keyword in the STSDAS image header.
{\bf Note:} this routine {\it does not} write the modifications to a header file.

\begin{itemize}

\item {\bf header}---A string vector containing the header.
If not defined, {\bf SXADDPAR} will create an empty header vector.

\item {\bf keywordname}---The name of the FITS keyword to add to the header.  
If {\bf keywordname} is already 
in {\bf header}, its value and possibly the comment 
fields will be modified. Otherwise a new record is added to {\bf header}.
If {\bf keywordname=}{\it 'HISTORY'}, then its contents will be added to the header 
without replacement.

\item {\bf value}---The value of the added FITS keyword. If {\bf value} 
is assigned a logical {\bf 1}, then {\bf value='T'} and similarly for 
a logical {\bf 0}.  {\bf Note:} if {\bf name=}{\it 'HISTORY'}, then 
{\bf value} is a comment string describing the history.

\item {\bf comment}---An optional input string describing the {\bf name} and/or
its associated {\bf value}.  The ``/'' is added by {\bf SXADDPAR} at 
string position 31 (to comply with FITS format rules).  If not supplied, or 
set to a null value ({\bf comment=' '}), the previous {\bf comment} field 
is retained (if found).

\item {\bf location}---This is the character string name of a keyword that 
already exists in the header.  The new keyword, its value, and any comment will
be inserted into the header {\it before} the position of the 
keyword assigned to {\bf location}.\\

\noindent
For example, if {\bf location=}{\it 'GCOUNT'}, the new keyword 
will be added to {\bf header} {\it before} the keyword {\bf GCOUNT}.
{\bf Note:} this applies only when adding a new keyword; keywords already in 
the header are kept in the same position.

\item {\bf format=fmt\_string}---An optional IDL keyword string used to 
specify the FORTRAN format for a keyword {\bf value}.
\end{itemize}
\newpage

\noindent
Examples:\\

\begin{tabular}{ll}
GHRS$>${\bf sxopen}, {\it 1, 'zcal:sf\_g2\_01', header} & ; get header\\
GHRS$>${\bf sxaddpar},{\it header, 'spam', 0.9, 'filling factor',\$} & \\ 
\hspace{1.1in}{\it 'end', format='f4.1'} & \\
GHRS$>${\bf print}, {\it header} & ; new header \\
\end{tabular}\\

\noindent
In this example, an existing header is read into {\bf header}.  A new keyword, 
{\bf spam}, its value, and the comment fields are added to {\bf header} in a 
position {\it before} the {\bf END} keyword.\\

\begin{tabular}{ll}
GHRS$>${\bf sxopen}, {\it 1, 'zcal:sf\_g2\_01', header} & \\
GHRS$>${\bf sxaddpar}, {\it header, 'history', 'modified Dec 1, 1992'} & \\
GHRS$>${\bf print}, {\it header} & ; new header \\
\end{tabular}\\

\noindent
In this example, a {\bf HISTORY} keyword is added to the header and is 
positioned before the {\bf END} keyword.\\

\begin{tabular}{ll}
GHRS$>${\bf header=}{\it strarr(10)} & ; blank header\\
GHRS$>${\bf sxaddpar}, {\it header, 'spam', 0.9, 'filling factor',} & \\ 
\hspace{1.1in}{\it format='f4.1'} & \\
GHRS$>${\bf print}, {\it header} & ; new header \\
\end{tabular}\\

\noindent
In this example, a new keyword is added to an {\it empty} header.  {\bf Note:} 
the keyword {\bf END} is also added by this statement.

\item [SXADDHIST, {\it history, header} :] 
\index{SXADDHIST}
\index{SDAS image - adding history}

This procedure adds one or more lines of history to an image header.  {\bf Note:} if the 
header to be modified comes from an existing file, the file must first be 
opened with {\bf SXOPEN}.  In addition, the modified header is not written to
a header file with this routine.

\begin{itemize}

\item {\bf history}---A string or string vector containing history line(s) to 
add  to the image header (maximum length of 72 characters).  

\item {\bf header}---The header vector to be added to.  If {\bf header} is
blank, it must first contain the {\bf END} keyword.  The history records are
then added.

\end{itemize}
\newpage
\noindent
For 
instance:\\

\begin{tabular}{ll}
GHRS$>${\bf sxopen}, {\it 1, 'zcal:sf\_g2\_01', header} & ; get existing header\\
GHRS$>${\bf hist\_recs=}{\it strarr(2)} & ; add 2 history records\\
GHRS$>${\bf hist\_recs(0)=}{\it 'History record 1'} & \\
GHRS$>${\bf hist\_recs(1)=}{\it 'History record 2'} & \\
GHRS$>${\bf sxaddhist}, {\it hist\_recs, header} & \\
GHRS$>${\bf print}, {\it header} & ; view modified header\\
\end{tabular}\\

\noindent
This example adds the history records to an existing header before the {\bf
END} keyword.\\

\begin{tabular}{ll}
GHRS$>${\bf data=}{\it fltarr(10,10)} & ; template data array\\
GHRS$>${\bf sxmake}, {\it 1, 'myfile', data, 0, 1} & ; make new header file\\
GHRS$>${\bf sxhread}, {\it 'myfile', header} & ; read header file\\
GHRS$>${\bf hist\_recs=}{\it strarr(2)} & ; add 2 history records\\
GHRS$>${\bf hist\_recs(0)=}{\it 'History record 1'} & \\
GHRS$>${\bf hist\_recs(1)=}{\it 'History record 2'} & \\
GHRS$>${\bf sxaddhist}, {\it hist\_recs, header} & \\
\end{tabular}\\

\noindent
These statements add the history records to a newly created STSDAS image
header before the {\bf END} keyword.

\item [SXHEDIT, {\it filename, header $[$, /vi$]$} :] 
\index{SXHEDIT}
\index{SDAS image - editing header}

This procedure allows easy editing of an STSDAS image header with using the VMS {\bf EDT} text 
editor (or {\bf vi, GNU emacs} editors on under Unix). {\bf SXHEDIT} re-formats the 
header to a normal ASCII text file, invokes the editor, and then re-formats 
the file back to FITS format (80 character fixed-length) when the editor is 
exited.  {\bf Note:} a new version of the header file is created in this 
process.  Under VMS, a new version number is created.  Under UNIX, a temporary 
file {\it sxhedit.tmp} is created which will contain the updated header 
information.  This file is also created on VMS machines and may be deleted.

\begin{itemize}

\item {\bf filename}---The filename of the image header (default extension is 
{\bf .hhh}).

\item {\bf /vi}---An IDL keyword (if using this routine under Unix only) 
which when present and non-zero, tells {\bf SXHEDIT} to use the
{\bf vi} text editor. Otherwise, the {\it GNU emacs} editor is used. 

\item {\bf HEADER}---An optional output which contains the edited version of the 
header.  
\end{itemize}
\newpage

\noindent
For 
example:\\

\begin{tabular}{ll}
GHRS$>$\${\bf copy} {\it zcal:sf\_g2\_01.$*$ $*$} & ; copy to current dir.\\
GHRS$>${\bf sxhedit}, {\it 'sf\_g2\_01', header} & ; open existing header\\
\end{tabular}\\

\noindent
opens the existing header file, places the user into the VMS {\bf EDT} text
editor at which point existing records can be modified or new records can be
added.  The new version of the header is then written to the user's current
directory.\\

\begin{tabular}{ll}
GHRS$>${\bf print}, {\it header} & ; view modified header\\
GHRS$>${\bf sxhread}, {\it 'sf\_g2\_01', header} & ; read modified header\\
\end{tabular}\\

\noindent
{\bf SXHREAD} is then used to read the newly modified header. 
\end{description}

\subsection{\bf Operating on STSDAS Tables}

\index{SDAS tables, operating on}
This section describes the procedures used to create, read in and modify 
STSDAS tables. There are two groups of procedures, operating at 
high and low-levels. The high-level routines (prefaced by {\bf TABLE}), 
are easier to use, but are more restrictive than the low-level routines 
(prefaced by {\bf TAB}).\\

An STSDAS 
table consists of a specified number of rows and columns into which 
data are stored and later manipulated.  Each column typically has both a name 
associated with it, and a specified data format.  The table format 
(number of rows, columns, column names, data formats) specifications are 
contained within a {\it Table Control Block} or {\bf TCB}.  The data that are 
entered in the rows and columns are contained in the {\it Data Table Array} or 
{\bf TAB}.\\
\index{SDAS tables - high level routines}

One of the major differences between the high and low-level routines is that
they work by manipulating IDL variables ({\bf TCB} and 
{\bf TAB}), whereas the high level routines primarily work with the table as 
a whole and are designed for easy display of its contents.\\


\subsubsection{\bf The High-Level TABLE Routines}
\label{sdas table high}
\index{SDAS tables - high level routines}
Procedures 
included in this section are summarized below:

\begin{description}
\item [TABLE\_HELP :] A procedure that prints a summary of STSDAS table 
contents.
\item [TABLE\_PRINT :] A procedure used to create a listing of the STSDAS table.
\item [TABLE\_LIST :] A procedure that generates a listing of specific 
columns in a table.
\item [TABLE\_EXT :] A procedure used to extract values from specific columns 
of a table.
\item [TABLE\_SORT :] A procedure used to sort table data in ascending order.
\item [TABLE\_CALC  :] A procedure used for calculating a new column based 
on existing table columns,
\item [TABLE\_APPEND :] A procedure used to merge two or more similar STSDAS 
tables.
\item [TABLE\_DELETE :] A procedure for deleting specific rows from an STSDAS 
table.
\end{description}

\vspace{0.25in}

\begin{description}

\item [TABLE\_HELP, {\it tabname $[$, header$]$} :]

\index{TABLE\_HELP}
\index{SDAS tables - help}
\index{help - SDAS tables}

This 
procedure prints a summary of the STSDAS table contents. This includes the size of the 
table, column names, column units, data type and output format (in SPP code).

\begin{itemize}

\item {\bf tabname}---The STSDAS table name.

\item {\bf header}---An optional input header vector returned by {\bf
TAB\_READ}.  If supplied, it will be printed. 

\end{itemize}

\noindent
For example:\\

\begin{tabular}{ll}
GHRS$>${\bf tab\_read}, {\it 'zcal:blem\_001', tcb, tab, header} & \\
GHRS$>${\bf table\_help}, {\it tcb, header} & \\
\end{tabular}\\

\noindent
produces the following output to the screen:

\begin{scriptsize}
\begin{center}
\begin{verbatim}
	ZCAL:BLEM_001.TAB                                               
         nrows=         165               ncols=           8
       maxrows=         165             maxcols=          10
          npar=           0          row length=          28 words
     max n_par=           0      max row length=          28 words
    Table type=  Column-ordered
 
 col. number    column_name            units     type    SPP format code
 
     1            DETECTOR                     Integer*4       11d
     2               LINE1                        Real*4     16.8g
     3               LINE2                        Real*4     16.8g
     4             SAMPLE1                        Real*4     16.8g
     5             SAMPLE2                        Real*4     16.8g
     6             EPSILON                     Integer*4       11d
     7               DEPTH                        Real*4     16.8g
     8             COMMENT                        String       28s
 
END                                                                             
\end{verbatim}
\end{center}
\end{scriptsize}