EINT_3

IDL doc_library comment

 Function Eint_3 - Energy Integration of Lev-3 Spectra  TM-formats: f30, f40,f50


 function Eint__3_11, inpChannels,            
                      intPeriodCounts,        
                      EINT_CS=customChannels, 
                      EINT_EXP=export,        
                      EINT_CR=carrot,         
                      EINT_EINF=Einfo,        
                      EINT_JUSTINFO=justinfo, 
                      EINT_NOI=noinit


 Version 3.11


 Calling sequences:

       data = Eint__3_11(inpChannels)
       data = Eint_l3f30(inpChannels)
       data = Eint_l3f40(inpChannels)
       data = Eint_l3f50(inpChannels)


 Input parameters:

       inpChannels      Vector of ERNE level-3 spectra records of type 'TobSpectra_b'

       intPeriodCounts  Vector containing the number of time integrated measurement periods in each input channel record.
                        Because of lost measurement frames the exact numbers usually vary from record to record.

 Returns:

       Vector of ERNE level-3 spectra records of a custom type



 Keyword parameters:

       EINT_CS   customChannels

                 Matrix (3 x nCh x 2) directing the custom energy binning. It gives the minimum and maximum energy index
                 of the input record for each isotope and output energy bin.

                 First index is the isotope (0=p,1=He3 and 2=He4)
                 Second index is the ouput bin (0..n_bins-1)
                 Third is the min/max (0=min,1=max) energy index of the coresponding isotope in input record

                 There are no limits for the number of output bins, the number is deduced from the total number
                 of elements in the matrix. Only limitation is that there must be the same number of output
                 bins for each isotope. If there is a need for different binning you must use dummy bins
                 as in example 2 below.

                 Examples:

                  1) If we want to integrate all the LED protons in one bin and all the HED in another
                     and similarly for He3 and He4 we will have:

                       customChannels[0,0,0] =  0    protons - first output bin  - minimum input bin
                       customChannels[0,0,1] = 33                                  maximum input bin
                       customChannels[0,1,0] = 34              second output bin - minimum input bin
                       customChannels[0,1,1] = 67                                  maximum input bin
                       customChannels[1,0,0] =  0    he3     - first output bin  - minimum input bin
                       customChannels[1,0,1] = 33                                  maximum input bin
                       customChannels[1,1,0] = 34              second output bin - minimum input bin
                       customChannels[1,1,1] = 67                                  maximum input bin
                       customChannels[2,0,0] =  0    he4     - first output bin  - minimum input bin
                       customChannels[2,0,1] = 33                                  maximum input bin
                       customChannels[2,1,0] = 34              second output bin - minimum input bin
                       customChannels[2,1,1] = 67                                  maximum input bin

                  2) Same as above, but we want to have better resolution in LED proton measurement

                       customChannels[0,0,0] =  0    protons - first output bin  - minimum input bin
                       customChannels[0,0,1] =  9                                  maximum input bin
                       customChannels[0,1,0] = 10              second output bin - minimum input bin
                       customChannels[0,1,1] = 33                                  maximum input bin
                       customChannels[0,2,0] = 34              third output bin  - minimum input bin
                       customChannels[0,2,1] = 67                                  maximum input bin
                       customChannels[1,0,0] =  0    he3     - first output bin  - minimum input bin
                       customChannels[1,0,1] = 33                                  maximum input bin
                       customChannels[1,1,0] = 34              second output bin - minimum input bin
                       customChannels[1,1,1] = 67                                  maximum input bin
                       customChannels[1,2,0] =  0              third output bin  - minimum input bin DUMMY bin
                       customChannels[1,2,1] =  0                                  maximum input bin DUMMY bin
                       customChannels[2,0,0] =  0    he4     - first output bin  - minimum input bin
                       customChannels[2,0,1] = 33                                  maximum input bin
                       customChannels[2,1,0] = 34              second output bin - minimum input bin
                       customChannels[2,1,1] = 67                                  maximum input bin
                       customChannels[2,2,0] =  0              third output bin  - minimum input bin DUMMY bin
                       customChannels[2,2,1] =  0                                  maximum input bin DUMMY bin



       EINT_EXP  export
                 If set the output binning will be the same used for EXPORT data.
                 If set the 'EINT_CS' and 'EINT_CR' keywords are ignored.


       EINT_CR   customChannels
                 If set the output binning will be the same used for Carrington Rotation web-plots.
                 If set the 'EINT_CS' keyword is ignored.


       EINT_EINF Einfo

                 Matrix (3 x nCh x 3) returning info on the result energy bins.

                 First index is the isotope (0=p, 1=He3 and 2=He4)
                 Second index is the ouput bin (0..n_bins-1)
                 Third are the values (0=Average Energy, 1=Low energy limit, 2=High energy limit)


       EINT_JUSTINFO justinfo

                 If set the program returns the Einfo-matrix instead of the regular integration results.


       EINT_NOI  noinit
                 If set the initialization section is skipped. This will speed up the execution
                 if the function is being called several times with same control parameter set
                 (the parameters are stored in a common block between successive calls).
                 Note that on the first call of the EINT-function setting the keyword has no effect.



 Depends:
         The following files have to be in path:

           l3f30_Spectra_Parameters_t2_Template
           l3f30_Spectra_Parameters_t2

 Version history:

 3.11 - 2007-02-01 (ER)

        Transferred parPath variable to the common block
        'ERNE_parameters'.


 3.10 - 2007-01-19 (ER)

        1) Changed the reference of the science header type to utilize the new automatic structure
           type definition system.
           Note that the other types are still defined internally in the program.
        2) Added keyword EINT_JUSTINFO


 3.9 -  2002-09-24 (ER)

        Bug correction. The 'obIntTime' parameter in the 'ERNE_parameters' common block was referenced
        explicitely as the first parameter of the block. The first parameter of the block was actually
        the 'defined' flag of the block as set in the ERNE IDL intialisation code and thus obIntTime
        parameter in the function got value of '1' instead of the intended '59.99...'.
        The reference was changed to more robust 'Common Block Reference Statement', where the parameter
        names are not written explicitely.


 3.8 -  2002-09-11 (ER)

        Changed program to use type-2 parameter tables that include also maximum and minimum limits
        for the enrgy channels. These data are now also written to the Einfo parameter.


 3.7 -  2002-09-09 (ER)

        Bug correction. Error in 'Einfo'-construction. When nominal wighted energies for a channel were
        calculated the GdE-for protons were referred in one instance instead of the the ones for the
        isotope in question.


 3.6 -  2002-09-04 (ER)

        Bug correction. Changed the behaviour of energy integration for output channels consisting
        only of one input energy channels, that is no energy integration for that channel. In these
        cases the 'total'-function is not appropriate and the cases must be handled separately.


 3.5 -  2002-06-28 (ER)

        Added keyword EINT_CR.


 3.4 -  2002-06-26 (ER)

        Bug fix. In 'unfinit'-handling (see version 3.3), the WHERE-function result was checked agains '-1',
        now the correct form of checking the 'count'-parameter against '0' is used instead.


 3.3 -  2002-06-19 (ER)

        Added check for 'unfiniteness' of intensity values after the energy integration. This would occur at
        least for bins where the number of time integrated records were 0. And also for some more degenerate
        cases, e.g He3 has GdE-value of 0 for low hed energies.

        Now these intensities are forced to 0.


 3.2 -  2002-06-18 (ER)

        Added keyword EINT_EINF.


 3.1 -  2002-06-16 (ER)

        a) Changed name of the function to 'EINT__3_1'.
        b) Added input parameter 'intPeriodCounts'.
        c) Changed type identifier of the result records 'Tres_spectrum_n' to 'Teint3_isot_n',
           and 'Tres_spectra_n' to 'Teint3_n'. Here 'n' is the number of initialisations (nResets)
           of this function during this IDL-session.
        d) Added wrapper functions 'Eint_l3f30', 'Eint_l3f40' and 'Eint_l3f50'.
        e) Renamed parameter file and the corresponding template file to 'l3f30_Spectra_Parameters'
           'l3f30_Spectra_Parameters_Template'. These ase supposed to be links to the actual versions
           of the files to use.


 3.0 -  2002-05-16 (ER)

        Original version