GED_L3_SPECTRA

The ged_l3_spectra function reads level-3 onboard spectra from disk files. There are numerous keywords available to control the processing of the data for output. Typically the function will handle time and energy integration of the data. Time integration is handled internally. Energy integration is done by the standard filter functions Eint_1 (f10 spectra) and Eint_3 (f30, f40 or f50 spectra). For other options see the list of keywords below.

Input file format:

    ● TobSpectra_a (f10)
    ● TobSpectra_b (f30,f30,f40)

Output data format:

    ● TobSpectra_a or Eint_1 output (f10)
    ● TobSpectra_b or Eint_3 output (f30,f40,f50)

IDL doc_library comment

 function  GED_L3_SPECTRA - get ERNE Level-3 Spectra.
                            TM-formats: f10,f30,f40,f50


 Version 2.15


 Calling sequences:

       data=ged_l3_spectra__2_15(fnames)
       data=ged_l3_spectra(fnames)
       data=ged_l3f10_spectra(fnames)
       data=ged_l3f30_spectra(fnames)
       data=ged_l3f40_spectra(fnames)
       data=ged_l3f50_spectra(fnames)


 Input parameters:

       fnames  list of input file names


 Returns:

       Vector of level-3 spectrum records, possible time integrated and otherwise filtered if requested.


 Keyword parameters:

      G3SPE_DT     delta_t
                   Length of time integration bins in seconds.
                   If set the time stamp for each output record is set at the middle point of the corresponding integration bin.
                   If not set there is no time integration and the time stamps are not touched.

      G3SPE_EEXP   Eexport
                   If set, the energy integration will be done to produce the ERNE Export channel division.
                   See function Eint for details. Especially on what will happen when more than one of the
                   keywords  G3SPE_EEXP, G3SPE_ECARR, G3SPE_ECUST are set simultaneously.

      G3SPE_ECARR  Ecarrot
                   If set, the energy integration will be done to produce the ERNE Export channel division.
                   See function Eint for details. Especially on what will happen when more than one of the
                   keywords  G3SPE_EEXP, G3SPE_ECARR, G3SPE_ECUST are set simultaneously.

      G3SPE_ECUST  Ecustom
                   Matrix defining custom energy integration binning.
                   See function Eint for details. Especially on what will happen when more than one of the
                   keywords  G3SPE_EEXP, G3SPE_ECARR, G3SPE_ECUST are set simultaneously.

      G3SPE_EINFO  Einfo
                   Matrix containing info on the final energy bins.
                   See function Eint for details.

      G3SPE_FTS    ffuncs
                   List of filter functions. After processing of each input file, the ready time integrated records will
                   be fed through the filter function(s). The output of each function will be input for the next. The resulting
                   records will be then concatenated to the output vector.

      G3SPE_T0     startlobt
                   Starttime for integration in LOBT-format (TAI-format)
                   Normally, if G3SPE_T0 is not set, starttime (startlobt) is set at the start of the first file day.
                   NOTE: G3SPE_T0 has no effect if G3SPE_DT is not set also.

      G3SPE_NTS    noTsync
                   Normally, if G3SPE_T0 is not set, starttime (startlobt) is set at the start of the first file day.
                   Setting G3SPE_NTS overrides the default action, and first lobt-value in the first input file is used instead.
                   NOTE: if G3SPE_T0 is set G3SPE_NTS has no effect.

      G3SPE_HHL    hedHitLevel
                   HED Hit Level selector:
                      0: Both hit levels records accepted
                      1: Only 1x hit level records accepted
                      3: Only 3x hit level records accepted
                   If not set effect is same as 0

      G3SPE_LHL    ledHitLev
                   LED Hit Level selector:
                      0: Both hit levels records accepted
                      1: Only 1x hit level records accepted
                      3: Only 3x hit level records accepted
                   If not set effect is same as 0

      G3SPE_HOL    hedOverLoad
                   If set HED overload minutes will be included.
                   Default action is to discard HED overload minutes.

      G3SPE_LOL    ledOverLoad
                   If set LED overload minutes will be included.
                   Default action is to discard LED overload minutes.

      G3SPE_NH3C   NOhed3xCorr
                   If set there will be no HED 3x Hit Level effectivity correction
                   NOTE: See G3SPE_H3IP below.

      G3SPE_NL3C   NOled3xCorr
                   If set there will be no LED 3x Hit Level effectivity correction
                   NOTE: See G3SPE_L3IP below.

      G3SPE_H3IP   hed3xInterpol
                   If set the HED 3x values will be replaced by interpolating from the 1x values.
                   NOTE: If G3SPE_H3IP is set G3SPE_NH3C has no effect.

      G3SPE_L3IP   led3xInterpol
                   If set the LED 3x values will be replaced by interpolating from the 1x values.
                   NOTE: If G3SPE_L3IP is set G3SPE_NL3C has no effect.

      G3SPE_LINIP  lin3xInterpol
                   Use linear interpolation in hed and led 3x interpolation.
                   Default is to use logarithmic interpolation.
                   NOTE: If neither of G3SPE_L3IP or G3SPE_H3IP are set, this keyword has no effect.

      G3SPE_HEIP   heip
                   Interpolate also the helium isotope(s). Default is to interpolate only protons.


      G3SPE_NS1XEC NOs1xEffCorr
                   If set there will be no effectivity correction for f40-intensities following the HED S1H2X breakdown on
                   2000-11-21 00:15:44.833.

      G3SPE_TMF    tmFormat
                   Telemetry format of the input files ('f10','f30', etc). If not set, the format is deduced from the first
                   file name assuming standard naming convention.


 Depends:
         The following files (links) have to be in path:


           l3f10_x3eff_Template
           l3f30_x3eff_Template
           l3f40_x3eff_Template
           l3f50_x3eff_Template

           l3f10_hedx3eff
           l3f30_hedx3eff
           l3f40_hedx3eff
           l3f50_hedx3eff

           l3f10_ledx3eff
           l3f30_ledx3eff
           l3f40_ledx3eff
           l3f50_ledx3eff

 Version history:

 2.15 - 2007-05-23 (ER)

        Changed keyword 'G3SPE_EINF' to 'G3SPE_EINFO',
        to keep syntax similar with LED direction spectra
        reader.


 2.14 - 2007-02-01 (ER)

        Transferred parPath variable to the common block
        'ERNE_parameters'.


 2.13 - 2007-01-17 (ER)

        Updated to utilize the new functionality in the energy
        integrator filters that allow for requesting for the energy
        channel parameters even with no integration.


 2.12 - 2006-12-12 (ER)

        Updated to utilize automated (on-need) structure definition.


 2.11 - 2006-06-19 (ER)

        Changed default 3x interpolation to concern only protons.
        Added keyword G3SPE_HEIP, to interpolate also helium(s).


 2.10 - 2005-09-28 (ER)

        Added keyword  G3SPE_LINIP.
        From now on the default is to use logarithmic interpolation in
        case interpolation is requested.


 2.9 - 2005-09-22 (ER)

        Added keyword G3SPE_H3IP.
        Interpolation tranferrred to a separate IDL-function: 'ged_interpol3x'.


 2.8 - 2005-06-30 (ER)

        Added keyword G3SPE_L3IP.


 2.7 - 2003-12-06 (ER)

       Removed a bug introduced in version 2.6. The whole spectra
       was corrected for the HED efficiency drop (S1H2X breakdown f40).
       Instead, only the HED part of the spectra should be corrected.


 2.6 - 2003-09-02 (ER)

        New feature and associated keyword.
        Format-40 intensities from the HED S1H2X breakdown onwards
        (2000-11-21 -- 2001-07-02), are by default corrected for the
        estimated efficiency drop. This can be circumvented by setting
        the new keyword 'G3SPE_NS1XEC'.


 2.5 - 2003-06-13 (ER)

        Corrected typo. In two lines there were references to 'LED3xeff'
        instead of the correct reference 'LEDx3eff'.


 2.4 - 2003-01-29 (ER)

        Changed the handling of overload periods. Now the periods with
        HED or LED overload are discarded as default. This action can be
        altered by the new keywords G3SPE_HOL and G3SPE_LOL.


 2.3 - 2003-01-26 (ER)

        Bug fix regarding 3x-hit level efficiency correction.
        The efficiency correction was done only to the intensity values
        before time and energy integrations. As the energy integration
        recalculates the intensity values based on normalized counts the
        efficiency corrections were lost in the process. Now both
        the intensity and normcount values are corrected.


 2.2 - 2002-07-02 (ER)

        Added keyword G3SPE_ECARR.


 2.1 -  2002-06-18 (ER)

        a) Energy integration
        There was an error in the previous implementations regarding
        energy integration. In order to recalculate the new intensities
        properly the energy integrator needs to know how many measurement
        periods was actually combined in each time integrated bin.
        It was also considered more intuative to consider both time and
        energy integration to be on equal basis from the user perspective.
        Thus,  while the energy integration is still internally implemented
        as a separate function, the user sees 'ged_l3_spectra'-as one
        function that will handle both of the integrations similarly.

        b) 3-fold hit level corrections
        The file names for the associated templates and efficiency factor
        files have been changed to descriptive (link) names instead of
        the previous exact file names.

        c) Added keyword G3SPE_EINF for returning data for the combined
        energy channels.
        NOTE: There is a feature :-) in the current implementation that
              energy information will not be updated if there is no
              energy integration requested!


 2.0 -  2002-06-12 (ER)

        New version that accepts filter functions.

        The main motivation behind this was that the older version
        would run out of memory for really long time series as the
        energy-integration could be done only after the total time-
        integrated series was complete.

        Using the new option the filtering (e.g., Energy integration)
        will be done on the resulting output records after time
        integration of each input file data. In order to be able to
        handle output records that are split across one or more input
        files the whole 'split-record' logic had to be rewritten.

        Changed the keyword prefix from 'GSPE_' to more distinctive
        'G3SPE_'.


 1.0 -  2002-05-21 (ER)

        Original version