GOES IDL Users Guide

D. M. Zarro (ADNET/GSFC) and K. Tolbert (Wyle/GSFC)

The following SSW IDL commands are useful for accessing and analyzing GOES lightcurve data. They use the IDL class goes to create a GOES lightcurve object.

Finding the GOES data

The goes object will automatically search across the network for GOES data files from the SDAC or YOHKOH GOES archives and download the files.

If the files are available locally (mounted via NFS or equivalent on your computer, or copied manually), you can speed things up by setting some environment variables so they can be read directly instead of copied. For the SDAC GOES files, set the environment variable GOES_FITS to the directory containing the GOES FITS files. For the YOHKOH GOES files, set SSWDB to the directory containing the ydb directory, and the SSW setup will take care of the rest.

The two archives primarily serve as backup for each other. The differences are -

The YOHKOH files contain cleaned data, while the SDAC files contain raw data, which is cleaned by default in the object
The YOHKOH files have time resolutions of 3 seconds, 1 minute, and 5 minutes, while the SDAC files have only 3 second resolution.
The YOHKOH files are usually more up-to-date, sometimes within an hour of the current time, while the SDAC files are usually at least a day behind.

How to access GOES data using the Graphical User Interface (GUI):

You can work with the GOES GUI and command line interface interchangeably. Use any of the following to start the GUI:

IDL> goes ;-- start the GOES GUI
IDL> goes, a ;-- start the GOES GUI and return GOES object reference
IDL> a->gui ;-- start GOES GUI with an existing GOES object

If you change any parameters from the command line, click the Refresh button in the GUI to reflect the new settings.

How to create a GOES object:

All of the commands below assume you have created a goes object:

IDL> a = ogoes()

All of the GOES parameters and their default values are listed below. To change options, set any of the parameters via the set command, or on the plot (or plotman or getdata) command itself. Any parameter you set will persist until changed explicitly. Use a->help to see current settings for all parameters, or a->get(/xxx) to see the current value of parameter xxx, e.g. print,a->get(/sdac).

And remember - any time you want to use the GUI with your existing object, just type a->gui. You can quit and restart the GUI any time with this object a.

How to plot a GOES lightcurve:

IDL> a->plot ;-- plot GOES lightcurve
IDL> a->plotman ;-- plot GOES lightcurve in interactive plot interface
IDL> a->plot,'1-jun-04' ;-- plot a different day
IDL> a->plotman, '1-jun-04', '5-jun-04' ;-- plot four days

Note: If you specify times in seconds rather than one of the fully qualified time formats, they will be interpreted as seconds since January 1,1958 (UTC or TAI), not 1979.

Example: To plot 18:00-19:00 on 22-mar-2002, 1-minute GOES data from the YOHKOH archive, preferably GOES10, with no GOES class level markings, you can do either of the following:

IDL> a->set, tstart='22-mar-2002 18:00', tend='22-mar-2002 19:00', $
   /yohkoh, sat='goes10', mode=1, showclass=0
IDL> a->plot

IDL> a->plot, tstart='22-mar-2002 18:00', tend='22-mar-2002 19:00', $
   /yohkoh, sat='goes10', mode=1, showclass=0

How to retrieve a GOES lightcurve:

IDL> d = a->getdata() ;-- retrieve 2 channels of GOES data
IDL> help,data FLOAT = Array[115087, 2]
IDL> low=a->getdata(/low) ;-- extract low channel only
IDL> high=a->getdata(/high) ;-- extract high channel only
IDL> times = a->getdata(/times) ;-- extract time array and UTBASE IDL> utbase = a->get(/utbase)
IDL> utplot,times,high,utbase ;-- plot high channel data
IDL> deri=deriv(times,high) ;-- take time derivative of high energy ; channel (for Neupert Effect lovers)

NOTE: The data extracted will be cleaned and/or background-subtracted if those options are set.

See below for how to retrieve all quantities in a structure with one call.

How to subtract background for GOES:

Any number of background time intervals can be selected. The background for each channel is computed by fitting the selected function to every flux value in all of the background time intervals.

IDL> a->set, btimes= [ ['22-Mar-2002 18:12:54', '22-Mar-2002 18:14:36'], $
    ['22-Mar-2002 18:40:57', '22-Mar-2002 18:42:06'] ]

or set different background time intervals for each channel using b0times, b1times (btimes takes priority so disable btimes first):

IDL> a->set, btimes=0
IDL> a->set, b0times= [ ['22-Mar-2002 18:12:54', '22-Mar-2002 18:14:36'], $
    ['22-Mar-2002 18:40:57', '22-Mar-2002 18:42:06'] ]
IDL> a->set, b1times=  ['22-Mar-2002 18:14', '22-Mar-2002 18:15']

IDL> a->set,bfunc='exp'      ;-- choices are 0poly,1poly,2poly,3poly, or exp

IDL> a->set, /bsub

IDL> a->plot, /bk_overlay    ;-- plot two channels and background for two channels

Any data you retrieve or plot after setting valid btimes intervals, and setting bsub to 1, will have the background in each channel subtracted. To stop subtracting background, set bsub to 0 or set btimes to 0.

IDL> a->set, bsub=0          ;-- don't subtract background

Even if you are working from the command line, you can use the PLOTMAN interface to select background intervals graphically by typing:

IDL> a->select_background    ;-- use graphical interface for selecting background.
                             ;   Use /ch0 or /ch1 for selecting b0,b1times.

IDL> ptim, a->get(/btimes)   ;-- display background time intervals in ASCII format.

You can also set the background data manually for either channel using the b0user, b1user parameters. If either of these is set, it overrides the background computed from the background time interval.

IDL> a->set, b0user = 1.4e-7  ;--  can be scalar or vector.  If vector, it's interpolated 
                              ;    to the # data points in the selected time interval

How to extract temperature, emission measure, and energy loss rate for GOES:

IDL> temp = a->getdata(/temperature)

IDL> emis = a->getdata(/emission)

IDL> lrad = a->getdata(/lrad)              ;-- get total radiative energy loss rate

IDL> lx = a->getdata(/lx)                  ;-- get X-ray energy loss rate

IDL> lrad = a->getdata(/lrad, /integrate)  ;-- cumulative sum of lrad

IDL> a->set,abund='Coronal'                ;-- choose spectral model
                                           ;   choices are 'Coronal', 'Photospheric', 'Meyer'

IDL> a->set,itimes=['22-Mar-2002 18:16:18', '22-Mar-2002 18:30:57'] ;-- set time for lrad integration

To unset integration time, set itimes to [0.,0.] or -1.

Even if you are working from the command line, you can use the PLOTMAN interface to select integration intervals graphically by typing:

IDL> a->select_integration_times ;-- use graphical interface for selecting integration times
IDL> ptim, a->get(/itimes) ;-- display integration time intervals in ASCII format

See below for how to retrieve all quantities in a structure with one call.

How to plot temperature, emission measure, and energy loss rate for GOES:

IDL> a->plot, /temp ;-- (or could use plotman)
IDL> a->plotman, /emis ;-- (or could use plot)
IDL> a->plot, /lrad ;-- plots lrad and lx (total and X-ray energy loss rate)
IDL> a->plot, /lrad, /integrate ;-- plots integrated lrad and lx

More options for extracting GOES data arrays:

Instead of calling getdata for each quantity you need, call getdata with the /struct keyword to return a structure containing all of the available quantites, as follows:

IDL> data = a->getdata(/struct)       ;-- extract data and derived quantities
                                      ;   into a structure

IDL> help, data, /struct

IDL> help,data,/st
** Structure <70774e0>, 15 tags, length=3936, data length=3928, refs=1:
UTBASE STRING '22-Mar-2002 18:00:00.000' ; utbase time
TARRAY LONG Array[61]         ; time array in seconds relative to utbase
YDATA FLOAT Array[61, 2]      ; 2 channels of GOES data in watts/m^2
YCLEAN FLOAT Array[61, 2]     ; 2 channels of cleaned GOES data in watts/m^2
YBSUB FLOAT Array[61, 2]      ; 2 channels of cleaned background-subtracted data in watts/m^2
BK FLOAT Array[61, 2]         ; 2 channels of computed background in watts/m^2
BAD0 INT -1                   ; indices for channel 0 array that were bad
BAD1 INT -1                   ; indices for channel 1 array that were bad
TEM DOUBLE Array[61]          ; temperature array in MK
EM DOUBLE Array[61]           ; emission measure array in cm^-3 * 10^49
LRAD DOUBLE Array[61]         ; total radiative energy loss rate (or integral) array in erg/s
LX FLOAT Array[61]            ; radiative energy loss rate in X-rays (or integral) array in erg/s
INTEGRATE_TIMES STRING Array[2]   ; integration time interval
YES_CLEAN INT 1               ; 0/1 means data wasn't / was cleaned
YES_BSUB INT 1                ; 0/1 means background wasn't / was subtracted

Note: if you use getdata(/struct, /integrate) then lrad and lx are the cumulative integrals.

How to examine current GOES object settings :

IDL> a->help

GOES parameter values:
Last data interval read:
  1-Jun-2002 00:00:00.000 to 3-Jun-2002 00:00:00.000
Current TSTART / TEND:
  1-Jun-2002 00:00:00.000 to 3-Jun-2002 00:00:00.000
ARCHIVE: YOHKOH then SDAC
MODE: 0
DATA TYPE: GOES8 3 sec
NEED_UPDATE: 0
CLEAN: 1
MARKBAD: 1
SHOW CLASS: 1
SUBTRACT BACKGROUND: 1
BACKGROUND TIMES:
  1-Jun-2002 07:53:39.000 to 1-Jun-2002 08:34:36.000
BACKGROUND FUNCTION: 0poly
USER BACKGROUND:
  Channel 0 : None
  Channel 1 : None
INTEGRATION TIMES:
  None
ABUNDANCE: Coronal (5.1)

IDL> print,a->get(/showclass)

See the list of GOES parameters for the names of each object parameter.

How to save GOES data in an IDL save file:

IDL> a->savefile, filename='goes.sav'       ;-- If you don't specify a filename, a dialog box
                                            ;   will pop up to let you navigate to a file.

This saves the raw, cleaned, and background-subtracted flux in the two GOES channels, and time array, the temperature , emission measure and energy loss rate, and more.

IDL> restore, 'goes.sav'                    ;-- Restore saved data

IDL> prstr, readme                          ;-- Print the readme variable to see a summary 
                                            ;   of the saved variables

Summary of GOES parameters:

The following parameters can be set into the GOES object and will persist until changed. You can set them via the set command, or by passing them as keywords in calls to getdata or plot or plotman.

tstart	Start time. Default is start of the day two days ago. (If seconds, use TAI, relative to 1958.) Example: a->set, tstart='13-Nov-2005 12:33.12.123'
tend	End time. Default is end of the day two days ago. (If seconds, use TAI, relative to 1958.) Example: a->set, tend='13-Nov-2005 16:12:34.567'
sat	Satellite preference. Options are goes6, goes7, goes8, goes9, goes10, goes12. If selected satellite isn't available for selected time, returns data for the latest satellite that does contain the time. Example: a->set, sat='goes12' or a->set, /goes12
sdac	Selects which archive to use, SDAC or YOHKOH. Options are 0 - use YOHKOH 1 - use SDAC 2 - use YOHKOH, then SDAC (if not available in YOHKOH, use SDAC) 3 - use SDAC, then YOHKOH Default is 2. Example: a->set, /sdac or a->set, sdac=0 (or a->set,/yohkoh) or a->set,sdac=3
mode	Data resolution. Options are 0,1,2 for 3-second, 1-minute, and 5-minute data. Can set via 0,1,2 or /three, /one, /five. Default is 0. Example: a->set, /five or a->set, mode=2
clean	If set, clean glitches from gain changes, etc in data. Default is 1. Example: a->set, /clean
bsub	If set (and btimes or b0user/b1user is set), subtract background. Default is 0. Example: a->set, /bsub
btimes	Any number of background start/end times in [2,n] array. Default is none. (If seconds, use TAI, relative to 1958.) Example: a->set, btimes= [ ['22-Mar-2002 18:12:54', '22-Mar-2002 18:14:36'], $ ['22-Mar-2002 18:40:57', '22-Mar-2002 18:42:06'] ]
b0times	Same as btimes, but for channel 0 background. btimes takes priority if set.
b1times	Same as btimes, but for channel 1 background. btimes takes priority if set.
bfunc	Function to use for computing background. Options are 0poly, 1poly, 2poly, 3poly, exp. Default is 0poly. Example: a->set, bfunc='exp'
b0user	User-defined background for channel 0. Scalar or vector. Set to -1 to disable. Example: a->set, b0user=4.e-7
b1user	Same as b0user, but for channel 1
showclass	If set, show A,B,C,M,X level on side of plots. Default is 1. Example: a->set, showclass=0
markbad	If set, mark bad points (that are cleaned if clean is set) with an X in plots. Default is 1. Example: a->set, markbad=0
abund	Spectral model used in calculation of temperature and emission measure. Options are 0/1/2 for Coronal, Photospheric, Meyer. Default is 0. Example: a->set, abund=1 or a->set, abund='photospheric'
itimes	A single time interval to define the integration interval for energy loss calculation. Default is none, which means integrate over the entire time interval. (If seconds, use TAI, relative to 1958.) Example: a->set,itimes=['22-Mar-2002 18:16:18', '22-Mar-2002 18:30:57']

The following keyword parameters apply only to the getdata, plot, or plotman methods, and do not persist, i.e. they apply to the current call only.

temperature	If set, return or plot temperature. Example: a->plot, /temperature
emission	If set, return or plot emission measure . Example: emis = a->getdata(/emis)
lrad	If set, return or plot radiative energy loss rate Example: a-> plotman, /lrad
integrate	If set, and lrad is set, return or plot integrated energy loss rate. Uses itimes for integration times.
structure	Applies only to getdata call. If set, getdata returns a structure with everything. Example: struct = a->getdata(/struct)
quick_struct	Applies only to getdata call. If set, getdata returns a structure with items specified by keyword arguments. Faster than /struct if you don't need everything computed. Example: struct = a->getdata(/quick_struct)

Last Revised: