This chapter describes the software used to analyze TRACE data. Except for section 2.9, all the descriptions relate to IDL software.
All TRACE software is distributed as part of the SolarSoft (SSW) software tree which is mastered at NASA-GSFC. To analyse TRACE data, the gen/, trace/ and packages/binaries/ branches of the tree need to be installed; to use the ANA Browser, the packages/ana/ branch must also be installed. To use the TRACE catalog, and to apply some of the corrections in trace_prep, the TRACE branch of the SolarSoft DataBase (SSWDB) must also be installed. More details about installing SolarSoft are given in Appendix C.
Within SolarSoft, at the Unix shell level configure your software
environment for TRACE, or TRACE and other instruments by entering:
> setssw trace
or
> setssw trace sxt mdi
IDL is then started with the command
> sswidl
The User's Guide gives an outline of how to use the software to analyse TRACE data. For help on how to get additional information on the TRACE software, see Section 2.10. One-line description of useful routines are given in Appendix A.
The TRACE catalogs hold details of the times, wavelengths, pointing, etc. of all observations made by the TRACE instrument. Since the TRACE instrument data files are large and it is therefore difficult for many sites to hold a large number of them on-line, the catalog makes an excellent entry point into the TRACE data. There are several catalogs, all are held under $tdb: tcl files form the normal catalog; the tcs files are a short-form of the catalog; and tce are an engineering log. The catalog may be read and listed using the routines trace_cat and trace_list_index, thus:
IDL> trace_cat, start_time, end_time, catalog [,/short]
IDL> more, trace_list_index(catalog)
The catalog structure can be used to read in the index and data arrays (see the examples in Section 2.2.2) and plot lightcurves of the average intensity (see Section 2.3.4).
There is an archive of full-disk images taken by TRACE which is formed from mosaics of many spacecraft pointings (available if $tdb is installed). This can also provide an insight into what TRACE was observing. The image for a selected date (or the nearest image to that date) may be viewed with view_trace_mosaic:
IDL> view_trace_mosaic,date
The names of any reformatted TRACE files that are on-line at the installation you are using (between a start and end time) may be determined with the function trace_files:
IDL> more, trace_files(start_time, end_time)
Information relating the TRACE ephemeris can be read with rd_fdss, and listed using pr_fdss. The fdss files used by these routines are held under $tdb:
IDL> fdss_struct = rd_fdss(start_time, end_time, type)
IDL> pr_fdss, fdss_tsruct
or
IDL> pr_fdss, start_time, end_time, type
where the text string type can have the values: `durevt' (day, radiation belts (SAA and HLZ's), etc.), `grndtrk' (spacecraft ground track), `orbevt' (orbit nodes), `viewpd' (station-pass view of the spacecraft), and 'station' (station-pass id).
During each orbit, passages through the radiation belts produce EUV images with a large number of spikes in the data due to energetic particles. Also, each year TRACE is in its eclipse season for a few weeks around the winter solstice between November and February. The status of the spacecraft in relation to these items can be confirmed using the routine pr_fdss:
IDL> pr_fdss, start_time, end_time, 'durevt'
Any TRACE file (including .mxf files) may be read with the routine read_trace. If the file contains JPEG compressed data, the packages/binaries/ branch must be included in your SolarSoft installation (this contains the shared object binary trace_decode_idl.so).
Calling read_trace with only one output parameter will just do a fast read of the headers and map them into an IDL structure vector with the same TAGs/field names. The equivalence of the ``FITS FIELDS'' and IDL structure tags permits vectorized searching on instrument parameters without any string parsing normally associated with FITS files. The same logic applies to SXT, EIT, MDI, etc. when accessed via SolarSoft.
The following commands read the index records (and optionally the data) in the specified files - the ss parameter specifies which images are required; -1 means all images. Again, the trace_list_index can be used to list the index structure:
IDL> read_trace,files,-1,index
or
IDL> read_trace,files,ss,index,data
IDL> more, trace_list_index(index)
The routine trace_prep can also read images with a similar calling sequence.
If you have already extracted a catalog structure using trace_cat, this may be used to read in the index and data arrays using trace_cat2data with the following calls.
IDL> trace_cat2data,catalog,index [,data]
or
IDL> trace_cat2data,catalog,files,ss,/filedset
IDL> read_trace,files,ss,index,data
The TRACE images are large and there are a lot of them, so it is better to select a subset before attempting to read them in. The function trace_sswhere provides a filter to do this, allowing the user to select images through a widget interface. Thus:
IDL> read_trace,files,-1,index ; get all the index structures
IDL> ss = trace_sswhere(index) ; select wavalength, etc. of choice
IDL> read_trace,files,ss,index,data ; read in the desired data
For a given index or catalogue structure, the function trace_sswhere allows the following to be selected by the user:
trace_sswhere can be used to select a subset of images from a catalog structure before the data is read in:
IDL> trace_cat, start_time, end_time, catalog
IDL> ss = trace_sswhere(catalog)
IDL> trace_cat2data,catalog(ss),index,data
It may also be desirable to only read part of the the image since individual images can be quite large, and an array can take a lot of memory. The routine read_trace_fov allows the user to select a sub-frame within the first selected image before reading the data:
IDL> trace_cat, start_time, end_time, catalog
IDL> ss = trace_sswhere(catalog)
IDL> read_trace_fov,catalog,ss,index,data
read_trace_fov can also be called with just the files and ss arrays:
IDL> read_trace_fov,files,ss,index,data
Filtering can also be done at the IDL command level. For example, this three line segment reads NN file headers (subset of -1 implies all images), applies a filter for full resolution 171 Å images and then reads that data cube.
IDL> read_trace,files,-1,index ; read all HEADERS->structs
IDL> ss=where(index.wave_len eq '171' and index.naxis1 eq 1024) ;some FILTER
IDL> read_trace,files,ss,index,data ; read subset DATA (3D)
The routine struct_where is a more generalized filter that works on
index or catalog structures. The selection is made according to filters
supplied in a configuration file or string array. This method is
particularly useful when the same set of filters are always employed to
process data, e.g. when making a movie.
IDL> ss = struct_where(index, count, conf_file=conf_file)
or
IDL> ss = struct_where(index, count, test_array=test_array)
Where the contents of conf_file or test_array are of the form:
<TAG> <OPERARTOR> <VALUE>
For example, a configuration file might contain:
; you can include free-form comments using ';' delimiter NAXIS1 = 512,1024 ; Lists (comma delimited) IMG_MIN > 1. ; Single value (boolean) WAVE_LEN = 171,195,284 ; XCEN=600.~800. ; Range (tilde separated) IMG_AVG > 100 && IMG_MAX < 4096 ; Compound BooleanOr, the following test_array filter would select all TRACE images in 171 Å of 1024×1024 pixels:
IDL> filter = ['wave_len = 171','naxis1 = 1024'] IDL> ss = struct_where(index,count,test_array=filter)
If you need to select a series of images at a pre-defined cadence from an
index or catalog structure, then use grid_data. To select images at
a particular time, use tim2dset. For example:
IDL> ss = grid_data(index, min=5)
and
IDL> trace_cat,'31-may-98 12:00','31-may-98 14:00',cat
IDL> ss = tim2dset(cat,'31-may-98 13:08')
If you have a list of favourite images generated by the ANA Browser (section 2.9), this can be read into IDL using read_analist. The index and data arrays can then be read with read_trace.
IDL> read_analist,analist_filename,files,ss
IDL> read_trace,files,ss,index,data
The routine trace2x will also read a list produced by the ANA Browser (section 2.9) and return a scaled (windowed) array - see the file header for more information.
Image files created by ANA can be read into IDL using anafrd:
IDL> img = anafrd(ana_image_filename,head)
For qualitative work, there are a number of routines to try. Here we assume that the index and data arrays have already been read in, e.g. using read_trace. Since the TRACE index structure contains the SolarSoft standards for time and pointing references, you can use a lot of standard software including utplot, the mapping software, etc..
For single (2D) images, try the following:
IDL> sdata=trace_scale(index,data,/despike,/byte) ; "standard" scaling
IDL> wdef,im=sdata ; make a window the right size
IDL> trace_colors,index ; Load standard wave color table
IDL> tv,sdata
Here the function trace_scale is used to scale the TRACE image to the desired range, and trace_colors loads the standard TRACE color table. If the image is large, it may also be viewed with slide_image (the optional keyword inputs change the image display size):
IDL> slide_image,sdata [,xvis=400,yvis=400]
When whole (1024×1024 pixel) TRACE images are viewed, the effects of vignetting are evident - the cause of this is decribed in Section 3.2.3.
TRACE image cubes may be viewed with the generic viewer xstepper. This needs a data array, and optionally an information array. The generic IDL (structure to text array) translator get_infox is one way of producing the required info array. Sample calls may thus be:
IDL> xstepper, sdata, info
IDL> xstepper, sdata, get_infox(index,'naxis1,wave_len,',/fmt_tim)
The xstepper procedure can also be used to blink between two images. Just load the image pair when starting xstepper and adjust the frame rate as desired.
TRACE movies can also be made by other routines, including trace_uniq_movies and image2movie. To see examples of the Web of movies created with the software mentioned here, look at < http://trace.lmsal.com/last_movies/ > .
Lightcurves of a selected area of an image cube may be made using lcur_image:
IDL> lcur_image,index,data [,lcur]
To mark an arc on an image (e.g. to pick out a loop) and plot the intensity along the strip use plot_arc. The lightcurve of the arc may optionally be returned:
IDL> plot_arc, index, image, width [, xlcur=xlcur, lcur=lcur]
Time series of parameters may be plotted with utplot.
IDL> utplot,index,index.XXX ; time series of some SSW parameter
IDL> outplot,index,index.YYY ; overplot
IDL> evt_grid,index,ticklen=.1 ; overlay 'events' on existing utplot
The normalized lightcurve of the average counts in an image may be plotted using plot_trace:
IDL> plot_trace,index,wave='1600',nx=256
In this example, the average counts of the 1600 Å band from TRACE index (or catalog) structure is plotted (selecting the 256×256 pixel images). Counts in the .img_avg tag are used because the .img_max values are affected by particle-induced spikes in the data. The countrates are normalized for exposure time, after the CCD readout pedestal (section 3.2.2) has been subtracted. Note: The times listed in the index (and catalog) structures are the time the shutter closes (section 3.2.5). The times plotted by plot_trace are the mean time, i.e. the end time minus half the exposure time. By default, bad data is filtered from the plot.
The routine trace_prep is intended to guide the processing of TRACE data from raw to level 0 according to the order and algorithms defined by the TRACE PI Team. For those familiar with SolarSoft, it is similar in philosophy and interface to sxt_prep and eit_prep. A number of TRACE database files need to be installed under $tdb to run trace_prep - these include the dark current frame files (tdc) - see Appendix C for more information.
The trace_prep routine will work with both 2D and 3D data arrays. Assuming that the index and data records have already been read in, the call to trace_prep is:
IDL> trace_prep,index,data,outindex,outdata
[,/wave2point][,/unspike][,/destreak][,/deripple]
Examine the procedure header for the current status of trace_prep, or e-mail Richard Nightingale at Lockheed (ngale@lmsal.com). As of November 1999, trace_prep performs the following steps:
Optionally, the following corrections are applied if the appropriate keywords are used:
In the future, it is hoped that trace_prep will also:
The TRACE images are large and numerous and it may be necessary to work with only part of each image. Since some of the corrections are best performed on complete TRACE images, the extraction should be done after the corrections have been applied. There are four keyword parameters within trace_prep that allow the user to extract part of an image after it has been processed. These are: sllex and slley (which specify the coordinates of the subimage lower left corner), and subimgx and subimgy (which specify the number of pixels in the x and y axes). If the data are extracted in this way, the pointing and image tags in the index record are updated; the use of the /new_avg keyword is also recommended. An example of a call including these paramaters, and the keywords to correct the images would be:
IDL> trace_prep,index,data,outindex,outdata, $
/wave2point,/unspike,/destreak,/deripple, $
sllex=x0,slley=y0,subimgx=nx,subimgy=ny,/new_avg
The trace_prep routine can also be used to read directly from the raw FITS file and write calibrated data to a new file. Examine the procedure header for more information. Such files can be read in using read_trace.
Below are examples of calls for routines that are used in correcting and calibrating TRACE data. Most can be called as options in trace_prep and as such do not need to be called separately. Note: the advantage of calling the routines within trace_prep is that history records are included in the index structure to flag that the correction has been applied - this reduces the chance of applying the same correction more than once.
Spikes caused by high energy particles in the images (see 3.2.2 and 3.2.7) can be removed by tracedespike or trace_unspike. The routines trace_unspike and trace_destreak (together with trace_cleanjpg) can be used to remove spikes and streaks, and repair some of the damage caused when the spikes are compressed by the JPEG algorithm. If you have a series of images, the routine trace_unspike_time will removing spike-like features that only occur in one frame.
The herring-bone patterning on the CCD pedestal (see 3.2.2) can be removed with trace_knoise.
IDL> imout = tracedespike(tracedespike(image)) ;twice for faint fields
IDL> imout = tracedespike(image,statistics=6) ;correct > 6sigma outliers
IDL> imout = tracedespike(image,minimum=100,ri=3) ;low-quartile correrctions
IDL> imout = trace_unspike(image, /cleanjpg [, sens=sens])
IDL> imout = trace_destreak(image [, sens=sens, thresh=thresh])
IDL> clean_data = trace_unspike_time(index,data [,threshold=threshold])
IDL> imout = trace_knoise(image)
The routine trace_wave2point is used to correct the index structure for differences in the alignment of the TRACE images in different channels (see 3.2.3).
IDL> newindex = trace_wave2point(index [,/noapply] [,version=xx] )
Processed TRACE data may be stored in files in a number of formats. Remember that the data will no longer be compressed and the files will be much bigger than the raw files if all the frames are included. Use write_trace to write such files. The default is a FITS file, but GIF, TIFF and JPEG are also possible:
IDL> write_trace,index,data,outfile=filename
TRACE is often rastered about the disk to generate a mosaic image of all or part of the sun: full-disk mosaics are a standard synoptic campaign when EIT is not running, and TRACE began making Lyman Alpha observations of the solar limb in collaboration with UVCS in early 1999. An alternative to using the mosaic database is to generate the mosaics by hand with trace_build_mosaic. It is not necessary to have all the images from the mosaic on hand to generate a partial solar mosaic.
IDL> file = trace_files('05:00:00 16-JUN-1999', '05:30:00 16-JUN-1999')
IDL> read_trace, file, -1, i, /nodata
IDL> subs = where(i.obs_prog eq 'STD.smallmosaic', count)
IDL> read_trace, file, subs, i, d
IDL> for j=0, count-1 do begin & d[*,*,j]=trace_unspike(d[*,*,j],/cleanjpg)
IDL> trace_prep, i, d, iout, dout
IDL> trace_build_mosaic, iout, dout, mosaic
It is possible to overlay TRACE images with images from other sources using IDL Map Objects - this is a family of routines that was developed by Dominic Zarro. From the index and data arrays the routines create Map Objects which can be spatially scaled, differentially rotated, overlayed, plotted with the limb or a latitude and longitude grid. Note the sequence read_trace > index2map > plot_map used in the example below to create and plot map objects - a similar sequence can be used for many other instruments supported by SolarSoft. For the best source of information on what options are currently available, see the header of the routine plot_map.
Assuming that the index and data arrays have been read in, a Map Object of TRACE data may be created and plotted using index2map and plot_map:
IDL> index2map, index, data, tracemap ; make a map from scaled data
IDL> plot_map, tracemap, fov=10, grid=5 ; plot it, centered in 10 arcmin
; FOV , overlay 5" solar grid
Note that image center defined in the index (or catalog) structure represents the center of the TRACE White Light channel - this is the same in the FITS file header. Since the centers of EUV and UV channels are offset with respect to the white light image (see the Instrument Guide, Section 3.2.6), a correction must be applied before the images can be co-aligned. The correction can be made using trace_wave2point - this can be optionally applied when using trace_prep.
A useful routine to use with Map Objects is ssw_track_fov. This extracts a sub-field from the SSW-compliant (2D) image data given the time and image coordinates from a reference Map Object; alternatively, a desired reference time and set of heliocentric coordinates can be supplied as keywords. The interactive selection of coordinates is also possible:
IDL> ssw_track_fov, index, data, outindex, outdata, ref_map=ref_map
or
IDL> ssw_track_fov, index, data, outindex, outdata, helio=[LAT, LON], $
date_helio=ssw_std_time
or
IDL> ssw_track_fov, index, data, outindex, outdata, /interactive
The co-alignment of images from various sources can be improved by using
cross-correlation. There are a number of routine in the SSW tree to do
this, but one way is shown below using align_cube_correl:
IDL> mreadfits, files, index, data [, outsize=xxx] ; xxx= 256 or 512
IDL> [normalize data cube if possible - might try 'normalize_cube']
IDL> align_cube_correl, data, outdata [,reference=NN] ; CC alignment
Routines that use the TRACE data to determine plasma diagnostics are detailed below. See the Instrument Guide (Section 3.4) for more information on the techniques involved and the limitations of the data.
When TRACE is in or near its eclipse season, care should be taken when using data for diagnostic purposes because of the effects of atmospheric absorption - see Appendix B.4.
The response of the TRACE EUV channels with respect to temperature is given by trace_t_resp. To plot the response of a channel against temperature use:
IDL> temp=1.0e5+1.0e4*findgen(200) ; generate temperature vector
IDL> response=trace_t_resp('171ao',temp) ; calculate and plot response
IDL> plot,temp,response
The routine trace_dem characterizes the differential emission measure (DEM) along the line of sight by fitting a 3-parameter model. It uses linear techniques to solve what is normally considered an ill-posed inversion problem. The keyword paramater ``basis'' contains the name of the function that will supply the basic elements necssary of constructing the DEM curves - the default is trace_sbasis (see trace_dem_setup); trace_tbasis is another routine that can be used. The call for trace_dem is given below:
IDL> trace_dem, index, data, emc, Tavg [,basis=basis]
The routine trace_tmap produces maps of temperature and emission measure, given two or more TRACE EUV channels as input - it uses chi-squared minimization. The routine is computationally intensive and takes a lot of memory. Like trace_tmap, the routine trace_isothermal uses chi-squared minimization, but is less memory intensive. Neither method is particularly fast - trace_isothermal is extremely slow and its use is only recommended for small fields-of-view.
IDL> trace_tmap, index, data, tmap=tmap, em=em
or
IDL> trace_isothermal, index, data, tmap=tmap, em=em
The results of trace_tmap and trace_isothermal can be displayed using trace_disp_tem. This produces maps that visualize temperature and emission measure simultaneously by means of hue angle and lightness. The maps look best when viewed on a 24-bit display, although the output may also be written to the PostScript device. When using an 8-bit display, the /quantize keyword is required.
IDL> trace_disp_tem, tmap, em [,/legend] [,/quantize]
It is also possible to calculate the temperature and emission measure maps from a pair of of TRACE EUV images using the routine trace_teem. This is a filter-ratio method that is based on the assumption that a structure seen in the two wavelengths is i) isothermal, and ii) of a temperature that lies between the peak temperatures of the response functions of the two wavelength filters, T1 < T < T2; suitable pairs are 171 and 195 Å, and 195 and 284 Å. The trace_teem is faster than trace_isothermal because of its vectorization and because it only requires two wavelength images.
IDL> trace_teem,index1,data1,index2,data2,em,te
where index1 and data1 relate to the lower wavelength image, and index2
and data2 relate to the higher wavelength image. All data should be
prepared using trace_prep.
The routine civ_subtract can be used to generate a clean C IV image, given an input set of TRACE UV images at 1550 Å, 1600 Å and 1700 Å. Any pair of these channels will produce a result, but the quality is degraded if only two channels are used. The call for civ_subtract is:
IDL> civ_subtract, index, data, iout, dout
It is possible to browse TRACE data using ANA. The ANA utility was developed during the SMM era by Dick Shine and others. The Browser was written to assist the analysis of data from the SOUP instrument on Spacelab 2. A detailed description of the ANA Browser is given in the write-up by Dick Shine (shine@lmsal.com; Appendix D), but a few pointers are given here. At most stages, help can be obtained by hitting the ``Help'' button in a particular Browser window.
The ANA Browser is started at the Unix shell level by entering:
> browser
When writing a 3-D array, three separate arrays may be written to disk. The three files have default extensions of ``.cube'', ``.times'', and ``.notes'' - the filename is supplied by the user (the default is ``movie''). Timing information available from the TRACE hourly files (i.e. the time of each exposure) can be saved in the ``.times'' array; the ``.notes'' array is for optional extra comments. 3-D arrays may be written as either FITS or FZ files.
Arrays of 2-D images may be written in the same formats as single images. The filenames are created from a numbered list based on the file name template (using the ``#'' character) and range. For example, ``movie####.file'' with a range of 1-10 will write ten images with file names ``movie0001.file'' through ``movie0010.file''.
Note: There is a WYSIWYG file write option, but this works only for users running from Silicon Graphics machines.
An image cube created by ANA can be imported into IDL using the routines open_anacube, window_anacube, and close_anacube. After opening the cube with open_anacube, the desired sub-window of a reference image can be read using window_anacube; frames can be selected using an ss vector. Some selection before reading is recommended since the cubes are often quite large. More recently written cubes may have ``.times'' and ``.notes'' files associated with the ``.cube'' file - these contain timing and other information.
IDL> open_anacube,filename
IDL> cube = window_anacube(ref_no,/read [,ss=ss])
IDL> close_anacube
Within IDL, the routines doc_library, doc_library2, xdoc, sswloc and chkarg can provide imformation on the software - sswloc also works at the Unix shell level.
Within the ANA Browser, at most stages help can be obtained by hitting the ``Help'' button.
Appendix C gives information on installing SolarSoft.