GOES IDL User Guide

Data from multiple generations of Geostationary Operational Environmental Satellites (GOES) since 1976 are available.  Each GOES satellite carries an X-Ray Sensor (XRS) consisting of two ionization chambers to measure the total solar flux in two wavelength bands, 0.5 - 4 and 1 - 8 Angstroms.

IDL software distributed in SolarSoft (SSW) provides an easy way to access and analyze the GOES lightcurve data.  The goes IDL class in SSW creates a GOES lightcuve object that users control from the IDL command line, a GUI interface, or a combination of the two.

Finding the GOES data

The goes object automatically searches for and retrieves GOES data files across the network for the time interval requested. 

There are two GOES archives used by the goes object, -YOHKOH (originally created for the YOHKOH project) and SDAC (Solar Data Analysis Center) both stored on servers at GSFC.  The two archives are essentially the same; they 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 can be more up-to-date, sometimes within an hour of the current time, while the SDAC files contain data through the end of the day previous to the current time.
• The YOHKOH files are written in a yohkoh-specific weekly file format; the SDAC files are daily files written in standard FITS format.

Location and description of files (though, as mentioned above, the software automatically retrieves them, so users don't need to know this):

When the files are copied to the user's computer, they are placed in a goes directory in the user's temporary directory (whatever is returned by the function get_temp_dir() ).

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. 

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

Use any of the following commands to start the GOES Workbench.  Note that you can work with the GOES Workbench and command line interface interchangeably.  

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

Any of the commands above will bring up the widget interface to the right. Set the time interval you're interested in, and click Plot.  By default the lightcurve in the two channels will be plotted in PLOTMAN (an interactive plot interface). The setup at right produced this plot. Clicking List will display a list of time periods covered by each of the ~16 satellites in use since 1976. Clicking Event List will display a list of all GOES events (defined by NOAA) during the time interval selected. Before plotting temperature, emission measure, or energy loss, you may want to define background time intervals and a functional form for estimating background throughout the flare, and click the option to subtract background. If you started the GUI using either the 'goes,a' or 'a->gui' commands, then you have access to the goes object, a, at the command line.  You can use any of the commands described below to set options or retrieve or plot the data.  If you change any options from the command line, click the Refresh button on the GUI to reflect the new settings.  And when you click Quit, the object a is still available at the command line.

How to create a GOES object:

To create a goes object without opening the GUI:

IDL> a = ogoes()

To create a goes object and open the GOES GUI:

IDL> goes, a

All of the commands below assume you have created a goes object called a (either with or without the GUI).

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 print,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 set options in the GOES object:

To set the time interval, and satellite preference:

IDL> a->set, tstart='13-Nov-2005 12:33.12.123', tend='13-Nov-2005 16:12:34.567', sat='goes12'

All of the  GOES parameters and their default values are listed below.

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.

To retrieve all quantities with one call (see below for more details):

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

How to subtract background for GOES:

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

IDL> a->set, /bsub           ;-- set bsub to 1

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           ;-- set bsub to 1

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

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

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 level 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

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:

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

How to get the GOES event list for a time period:

IDL> gev = a->get_gev(/show)

IDL> gev = a->get_gev('23-jul-2002', '23-jul-2002', /struct, /class_decode)

Options to the get_gev function are:

How to examine current GOES object settings :

Print individual parameters (see the list of GOES parameters for the names of each object parameter), e.g.

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

or use the help method to show a summary of parameter 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)

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.

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 keyword parameters apply only to the getdata, plot, or plotman methods, and do not persist, i.e. they apply to the current call only.