Space Research Laboratory

When using ged to read ERNE data, the type of data and the associated reader function is determined based on the data file name (or the name of the first file in a file name array). Some reader functions can process the data based on keywords. The set of acknowledged keywords are typically specific to the reader function in question, so in order to find what options are available, the user should consult the documentation of the reader function associated with the desired data type. The functions for each data type can be found in the quick reference tables on the main page.

This is the most basic example of ged usage.

IDL> mydata = ged()

If FILENAMES keyword is not set, ged will call datafilename function which will open a Graphical User Interface (GUI) window to let user interactively select the desired files. The result mydata will be an array of file records. Level-2 pulse height data are exceptions, as the reader output record structure is slightly modified from the one used in the input disk files (see the quick reference table on the main page).

User can provide keywords for the datafilename function via ged. The most important keywords are:

• START: a string coding the date of the first file. Format = 'DDMMYYYY'
• STOP: a string coding the date of the last file. Format = 'DDMMYYYY'
• DATATYPE: a string coding the data type, see datafilename for the list of available types.
• DLEVEL: a string coding the data level. This defaults to '3', so it must be set only if requesting for level-2 data.
• UNDERCOVER: if set (UNDERCOVER=1 or /UNDERCOVER) the interactive window will not open. This assumes of course that the three keywords (START,STOP and DATATYPE) with no default values are set also.
• MUTE: setting (MUTE=1 or /MUTE) will prevent datafilename from printing its informative messages on the console.

The DATA FORMAT -field will be set automatically depending on the value of the START-field, but can be also set manually in special cases. The other available parameters in the GUI have default values that should not be changed for normal operations. The GUI doesn't present all the available keywords, these have to be set manually in the ged call if needed. See datafilename for the description of the whole keyword set.

IDL> mydata = ged(START='01012000',STOP='10012000')

as previously the datafilename function will open the GUI, but this time the start and stop date fields will have preset values via the keywords. Note that user can use also string variables in place of the string constants (literals).

IDL> dt0 = '01012000'
IDL> dt1 = '10012000'
IDL> mydata = ged(START=dt0,STOP=dt1)

IDL> dt0 = '01012000'
IDL> dt1 = '10012000'
IDL> mydata = ged(START=dt0, STOP=dt1, DATATYPE='Proton+Helium Spectra', /UNDERCOVER, /MUTE)

will silently read ten days of onboard spectra records (structure type 'TobSpectra_a') into mydata array.

The most important keyword for ged-function is FILENAMES The corresponding parameter is assumed to be a file name string or an array of name strings. One way to obtain valid file names is to call datafilename directly before ged call:

IDL> fns = DATAFILENAME()
IDL> mydata = ged(FILENAMES=fns)

It is of course also possible to provide the name(s) in any other means. However ged requires the names allways to obey a standard format, see ged for details. Note that in case DATAFILENAMES keyword is set, ged will not call datafilename, and thus e.g., setting any of the datafilename keywords will have no effect.

The other ged keywords are more or less technical, and are intended to be used in some special situations.

Level-3 spectra reader ged_l3_spectra provides a comprehensive set of keywords. The most important of them are the ones that control the time and energy integration. The energy integration is done via separate 'filter functions' Eint_1 (f10 data) and Eint_3 (f30, f40 and f50 data). The format of the energy integration control parameter differs between the filter functions and so when using his/her own energy integration parameter the user must be aware which data format he/she is operating with, see the discussion of the keyword EINT_CS in Eint_1 and Eint_3 for details.

IDL> dt0 = '01012000'
IDL> dt1 = '10012000'
IDL> mydata = ged(START=dt0, STOP=dt1, DATATYPE='Proton+Helium Spectra', G3SPE_DT=6*60*60.0, /G3SPE_EEXP, G3SPE_EINFO=info, /UNDERCOVER, /MUTE)

This will silently read ten days of onboard spectra records into mydata array. The data will be time integrated in to 6 hour bins. The energies will be integrated in to the ERNE Export Data channels, and the energy information about the channels will be returned in the info table. Note that the output data is in a customized structure, depending on the number of requested channels.

Let's assume we have prepared an energy channel selector table chsel using the guidelines for the appropriate filter function (which as discussed above, depends on the data format).

IDL> mydata = ged(G3SPE_DT=15*60.0, G3SPE_ECUST=chsel, G3SPE_EINFO=info)

This will call datafilename for interactive file selection and assuming we select level-3 spectra as the data type, we will get an time integrated spectra with 15 minute binning and custom energy channels. The behaviour is unpredictable if we happened to choose some other data type for which the keywords have no meaning (in some cases the keywords are ignored in other cases the call will fail).

level-3 pulse height data reader is ged_l3_pha. The current keyword set is quite small.

IDL> dt0 = '01012000'
IDL> dt1 = '10012000'
IDL> mydata = ged(START=dt0, STOP=dt1, DATATYPE='LED Pulse Height Data', G3PHA_AMP=amps, /UNDERCOVER, /MUTE)

This will read ten days of LED Pulse height records of type TledPartData_a into mydata array. Information on the LED onboard amplification parameter setting will be returned in amps which is a structure of type TledAmpParams_a.

The following will do the same for HED.

IDL> dt0 = '01012000'
IDL> dt1 = '10012000'
IDL> mydata = ged(START=dt0, STOP=dt1, DATATYPE='HED Pulse Height Data', G3PHA_AMP=amps, /UNDERCOVER, /MUTE)

The record type of mydata array will be ThedPartData_a and the structure of amps will be ThedAmpParams_a.

LED Direction Spectra reader is ged_l3_leddirspectra. As with the regular onboard spectra the energy integration is done with a standard filter function, in this case with Eint_leddir. In contrast to ged_l3_spectra, there are no keywords for the energy integration for ged_l3_leddirspectra. Instead it is intended that the user sets the filter function keywords explicitly.

IDL> mydata = ged(DATATYPE='LED Direction Spectra', G3LDS_EINFO=info)

This will initiate the call to datafilename in interactive mode, with the 'Data File Type' preset. Result in mydata will be an array of LED direction records with a default structure i.e., with the low energy channels covered by only by LED-I (thin D1 detectors, D11 and D16), discarded. The info variable will be a structure containing information on the energy channels and direction of each D1-detector. Both proton and helium data will be present.

IDL> psel = [6,10,14]
IDL> mydata = ged(DATATYPE='LED Direction Spectra', G3LDS_EINFO=info, EILD_CHS_P=psel, EILD_CHS_HE=-1)

As with above except, result in mydata will be an array of LED direction spectra records with a custom structure for the requested proton channel combinations. There will be three integrated energy bins, first containing the original channels 6-9, second containing the channels 10-13 and the last for the rest i.e., 14 and 15 . The info variable will be a structure containing information on the resulting proton energy bins and direction of each D1-detector. There will be no entries for helium in either of the direction spectra or the info the record.