SMM X-RAY POLYCHROMATOR

SOFTWARE USER’S GUIDE

October 1993 (Version 2.0)

Prepared for Goddard Space Flight Center Solar Data Analysis Center

Contract NAS5-31235

by

Dr. Dominic M. Zarro

Applied Research Corporation 8201 Corporate Drive Landover, MD 20785

Dr. Julia L. R. Saba

Lockheed Solar & Astrophyics Laboratory O/91-30, Bldg. 252, 3251 Hanover Street

Palo Alto, CA 94304

and

Dr. Michael McSherry

University of Belfast Ireland

TABLE OF CONTENTS

1. OVERVIEW 1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–1 1.2 Description of the XRP Instrument . . . . . . . . . . . . . . . . . . . . . 1–1 1.2.1 The BCS Instrument . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–2 1.2.2 The FCS Instrument . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–2 1.3 Summary of XRP Data and Software . . . . . . . . . . . . . . . . . . . . 1–4 1.4 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–5 1.4.1 REFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–7

2. FORTRAN DATA REDUCTION PROGRAMS 2.1 BCS Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–1 2.1.1 BOTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–1 2.1.2 MKBRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–1 2.1.3 LISTBRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–2 2.1.4 CALBRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–4 2.1.5 SPCFIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–5 2.1.6 BCSPRO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–6 2.2 FCS Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–7 2.2.1 FOTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–7 2.2.2 MKFIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–7 2.2.3 LISTFIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–8

3. IDL DATA ANALYSIS PROGRAMS 3.1 BCS Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–1 3.1.1 PLOTBDA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–1 3.1.2 PLOTBRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–2 3.1.3 PLOTFIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–3 3.2 FCS Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–3 3.2.1 PLOTFIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–3 3.2.2 RDFIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–5 3.2.3 RUST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–6 3.2.4 FLUXCAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–7 3.2.5 FTEMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–9 3.2.6 PLOTFTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–11 3.2.7 TEMCAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–11

4. IDL/WIDGET PROGRAMS 4.1 BCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–1 4.2 FCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–3 4.3 LISTBCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–4

1. OVERVIEW

1.1 INTRODUCTION

This manual describes the programs that are available for the reduction, display, and analysis of soft X-ray imaging and spectral observations obtained with the X-ray Polychromator (XRP) instrument on the Solar Maximum Mission (SMM). The XRP programs are written in Fortran and Interactive Data Language and are tailored for a VAX/VMS operating system. The Fortran programs are used primarily for copying raw data from tape to magnetic disk, applying first order corrections to the data (e.g., background subtraction, sensitivity corrections), and listing the contents of particular data files. The IDL programs are used primarily for reading and plotting spectra, images, and lightcurves from selected data files. The software is available online at the Solar Data Analysis Center (SDAC) (NASA/GSFC, Greenbelt, MD) and can be accessed as discussed in Appendix A.

This manual is divided into four chapters. Chapter 1 gives a brief overview of the XRP instrument, a description of the associated data files that are created during various stages of the data reduction and analysis (Table 1-3), a summary listing of the available programs in alphabetical order (Table 1-4), a flowchart relating the data files and their associated programs (Figure 1-1) and a summary guide to the programs ordered by task (Table 1-5). It also describes the REFORMAT procedure which is the necessary first step in copying XRP data from Exabyte tape to disk. Chapters 2 and 3 give detailed descriptions of the Fortran and IDL programs, respectively, concentrating on their usage and their limitations. Chapter 4 describes the newly developed IDL/widget programs that provide a graphical user interface to the XRP software. Further information about the XRP software can be obtained by contacting the SDAC staff (see Appendix A).

1.2 DESCRIPTION OF THE XRP INSTRUMENT

The primary objective of the SMM-XRP was the study of the physical conditions in the corona for a variety of solar phenomena. This was achieved through the use of two complementary instruments: the Bent Crystal Spectrometer (BCS) and the Flat Crystal Spectrometer (FCS). The XRP acquired data during the peak of solar cycle 21 (February to November 1980), during its decline (following the in-orbit repair of SMM in April 1984), and through the rise phase of cycle 22 (until October 1989).

1.2.1 The BCS Instrument

The BCS was designed to observe the spatially integrated fluxes in eight hightemperature soft x-ray emission lines produced by solar flare plasma. The primary goals of the BCS were:

XRP USER’S GUIDE – 1. OVERVIEW

1–1 • to study flare dynamics using line shift and broadening measurements;

• to measure temperature, emission measure, abundances, and equilibrium states to characterize the physical conditions in the flare plasma.

The characteristics of the BCS are listed in Table 1-1. The BCS had eight bent Bragg crystal spectrometers with position-sensitive detectors. It was collimated to 6 arcmin FWHM and was capable of changing its time resolution from 11 s to 0.5 s or less by using dynamic memory and sacrificing spectral coverage or resolution. The BCS was sensitive to the high-temperature (T_{e} > 10 MK) component of the flare plasma. Most of the BCS data were taken in the standard flare mode, which recorded spectra every 11 or 7.6 s (depending on the number of operational channels) until a specified threshold was reached. In flare mode, the integration time decreased to 3.6 s. After 1980, BCS channels 2 and 8 no longer functioned. Most of the BCS analysis software has been written for Channels 1 (the Ca XIX channel) and 4 (the low-resolution Fe XXV channel).

Table 1-1. BCS Characteristics

Channel  Ion Stage  Wavelength  Peak T_{e}  Resolution
Number  (Å)  (10^{6} K)  λ/δλ
1  Ca XIX  3.165 – 3.231  35  3463
2*  Fe_{shell}^{inner}  1.928 – 1.945  2  11206
3  Fe_{shell}^{inner}  1.839 – 1.947  2  4075
4  Fe XXV  1.840 – 1.984  50  3967
5  Fe XXV  1.866 – 1.879  50  8937
6  Fe XXV  1.854 – 1.867  50  8937
7  Fe XXV  1.842 – 1.855  50  8911
8*  Fe XXVI  1.769 – 1.796  60  7005

* Channel has data for 1980 only

1.2.2 The FCS Instrument

The FCS was designed to:

• image soft X-rays emitted over a wide range of coronal temperatures (from 2-70 MK) to determine the structure and evolution of flares and active regions;

• obtain high resolution spectra from 1.5-23 Å to determine plasma temperatures, emission measure, density, abundances, and dynamics;

• monitor the evolution of soft X-ray fluxes with up to 0.256 s time resolution.

The FCS characteristics are listed in Table 1-2. The FCS was a seven-channel Bragg crystal spectrometer built on a raster mechanism. The FCS contained an optical sensor in channel 8 (with a small known offset from the X-ray detectors) which could be used for image coregistration. The FCS isolated specific areas in the corona for study through its narrow collimation (12-16 arcsec FWHM response, depending on the detector), producing

1–2

1.2 DESCRIPTION OF THE XRP INSTRUMENT

modest spatial resolution images or well-resolved X-ray spectra. At the “home position” (HP) of the wavelength drive, each X-ray channel could monitor the emission from a prominent soft X-ray line. By scanning its wavelength drive, the FCS could access an even wider range of soft X-ray lines. The FCS could image an area up to 7 arcmin square in up to six bright spectral lines simultaneously, make rapid scans over a wide wavelength range or at high resolution across individual line complexes, or combine the two modes to make spectroscopic observations over a predetermined area.

About 400 FCS observations using the wavelength drive (“crystal runs”) were executed during the mission. These included scans of individual profiles at one or more spatial locations, taking 10-30 s each; scans of line complexes (such as density-diagnostic triplets), taking 1-2 mins; and long spectral scans of all the accessible wavebands, taking 10-20 mins. Several sequences combined images in bright lines at several wavelength drive positions with scans of the corresponding line profiles at the brightest pixel. Some of the FCS sequences (designed to study active regions or quiescent solar structures) were run in a “standalone mode”. Most of the remaining sequences (designed to study flares) were triggered by a flare flag from the BCS.

Table 1-2. FCS Characteristics

HP Ion Wavelength Peak T_{e} Crystal  Scan Extent Resolution  FOV
Stage  (Å)  (10^{6} K)  (Å)  (λ/δλ)  (arcsec)
O VIII  18.969  3  KAP  13.1 – 22.4  997  16
Ne IX*  13.447  4  Beryl  10.5 – 14.9  2300  15
Mg XI  9.169  6  ADP  7.3 – 10.1  8140  14
Si XIII  6.649  10  Quartz  4.9 – 7.6  5500  14
S XV  5.039  16  Quartz  3.6 – 5.8  10300  13
Ca XIX** 3.173  35  Ge  2.3 – 3.6  5170  14
Fe XXV  1.850  50  Ge  1.4 – 2.1  25100  14

* Channel not operational after February 1985 ** Channel not operational after 1980

FCS Channel 6 (Ca XIX) was misaligned with respect to the other detectors, so that Ca XIX was offset from HP. After 1980, this channel no longer functioned. After February 1985, engineering data was output into the telemetry for Channel 6. In early 1985, FCS Channel 2 (Ne IX) was lost, so that coverage of the Ne IX complex was available only at the short wavelength end of Channel 1. Soon thereafter, the Channel 2 telemetry was replaced with telemetry from the FCS optical sensor # 8 to allow higher spatial sampling of its output. By 1987, the remaining FCS thin-window detectors (Channels 1, 3, and 4) began to run out of gas, so that they were used only intermittently in a “campaign mode”. By May 1989, only the high-energy FCS channels remained, so that the FCS became restricted to flare studies. After December 1987, the wavelength drive experienced increasing problems. No FCS spectroscopic sequences were run successfully after April 1988.

1–3

For further details of the XRP instrument design and operational capabilities, see Acton et al., Solar Physics, 65, 53-71, 1980. Instrumental considerations such as calibration, sensitivity, alignment, fluorescence, and background are discussed by Bentley (Ph.D. thesis, Department of Physics and Astronomy, University College London, 1986).

1.3 SUMMARY OF XRP DATA AND SOFTWARE

Table 1-3 summarizes the different file types that are associated with the reduction and analysis of XRP data. These files contain data ranging from raw detector count rates, to processed images and spectra, to physical parameters such as plasma temperature and emission measure. Table 1-4 gives an alphabetical listing of the programs that operate on and produce these files.

The BCSDA, BCSIX, FCSDA, FCSIX, ENG, and SPSUB files are referred to as reformatted files and are created by the REFORMAT program (§ 1.4), which copies XRP data from Exabyte tape to disk. The files contain the raw data (count rates) and associated detector and spacecraft attitude information for the two XRP instruments. These files are considered old format files in the sense that the software to read them is no longer supported. The naming convention of these files is BCSDAhhmm.doy, FCSDAhhmm.doy, etc., where:

hh  - start hour of data
mm  - start minute of data (approx)
doy - day of year of data

The BDA and FDA files are considered new format files and are created by the programs BOTON (§ 2.1.1) and FOTON (§ 2.2.1), respectively. The naming convention of these files is BDAyymm.hhmm and FDAyymmdd.hhmm where:

yy  - year of data
mm  - month of data
dd  - day of data
hh  - start hour of data
mm  - start minute of data (approx)

The BRR and FIS files are processed files that contain selected spectra (BRR) or images and spectra (FIS). These files are created from the BDA and FDA files by the MKBRR (§ 2.1.2) and MKFIS (§ 2.2.2) programs, respectively. The bulk of the IDL software described in this manual operates on these files. The FTE, SPC, and FIT files are summary files that contain physical parameters (such as temperature and emission measure) that have been derived from the FIS and BRR files. Figure 1-1 presents a flowchart of the relationship between these files and their associated programs.

1–4

1.4 GETTING STARTED

Table 1-3. XRP Data Files

DATA FILE  DESCRIPTION
BCSDA  Raw data count rates for the eight BCS channels.
BCSIX  Index file providing pointers to the data in the BCSDA file.
BDA  The BCSDA and BCSIX files combined.
BRR  Keyed-access file (VMS only) containing BCS spectra

that were selectively extracted from BDA files.

FCSDA  Raw data count rates for the eight FCS channels.
FCSIX  Index file providing pointers to the data in the FCSDA file.
FDA  The FCSDA and FCSIX files combined.
FIS  Unformatted file containing image and/or spectra extracted

from FDA files.

FIT  ASCII file containing various physical parameters

(e.g., T_{e}, EM, v_{turb}) derived from fits to BRR spectra.

FTE  IDL XDR saveset containing maps of flux, temperature, and

emission measure for selected images from FIS files.

ENG  Engineering file containing detector information needed for

analysis (e.g., FCS crystal address, detector status).

SPC  Keyed-access file consisting of model calcium and iron line

spectra fitted to selected spectra from BRR files.

SPSUB  Pointing file containing SMM spacecraft attitude information.

1.4 GETTING STARTED

The first step in analyzing XRP observations is to read the raw data stored on Exabyte tapes at the SDAC. There are 79 tapes each containing a month of data, with each day saved as a separate file on the tape. The REFORMAT procedure (§ 1.4.1) is used to read and copy specific data sets from these tapes to magnetic disk. Because the REFORMAT procedure can be extremely slow, it is recommended that you first examine the XRP data that has already been processed and archived in the Selected Data Archive (SDA) which resides on disk at the SDAC.

The SDA contains FIS and BDA files for approximately 400 FCS spectroscopic observations and over 700 BCS observations for which the count rate in the Ca XIX channel exceeded a threshold of 250 counts/sec (equivalent to a GOES mid-class C event, a few times 10^{−6} W m^{−2}). There is a good chance that FIS and BDA files pertaining to a strong flare (above C level) or to a crystal scan will be in the SDA.

To see whether processed XRP data already exist for a given date and start time (encoded into the file name as discussed in § 1.3), you can search the SDA by using the

1–5

Table 1-4. XRP Programs

PROGRAM  DESCRIPTION
BCS  A widget interface to BCS data and software.
BCSPRO  Creates a command file to execute MKBRR + CALBRR + SPCFIT
BOTON  Creates BDA files from BCSDA and BCSIX files.
CALBRR  Wavelength calibrates channel 1 and 4 spectra in BRR files.
FCS  A widget interface to FCS data and software.
FLUXCAL  Flux calibrates FCS detector count rates.
FOTON  Creates FDA files from FCSDA and FCSIX files.
FTEMAP  Computes flux, temperature, and emission measure maps from FCS

line ratios maps and creates FTE files.

LISTBRR  Lists the contents of a BRR file.
LISTBCS  Lists the flares in the BCS event catalog.
LISTFIS  Lists the contents of a FIS file.
MKBRR  Creates BRR files from BDA files.
MKFIS  Creates FIS files from FDA files.
PLOTBDA  Plots spectra and lightcurves from BDA files.
PLOTBRR  Plots spectra and lightcurves from BRR files.
PLOTFIS  Plots images and spectra from FIS files.
PLOTFIT  Plots theoretical profiles and fitted parameters from SPC and FIT files.
PLOTFTE  Plots temperature and emission measure maps saved in FTE saveset

files created by FTEMAP.

RDFIS  Extracts an image from a FIS file and returns it in a structure variable.
RUST  Reads and unpacks the image structure created by RDFIS.
SPCFIT  Fits theoretical profiles to channel 1 and 4 spectra in BRR files and

creates SPC and FIT files.

TEMCAL  Computes temperature and emission measure from FCS count rate

measurements.

VMS logicals (or UNIX environment variables) BCS DATA and FCS DATA, as discussed in Appendix A, or by using the IDL/widget programs BCS and FCS, as discussed in Chapter 4. If the relevant files exist, then you can skip the REFORMAT procedure and go directly to creating BRR files (§ 2.1.2).

1.4.1 REFORMAT

REFORMAT is an IDL procedure that invokes a command procedure to perform the

1–6 copying and reformatting of FCS and BCS data from Exabyte tape to magnetic disk. To run this procedure type:

IDL> REFORMAT

You will be prompted for a number of responses. (When available, default choices given between square brackets are selected by hitting return.)

First you will be asked if you require both FCS and BCS data:

* do you require FCS data [def=y]?
* do you require BCS data [def=y]?

Then you must load the Exabyte tape corresponding to the month containing the required data. You will be asked to enter the number corresponding to the tape drive in which the Exabyte is loaded:

* load tape and enter corresponding drive number from above (q to quit):  0

Then you will be asked to enter start and stop times in the format specified below. If the start and stop times have the same month and day, the information on year, month, and day need not be repeated, as shown in the example:

* enter start time to extract [yy/mm/dd, hhmm:ss.msec] 85/01/01, 0100
* enter end time to extract [yy/mm/dd, hhmm:ss.msec] 0200

The total time for a given interval must be less than two hours. Longer times must be broken into subintervals which are reformatted one at a time.

You will be given status messages as blocks are copied, and asked at the end whether you want to keep the old format files FCSDA, FCSIX, BCSDA, BCSIX, ENG, and SPSUB, for which the default response is ”n”. (Answer ”y” if you require FCS Sit & Stare data.) Recall that old format files have a different convention than new format files for designating the time incorporated into the filename, as discussed in § 1.3.

1–7 XRP USER’S GUIDE – 1. OVERVIEW

Table 1-5. XRP Analysis Quick Start

GOAL  METHOD
Instrument overview  See § 1.2 (XRP), § 1.2.1 (BCS), and § 1.2.2 (FCS).
Data file overview  See § 1.3 and Table 1-3.
To access data  For flares or FCS spectral scans, first check Selected

Data Archive (SDA) to see if data online: use BCS DATA and FCS DATA (see Appendix A) or IDL/widgets BCS and FCS (§§ 4.1 and 4.2)

If data not in SDA, use IDL> REFORMAT (§ 1.4.1) on Exabyte tape(s) to get BCS spectral (BDA) files and FCS image and spectral (FIS) files.

To examine BCS  Use widget interface IDL> LISTBCS (§ 4.3)

flare catalog

To convert old format  Use BOTON (§ 2.1.1) on BCSDA + BCSIX to make BDA
file to new format  file; use FOTON (§ 2.2.1) on FCSDA + FCSIX + ENG

to make FDA file.

To reduce BCS  Use MKBRR (§ 2.1.2 and Table 2-1) on BDA files
spectral data  to create BRR files of selected spectra, corrected for

crystal curvature, for desired integration times. Then use CALBRR (§ 2.1.4) to wavelength calibrate spectra.

Alternatively, use BCSPRO (§ 2.1.6) to run MKBRR and CALBRR as batch job.

To reduce FCS image  Use MKFIS (§ 2.2.2) to extract images and spectra
and spectral data  from FDA file into FIS file. (Also done automatically

in REFORMAT process (§ 1.4.1).

1–8

1.4 GETTING STARTED

Table 1-5. XRP Analysis Quick Start

GOAL  METHOD
To create FCS  Use RDFIS (§ 3.2.2) to read images from FIS files
image structure  and create data structure variable for other programs.
To read FCS  Use RUST (§ 3.2.3) to read and unpack image data
image structure  structure created by RDFIS for other programs.
To list contents  Use LISTBRR (§ 2.1.3) to list BCS spectra in BRR file;
of data files  use LISTFIS (§ 2.2.3) to list FCS modes, crystal address,

spacecraft pointing, etc. in FIS file.

To plot BCS spectra  Use IDL> PLOTBDA (§ 3.1.1) on BDA files,
and lightcurves  or use IDL> PLOTBRR (§ 3.1.2) on BRR files,

or use widget interface IDL> BCS (§ 4.1).

To fit BCS spectra  Use SPCFIT (§ 2.1.5) on BRR files, or use

BCSPRO (= MKBRR + CALBRR + SPCFIT) on BDA files (§§ 2.1.2 to 2.1.6).

To plot BCS fits or  Use PLOTFIT (§ 3.1.3) to plot results of BCS
time histories of  spectral analysis by SPCFIT.

plasma parameters

To plot FCS images  Use IDL> PLOTFIS (§ 3.2.1) on FIS files,
and spectra  or use widget interface IDL> FCS (section 4.2).
To get FCS fluxes  Use IDL> FLUXCAL (§ 3.2.4) to convert FCS count

rates to photon flux.

To get temperature  Use IDL> TEMCAL (§ 3.2.7).

and emission measure from FCS line ratios

1–9 XRP USER’S GUIDE – 1. OVERVIEW

Table 1-5. XRP Analysis Quick Start

GOAL  METHOD
To get fluxes and  Use IDL> FTEMAP (§ 3.2.5) on FIS file.

physical parameters from FCS maps

To plot fluxes and  Use IDL> PLOTFTE (§ 3.2.6) with FTE IDL save
physical parameters  files created by FTEMAP.

from FCS maps

1–10

2. FORTRAN DATA REDUCTION PROGRAMS

This chapter describes the XRP fortran programs that were listed in Table 1-4. The programs are described in the chronological order in which they are likely to be used. The fortran programs are used primarily for the conversion of one file type to another, or for the extraction of selected data products from files. In general, they are executed by typing a DCL symbol that is defined in the LOGIN.COM file for the XRP account.

2.1 BCS PROGRAMS

2.1.1 BOTON

BOTON creates a BDA file from BCSDA and BCSIX files. Although BOTON is run automatically during the REFORMAT procedure, it can be executed manually by typing:

$ BOTON filid

where ’filid’ is the hhmm.doy extension of the BCSDA and BCSIX files produced by REFORMAT. If the reformatted files are not in the current directory, then the full directory and filename must be entered on the command line. BOTON will prompt for these inputs if ’filid’ is not entered. Note that the BDA file id is different from that of the BCSDA file. The BDA file contains spectra (at the original observed time resolution) for all the available BCS channels. These spectra can be examined with the IDL program PLOTBDA (§ 3.1.1)

2.1.2 MKBRR

MKBRR creates BRR files from BDA files. The BRR files are keyed-access ISAM files that contain selected spectra that have been accumulated for a specified time and corrected for crystal curvature effects. These files are the starting point for the derivation of flare parameters (temperature, emission measure, velocity) from the BCS spectral data.

MKBRR can be run interactively or by using command line switches. To run interactively, type:

$ MKBRR

The following prompts will appear:

* Enter BDA File id or name [yymmdd.hhmm]

2–1

XRP USER’S GUIDE – 2. FORTRAN DATA REDUCTION PROGRAMS

In default mode :,
        -  Channels 1 & 4 are processed,
        -  20 sec is assumed for data gathering interval,
        -  Crystal curvature corrections applied.
* Use default mode ?  [def=y]

Answering YES (after entering the file name) will invoke the default mode. In this mode, MKBRR extracts spectra for channels 1 (Ca XVIII-XIX) and 4 (Fe XXII-XXV), and accumulates the data into approximately 20 s intervals. Curvature corrections are also applied. These corrections essentially straighten the spectra, and have been calibrated only for channels 1 and 4. Answering NO will allow you to override these defaults.

The non-interactive mode allows more control over the BRR output file. There are six switches available, which may be included in any order. An example of their usage is as follows:

$ MKBRR /fil:800629.1810/chn:1/int:15/sta:18,25/end:18,30/cnt:4000,1

In this example, channel 1 Ca XIX data in the BDA file with file id 800629.1810 will be accumulated into 15 s (or greater) intervals starting at 1825 UT and ending at 1830 UT. The accumulation interval for each spectrum will be increased until a 4000 total count level is reached in channel 1. The spectra within the BRR file can be examined by using the IDL program PLOTBRR (§ 3.1.2). In practice, you would use MKBRR to extract BCS channels 1 and/or 4 only. The remaining fortran BCS analysis programs that are described in this section do not operate on any of the other channels.

2.1.3 LISTBRR

LISTBRR lists contents of a BRR file. It is executed by typing:

$ LISTBRR filid

where ’filid’ is the BRR file id (which is inherited from the original BDA file). A sample listing is as follows:

Summary of BRR file:  SYS$DATA:[XRP.DATA]BRR850123.0657;12
Total number of spectra:    292   146   0   0 146   0   0   0   0
Chan      Mean time          sdgi    num     dw        w0     rate Corrected
1    7 26 28  23  1 85    65.280     5  3.02E-04  3.24E+00    64    1 1
1    7 27 15  23  1 85    30.720     7  3.11E-04  3.24E+00   141    1 1
1    7 27 45  23  1 85    19.200     9  3.01E-04  3.24E+00   221    1 1

2–2

2.1 BCS PROGRAMS

Table 2-1. MKBRR Switches

SWITCH  DESCRIPTION
/fil:  This switch specifies the file id of the BDA file. If present,

then MKBRR will ask no questions (appropriate for running in batch mode) and, by default, the crystal curvature corrections will be applied. If not present, then the /chn:, /int:, /sta:, and /end: switches will be ignored.

/chn:  Specifies which channel to process. If absent, then MKBRR extracts

channel 1 and 4 data. Can also specify multiple channels as /chn:1,4 (no blanks). This switch is ignored if the /fil: switch is absent.

/int:  Integration time (integer) in secs. The default is to accumulate

spectra with 20 s time resolution. This switch is ignored if the /fil: switch is absent.

/cnt:  Sets the (total) count level (integer) which must be accumulated.

The integration time will be the minimum specified with the /int: switch. If the specified count rate is not detected, then the integration time is increased until the desired count rate is reached. The format is /cnt:level,chan such as /cnt:1000,1 (no blanks allowed). If the channel number is omitted, then the lowest selected channel is used. If the /cnt: switch is supplied, then /int:0 will be used. In this case, the shortest integration time which supplies the desired total count rate in the specified channel will be used. If multiple channels are selected, then the same integration time will be used for the other channels. This switch is ignored if the /fil: switch is absent.

/sta:  The start time in hh,mm,ss,dd,mm,yy format, (from minutes onward

the quantities are optional). The omission of this switch will cause MKBRR to begin with the earliest available data.

/end:  The end time in hh,mm,ss,dd,mm,yy format. The omission of this

switch will cause MKBRR to process until the end of the BDA file.

2–3

1    7 28  9  23  1 85    15.360    11  3.02E-04  3.24E+00   279    1 1

Such a listing will appear for each channel processed by MKBRR. The listed parameters have the following definitions:

chan – the channel number.

mean time – the mean time of the accumulated interval.

sdgi – the actual accumulation time of the spectrum.

num – the spectrum number.

dw – the nominal wavelength dispersion (Å per bin).

wo – the nominal wavelength of the first detector bin (number 0).

rate – the total accumulated count rate (summed over wavelength bin).

2.1.4 CALBRR

CALBRR wavelength calibrates the BCS channel 1 and/or channel 4 spectra contained in a BRR file. Because of the nature of a Bragg crystal spectrometer, the relationship between detector bin and wavelength scale is not absolute, and depends upon the relative position of the emitting source within the spectrometer field of view in the direction of dispersion. CALBRR calibrates this scale within the rest frame of the observer by fitting key lines within the spectra, and referencing their centroids to known laboratory wavelengths. CALBRR is invoked by typing:

$ CALBRR filid [/vel] or [/novel]

where ’filid’ is the usual file id of the BRR file to be processed. The /vel switch will implement the fitting of a secondary blueshifted component to the Ca XIX and Fe XXV w resonance lines in channels 1 and 4, respectively. By default, this switch is on. In cases where a blueshifted component is unlikely to be pronounced (such as in a limb flare), it is recommended that blueshift fitting be turned off by using the /novel switch. CALBRR automatically updates the wavelength scale of individual spectra in the BRR file. If ’filid’ is not entered, then CALBRR will run interactively and prompt for assorted inputs. The results of CALBRR are written in the summary ASCII file CALyymmdd.hhmm, which inherits the file id of the BRR file.

2–4

2.1 BCS PROGRAMS

2.1.5 SPCFIT

SPCFIT fits theoretical profiles to BCS channel 1 calcium and/or channel 4 iron spectra contained in a BRR file. The electron temperature, emission measure, nonthermal broadening, and line-of-sight upflow velocity of the soft X-ray source are determined from these fits. As with MKBRR, this program has several control switches. An example of its usage is as follows:

$ SPCFIT /fil:800628.1810 /chn:1 /vel:3

The /fil: and /chn: switches refer, respectively, to the BRR file id and the channel number to be fit. It is important that the spectra for the requested channel be extracted first by MKBRR and wavelength calibrated by CALBRR before being processed by SPCFIT. Note that SPCFIT (like CALBRR) will process only channels 1 and/or 4. In addition, SPCFIT will fit only spectra with sufficiently good statistics. Hence, the program is very likely to skip spectra observed very early during the flare impulsive phase or late during the decay phase.

The /vel switch is an optional input that controls how fitting of a secondary blueshifted component will be handled. CALBRR will have already made a first approximation at fitting this component if the /vel switch was used. A detailed description of the velocity model used by SPCFIT is given in Fludra et al. (1989, Ap.J., 344, 991). Basically, the model assumes that the doppler broadening width of the secondary component is proportional to its blueshift velocity from the primary w resonance line of Ca XIX (or Fe XXV). The following values can be entered for this switch:

0 ⇒ do not fit a blueshifted component. This is the stationary model.

1 ⇒ use the blueshift results from CALBRR as final, and do not iterate further.

2 ⇒ use the blueshift results from CALBRR. Iterate further on the intensity of the blueshifted component, but keep it’s velocity fixed.

3 ⇒ use the blueshift velocity and intensity from CALBRR as first guesses and iterate further. This is the default option.

The outputs of SPCFIT are written to two files that inherit the file id of the BRR (and CAL) file:

FITyymmdd.hhmm is an ASCII file that contains the fitted parameters (temperature, emission measure, doppler broadening, and blueshift) derived from the theoretical profiles fitted to the Ca XIX or Fe XXV spectra. These parameters can be examined by using the IDL program PLOTFIT (§ 3.1.3).

SPCyymmdd.hhmm is a keyed-access isam file that contains the final synthesized theory spectra. These spectra can be examined also by using PLOTFIT.

2–5 2.1.6 BCSPRO

BCSPRO facilitates the task of fitting BCS channel 1 and 4 spectra in BDA files by creating a command file to run MKBRR, CALBRR, and SPCFIT in batch mode. It can be run non-interactively by typing:

$ BCSPRO filid int

where ’filid’ is the file id of the input BDA file, and ’int’ is the integration time in seconds. The default integration time is 20 s, which is optimum for producing spectra of sufficiently high signal to noise to allow good quality fits of theoretical models. BCSPRO will then submit a batch job to run the above three programs in succession. The name of the batch command file is: BCSPROhhmm.dmp, where hhmm is the file extension of the input file id.

If the file id is omitted, then the program will run interactively and the following prompts will appear:

*****  XRP BCSPRO PROGRAM  V2.1  Mar 1990        *****
There are a possiblility of 3 operations performed:
1) MKBRR         - Write BRR file (read BDA file)
2) CALBRR        - Calculate DW,W0, write CAL file
3) SPCFIT        - Fit Te,Td,EM     write FIT file
Enter 1 or 1,3 for:  1+2+3
2 or 2,3 for:  2+3
1,1      for:  1, etc.
[def=1,3]:

At this point, you can control which programs to run by entering the appropriate number. For example, entering 1 will initiate all three programs in succession. You will then be asked the following series of questions:

* Enter the BDA file id or filename:
* Enter the integration time (sec) [def=20]:
* Change the start or stop times ?  [def=N]:
The command file = BCSPROhhmm.dmp
The submit instruction looks like :
$ SUBMIT/NOPRINT/ID/NOTIFY/NOLOG/RESTART BCSPROhhmm.DMP
* Submit BCSPROhhmm.dmp file as a batch job?  [def = y]:

2.2 FCS PROGRAMS

2–6 Accordingly, you enter the BDA file id, the integration time, and whether or not you wish to change the start and end times for processing. By default, BCSPRO will adopt the start and end times of the data in the BDA file. The final question asks whether you wish to submit the subsequent program execution as a batch job. For both the interactive and non-interactive modes, the completion of the batch job will be signalled by an e-mail message sent to your login account.

2.2 FCS PROGRAMS

2.2.1 FOTON

FOTON creates an FDA file by combining the FCS count and index data in FCSDA and FCSIX files, together with the engineering ENG file. It is run automatically at the end of the reformat process. It can be also run manually by typing:

$ FOTON filid

where ’filid’ is the hhmm.doy extension of the FCSDA and FCSIX files. If the reformatted files are not in the current directory, then the full directory and filename must be entered on the command line. FOTON will prompt for these inputs if ’filid’ is not entered. It is very important that the ENG file exist for FOTON to create a complete and correct FDA file. Although FOTON will create an FDA file without this file, the subsequent analysis software may fail if the engineering data are missing from the FDA file. Note that the FDA file id is different from that of the input FCSDA file.

2.2.2 MKFIS

MKFIS extracts all available images and spectra from an FDA file and copies them to a FIS file. It is run by typing:

$ MKFIS filid

where ’filid’ is the yymmdd.hhmm extension of the FDA file. If the FDA file is not in the current directory, then the full directory and filename must be entered on the command line. MKFIS will prompt for these inputs if ’filid’ is not entered. Note that MKFIS may often not process incomplete image or spectral modes (such as modes interrupted by spacecraft night of South Atlantic Anomaly [SAA]). In addition to creating a FIS file, MKFIS will produce a log file: FISyymmdd E.hhmm. The latter file can usually be ignored. The data in the FIS file can be examined by using the IDL program PLOTFIS (§ 3.2.1).

2–7 2.2.3 LISTFIS

LISTFIS lists the contents of a FIS file. The program does not accept command line parameters. Upon typing LISTFIS, you will be asked whether you would like the output information sent to a file. The default is NO. You will then be asked to enter 1 (for a brief listing), or 2 (for a full listing). A brief listing is recommended over a full listing. The program will then prompt for the file name. You must enter the full directory specification of the file if it is not in the current directory. A sample screen output is shown below.

Data    Time    Date   Mode    #Yx#Z(dY)   St.  Add.    Exp.              Mode ID
Set                                       Add  Step (DGI) Pts.    Reg.
1  14:45:50  14/ 7/86  RAST 16x16( 3)   6353   0     4    1  1 182 1.0.24.0
2  14:50:17  14/ 7/86  RAST  5x 5( 1)   6353   0     4    1  1   2 1.0.24.0
3  14:51:41  14/ 7/86  SS    1x 1( 0)    528   3     1 3325  1   0 3.0.28.1
4  15:06:01  14/ 7/86  SS    1x 1( 0)    528   3     1 3325  1   0 3.0.28.1
Data         Initial    Spacecraft       #Samp #Bad  %
Set (c'ont)  Y    Z   Pitch  Yaw  Roll
1         -23   23  -82 -970     0.0  256   0 100.0
2           2   -5  -82 -970     0.0   25   0 100.0
3           3   -7  -82 -970     0.0 3325   6  99.8
4          -7   -7  -81 -970     0.0 3325   1 100.0

The listed information includes: the date, time, and type of FCS mode (e.g., RASTer or SpectroScopic), the mode id, the spacecraft boresite pointing (pitch and yaw), the number of data samples, the integration time per sample (in units of .256 s [DGI]), and the percentage of good quality data in the mode. Since the width of the screen output exceeds 80 columns, it is recommended that the screen width be widened prior to executing LISTFIS by using the (DCL) SET TERM/WIDTH command.

2–8

3. IDL DATA ANALYSIS PROGRAMS

This chapter describes the IDL (version 2) programs that were listed in Table 1-4.

3.1 BCS PROGRAMS

3.1.1 PLOTBDA

PLOTBDA plots BCS lightcurves and/or spectra contained in BDA files created by BOTON. The program will first prompt for the BDA filename and directory location. If you can’t remember the full BDA file name, you can use wild characters (e.g. BDA*.*) and a menu of all the available BDA files on the current (default) disk will be listed for you.

After selecting the file, you will be asked to enter the channel numbers to extract. Because of IDL memory limitations, it is unwise to request more than three channels. Typically, you would enter 1,4,7 to read the Ca XIX, and the Fe XXV low and high resolution channel data (§ 1.2.1 Table 1-1), respectively. You will then be asked for the maximum accumulation time over which to sum the data. The default is 10 s, which means that the BCS data in the selected channels will be summed until the total integration time per spectrum is ≥ 10 s. Note that, because the actual BCS integration times are usually non-integer (e.g. 3.6 s around the flare peak, and 7.2 s during the decay), the final accumulation time will rarely be exactly equal to the requested accumulation time.

After reading and accumulating the requested channel data, PLOTBDA will ask you to enter a channel number to plot. This question will be skipped if you initially extracted only one channel. A lightcurve of the selected channel will then appear. You will then be asked whether you wish to plot spectra. Answering YES (or Y) will produce a vertical cursor (ignore the horizontal cursor). You will be asked to mark the start and end times (on the lightcurve plot) during which you would like to extract and accumulate spectra. Hitting any key will automatically select the spectrum nearest the time where the vertical cursor is located. Hitting a key once, then moving the cursor to another position on the lightcurve, and then hitting a key again will cause PLOTBDA to select all spectra in between the start and end cursor positions and plot an average of the selected spectra. Of course, hitting a key twice without moving the cursor will cause PLOTBDA to plot a single spectrum nearest the cursor position. PLOTBDA will ask next whether you wish to make a hardcopy of the plotted lightcurve and/or spectrum. Answering YES (or Y) will generate a Postscript plot file (IDL.PS) that will be printed on the available output device. Finally, PLOTBDA will ask whether you wish to repeat the whole plot process.

PLOTBDA has several optional command line arguments and keyword parameters that provide access to the plot arrays and more control over the plot. (N.B. although most command line arguments are optional, they must be entered in the correct order. Keywords can be entered in any order).

XRP USER’S GUIDE – 3. IDL DATA ANALYSIS PROGRAMS

3–1 Calling Sequence:

PLOTBDA, T, Y, W, Z, /LOG, /EBAR, BIN=BIN

\underline{Outputs:}

T – the time array (in seconds since the start of day) for the plotted lightcurve.

Y – the count rate array for the plotted lightcurve.

W – the wavelength (Å) array for the spectrum selected using the cursor.

Z – the corresponding spectrum array (counts per sec per bin).

\underline{Keywords:}

LOG – plot lightcurve on a log_{10} scale.

EBAR – overplot uncertainties on the lightcurve.

BIN – a value by which to rebin the spectrum (e.g., bin=2 to double bin).

3.1.2 PLOTBRR

PLOTBRR plots BCS lightcurves and/or spectra contained in BRR files created by MKBRR. The program is analogous to PLOTBDA except that you will not be asked to enter the channels to extract nor the accumulation time. The latter selections were made in MKBRR. The program will first prompt for the BRR filename and directory location. After reading the file, it will then list the available channels, their associated ions (usually Ca XIX and Fe XXV), and the total number of spectra in each channel. You will then be asked to select a channel to plot.

PLOTBRR will first plot the lightcurve for the selected channel. It will then ask whether you wish to plot spectra. From this point on, the program will proceed exactly as PLOTBDA. In addition, PLOTBRR has the same optional command line arguments and keyword parameters as PLOTBDA.

Calling Sequence:

PLOTBRR, T, Y, W, Z, /LOG, /EBAR, BIN=BIN

3–2 3.1.3 PLOTFIT

PLOTFIT plots the results of the BCS analysis program SPCFIT. In particular, it will read the FIT and SPC files created by SPCFIT and provide time history plots of the electron temperature, emission measure, nonthermal broadening, and upflow velocity deduced from fits of theoretical profiles to the BCS Ca XIX (Ch 1) and Fe XXV (Ch 4) detectors. PLOTFIT commences with the following menu of available items to plot:

* enter:
1 :  for electron temperature
2 :  for primary component emission measure
3 :  for primary component nonthermal broadening
4 :  for secondary component blueshift velocity
5 :  for secondary/primary component emission measure ratio
---->

After you have entered the item number, you will be prompted for the name of the FIT file and it’s directory location. After reading the selected FIT file, PLOTFIT will print the start and end times of the file. The default action is to plot the time history of the selected parameter between these start and end times. You can override these defaults by entering your own start and end times explicitly in the format: hhmm:ss.msec, where ’hhmm’ is the hour and minute (e.g. 0750), and ’ss.msec’ is the second and millisecond (e.g. 23.123). The latter two time elements are optional. You will then be asked to enter the channel number. The default is channel 1. If you enter channel 4 and you did not process channel 4 data with SPCFIT, then you will be later asked to re-enter the appropriate channel number.

After the selected time plot appears, you will be asked whether you wish to examine the fitted spectra that were computed by SPCFIT during the derivation of the fitted parameters. Answering YES (or Y) will invoke a cursor that you can use to mark the time on the plot when you wish to view the fitted BCS spectrum. PLOTFIT will read the observed and fitted spectra nearest the time of the cursor from the BRR and SPC files, respectively, associated with the FIT file. The BRR and SPC files must be in the same directory as the FIT file for this feature to work. A plot of the observed BCS spectrum with the corresponding fitted spectrum superposed will appear. The final two questions asked by PLOTFIT are whether you desire a hardcopy of the screen plots that you have generated, and whether you wish to repeat the program.

3.2 FCS PROGRAMS

3.2.1 PLOTFIS

PLOTFIS plots images and/or spectra from FIS files created by the program MKFIS. The program will first prompt you to enter I or S according to whether you to wish to plot images or spectra. The default is to plot images. You will then be asked to enter the FIS

3–3 Calling Sequence:

PLOTFIT, T, Y, E, W, Z, ZF, /LOG

\underline{Outputs:}

T – the time array (in seconds since the start of day) for the plotted lightcurve.

Y – the selected fitted parameter.

E – the uncertainty of the fitted parameter.

W – the wavelength array for the spectrum selected using the cursor.

Z – the observed spectrum array nearest the time of the cursor. ZF – the fitted spectrum array nearest the time of the cursor.

\underline{Keywords:}

LOG – plot the fitted parameter on a log_{10} scale.

file name and it’s directory location. If you selected images, then PLOTFIS will read all the image modes from the selected FIS file and present a menu of the times of each mode. You can choose a time by using a mouse in X-windows, or entering the number of the mode on a regular terminal. You will then be presented with a menu of available channels for the selected mode time. PLOTFIS will plot a color image of the selected channel ion data. You will then be asked whether you wish to make a hard copy plot, and whether you wish to repeat the program. It is not necessary to read the FIS file again if you wish to plot a different image – all the available images are saved in memory after the initial read. However, you must read the file again if you wish to plot spectra.

If you selected spectra, then (after entering the FIS file name) you will be presented with the following menu:

Display Data Blocks
Select ALL Data Blocks
Enter a List of Blocks to Extract
Enter a Range of Blocks to Extract
Enter a Type of Block to Extract
Quit

Because of memory limitations, it is recommended that you do not read all the FIS spectral modes at one time. Hence, you should begin by displaying all the available modes and then selecting a particular mode to plot. After making a mode selection, PLOTFIS will

3–4 list the available channels and proceed as described earlier for images. If you choose to repeat the program after making a hard copy (and you wish to plot a different spectral mode) then you must remember to read the FIS file again. Unlike images, all the available spectra in the FIS file are not saved in memory – only the most recent spectrum is saved.

Calling Sequence:

PLOTFIS, X, Y, IMG, /NOBKG, /CONT, BIN=BIN, /FLUX

\underline{Outputs:}

X – the wavelength array of the selected FCS spectrum.

Y – the count rate (per address bin) array of the selected FCS spectrum. IMG – the selected FCS image returned in a structure (see RDFIS).

\underline{Keywords:}

BIN – a value by which to rebin the spectrum or image data.

NOBKG – inhibit background subtraction of FCS image (default is to subtract).

CONT – plot image as a contour (default is to image). FLUX – flux calibrate spectrum [photons cm^{−2} s^{−1} Å^{−1}].

3.2.2 RDFIS

RDFIS reads images from FIS files and returns the data in a structure variable that can be used by other programs. The program prompts first for the name and directory location of the FIS file. It will then read all the image modes from the selected FIS file and present a menu of the times of each mode. You can choose a time by using a mouse in X-windows, or entering the number of the mode on a regular terminal. You will then be presented with a menu of available channels for the selected mode time. The selected image will be returned in a structure variable IMG which contains the following tags:

IMG.DATA  = a 1-d float array containing the image count rates
IMG.NX    = the number of columns in the image
IMG.NY    = the number of rows in the image
IMG.XP    = 1-d float array with the x-coordinates of the data pixels
IMG.YP    = 1-d float array with the y-coordinates of the data pixels

3–5

IMG.ID    = string name identifying the image
IMG.TIME  = string time of data in UT format (e.g.  87/11/12, 0300:12)
IMG.EXPS  = exposure time per pixel (secs)
IMG.PITCH = = spacecraft pitch (arcsecs)
IMG.YAW   = spacecraft yaw (arcsecs)
IMG.ROLL  = spacecraft roll (degrees clockwise from solar north)
IMG.ADD   = detector address or wavelength of image

The pitch and yaw variables are the pointing coordinates of the spacecraft boresite. Positive pitch and yaw are measured in arcsecs south and east, respectively, relative to the center of the solar disk. The cartesian coordinates of the FCS images are also in arcsecs relative to the solar origin, however their sense is reversed such that solar north and west are positive. To avoid structure size conflicts in IDL, it became necessary to store the 2-d images as a 1-d array.

Calling Sequence:

RDFIS, IMG, CHNUM, BACK, /NOBKG

\underline{Outputs:}

IMG – a structure with the selected FCS image.

CHNUM – the FCS channel number of the selected image.

Optional Outputs:

BACK – corresponding structure with image background data.

\underline{Keywords:}

NOBKG – inhibit background subtraction of FCS image (default is to subtract).

3.2.3 RUST

RUST reads and upacks the data and pixel coordinate arrays for an FCS image saved in a structure variable created by RDFIS. This is a useful procedure that provides easy access to the FCS data arrays.

3–6 Calling Sequence:

RUST, IMG, DATA, XP, YP, DX, DY, XC, YC

\underline{Inputs:}

IMG – structure created by RDFIS.

\underline{Outputs:}

DATA – 2-d data array (counts per sec).

XP – cartesian coordinates of image pixels in x-direction (+ W). YP – cartesian coordinates of image pixels in y-direction (+ N). DX – average spacing (arcsecs) between pixels in x-direction. DY – average spacing (arcsecs) between pixels in y-direction.

Optional Outputs:

XC – x-coordinate of center of image (relative to Sun center). YC – y-coordinate of center of image (relative to Sun center).

3.2.4 FLUXCAL

FLUXCAL converts FCS count rates to photon number flux (photons cm^{−2} s^{−1}). The procedure approximates the FCS line profile by a symmetric Voigt function and converts the input count rate (which normally corresponds to the intensity at the peak of the line) to a total intensity by integrating the area beneath the Voigt profile. To compute this integral, the program requires the total (thermal plus nonthermal) line doppler width. You will be prompted for this width in velocity units of km s^{−1}, or you can enter it via the keyword DOPP (see below). The default value is 100 km s^{−1}. A typical value is somewhere between 50 and 100 km s^{−1} in active regions, and above 200 km s^{−1} in flares. In some cases, you may already have available the total integrated line intensity (e.g., from actually fitting a line profile). Under these circumstances, it is not necessary to use the Voigt profile approximation. To inform the program of this case, simply use the TOTAL keyword and the input rate will be treated as a total (wavelength-integrated) intensity – the DOPP keyword will be ignored in this case. Note that the FCS profile often sits on a “pedestal” fluorescence background that is dependent upon peak intensities in other FCS

3–7 XRP USER’S GUIDE – 3. IDL DATA ANALYSIS PROGRAMS detectors. The pedestal correction is not applied in this program. Except in the case of a strong (high C-level) flare, this background is generally negligible.

The following is a sample session with FLUXCAL:

IDL> fluxcal
* enter FCS line counts per second:  100
* enter FCS channel no [1-7]:  1
* enter FCS XTAL address of observation [def=6563]:  6563
% FLUXCAL: count rate is assumed to be at line peak
* enter total line doppler width [def = 50 km/s]:  100
* line flux (ph cm-2 s-1) =   9.86e+04

In this example, FLUXCAL computes the FCS line flux for an observed count rate of 100 counts per sec in channel 1, with the crystal positioned at address 6563 (i.e. the home position). A doppler velocity of 50 km s ^{−1} is assumed for the line width.

Calling Sequence: FLUXCAL, RATE, CHAN, ADD, FLUX, DOPP=DOPP, /TOTAL \underline{Inputs:} RATE – FCS counts per sec at line peak (i.e., line center). CHAN – FCS channel (between 1 and 7) of the observed line. ADD – FCS crystal address (e.g., 6563 for the home position). \underline{Outputs:} FLUX – total line flux (photons cm^{−2} s^{−1}). \underline{Keywords:} DOPP – total line doppler width (thermal plus nonthermal) in km s^{−1}. TOTAL – informs FLUXCAL that RATE is a total count rate.

3–8 3.2.5 FTEMAP

FTEMAP computes isothermal temperature and column emission measure maps from pairs of FCS images. The program begins by prompting for the FIS file which contains the FCS images in different channels. It will read all the available images from the FIS file and list their corresponding times, ion identifications, and mode characteristics (e.g., number of pixels, pixel size, exposure time, spacecraft pointing, etc). To compute a temperature map, you must choose images observed in two different ions (e.g. Mg XI and O VIII) and as close as possible in time (preferably the same time). FTEMAP uses the FLUXCAL procedure to compute the flux for each pixel in the two ion maps, and derives a temperature (in MK) and column emission measure (∫ n_{e}^{2}dl cm^{−5}) by interpolating the ratios of these fluxes onto the ratio of corresponding ion emissivity functions obtained from the Mewe tabulations (see Mewe, Gronenschild, and van den Oord, 1985, Astron. Astrophys. Suppl. Ser., 62, 197). The column emission measure is computed from the total volume emission measure (deduced from the total line flux) divided by the FCS pixel area size.

After selecting an ion pair, the following menu will appear:

-------------------------------------------------------------
* DEFAULT MODE IS TO RUN ASSUMING:
-------------------------------------------------------------
1:  Meyer coronal abundances
2:  Nonthermal line doppler width = 50 km/s
3:  Range of temperatures searched = 2 - 10 MK
4:  Pixels with count rates below half sigma rejected
5:  Adjacent pixels not averaged
6:  Calculation results saved in XDR SAVE file:  FTEyymmdd.hhmm
--------------------------------------------------------------
* do you wish to modify any of these assumptions [def=n]?

These options have the following explanations:

(1) the Meyer (1985, Ap.J. Supp., 57, 173) coronal abundances will be used to rescale the Mewe emissivity-temperature functions for the selected ion pair. You can enter your own abundances (relative to atomic hydrogen) via this option.

(2) a nonthermal doppler velocity width of 50 km s^{−1} will be assumed to reconstruct the line profile when FLUXCAL computes the total line flux. You can enter a different velocity with this option. Note that FTEMAP will add (in quadrature) the nonthermal width to the thermal width (from the derived temperature) to produce a total line width.

(3) in some cases, the temperature solution obtained from line ratios can be multivalued. You can “window” single-temperature solutions by varying the temperature range with this option.

(4) in some cases, the ratio of two noisy low signal-to-noise pixels can result in a seem-

3–9 ingly valid temperature value. To correct for this effect, FTEMAP will compute the standard deviation of the count rates in the two selected maps and reject all data values that fall below half a sigma. You can change this cutoff threshhold via this option.

(5) by default, FTEMAP will not smooth or average ion maps. With this option, you can choose to rebin the FCS count rates in order to improve signal-to-noise at the expense of degraded spatial resolution.

(6) the temperature and column emission measure maps (together with the corresponding flux maps for the two ions used to derive them) will be saved as structures in a portable XDR IDL save file: FTEyymmdd.hhmm, where the file name is created from the file id of the original input FIS file. You can choose a different output file name with this option.

After FTEMAP has completed it’s calculations, it will print the following menu:

ENTER:
1) to QUIT FTEMAP
2) to REPEAT calculation
3) to PLOT ION1 flux map
4) to PLOT ION2 flux map
5) to PLOT TEMPERATURE map
6) to PLOT COLUMN EMISSION MEASURE map
7) to SAVE results in FTExxxxxx.xxxx
8) to HARD COPY latest map

The required responses to these choices are obvious. Note that, if no valid temperatures are found for any of the pixels in the selected ion pair then options 5–8 will not appear.

Calling Sequence:

FTEMAP, TEMP, EMISS, FLUX1, FLUX2

Optional Outputs:

TEMP – temperature (10^{6} K) array.

EMISS – column emission measure (cm^{−5}) array.

FLUX1 – flux (photons cm^{−2} s^{−1}) array for the first selected ion. FLUX2 – flux (photons cm^{−2} s^{−1}) array for the second selected ion.

3–10 3.2.6 PLOTFTE

PLOTFTE plots maps of temperature, emission measure, and fluxes saved in FTE saveset files created by FTEMAP. The program commences by asking for the name and directory location of the FTE file. It restores the contents of the file and presents the following (sample) menu:

* following images are available in:
FTE850123.0657
-----------------------------------------------------
1) TEMP (MK)
2) EM (10^28 CM-5)
3) Mg XI (PH CM-2 S-1)
4) O VIII (PH CM-2 S-1)
-----------------------------------------------------
* enter image number to plot [def = 1]:
* hardcopy [def=n]?
* another plot [def=n]?

In this example, you have the choice of plotting maps of temperature, emission measure, and Mg XI and O VIII fluxes that are saved in the file FTE850123.0657. After plotting the selected map, PLOTFTE will give you the options of making a hardcopy and returning to the above menu for a new plot. PLOTFTE has output parameters that are indentical to those of FTEMAP, with the following additional keywords.

Calling Sequence:

PLOTFTE, TEMP, EMISS, FLUX1, FLUX2, COLOR=COLOR, /CONT

\underline{Keywords:}

COLOR – color table value (e.g. 0 for B/W [def], 3 for red-temperature). CONT – plot maps as contours (user is prompted for contour level values).

3.2.7 TEMCAL

TEMCAL calculates temperature (isothermal) and emission measure from intensity ratios of two FCS lines. The following sample session illustrates the usage of this program.

3–11

IDL> temcal
* enter two FCS detector nos [def =  1, 3]
---> 1, 3
* enter corresponding line IDs from Mewe list [H for help; def =  752, 306]
---> 752, 306
* ion = O VIII
* central wavelength =  18.97
* O VIII MEYER abundance used = 2.47e-04
* ion = MG XI
* central wavelength =   9.17
* MG XI MEYER abundance used = 3.73e-05
* change ion abundances [def=n]?  n
* enter corresponding observed counts/sec:  100,200
* are these integrated line rates [def = n]?  n
* enter non-thermal Doppler velocity in km/s [def = 50]:  50
* enter range for temperature solution [def = 2, 10]:
% TEMCAL: -- temperature iterations in progress ---
-----------------------------------------
Te       Log10(EM)
(10^6 K)     (cm-3)
-----------------------------------------
4.9        47.4
-----------------------------------------
* do you wish to plot G(T) ratios [def=y]?  y
* enter temperature range (in MK) for plot [def=2,20]:  2,20
* hardcopy [def=n]?
* another calculation [def=n]?

In the above example, TEMCAL computes temperature and emission measure using an O VIII count rate of 100 in FCS channel 1, and a Mg XI count rate of 200 in FCS channel 3. The numbers 752 and 306 correspond to the identifications of the O VIII and Mg XI emissivity functions in the Mewe line tabulations. By default, TEMCAL will normalize these functions to the Meyer coronal abundances. You can override this default by answering YES (or Y) to the change ion abundances question. By default, TEMCAL assumes that the input count rates are peak line center values and will use FLUXCAL to compute an integrated line intensity. If the input rates are integrated values, then you can skip the integration step by answering YES (or Y) to the next question. If the rates are peak values, then TEMCAL needs the nonthermal Doppler width (km s^{−1}) in order to reconstruct the line profiles. Lastly, TEMCAL requires a temperature range within which to confine its calculation. Such a range is necessary in case of multiple solutions.

3–12

TEMCAL iterates the line flux ratios until the emission measures deduced from the individual line fluxes are identical. If a converged solution is not achieved, you will be given the option of varying the temperature range for the calculation. After printing the converged solution, TEMCAL provides options for plotting the ratio of the ion emissivity functions, producing a hard copy, and finally repeating the calculations.

Calling Sequence:

TEMCAL, TEMP, EMISS

Optional Outputs:

TEMP – temperature (10^{6} K).

EMISS – volume emission measure (cm^{−3}).

3–13

4. IDL/WIDGET PROGRAMS

This chapter describes the IDL/widget programs that enable reading and displaying of BCS and FCS data. These programs provide the user with a Windows graphical user interface (GUI) to many of the programs described previously.

4.1 BCS

The IDL/widget interface to BCS lightcurves and spectra is invoked by typing:

IDL> BCS

The program accepts BDA files as input and assumes that the logical BCS DATA points to the directory location of the BDA files. If this logical is not defined, then you will be asked initially to enter the directory location of the BDA files that you wish to plot. Figure 4-1 shows the main widget display produced by BCS. A listing of the BDA files in the current working directory appears under the listing:

SELECT FROM THE FOLLOWING FILES

You can select from this list by using the mouse (and hitting the leftmost button). By default, BCS will read channel 1 spectra, integrating with 10 s time resolution. These values can be changed at any time by clicking on the desired channels in the CHANNEL BUTTONS menu, and sliding the ACCUMULATION TIME slide bar to the desired integration time value (where 0 corresponds to the minimum available time resolution). Because of memory limitations, it is not recommended that you read more than two channels at a time.

The main widget display contains additional buttons which have the following functions:

• Spawn To OS – will temporarily suspend the main IDL widget program and spawn to the current operating system (VMS or UNIX).

• Change Directory – will permit the user to switch to another working directory, and also to select files from the Selected Data Archive (§ 1.4) by choosing a date.

• Help – will print some very brief help information.

• Replot Latest File – will replot the lightcurve from the latest file that has been read into memory.

• Quit – quit and exit BCS.

4–1

XRP USER’S GUIDE – 4. IDL/WIDGET PROGRAMS

Upon reading the selected BDA file, BCS will plot lightcurves for each of the selected channels. Recall that the lightcurves are derived by summing individual spectra over address bin. The lightcurve plot will appear in a separate widget window.

Figure 4-2 shows a sample BCS lightcurve window with the following application buttons:

• Log Scale – if set, then plot the lightcurve using a log_{10} scale.

• Oplot Errors – if set, then plot the lightcurve with square root uncertainties for each data point.

• Hard Copy – make a hardcopy of the current plot.

• Integrate Spectra – integrate BCS spectra during the time interval defined by the two most recent cursor positions on the lightcurve plot.

• Write Data – write the BCS count rate and universal time arrays to a data file (ASCII or IDL/XDR saveset).

• Zoom Lightcurve – zoom in on lightcurve during the time interval defined by the two most recent cursor positions on the lightcurve plot.

• Done – exit the lightcurve application and return to main calling widget.

After the lightcurve is plotted, the message:

USE CURSOR TO SELECT TIME OF SPECTRUM

will flash. At this point, you can view a BCS spectrum for a particular time by clicking the mouse button at the corresponding time position on the lightcurve. The selected spectrum will be plotted in a new widget window. Figure 4-3 shows a sample BCS spectrum window with the following application buttons:

• Double Bin – if set, then spectrum will be plotted with double binning (i.e. count rates in two adjacent address bins averaged into a single bin).

• Wavelength Axis – if set, then the spectrum will be plotted using a nominal wavelength (Å) axis (i.e., uncorrected for position of the source relative to the dispersion axis).

• Fit Options – opens a sub-menu of functions (Gaussian, Voigt) to fit to a zoomed portion of the spectrum. (This facility is still under development at time of writing).

• Write Data – write the BCS count rate and address/wavelength arrays to a data file (ASCII or IDL/XDR saveset).

• Zoom Spectrum – zoom in on a portion of spectrum between address/wavelength values defined by the two most recent cursor positions on the spectrum plot. Zooming must be performed prior to fitting.

4–2

4.2 FCS

• Done – exit the spectrum application and return to main calling widget.

4.2 FCS

The IDL/widget interface to FCS images and spectra is a direct analog of the BCS widget program. It is invoked by typing:

IDL> FCS

The program accepts FIS files as input and assumes that the logical FCS DATA points to the directory location of the FIS files. If this logical is not defined, then you will be asked initially to enter the directory location of the FIS files that you wish to plot. Figure 4-4 shows the main widget display produced by FCS. The main widget contains application buttons (Spawn To OS, Change Directory, Help, Quit) that have the same functions as in the BCS main widget program. A listing of the FIS files in the current working directory appears under the heading:

SELECT FROM THE FOLLOWING FILES

You can select from this list by using the mouse (and hitting the leftmost button).

The FCS instrument operated in two modes: imaging and spectral. You must first select between these two modes by clicking on the corresponding buttons (IMAGE and SPECTRA) that are adjacent to the FIS file selection window. The program will read the header of the selected FIS file and list the times of the selected mode, with imaging and spectral modes identified by the labels RAST and SS, respectively, under the heading:

SELECT FROM THESE FCS TIMES

(The labels: IS, MSS, and MSSR denote spectral modes corresponding to integral scans, multiple spectroscopic scans, and multiple spectroscopic scans in a raster, respectively). After you select a mode time, the program will list the channel information for the FCS detectors that were switched on during the time of the mode. This information will appear under the CHANNEL BUTTONS menu in the form of channel number and corresponding ion transition. Detectors that were off during the selected time are not selectable. Clicking on a valid channel will produce an image or spectrum window plot depending on the selected mode type.

Figure 4-5 shows a sample FCS image window. The image is plotted as a contour with a solar heliographic grid. The application buttons: Hard Copy, Write Data, and Done have the same functions as in the BCS program. The remaining buttons have the following definitions:

• Double Bin Image – if set, then image will be plotted with double binning (i.e. count rates in two adjacent pixels averaged into a single bin).

4–3 • Contour Image – if set, then plot the image as a contour. Otherwise, plot as color

image.

• Gang Images – if set, then divide the plot window into four quadrants and plot successive images in separate quadrants.

• Heliographic Grid – if set, then overplot a solar heliographic grid coordinate system.

• Log Scale Image – if set, then plot the image using log_{10} scaling.

• Overplot Images – if set, then successive images will be overplotted as contours on the first image.

• Subtract Background – if set, then subtract detector background from image.

• Tools – opens a submenu of tools to customize the color table; check and correct the spacecraft pointing. (These tools are still under development at the time of writing).

Figure 4-6 shows a sample FCS spectrum window. The application buttons in this window have the same functions as those described previously, with the following additional button:

• Flux Axis – plot spectrum in units of photons cm^{−2} s^{−1} Å^{−1} at the detector.

4.3 LISTBCS

LISTBCS provides a simple widget interface to the BCS catalog of flares in which the total count rate in the Ca XIX channel exceeded 18 counts per sec. The catalog is approximately 90% complete at the time of writing. The program is invoked by:

IDL> LISTBCS

Figure 4-7 shows a sample display produced by LISTBCS. The events are listed by start and stop time (as determined by Ca XIX count rates), as well as peak Ca XIX and Fe XXV count rates (and corresponding times). The application buttons in this display have the following definitions:

• Select Date – permits the user to choose the year, month, and day for which to search the BCS catalog.

• print Listing – print the listing on a hardcopy device.

• Quit – exit the program.

4–4