.ap .k .ps 60,75 .rm 75 .spr 0,0,2 .s .c;BCS Analysis Software .c;A Users Manual .s .c;R.D.Bentley, 18-Jul-1992 .c;Revised, 23-June-1993 .s 2 .c;This document is: $DIR__BCS__DOC:bcs__software.mem (under VMS) .c;##################$DIR__BCS__DOC/bcs__software.mem (under Unix) .s 2 The purpose of this document is to help the user access the BCS data using the various pieces of software that have been written. All the routines discussed use the reformatted database; IDL code assumed IDL version 2 (or greater). See the various documents by Mons Morrison for more information on the Yohkoh data archive, and consult the IDL Users Guide if you need to know more about the IDL language. .s This document only presents an outline of how to use the routines. Please use DOC__LIBRARY for further information on any particular routine. The Widget routine XDOC is particularly useful if you wish to search for information on a directory by directory basis (it also allows the user to examine the body of the procedure). Information on the calling arguments for a procedure or function can be determined with CHKARG. .i5;IDL> doc__library,'procedure__name' .i5;IDL> xdoc,'procedure__name' .i5;IDL> chkarg,'procedure__name' .s There are many additional BCS Reference Documents: .br;1)#Please refer to Dominic Zarro's AAAREADME.TXT file on the his ucon directory for information about the BSC routines (see ys:[ucon.soft.zarro] under VMS; /ys/ucon/soft/zarro/ under Unix). .br;2)#Please also refer to Dave Pike's document on GS routines for further information on this suite of routines (see $DIR__BCS__DOC). .br;3)#There are also several documents relating to the Fortran software (see $DIR__BCS__DOC). .s BEWARE: The software is constantly being updated, normally to provide enhanced performance. Occasionally the form of the call to a routines may have changed since the last release of this document. Some routines, particularly the very old ones, will only work correctly if called in the correct sequence. If you have difficulties check the calling procedure using the methods described above; if you still have problems, contact the author of the routine (NOT the author of this document!) .s .lm 2 Notes: .br;1) In this document, data and index arrays relating to the BDA file are called "index" and "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". .br;2) Often in procedure calls there are additional, optional paramaters 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 paramaters. .lm 0 .s 2 Section 1 details how to first access the BCS data. If the desire is to do detailed analysis work on the spectra, see sections 4 and 5; otherwise, use the routines in section 2 and 3. Several other useful BCS routines are summarized in section 6. .lm 0 .tp 10 .hl 1 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 apriori knowledge of its occurrence. .hl 2 Accessing a specific time interval If you are interested in a particular time interval, you have probably found out that there is an event from the BCS Light Curve Book, SA plots, PLOTY plots, GOES light curves, the event lists, the occurrence of a flare flag, from something seen in another instrument, or by looking us up in the Yellow Pages. In this case, the way to proceed is to use YODAT (formally called TEST__RD) or WBDA. .hl 3 Using YODAT .s 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 elsewhere, but we present a short summary. .s Basically, after starting YODAT within IDL .i5;IDL> .run yodat .br the user must select a data set (or sets). YODAT reads in the roadmap of the file and the user must then decide on which further selection procedure to use. The user can: .s i) Use the -44x options within YODAT to select a time interval using a BCS lightcurve 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 optionally the dp__sync array. .s ii) Exit YODAT in order to allow further selection of the data from the roadmap by constructing an "ss" vector and then getting the data by re-running YODAT with option -99. Again, YODAT will return the data and index arrays, and optionally the dp__sync array. This non-YODAT selection can be done in various ways, two are: .s .lm 2 a) use LIST__BDA to list the mode header information from the roadmap, then find the time interval and use the SS=SS option to produce the "SS" array that can be used with YODAT. .i5;IDL> list__bda,roadmap,start,nrec,ss=ss .s b) use SELECT__BDA to plot the roadmap light curve of a selected channel and select the time period of interest using the cursors. (Note: there is an option to read the data in with select__bda if required). .i5;IDL> .run select__bda .if qq .s .i -4;or##iii) use RMAP__TIM2REC to find the data sets that represent the beginning and end of the required time interval. The routine also creates the "SS" array used by YODAT. This route is quicker than SELECT__BDA or LIST__BDA, but less selective. .s .i -4;or##iv) use TIME__BDA to find the records that correspond to the start and end times of the interval of interest (this method is only recommended if you are already familiar with the dataset). .lm 0 .s If the desire is to further examine the data, the spectra can be read in by again running YODAT and use the -99 option (if the "SS" array was produced by SELECT__BDA, or LIST__BDA. .endif qq .lm 0 .lm 2 Notes: .br;a) BCS data file have the prefix "bda" - the rest of the name represents the start time of the file in the form "yymmdd.hhmm". .br;b) 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.*) .br;c) For most applications, the DP__SYNC data is not needed - it is however required for deadtime correction within GO__BSC. .lm 0 .hl 3 Using WBDA .s 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 interactive work with the data. If the data and index array have not already been read in using YODAT, it is recomended that a specific date be requested when running WBDA; a question concerning the required date is asked if WBDA is called without any input patameters. .i5;IDL> wbda,index,data .i5;IDL> wbda .hl 2 Browsing If you do not know exactly which time 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, or by producing a grey-scale image of spectra against time using GS. .hl 3 If you interested only in whether the BCS has seen anything, use BCS__24HR__PLOT. This works using either the BDA roadmaps or the Observing Logs and allows intervals to be selected by date (all files covering this data are then used). By default, channel 3 (Ca XIX) is plotted. Note: YODAT does NOT need to have been run before BCS__24HR__PLOT. .i5;IDL> bcs__24hr__plot,'dd-mmm-yy' [,chan=n] .i5;IDL> bcs__24hr__plot,'dd-mmm-yy',/obs [,chan=n] .if ww ** Allow bcs__24hr__plot to start at any time (hour/6-hour boundary?) .endif ww .hl 3 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. .i5;IDL> wbda .hl 3 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 (of 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 GS__) require that a time-period be selected first using the cursor routine, GS__CUR. .i5;IDL> .run gs .i5;IDL> .run gs__cur .s .br;Warning: The time axis on the GS greyscale plot may not be uniform!! .tp 10 .hl 1 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). .hl 2 Listing the BDA data If you are interested in what modes the BCS was executing, or what the countrate 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 countrate for channel 3 (Ca XIX) is given in the listing. .i5;IDL> list__bda,roadmap,start__rec,nrec [,chan=n, etc.] .i5;IDL> list__bda,index,start__rec,nrec [,chan=n, etc.] .hl 2 Spectra and Light-curve plot routines The light-curve and spectra from the BDA file may be displayed using WBDA. This is an interactive programme. .i5;IDL> wbda,index,data .if gg PLOTBDA. Thus is an interactive programme. .i5;IDL> .run plotbda (note: reads its own data) .endif gg .s Times can be selected by the cursor from a lightcurve and summations overplotted together with a lightcurve using BCS__SURVEY. .i5;IDL> bcs__survey,index,data [,chan=n [,/norm , etc]] .s Spectra summed over times selected by the cursor from the GS greyscale can be plotted with GS__SP .i5;IDL> .run gs__sp (4sp) .s 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 programme. (JTM new VG programme ???) .i5;IDL> .run vg (lc + 3sp) .i5;IDL> .run gs__vg (lc + 3sp) .s .hl 2 Light Curve (only) plot routines .i5;IDL> lcbda,index [,chans=[2,3,4],psym=psym,/log] .s .i5;IDL> plott__bda,index [,psym=psym] .i5;IDL> plott__bda,roadmap [,psym=psym] .hl 2 Single spectra plot routines .i5;IDL> plots__bda,index,data .hl 2 Multi-spectral plot routines Many spectra may be plotted on a page for the same channel with BCS__MULTI. .i5;IDL> bcs__multi,index,data [,chan=n, etc.] .s MPLOT allows the user to overplot many spectra - note that the BCS channel must have been extracted before calling this routine (e.g. with ext__bcschan - see section 6) .i5;IDL> mplot,xvals,chan__data,x__spacing,y__spacing .br;where chan__data#=#ext__bcschan(index,data,chan) .hl 2 2-d Plots of Spectra against Time The evolution of spectra against time can be displayed as a countour map by BCS__CONT, or as a greyscale image using DISP__BDA and GS. Note: The time axis of BCS__CONT is uniform, but that of DISP__BDA and GS are not. .i5;IDL> bcs__cont,index,data [,chan=n, range=[n1,n2], etc.] .s .i5;IDL> disp__bda,index,data .i5;IDL> .run gs .tp 6 .hl 2 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: these programmes will only run on an X-windows workstation. .i5;IDL> bcs__spmovie,index,data [,chan=n, etc.] .if gg .s .i5;IDL> .run gs__movie .hl 2 BCS 24Hr Plot (??) Plot of light curve of selected channel against time. .endif gg .hl 1 Preliminary Analysis/ Characterization using BDA data. There are many programmes that have not been fully tested or documented in this section: .hl 2 Overplotting spectra Overplot several spectra to show evolution of blue wing and line width. .i5;IDL> plot__ref,index,data,channel,dset__arr [, etc.] .s .i5;IDL> .run gad__blue__wing ??? .hl 2 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. .i5;IDL> .run gs__lc .hl 2 Temperature fit (by comparison) Compare measured spectra to set of spectra calculated at different temperatures. e.g. FE25__TEMP .hl 2 Jacques Dubau's programme (UNIX only??) # .hl 1 The BSD Analysis Software This sofware consists of three programmes that have been written in standard Fortran-77 to reduce the BCS data to fitted spectral parameters, together with a number of IDL routines. The Fortran programmes are MKBSD, BSDCAL and BSDFIT: .s .lm 6 .i -4;MKBSD extracts the spectra, applies instrument corrections and writes a new file, the BSD file. .i -4;BSDCAL fits selected lines in the spectra of the BSD file with Voigt profiles to produce a calibrated wavelength scale and writes this fit information to a BPC file. .i -4;BSDFIT fits a full theory spectra to the calibrated BSD data to give electron temperature, emission measure and plasma velocity; the BPC file provides the first guess for the fitting programme. The resulting fit parameters are written to a BFT file; the output theory spectra are written to the BTH file. .lm 0 .s These programmes can be run at the operating-system level using control files created either by using the setup sections of the programmes (in the case of MKBSD and BSDCAL), or with the editor. It should be noted, however, that the differences between VMS and ULTRIX complicate matters and the user may find it easier to run the programmes from IDL, using BCSPRO. To do this: .s .lm 2 i) Select a time interval by either: .lm 3 .br;a) Using the cursors in a -44x option in YODAT .br;b) Using SELECT__24HR__PLOT after running BCS__24HR__PLOT. .i5;IDL> .run select__24hr__plot .s .lm 2 ii) Execute BCSPRO to create the control files, and run the programmes. .i5;IDL> .run bcspro .s iii) It is sometimes necessary to edit the BPC file because the fits made by BSDCAL sometimes "fail": .lm 3 .br;a) Enter IDL and run ED__BPC to edit the required parts of the BPC file. .i5;IDL> .run ed__bpc .br;b) Again run the BSDFIT programme .s .lm 0 If more subtle variations of the code options are required, after creation the control files may be modified either using the setup sections of the programmes or by using the editor - the programmes should then be re-run. For more information on these programmes, see the various documents on $DIR__BCS__DOC. .s Under the different operating systems, different executables are needed. The BCSPRO routine takes care of this, but the user should be aware of the different names if running outside of IDL. The task names under the different operating systems are: .lm 2 .nf Name VMS UNIX MKBSD MKBSD $DIR__BCS__EXE/run__mkbsd__x BSDCAL BSDCAL $DIR__BCS__EXE/bsdcal__x BSDFIT BSDFIT $DIR__BCS__EXE/bsdfit__x .f Within UNIX: the "__x" should be replaced by "__u" under ULTRIX; "__s" under Sun/OS; and "__m" on the MIPS. .lm 0 .s IT SHOULD BE NOTED that the BSD files are not transfereable between machines and operating systems. Even though it would be possible (using IDL) to make them transferable, since the normal route for generating the files using the Fortran-77 code does not produce transferable files, it has been decided that the IDL code would follow the same restriction. The BSC files (see section 5), which are generated under IDL, are transferable. .s A BSD file may be read into IDL with GET__BSD. After modification a new file may be written with WR__BSD - see section 6. .hl 2 Displaying Data from the BSD file The light-curve from the BSD file may be plotted with LCBSD. .i5;IDL> lcbsd,filename .s The light-curve and spectra from the BSD file may be plotted by PLOTBSD. .i5;IDL> plotbsd,filename .hl 2 Displaying intermediate results (from BSDCAL) The fit results written to the BPC file by BSDCAL, can be over-plotted on the BSD spectra using PLOTBPC. .i5;IDL> plotbpc [,bpc__file,chan,option,start] .if ww .s The following plot intermediate VFIT file results .i5;IDL> plotit [,nchan,nopt,nspec] .s .i5;IDL> plotres [,nchan,nopt,nspec] .endif ww .hl 2 Displaying Fitted Spectral data (from BSDFIT) The theoretical spectra written to the BTH file by BSDFIT, can be over-plotted on the BSD spectra using PLOTBTH (was plotspc). This programme is interactive. .i5;IDL> plotbth,filename .tp 10 .hl 2 Displaying processed parameters (from BSDFIT) The parameters stored in the BFT file (created by BSDFIT), such as emission measure, electron temperature, may be plotted against time by PLOTBFT (was plotparams). .i5;IDL> plotbft,filename [,chan=n [,/plot__page, etc.]] .hl 1 The BSC Analysis Software. Since September 1992, Dominic Zarro has been working on a set of IDL routines that will replace much of the Fortran code described above; hopefully this will eliminate some of the difficulties encountered in the installation of the code on the various UNIX and VMS platforms. The routines are outlined here, but more information can be found in the AAAREADME file on Zarro's ucon directory (see ys:[ucon.soft.zarro] under VMS; /ys/ucon/soft/zarro/ under Unix). .s The routines work with structures that are compatable with all the other instrument structures in the Yohkoh database. An outline structure (the BSA structure) containing a specification of what data is to be extracted from the BDA file is first created by MKBSA, and then the BSC structure (and optionally a BSC file) is assembled by the routine MKBSC. .s First run YODAT to extract the index and data arrays from the BDA file for the selected time interval. A driver can then be used to run MKBSA and MKBSC, prompting the user for any information not supplied; this is called GO__BSC. Optionally a BSC file can be written. .i5;IDL> go__bsc,index,data,bsc__index,bsc__data,dp__sync=dp__sync .i5;IDL> go__bsc,index,data,dp__sync=dp__sync,/file .s .lm 2 The following routines are used in the assembly of the BSC file: .lm 4 .nf 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. .f .lm 0 .s Because the index and data records in a BSC file represent interleaved integrations for individual channels, if the user wishes to extract a single channel from the index structure they must use BSC__CHAN and GET__BSC. .i5;IDL> index = bsc__chan(bsc__index,chan,dset) .i5;IDL> data = get__bsc(bsc__index,bsc__data,chan=chan [,etc]) .s A BSC file may be read in with RD__BSC. After modification a new file may be written with SAV__BSC - see section 6. .s Currently, no fitting routines are available that directly use the BSC data. However, using BSC2BSD, it is possible to convert a BSC structure to a BSD structure (and optionally a BSD file); following this, any of the routines that normally work off the BSD file (including the programmes BSDCAL and BSDFIT) can be used. See section 4 for details on these routines. .i5;IDL> bsc2bsd,bsc__index,bsc__data,index=bsd__index,data=bsd__data .i5;IDL> bsc2bsd,bsc__index,bsc__data,filename=filename .hl 2 Listing the BSC file The contents of the BSC file or structure may be examined using LIST__BSC. .i5;IDL> list__bsc,bsc__index,chan .hl 2 Displaying data from the BSC file The lightcurve and spectra from the BSC file or structure may be interactively plotted with PLOT__BSC. .i5;IDL> plot__bsc,bsc__index,bsc__data .s A light curve of selected spectral regions can be produced with LC__BSC. .i5;IDL> lc__bsc,bsc__index,chan .s A psuedo-map of stacked BSC spectra can be produced with MAP__BSC. .i5;IDL> map__bsc,bsc__index,chan .hl 1 Other Useful BCS Routines There are a number of other, lower level, BCS routines. These are used within the programmes described above, but may be of use on their own: .s Data can be decompressed, or compressed using the BCS algorithm with the routines BCS__DECOMP and BCS__COMP: .i5;IDL> dd = bcs__decomp(data) .i5;IDL> dd = bcs__comp(data) .s The spectra for a single channel may be extracted from BDA data with EXT__BCSCHAN: .i5;IDL> dd = ext__bcschan(index,data,chan) .s The spectra may be normalized to the integration time, and fast queue data extracted with BCS__NORM: .i5;IDL> dd = bcs__norm(index,data) .s Thus a single channel can be extracted from the BDA data array, and then decompressed and normalized for integration time by the expression: .i5;IDL> dd = bcs__norm(index,bcs__decomp(ext__bcschan(index,data,channel))) .s The dead-time correction factors can be calculated with BCS__DTFAC: .i5;IDL> dd = bcs__dtfac(index,dp__sync,type,stime,etime) .s The calibration data (sensitivity, wavelength, etc.) for a channel may be read from the calibration files with BCS__BINCAL: .i5;IDL> dd = bcs__bincal(chans,modeid) .s The position of a source on the solar disk may be determined from the bin number of the resonance line with BCS__POINT. If the epoch is provided, this routine will also return the heliocentric latitude: .i5;IDL> dd = bcs__point(wbin [,chan=n [,date=date, etc.]]) .s .tp 3 A number of spectra may be summed with SUM__BDA: .i5;IDL> dd = sum__bda(index,data,modeid,nsum) .s There are also a number of "gt" functions that will extract the required parameter from either the INDEX or ROADMAP structures: .i5;IDL> dd = gt__total__cnts(index) .i5;IDL> dd = gt__blockid(index) .s 2 A BDA file may be read in using RD__BDA, and BDA data that has been modified may be written to disk a disk file with SAV__BDA: .i5;IDL> rd__bda,filnam,dset,index,data [,roadmap ,etc] .i5;IDL> sav__bda,filnam,index,data,qs,dp__sync .s 1 Data from the BSD file may be read in with GET__BSD (this call routines RD__BSD__HEADER, RD__BSD__RDMAP, and RD__BSD__DATA); BSD data that has been modified can be written to a disk file using WR__BSD: .i5;IDL> .run get__bsd .i5;IDL> wr__bsd,bsd__filnam,bsd__header,bsd__index,bsd__data .s 1 Similarly, a BSC file may be read in with RD__BSC, and BSC data that has been modified can be written to a disk file using SAV__BSC: .i5;IDL> rd__bsc,bsc__filnam,dset,bsc__index,bsc__data .i5;IDL> sav__bsc,bsc__filnam,bsc__index,bsc__data .if qqX .pg .hl 1 Housekeeping Software .hl 2 PHA software .hl 2 Microprocessor Memory Dump and Comparison When the microprocessor memory has been dumped, it is necessary to compare the dump with the ROM load. This can be done with the routine DUMP__COMPARE. This routine uses the DP__SYNC data to determine all the times in the file that a BCS memory dump was being performed (there should be two in the file - more if there was some kind of problem) and prompts the user to select which records are required. These records are then extracted from the BDA file (it is not necessary to re-run YODAT), and the dump is extracted from them. This can then be compared with a selected load file - the results of the comparison are printed to the screen. If a printout is required, the programme should be rerun, with the variable TTL set to a non-zero value, and afterwards printing this file using TEXTP. .hl 2 CPU Diagnostics .hl 2 Monitors of Status Change MEMCHK__TIMES, DETECTOR__SUMM .hl 2 Others .nf plot__bdaf plot__bda__dp print__bcs_qs .f .endif qqX