\magnification=\magstep1
\baselineskip=12pt
\parskip=5pt plus1pt
\parindent=0pt
\settabs 4 \columns
\tolerance=2000

\centerline{\bf BCS Quick Look IDL Routines}
\bigskip
\bigskip
\centerline{Dave Pike, ISAS.}
\bigskip
\bigskip

\centerline{\bf Introduction}

The following IDL routines are provided to make a quick-look inspection of
a BCS raw data file (prefix BDA).  They are structured so that they can be used
as a linked set of procedures although the individual routines may be used in
isolation, provided you know the 'hooks' necessary to link them with the data.
They were originally based around a grey-scale display of the data file and
hence all start with the GS\_ prefix.

\bigskip
{\bf 1.0  Loading the data.}
\bigskip

Start your IDL session by typing in the command WIDL since this ensures that
you load the version of IDL which has the widget routines. Before using the
GS\_ routines you must load the BDA data file (or in most cases only a part of
it) into the IDL variable DATA.  This is most easily done by using  {\bf
TEST\_RD}.  Thus:

IDL$>$ .run test\_rd

answer the prompt for the file name (if you haven't already, you will soon wish
you had a symbol set up for the data directory DISK\$DATA:[YOHKOH.BCS]).  You
may answer with a wild card specification eg DISK\$DATA:[YOHKOH.BCS]BDA*.* in
which case a list of all files fitting that description will be given and you
will be further prompted for a selection from it.  Even more generally, if you
are at a workstation you may enter MENU BDA*.* and IDL will automatically
search predefined directories for the available data files and you make the
choice via the mouse from the list of files presented.

TEST\_RD will inform you of the number of datasets in the particular BDA file of
your choice.  Note that if there are more than 900 then you cannot sensibly read in the
whole file and display it.  There are now many ways of selecting the data
you want using TEST\_RD, ask for instructions.


When asked if you want to read the DP\_SYNC data, take the default, No, option,
UNLESS you intend to calculate the dead\_time corrections in which case you will
need the DP\_SYNC data.

You should now be back at the IDL$>$ prompt.


\bigskip
 {\bf 2.0 Displaying the data.}
\bigskip

To display the data as a 2-dimensional array with spectrum horizontally and
time vertically run the routine {\bf GS}:

IDL$>$ .run gs

you can decompress the data at this stage if it helps the display, but if you
are looking for low-level features it doesn't make much difference. Not
decompressing at this stage does save memory because the decompressed data will
be an integer, rather than byte, array.

The image is scaled to the screen such that a reasonable representation of each
channel's data is made.  If the display is not to your liking, you may run the
look-up table adjustment procedure XLOADCT:

IDL$>$ xloadct

and use the mouse to interactively adjust the display. 


{\it As a result of running GS, the IDL array GSA is loaded. This will be of
dimensions (768,nnn) where nnn is the number of spectra (datasets) extracted.
This can be used for separate display commands or you can extract individual
spectra from it, eg:

IDL$>$ .run {\bf get\_sp}       will load the 4 channels' data into separate arrays  
}

NOTE: If the number of datasets extracted exceeds 900 then no image display is
possible. However, you  may still go through the motions of the GS and the
subsequent GS routines will still work.

\bigskip  
{\bf 3.0 Selecting the spectra of interest.}
\bigskip

With the data displayed on the screen, you may interactively refine your
selection of any of the data in any time window by using the cursor with
program {\bf GS\_CUR}. See below for using this code without the cursor!

IDL$>$ .run gs\_cur

Click the mouse twice to determine the first and last spectra required.  The
routine outputs information about the dataset numbers chosen (both in the
data array extracted from the BDA file and within the BDA file itself) and
about the times associated with those datasets.  Use this routine as often as
necessary to refine your selection.


As noted in section 9 below, these routines may be used on ordinary graphics
terminals in which case suitable prompts, in place of cursor input, are given.
If you actually wish to define the datasets to be used numerically instead of
using the cursor, then set the idl variable {\bf GS\_CUR\_FLAG} to 0/1 to
disable or enable the use of the cursor in this routine even if you are on a
suitable device for cursor use.

A related routine {\bf GS\_WHEN} has the cursor in a loop so a button click will
return the time of the spectrum identified.  This is useful for searching
around in a data file display.  To exit the routine just click in the same
place twice running. If you do not want the time information messing up the
display then set the IDL variable GS\_WHEN\_DISP = 0 (setting to 1 will switch
it on again).

\bigskip
\bigskip
{\bf 4.0  Plotting the mean spectrum.}
\bigskip

The average spectrum within the time window chosen using the cursor can be
plotted using the code {\bf GS\_SP}:

IDL$>$  .run gs\_sp

This routine (based on VG by J. Mariska) plots the four channels on to a 
single page. A hard copy can be produced by switching to device PS,
rerunning the plot command and sending it to the laser printer (if required,
don't forget to switch back to the windows display):

IDL$>$ set\_plot,'PS'

IDL$>$ .run gs\_sp

IDL$>$ pltdv2
 
( IDL$>$ set\_plot,'X')

If for some reason you want any or all of the mean spectra smoothed before
display, then use the IDL variable {\bf GS\_SP\_SM(4)} to set the smooth width
for each channel before running GS\_SP.  For instance, 

IDL$>$  gs\_sp\_sm = [5,0,0,0]

will smooth channel 1 data only with a box average of width 5.

If you are using {\bf GS\_PUTSP} and {\bf GS\_GETSP} (see section 8) to store
and read the mean spectrum  stored in the GSP 1-d array then you may want to
use GS\_SP without having the 2-d GSA array  available.  To do this, set the
IDL variable  {\bf GS\_SP\_OLD} = 1. This will make GS\_SP use the current GSP
array without trying to reload it from the GSA 2-d array.  Set the variable to
zero to return to extracting the mean spectrum from the GSA 2-d array. 

{\it The mean spectrum calculated is stored in variable GSP(768). Various parts
of this may be plotted as needed.}

\bigskip
{\bf 5.0 Spectral movie}
\bigskip

The individual spectra within the time window chosen can also be displayed in a
movie form with R Bentley's movie routine.  Here it has been interfaced to the
cursor output and is called {\bf GS\_MOVIE}. It can be run by:

IDL$>$ .run gs\_movie

\leftskip=10pt
select the channel

if the data are noisy you may want to smooth with a 3 bin filter.

if you select the bar you will get an indication on the light curve of when
the current spectrum was taken.

for short sequences of spectra, you might want to repeat the movie for several
loops.

Answer any questions about plot scales.

\leftskip=0pt


\bigskip
{\bf 6.0  Light-curves of spectral features.}
\bigskip

If you require the light curve (ie the integrated intensity as a function of
time) of a particular spectral feature use the routine {\bf GS\_LC}.  This
should only be run after GS and GS\_CUR have been used to define the data
limits. Be aware also that light curves may not make sense (or worse, be very
misleading) if you have not corrected for deadtime effects. See the
documentation on calculating the deadtime correction.  The deadtime correction
should always be in an array called DT\_FAC and the light curve routine will
ask whether this array exists and, more importantly, if it exists whether it is
applicable to the data in hand.

A plot of the mean spectrum in the chosen time interval is displayed (this is
the same plot as used in GS\_SP) and the user is prompted to select wavelength
windows for the spectral feature and an appropriate continuum region.  A
subsequent plot displays the integrated spectral and continuum counts and the
continuum-subtracted counts for the spectral feature.

Very often, because of the necessity of choosing a small continuum window, the
continuum counts are very noisy. The idl variable {\bf GS\_LS\_SMTH} can be set
to a value to define the box size for smoothing of the continuum counts. No
action is taken if this variable is undefined on entry to GS\_LC.

To obtain a hardcopy of these plots, first run in interactive mode, switch
device to PS and rerun.  The wavelength windows chosen previously are reused.
Use PLTDV2, as usual, to print the plot file. 


\bigskip
{\bf 7.0  Light curve and spectral display.}
\bigskip

The routine {\bf GS\_VG} (a copy of J. Mariska's procedure) can be used to
produce a four panel plot.  The total-count light curves are displayed together 
with channel 2,3 and 4 mean spectra (this was written in the pre-FeXXVI days!).
The time window of the spectra is marked on the light curve plots. Having
selected the data window with the cursor (or at least set the variables YDS1
and YDS2 by some means - see section 3 above) type:

IDL$>$ .run gs\_vg

 


\bigskip
{\bf 8.0  Saving and retrieving the mean spectrum array.}
\bigskip

The mean spectrum created (IDL variable gsp(768)) can be stored and retrieved
using the 2 routines {\bf GS\_PUTSP} and {\bf GS\_GETSP}.  Thus

IDL$>$ .run gs\_putsp         will prompt for file name to store spectrum

IDL$>$ .run gs\_getsp         will prompt for file name to read spectrum

See section 4 above for the use of the IDL variable GS\_SP\_OLD to be able
to plot a mean spectrum read from a stored file.


\bigskip
{\bf 9.0  Non-workstation use.}
\bigskip

If the workstations are busy, all of the GS\_ routines can be used at a normal
graphics terminal.  For obvious reasons the 2-d display is not used but the
same data extraction takes place and in place of the cursor you are
prompted for the dataset numbers so a spectral display is still possible.


 \bigskip 
{\bf 10.0  A link with the Fortran program MKBSD.} 
\bigskip

The routine {\bf GS\_WCFL}  writes a new MKBSD control file using the current
data file  name, the time parameters derived from GS and GS\_CUR, and, if the
IDL  variable {\bf INT\_TIME} is set up, then the accumulation time will be
updated  in the control file also.

The MKBSD control file to be updated must already exist! and its full (if not
in current directory) file specification be loaded into the IDL variable {\bf
CFL\_NAME} before running this code. For example, assuming the data have been
displayed and the spectra chosen using the cursor then:

IDL$>$ cfl\_name = 'myfile.cfl'

IDL$>$ int\_time = 21.0

IDL$>$ .run gs\_wcfl



\vfill\eject
\end
