Differences

This shows you the differences between two versions of the page.

--- ged_examples [2023/10/10 14:53] – created admin
+++ ged_examples [2023/10/11 14:49] (current) – admin
@@ Line 3: / Line 3: @@
 ==== Introduction ====
-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.
+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 [[ged_docs|main page]].
+(hr)
 ==== Empty keyword list ====
@@ Line 15: / Line 17: @@
 </code>
-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).
+If FILENAMES keyword is not set, [[GEDfunction|ged]] will call [[Datafilename|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 [[ged_docs|main page]]).
+(hr)
 ==== Keywords for DATAFILENAME ====
-User can provide keywords for the **datafilename** function via **ged**. The most important keywords are:
+User can provide keywords for the [[Datafilename|datafilename]] function via **ged**. The most important keywords are:
@@ Line 28: / Line 32: @@
   * **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.
+  * **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|datafilename]] for the description of the whole keyword set.
 === Example-2 ===
+<code>
+IDL> mydata = ged(START='01012000',STOP='10012000')
+</code>
+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).
 === Example-3 ===
+<code>
+IDL> dt0 = '01012000'
+IDL> dt1 = '10012000'
+IDL> mydata = ged(START=dt0,STOP=dt1)
+</code>
 === Example-4 ===
+<code>
+IDL> dt0 = '01012000'
+IDL> dt1 = '10012000'
+IDL> mydata = ged(START=dt0, STOP=dt1, DATATYPE='Proton+Helium Spectra', /UNDERCOVER, /MUTE)
+</code>
+will silently read ten days of onboard spectra records (structure type 'TobSpectra_a') into **mydata** array.
+(hr)
 ==== Keywords for GED ====
+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|datafilename]] directly before **ged** call:
 === Example-5 ===
+<code>
+IDL> fns = DATAFILENAME()
+IDL> mydata = ged(FILENAMES=fns)
+</code>
+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|datafilename]], and thus e.g., setting any of the [[Datafilename|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.
+(hr)
 ==== Onboard Spectra ====
+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.
 === Example-6 ===
+<code>
+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)
+</code>
+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.
 === Example-7 ===
+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).
+<code>
+IDL> mydata = ged(G3SPE_DT=15*60.0, G3SPE_ECUST=chsel, G3SPE_EINFO=info)
+</code>
+This will call [[Datafilename|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).
+(hr)
 ==== Pulse Height Data ====
+level-3 pulse height data reader is [[ged_l3_pha]]. The current keyword set is quite small.
 === Example-8 ===
+<code>
+IDL> dt0 = '01012000'
+IDL> dt1 = '10012000'
+IDL> mydata = ged(START=dt0, STOP=dt1, DATATYPE='LED Pulse Height Data', G3PHA_AMP=amps, /UNDERCOVER, /MUTE)
+</code>
+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.
 === Example-9 ===
+<code>
+IDL> dt0 = '01012000'
+IDL> dt1 = '10012000'
+IDL> mydata = ged(START=dt0, STOP=dt1, DATATYPE='HED Pulse Height Data', G3PHA_AMP=amps, /UNDERCOVER, /MUTE)
+</code>
+The record type of **mydata** array will be [[ThedPartData_a]] and the structure of **amps** will be [[ThedAmpParams_a]].
+(hr)
 ==== LED Direction Spectra ====
+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.
 === Example-10 ===
+<code>
+IDL> mydata = ged(DATATYPE='LED Direction Spectra', G3LDS_EINFO=info)
+</code>
+This will initiate the call to [[Datafilename|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.
 === Example-11 ===
+<code>
+IDL> psel = [6,10,14]
+IDL> mydata = ged(DATATYPE='LED Direction Spectra', G3LDS_EINFO=info, EILD_CHS_P=psel, EILD_CHS_HE=-1)
+</code>
+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.