%	Ver 10	RDB 11-Jan-94
%	Ver 11	MDM 11-Jan-94
%	Ver 12	MDM 12-Jan-94
%	Ver 13	MDM 13-Jan-94
%	Ver 14  MDM 20-Jan-94
%	Ver 15  MDM 25-Jan-94

\section{{\bf Bragg Crystal Spectrometer (BCS)}}

The purpose of this section is to help the user access the BCS data  using
the  various  pieces  of BCS software that have been written.  All the routines
discussed use the reformatted database; IDL code assumes IDL Version 3  (or
greater).  Note that some of the widget-based IDL routines only work with
more recent releases of IDL.

This document only presents an outline of how to use the routines.
Please use the IDL routines DOC\_LIBRARY, XDOC and CHKARG, together
with the Reference Guide chapter for further information on any
particular routine. 

There are several additional documents that describe different parts 
of the BCS software. All are kept on \$DIR\_BCS\_DOC; in particular:
\IItem
\item{Please refer to the document BSC\_SOFTWARE.TXT for the most
recent information on the BSC routines that Dominic Zarro has been
writing.} 
%%(Under VMS see ys:[ucon.soft.zarro]; Under Unix see
%%/ys/ucon/soft/zarro/).  
\item{Please also refer to Dave Pike's document GS\_PROCS.TEX for 
further information on the ``GS'' (grey scale) suite of software.} 
\item{There are also several documents relating to the BSD FORTRAN
software.}
\end{itemize}

Notes:
\EEnumerate
\item{BCS data files have the prefix ``bda'' -- the rest of the name represents
the start time of the file in the form ``yymmdd.hhmm''.}
\item{In the BCS section of the manual, data and index arrays relating
to the BDA  file  are called  {\it index}  and {\it data}.  Those related to
other files and structures will  will  have  some  type  of  prefix 
in  the  example  calls,   e.g. ``bsd\_data'', ``bsd\_index''} 
\item{Often in procedure calls there  are  additional,  optional  
parameters than  can  be used to further define what the routine will
do -- these are indicated by the use of [ ] within  the  example  of  a
routine  calling sequence; [,etc] means that there are several
additional parameters and the user should refer to the Reference
Manual.} 
\item{For most applications, the DP\_SYNC\footnote{
	The BCS dp\_sync data contain instrument data, including
	the detector event counters, in a form that is synchronous with the
	rest of the frames of the data from the spacecraft DP. The spectral
	data, because of the queue memory, are asynchronous to this data.} 
data are not needed --- they are however
required for deadtime correction within MK\_BSC.}
\item{On the VMS machines, the BDA data should be stored under several
directories that can be accessed with the logical BDA\_DAT: (e.g.
bda\_dat::bda911024.*)}
\end{enumerate}

Section~\ref{bcs_entry} details how to first access the BCS data.  To do
detailed analysis work on the spectra, see sections~\ref{bcs_cal1}
and~\ref{bcs_cal2}; otherwise, use the routines in
section~\ref{bcs_simple1}.  Several other useful BCS routines are
summarized in section~\ref{sw_bcs}.

\subsection{\label{bcs_entry} Entry Point Into the Data}

Basically here we are asking why are you wanting to look at BCS data.  This
is  because the approach used to access the data if you are interested in a
particular time is different from that used if you are trying to  find  the
occurrence  of  a particular type of event without any {\it a priori} knowledge of
its occurrence.

If you are interested in a particular  time  interval,  you  have  probably
found  out  that there is an event from the book of BCS Ca XIX
light curves, SA plots, PLOTY plots, GOES light curves, the event
lists, the occurrence of a  flare flag or from something seen in
another instrument.  In this case, the way to proceed is to use  YODAT
or WBDA. 

\subsubsection{Accessing a Specific Time Interval Using YODAT}

YODAT is a general purpose routine that will access  all  types  of  Yohkoh
data,  together with certain datasets from ground-based observatories.  The
detailed operation of YODAT is described on page~\pageref{yodat_sec}, but here we
present a  short summary. 

After starting YODAT (within IDL) the user must select a BDA file (or
files). YODAT reads in the  roadmap  of the selected file and the user
must then decide on which further selection procedure to use.  The
user can: 

\EEnumerate
\item{Use the $-44$x options within YODAT to select a time interval using a  BCS
light curve  and  read in the data for that time interval -- the best channel
to use for this is probably channel 3 (Ca XIX).  YODAT returns the data and
index arrays, and (for the BCS) optionally the {\it dp\_sync} array.}

\item{Exit YODAT (using the $-888$ option), make a selection of a part
of the  data from  the roadmap  by  constructing  an  {\it ss}\footnote{
	See the documentation of YODAT for details on the {\it ss} vector.}
vector, and then  read this data by re-running YODAT using option $-99$. 
Again, YODAT will return  the  {\it data}  and {\it index}  arrays,  and
optionally the {\it dp\_sync} array.  This non-YODAT selection can be done
in various ways, two are: 
\index{dp\_sync, BCS}

\EEnumerate
\item{use LIST\_BDA to list the mode header  information  from  the  roadmap,
then  find the time interval and use the {\it ss=ss} option to produce the {\it ss}
array that can be used with YODAT.
%
\idlinputa{list\_bda,roadmap,start\_rec,nrec,ss=ss}\index{LIST\_BDA}
}
%
\item{use SELECT\_BDA to plot the roadmap light curve of a  selected  channel
and  select the period of interest using the cursors.  (Note:  there
is an option to read the data in with select\_bda if required).
%
\idlinputd{.run select\_bda}\index{SELECT\_BDA}
}
\end{enumerate}  }
\end{enumerate}

%
\subsubsection{Accessing a Specific Time Interval Using WBDA}

A widget-driven interface that allows the user to examine any BDA  file  on
the  data  directories  (or to display and accumulate the contents of a BDA
file already read in using YODAT) is  the  procedure  WBDA.   This  routine
allows  the  user to interactively work with the data.  If the data and index
array have not already been read in using YODAT, it is  recommended  that  a
specific  date  be  requested  when running WBDA; a question concerning the
required date is asked if WBDA is called without any input parameters.
%
\idlinputa{wbda,index,data}\index{wbda}
\idlinputc{wbda}
%
\subsubsection{Browsing}

\insertplot{demo_bcs_24hr_plot.eps}{bcs\_24hr\_plot, '11-dec-91'}{demo_bcs_24hr_plot}{6.25}{8.25}
\index{light curves, BCS}

If you do not know exactly which period you are  interested,  you  can
get an idea of what the BCS has seen either by producing light curves using
BCS\_24HR\_PLOT, using WBDA to examine files, or by producing a
grey-scale  image  of  spectra against time within a selected file
using GS.  Fig.~\ref{demo_bcs_24hr_plot} shows a sample output for
the routine \label{bcs_24hr_plot} BCS\_24HR\_PLOT.
%
\vskip 0.1 in
If you interested only in whether the BCS  has  seen  anything,  this
can be determined using BCS\_24HR\_PLOT.   This  routine works using
either the BDA roadmaps or the Observing Log (OBD files in the case of
the BCS) and allows plots of a selected day to be made. The start of 
each (per-orbit) BDA file is marked, as are the times of SAAs and 
nights. By default, the observing log is used and channel 3 (Ca XIX)
is selected. Note: YODAT does NOT need to have been run before
BCS\_24HR\_PLOT. 
%
\idlinputa{bcs\_24hr\_plot,'dd-mmm-yy' [,chan=n]}\index{BCS\_24HR\_PLOT}
\idlinputb{bcs\_24hr\_plot,'dd-mmm-yy',/bda [,chan=n]}
%
The widget-driven interface WBDA allows the user to examine any  BDA
file  on the data directories.  This routine allows the user to interactive
work with the data, plotting the light curve and also plotting spectra
for selected times with the data. 
%
\idlinputa{wbda}
%
If you are interested in more detail of what  spectra  the  BCS  has
observed, use GS --- this routine must be run after the data has been read in
with YODAT.  There is a limit of how much data can be handled at a time 
(about 900 spectra), and some selection of the required time interval may be
needed using the methods described above, but for the per-orbit files, this
limit may not be a problem.  The advantage of GS is that you can get a good
idea of what has been seen in the spectra --- a particularly useful  tool  if
you  are  trawling  for  data.  Remember, all the routines that run from GS
(those that have names starting with GS\_) require that a time-period be selected
first using the cursor routine, GS\_CUR.
%
\idlinputa{.run gs}\index{GS}
\idlinputb{.run gs\_cur}\index{GS\_CUR}
%
Warning:  If there is a gap in the time coverage in a data file,
the time axis on the GS greyscale plot may not be uniform!!

\subsection{\label{bcs_simple1} Examining Data in the BDA Files}

These routines (except where stated) assume that the required spectral
data has already been read in (e.g. using YODAT). 

The data extracted from the BDA file is in compressed form and is not
normalized for the integration time. Also, spectra from all channels
are included in the data array and extraction of a channel may be
needed before the data can be properly displayed. 
A single channel can be extracted from the BDA data array, and 
then decompressed and normalized for integration time using 
BCS\_DSPEC. By default, channel 3 data are returned.
%
\idlinputa{chan\_data = bcs\_dspec(index,data)}
\idlinputb{chan\_data = bcs\_dspec(index,data,chan=n [,etc.])}\index{BCS\_DSPEC}
%
Essentially, this is the same as the following expression, but 
BCS\_DSPEC also does some additional things.
%
\idlinputd{chan\_data = bcs\_norm(index,bcs\_decomp(ext\_bcschan(index,data,channel)))}\index{BCS\_NORM}
%
\subsubsection{Listing the BDA Data}

If you are interested in what modes the BCS  was  executing,  or  what  the
count rate  in  a  particular  channel was at a particular time, this can be
determined by using LIST\_BDA.   The  procedure  will  work  on  either  the
roadmap  or  the index structure (which must have been read in with YODAT).
By default, the count rate for channel 3 (Ca XIX) is given in the listing.
%
\idlinputa{list\_bda,roadmap,start\_rec,nrec [,chan=n, etc.]}\index{LIST\_BDA}
\idlinputc{list\_bda,index,start\_rec,nrec [,chan=n, etc.]}
%
\subsubsection{Light Curve (only) Plot Routines}
\index{light curves, BCS}

These routines only plot light curves. Examples of calls to available 
routines are:
%
\idlinputa{lcbda,index [,chans=[2,3,4],psym=psym,/log]}\index{LCBDA}
\idlinputb{plott\_bda,index}\index{PLOTT\_BDA}
\idlinputc{plott\_bda,roadmap,psym=psym}
%
\subsubsection{Spectra and Light Curve Plot Routines}

The light curve, and spectra at times selected from the light curve, may
be displayed using WBDA. This is an interactive, Widget-driven 
program.  Notes: (i) WBDA can work either from extracted data, or can
extract its data directly from the BDA file; (ii) the spectral plots 
are versus wavelength.
%
\idlinputa{wbda,index,data}
%
Times can be selected by  the  cursor  from  a  light curve  and  summations
overplotted together with a light curve using BCS\_SURVEY.
%
\idlinputa{bcs\_survey,index,data [,chan=n [,/norm , etc]]}\index{BCS\_SURVEY}
%
Spectra summed over times selected by the cursor from the GS greyscale  can
be plotted with GS\_SP (which displays four spectra).
%
\idlinputa{.run gs\_sp}\index{GS\_SP}
%
There are several variants of a routine that  plots  spectra  from  several
channels  and  a  light curve  on  a  page.   In due course, these will be
combined into one program.   These routines display a light curve and
three spectra)
%
\idlinputa{.run vg}
\idlinputc{.run gs\_vg}\index{GS\_VG}
%
\subsubsection{Spectral (only) Plot Routines}

A plot with a spectrum for each channel stacked one above the other 
may be produced with PLOTS\_BDA; the user can page through the modes 
if more than one is passed in the arrays to the routine.
%
\idlinputa{plots\_bda,index,data}\index{PLOTS\_BDA}
%
Many spectra from the same channel may be plotted on a page as a 
matrix with the routine BCS\_MULTI.
%
\idlinputa{bcs\_multi,index,data [,chan=n, etc.]}\index{BCS\_MULTI}
%
MPLOT allows the user to overplot many spectra from the same channel, 
optionally displacing each one in the x- and/or y-direction. 
Note that the BCS channel must have been extracted before 
calling this routine (see earlier in this section).
%
\idlinputd{mplot,xvals,chan\_data,x\_spacing,y\_spacing}\index{MPLOT}
%

\subsubsection{2-d Plots of Spectra Against Time}

The evolution of spectra against time can be displayed as a contour map by
BCS\_CONT,  or  as a greyscale image using DISP\_BDA and GS.  Note:  The time
axis of BCS\_CONT is uniform, but those of DISP\_BDA and GS are not. 
Example calls of these routines are:
%
\idlinputa{bcs\_cont,index,data [,chan=n, range=[n1,n2], etc.]}\index{BCS\_CONT}
\idlinputb{disp\_bda,index,data}\index{DISP\_BDA}
\idlinputc{.run gs}
%
\subsubsection{Spectral Movie}

After selecting a time interval with YODAT, a movie of the changing spectra
for  a  given  channel  may  be  displayed  by  BCS\_SPMOVIE.   Note:  
this program will only run on an X-windows workstation.
%
\idlinputd{bcs\_spmovie,index,data [,chan=n, etc.]}\index{BCS\_SPMOVIE}
%
\subsubsection{Overplotting Spectra}

Overplot several spectra to show evolution of blue wing and line width 
with PLOT\_REF.
%
\idlinputd{plot\_ref,index,data,channel,dset\_arr [, etc.]}\index{PLOT\_REF}
%%%\idlinput{.run gad\_blue\_wing ???}
%
\subsubsection{Light Curves of Selected Bins}

Plot light curves of different regions of the spectra selected by  cursors.
Note:   With  GS\_LC, the time period must first have been selected from the
GS greyscale display with GS\_CUR.
%
\idlinputd{.run gs\_lc}\index{GS\_LC}
%
%%\subsubsection{Jacques Dubau's Program}
%%Unix only??
%
\subsection{\label{bcs_cal1} Calibrating and Fitting Spectra (using the BSC software)}
\index{calibrated spectra, BCS}
\index{BSC (BCS Spectrally Calibrated)}

BCS data that have had instrumental corrections and calibrations applied
to them are referred to as BSC data.  BSC stands for BCS Spectrally
Calibrated data which has had crystal curvature corrections applied and
has been converted to photons cm$^{-2}$ s$^{-1}$. For quantitative work
with BCS spectra the user should always begin by constructing the BSC data
structures from the raw data files. This IDL-based software replaces that
FORTRAN code that was previously used (see the section on BSD Analysis
Software); hopefully this will eliminate some of the difficulties
encountered in the installation of the FORTRAN code on the various Unix
and VMS platforms. The routines are outlined here, but more information
can be found in the BCS part of the reference manual.
%% more  information  can  be  found  in  the file on
%% Zarro's ucon directory (see ys:[ucon.soft.zarro] under VMS;
%% /ys/ucon/soft/zarro/ under Unix).

\vskip 0.1 in
The routines work with structures that are compatible with  all  the  other
instrument  structures  in  the Yohkoh database.  An outline structure (the
BSA structure) containing a specification of what data are to  be  extracted
from  the  BDA  file  is first created by MK\_BSA, and then the BSC structure
(and optionally a BSC file) is assembled by the routine MK\_BSC.

First run YODAT to extract the index and data arrays from the BDA file  for
the  selected  time  interval.   Make sure to ask for the DP\_SYNC data.
The routine MK\_BSC is then called as 
follows:
%
\idlinputa{mk\_bsc,index,data,bsc\_index,bsc\_data,dp\_sync=dp\_sync}\index{MK\_BSC}
\idlinputb{mk\_bsc,index,data,dp\_sync=dp\_sync,/file}
%
The second case will write the corrected data to a BSC file.
The following routines are used in the assembly of the BSC file:
\begin{verbatim}
    BCS_ACCUM     accumulates BDA data into a BSC structure.
    BSC_XCORR     applies curvature corrections to BSC data.
    BSC_FLUXCAL   applies flux calibrations to BSC data.
    BSC_ERRCAL    computes uncertainties for the BSC count spectra.
\end{verbatim}

If the /file option is not used when calling MK\_BSC, a BSC file may
be written using SAV\_BSC. An existing BSC file may be read in with
RD\_BSC and, after modification, again a new file may be written with
SAV\_BSC --- see the Reference Manual for more details. 

%
\subsubsection{Listing the BSC Data}

The contents of the BSC file or structure may be examined using LIST\_BSC.
%
\idlinputd{list\_bsc,bsc\_index,chan}\index{LIST\_BSC}
%
\subsubsection{Fitting the BSC Data}
\index{fitting, BCS}

BCS spectra that are held in a BSC structure my be fit using the 
routine FIT\_BSC.\footnote{
        It is also possible at this point to use the BSD suite of FORTRAN-77
	and IDL software. By using BSC2BSD, a BSC structure can be converted
	to a BSD structure (and optionally a BSD file) and following this, any
	of the routines that normally work off the BSD file (including the
	programs BSDCAL and BSDFIT) can be used. See section~\ref{bcs_cal2} for details
	on BSD routines.
%
\idlinputds{bsc2bsd,bsc\_index,bsc\_data,index=bsd\_index,data=bsd\_data}\index{BSC2BSD}
\idlinputds{bsc2bsd,bsc\_index,bsc\_data,filename=filename}
}
%
In the following example of a call to the routine, the results of the 
fit are returned in the parameters {\it fit\_index} and {\it fit\_data}: 
%
\idlinputa{fit\_bsc,bsc\_index,bsc\_data,fit\_index,fit\_data,chan=n}\index{FIT\_BSC}
\idlinputb{fit\_bsc,bsc\_index,bsc\_data,fit\_index,fit\_data,ss=ss}
%
All channels and all spectra are fit if no selection is specified. In
addition to the {\it chan} and {\it ss} keywords, there are many other keyword
parameters that specify of the range of the fit, allow the input of 
starting guesses of electron temperature and other parameters.
%
%!!!!!!!!!!!!!
Note: FIT\_BSC is relatively new and is still under development.
%
\subsubsection{Temperature Fit (by Comparison)}
\index{temperatures, BCS}
\index{determining temperatures, BCS}

Compare a measured spectrum (selected using an {\it ss} vector from 
several contained in {\it bsc\_index} and {\it bsc\_data}) to spectra calculated using 
BCS\_SPEC (for channel {\it chan}, at a temperature of {\it Te6} MK) using the
routine BCS\_SPEC\_PLOT. An example of the sequence of calls required 
to do this is given below:
%
\idlinputa{bcs\_spec\_plot,bsc\_index,bsc\_data,ss=ss}\index{BCS\_SPEC\_PLOT}
\idlinputb{spec=bcs\_spec(chan,Te6,wave=wave [,etc])}
\idlinputc{bcs\_spec\_plot,wave,spec,/over}
%

\subsubsection{Extraction from the BSC structures}
Because the index and data records in a BSC file represent interleaved
integrations  of individual  channels,  if  the  user wishes to extract a
single channel from the index structure they must use SEL\_BSC:
%
\idlinputa{sel\_bsc,bsc\_index,bsc\_data,new\_index,new\_data,wave,flux,eflux,chan=chan}\index{SEL\_BSC}
%
The selected index and data structures are returned in {\it new\_index} and 
{\it new\_data}.
The wavelength, flux, and uncertainties in the flux are returned in the arrays
{\it wave, flux} and {\it eflux}. The following keywords are also accepted: {\it TSTART, TEND}.

%%BSC\_CHAN and GET\_BSC.
%%%
%%\idlinputa{cindex = bsc\_chan(bsc\_index,chan,dset)}
%%\idlinputc{cdata = get\_bsc(bsc\_index,bsc\_data,chan=chan [,etc])}
%%%

%
\subsubsection{Displaying the BSC Data}
\index{plotting, BSC spectra}

The light curve and spectra selected from the light curve (from the BSC
file  or structure) may be plotted with PLOT\_BSC.
This program may be used interactively if desired, and can also be 
used to overplot fitted spectra (if FIT\_BSC has been called with the data).
If there are multiple spectra, PLOT\_BSC will provide a widget
interface to select the spectrum to plot. An example is shown in
Figure~\ref{demofitbsc} which plots data which has been fit using
FIT\_BSC. 
%
\idlinputa{plot\_bsc,bsc\_index,bsc\_data,chan=n}\index{PLOT\_BSC}
\idlinputb{plot\_bsc,bsc\_index,bsc\_data,chan=n,fit\_index,fit\_data}
%
\insertplot{demo_fit_bsc.eps}{
An example of a one-component fit of BCS channel 3 data by FIT\_BSC.
}{demofitbsc}{6.25}{4}


A light curve of FIT\_BSC results can be produced with the FIT\_BSC\_PLOT{}.
An example plot is shown in figure~\ref{demofitbsc2}.
\index{plotting, BSC fitting results}
\idlinputa{fit\_bsc\_plot, bsc\_index}\index{FIT\_BSC\_PLOT}
%
Note that FIT\_BSC\_PLOT displays the non-thermal broadening, or
turbulent velocity as a function of time.  The routine BCS\_BROAD is
used to make the conversion between line broadening and velocity. 
FIT\_BSC will optionally fit a second component with an upflow velocity
as one of the degrees of freedom.  \index{velocity, BCS}\index{BCS\_BROAD}\index{determining velocities, BCS}
%
A light curve of selected wavelength regions of a set of spectra can be produced with LC\_BSC.  
\idlinputa{lc\_bsc,bsc\_index,chan=n}\index{LC\_BSC}
%
A psuedo-map of stacked BSC spectra can be produced with MAP\_BSC.
%
\idlinputd{map\_bsc,bsc\_index,chan=n}\index{MAP\_BSC}
%

\insertplot{demo_fit_bsc2.eps}{
Time series plot of results from FIT\_BSC using FIT\_BSC\_PLOT.
}{demofitbsc2}{6.25}{8.25}

\subsection{\label{bcs_sw0} Other Useful BCS Routines}

See the routines listed in the Appendix of this User's Guide on
page~\pageref{sw_bcs}.
