2A25 USER'S GUIDE
                
This document is a concatenation of 7 files:
README_2A25           
2a25_algorithm.txt
2a25_files.txt
2a25_functions.txt
2a25_variables.txt
2a25_log.txt
CAVEATS_2A25


This is a README file for 2A-25 version 5.53

Source files, parameter files, header files and a 'make' file are 
in the directory of 'source'.

Document files are in the directory of 'documents.v5.53'.
    2a25_algorithm.txt: algorithm description
    2a25_files.txt:     list of files associated with the program
    2a25_functions.txt: description of each function
    2a25_variables.txt: input and output variables
    2a25_log.txt:       description of major changes in Ver. 5.53
	README_2A25:        This file
    CAVEATS_2A25:       Caveats 

Running the program :

   i.  Set the environment variable TSDISTK to the appropriate path to the toolkit.
       For example, 'setenv TSDISTK /data/tsdis/toolkit/toolkit_4.7b1'
  ii.  Modify the makefile '2a25v5.53.make' to your machine.
       This modification includes the paths to the hdf and toolkit libraries
       and include files.  
 iii.  type: make -f 2a25v5.53.make 
  iv.  type: 2a25v5.53 <1C-21 file> <2A-21 file> <2A-23 file> <2A-25 file> <VI file>

         for example:
            2a25v5.53  1C21.19980420.02263.5.HDF \
                       2A21.19980420.02263.5.HDF \
                       2A23.19980420.02263.5.HDF \
                       2A25.19980420.02263.5.HDF \
                       2A25.19980420.02263.5.VI

/* ------------------------------------------------ */
   Description of TRMM PR algorithm 2A-25, Ver. 5.53
/* ------------------------------------------------ */

Name of contact: 
      Toshio Iguchi
      Communications Research Laboratory 
      Global Environment Division
      4-2-1 Nukui-Kitamachi, Koganei, Tokyo 184-8795, Japan
      Phone: +81-42-327-7543
      Fax:   +81-42-327-6666
      e-mail: iguchi@crl.go.jp

Objectives:
	The primary objecive of 2A-25 is to compute the
	instantaneous rainfall rate and attenuation-corrected
	radar reflectivity factor at each radar resolution cell
	in rain areas.

Processing flow:

  Note: To calculate the non-uniformity parameter over 3 by 3 
	IFOVs, it is necessary to read and process some of the data 
	one scan ahead and to retain them.  In the description of 
	processing flow below, I do not include this time-lagged
	processing in order to clarify the main flow and to avoid
	the confusion. In the actual processing, steps from 5 to 18
	are carried out one scan ahead.  The original and processed 
	data in these steps are kept for the processing of the following 
	scan.  Instead, if you prefer, you can consider that steps from
	19 to 37 are lagged by one scan from steps from 5 to 18.

  0. Check the consistency of the command line.
	This process consists of checking the number of command line
	arguments and possible file name collision.
	
  0'. Open the verification intermediate (VI) file.

  1. The program opens all input and output data files.
	It then checks in function checkMetaData() the algorithm ID's 
	of input files and the orbit size and the begin/end date/time of input data.
	If any of the algorithm IDs is wrong, the program terminates
	with an error message.  If the orbit size or the begin/end time
	of the input data do not match, a warning message is produced.
	The orbit size for processing 2A-25 is set to the minimum of
	the orbit sizes among all input files.

  2. The necessary meta data in 2A-25 output is read 
	from the meta data in 1C-21 input file, and retained in
	an output buffer.

  3. Header information in 1C-21 is read, and 'rayStart', 
	'mainlobeEdge' and 'sidelobeRange' are kept in the program.

  4. Read the input parameters used in the program.  The parameters 
	are given in the parameter files 'parameters_3.dat' and 
        'param_error_3.dat'.

--- Repeat the processes from 5 to 37 for all scans. ----

  5. Read the input data (1C-21, 2A-21, 2A-23) scan by scan. 
	For each scan, the following processings are carried out.

  6. Check the scan status in 1C-21.

  7. Calculate the range bins of the surface, rain top and rain bottom
	to define the region to be processed.

  8. Set status flag for each IFOV.

  9. Calculate the range bins of ellopsoid, bright band, 2 km, 4 km,
	Z maximum, and 0C level. The value of Z maximum itself in rain 
	is also selected here.

  10. Calculate the k-Z parameters (alpha and beta).
	'alpha' is a range dependent parameter. The initial values of
	alpha at 5 nodes and that of beta are chosen from the parameter
	list according to the rain type.  The nodes are calculated from
	the rain type and the altitudes of storm height, 0C level esitimate
	or BB height (if it exists), and Z maximum.

  11. Interpolate the values of alpha at 5 nodes for all range bins.

  12. Calculate zeta = Integral of 0.2*ln(10)*beta*alpha*Z^beta.
	Integral is from the rain top to the rain bottom (= lowest 
	altitude free from ground clutter). 'zeta' is an index of attenuation.

  13. The range at which the integral of 0.2*ln(10)*beta*alpha*Z^beta
	from the rain top fist exceeds the given threshold is chosen while
	'zeta' is calculated.  This range corresponds to the bin number
	in 'rangeBinNum[][4]' and is used in the calculation of
	'thickThPIZ[nray]'.

---	If the IFOV is a rain bin, do 14 to 17.  If not, skip them. ---

  14. Calculate an independently estimated path-integrated attenuation
	(PIA) 'pia0' from either the decrease in surface cross section given 
	by 2A-21 (if this is reliable) or the constant-Z-near-surface assumption 
	(if the former is not reliable).

  15. The constant-Z-near-surface method calculates the PIA in such 
	a way that if this PIA is used for the attenuation correction 
	in the surface reference method, the resultant (attenuation-corrected)
	Z profile near the surface (bottom 5 range bins) becomes approximately
	constant.  'Approximately constant' here means that the regression 
	line for the bottom 5 points becomes constant.  If the PIA obtained
	by this method appears to be negative, it is set to 0.

  16. Find the best estimate of the path-integrated attenuation and
        the corresponding zeta 'zeta=cr' from 'zeta' and 'pia0'.

  17. Calculate the correction factor 'epsilonf'.

  18. Calculate the weighting factor.

  19. Calculate 'zeta_mn', 'zeta_sd', 'zeta_dev' and 'xi'.
	'zeta_mn' is the mean of zeta over 3 by 3 IFOVs.
	'zeta_sd' is the standard deviation of zeta over 3 by 3 IFOVs.
	'zeta_dev' is the deviation of zeta from the mean 'zeta_mn'.
	'xi' is the normalized standard deviation of zeta.

  20. Calculate 'pia_mn', 'pia_sd', 'pia_est' and 'nsd_l'.
	'pia_mn' is the mean of 'pia_est' over 3 by 3 IFOVs.
	'pia_sd' is the standard deviation of 'pia_est' over 3 by 3 IFOVs.
	'pia_est' is the estimated PIA from 'zeta_cr' obtained in step 18.
	'nsd_l' is the normalized standard deviation of 'pia_est'.

  21. Calculate the non-uniform beam filling correction factors;
	'nubfCFs' for surface attenuation, and 'nubfCFzr' for Z-R
	relationship from 'pia_est', 'pia_mn', 'nsd_l', and 
	rain type ('stormtype'). 

  22. Modify the surface attenuation given by 2A-21 with the 
	NUBF correction factor for aurface attenuation 'nubfCFs'.

---	If the IFOV is a rain bin, do 23 to 29.  If not, skip them. ---

  23. With this modified surface attenuation, repeat the procedure
	from 14 to 17 again.

  24. Using the correction factor 'epsilonf' obtained in this 
	second iteration, calculate the attenuation corrected Z factors.

  25. Calculate the Z-R parameters (a and b) in R=a*Z^b.
	Both 'a' and 'b' are range dependent. They are also adjusted by
        the value of 'epsilonf'. Their initial values 
	at 5 nodes are chosen from the parameter list according to 
	the rain type.  The nodes are calculated from
	the rain type and the altitudes of storm height, 0C level esitimate
	or BB height (if it exists).

  26. Set a reliability parameter 'reliab' for the estimates of
	rainfall rate 'rain' and Z-factor 'correctZFactor' at each range bin.

  27. Redefine Z to 0 dB if Z < 0 dB.

  28. Calculate the average rainfall rate between 2 and 4 km.
	Only the data free from noise or clutter are used in this process.

  29. Estimate the error budget.

  30. Assign output parameters to default values if no rain.

  31. Assign quality flag to each IFOV.

  32. Assign rain flag to each IFOV.

  33. Assign method flag to method for each IFOV.

  34. Assign the output variables to the output structure.
	In this stage, the range bin numbers in the input arrays 
	are rearranged so that each IFOV consists of 80 range bins
	with the last element corresponds to the earth's ellipsoid
	surface.

  35. Geolocation data are copied from 1C-21 to 2A-25 output 
	structure.

  36. Scan time structure in 1C-21 is copied to 2A-25 output sturcture.

  37. Write one scan of 2A-25 output scan data in the output file.

--- This is the end of data processing for one scan of data. ----

  38. Write the algorithm ID and the orbit size 
	in the meta data of the output file.

  39. Close the input and output files.

  40. Close the VI file.

Note.
    The description above is an outline of the processing flow. 
    Details of the algorithm including error estimation is described 
    in a separate document.
/* -------------------------------------------------- */
   Files related to TRMM PR algorithm 2A-25, Ver. 5.53
/* -------------------------------------------------- */

Name of contact: 
      Toshio Iguchi
      Communications Research Laboratory 
      Global Environment Division
      4-2-1 Nukui-Kitamachi, Koganei, Tokyo 184-8795, Japan
      Phone: +81-42-327-7543
      Fax:   +81-42-327-6666
      e-mail: iguchi@crl.go.jp

Source files (29 files):

	2a25v5.53.c            2A-25 MAIN
	alpha_coef.c           K-Z COEFFICIENTS
	checkMetaData.c        CHECK METADATA
	epsilonf2.c            SURFACE ATTENUATION CORRECTION FACTOR EPSILON
	epsilon_n3.c           SURFACE ATTENUATION CORRECTION FACTOR EPSILON
	error_est_2.c          2A-25 OUTPUT ERROR ESTIMATES
	kzpara_3.c               K-Z COEFFICIENTS
	maxInArray.c           MAXIMUM SEARCH ROUTINE
	method.c               METHOD OF RETRIEVAL
	nsd_pia.c              CALCULATION OF NSD OF ESTIMATED PIA
	nubfFactor4.5.c        NON-UNIFORM BEAM FILLING CORRECTION FACTOR
	pathIntZ_b.c           CALCULATION OF PATH INTEGRATED ZM
	piastnorm.c            PIA FROM THE CONSTANT-Z-NEAR-SURFACE CONDITION
	quality_f.c            QUALITY FLAG
	rainAverage.c          RAIN AVERAGE ROUTINE
	rain_flag.c            RAIN FLAG
	rangeBinNum1r4.c       RANGE BINS FOR SURFACE, RAIN TOP, and BOTTOM
	rangeBinNum2r3.c       RANGE BINS FOR BRIGHT BAND, Z MAX, 2 km and 4 km.
	read_error_p3.c         READ INITIAL PARAMETERS FOR ERROR ESTIMATION
	read_param_3.c         READ INITIAL PARAMETERS
	reliab_vp_r2.c         RELIABILITY FLAG ASSIGNMENT AT EACH RANGE BIN
	report_error.c         REPORT ERROR AND WARNING
	setStatusIFOV.c        SET STATUS FLAG FOR EACH IFOV
        sidelobe_remove.c      REMOVE SIDELOBE PEAKS IN THE INPUT DATA
	surfatten.c            SURFACE ATTENUATION WITH NUBF CORRECTION
	zestimate_2.c          ESTIMATION OF TRUE Z-FACTOR
	zetacalc_d.c           CALCULATION OF ZETA
	zetast.c               STATISTICS OF ZETA
	zrpara.c               Z-R COEFFICIENTS
	ztor.c                 CONVERSION FROM Z TO R

Parameter files (2 files):

	param_error_3.dat      Parameter Errors in dB 
	parameters_3.dat       Parameters used in the program

Include files (5 files):

	TS_2A25_30.h           Defines error/warning indices
	2a25v5.53.h            Defines function prototypes
	2a25_bin_num.h         Defines bin numbers in 1C-21
	error_p_3.h            Defines sturcture st_error_p
	raintype.h             Defines raintypes matched with 2A-23

Message file (1 file):

	TS_30                  TSDIS error message file for 2A-25

Make file (1 file):

    2a25v5.53.make

Input files (3 files):

	1C-21 HDF data file
	2A-21 HDF data file
	2A-23 HDF data file

Output files (2 files):

	2A-25 HDF data file
	VI file

/* ------------------------------------------------ */
   Description of functions used in
   TRMM PR algorithm 2A-25, Ver. 5.3
/* ------------------------------------------------ */

Name of contact: 
      Toshio Iguchi
      Communications Research Laboratory 
      Kashima Space Research Center
      893-1 Hirai, Kashima, Ibaraki 314-0012, Japan
      Phone: +81-299-84-7117
      Fax:   +81-299-84-7157
      e-mail: iguchi@crl.go.jp

-------------------------------------------------------
            description of functions
-------------------------------------------------------


==> 2a25v5.53.c <==
/**********************************************************
FUNCTION: int main()
SOURCE FILE: 2a25v5.53.c
TITLE: TRMM PR LEVEL 2, 2A-25 MAIN
PURPOSE: Estimate rain profiles form 1C-21, 2A-21, and 2A-23.
CALLING SEQUENCE:
    (I) int argc        : (number of command line strings)
    (I) char *argv[]    : see the note below
RETURN: normal=0
NOTE: This file 2a25v5.53.c contains the main() of 2A25.
    argv[0]: program name (2a25v5.5)
    argv[1]: input file name from 1C-21
    argv[2]: input file name from 2A-21
    argv[3]: input file name from 2A-23
    argv[4]: output file name from this program (2A25)
    argv[5]: verification intermediate (VI) file name
************************************************************/


==> alpha_coef.c <==
/**********************************************************
FUNCTION: int alpha_coef()
FILE NAME: alpha_coef.c
TITLE: TRMM PR 2A-25, K-Z COEFFICIENTS 
PURPOSE: Calculate the coefficient alpha in 
    the k-Z relation, k=alpha*Z^beta, at each range bin.
CALLING SEQUENCE:
    (I) int   rbinNode[][5]  : range bin numbers of the nodes.
    (I) float alphaNode[][5] : alpha values at nodes.
    (O) float alpha[][5]     : alpha at each range bin
RETURN: normal=0
NOTE:
    This routine calculates the nominal k-Z coefficient alpha  
at each range bin by interpolating the values in alphaNode[][5].
************************************************************/


==> checkMetaData.c <==
/**********************************************************
Version 5.3 of 2A25

FUNCTION: int checkMetaData()
SOURCE FILE: checkMetaData.c
TITLE: CHECK METADATA
PURPOSE: Check consistency of metadata in the input files
CALLING SEQUENCE:
    (I) IO_HANDLE *granuleHandle1C21
    (I) IO_HANDLE *granuleHandle2A21
    (I) IO_HANDLE *granuleHandle2A23
    (I) FILE      *out_debug
    (O) int       *norbit
RETURN: normal = 0
************************************************************
Note: Whenever TKreportError() is called, the process is
supposed to stop.  In the old Toolkit, however, it did not.
In order to give a proper error message in such a case,
I decided not to erase "n_err++;" lines after 
TKreportError() lines. (Sept. 8, 1997)
************************************************************/


==> epsilon_n3.c <==
/**********************************************************
Version 5.53 of 2A25 

FUNCTION: int epsilon_n3()
SOURCE FILE: epsilon_n3.c
TITLE: TRMM PR 2A-25, Z-R COEFFICIENTS
PURPOSE: Find the best estimate of the attenuation correction factor, epsilon 
FILE NAME: epsilon_n3.c
CALLING SEQUENCE:
int epsilon_n3(
    (I) float dsigma0      : delta sigma0 from 2A21 (+modification)
    (I) float zeta         : zeta
    (I) float beta         : beta in k = alpha Z^beta 
    (I) float stddev_sigma : standard deviation of dsigma0
    (I) float stddev_zeta  : standard deviation of zeta
    (I) float zeta_thresh  : threshold above which this minimization works
    (O) float *dsigma0_out : estimated dsigma0
    (O) float *zeta_out    : estimated zeta
    (O) float *dist        : normalized distance from obs. pt to solution
    (O) float *dsigma0_error : estimated error in dsigma0_out
RETURN: normal=0, 
1: zeta less than the threshold
2: dsigma0 larger than the threshold
3: minimization routine does not converge
************************************************************/


==> error_est_3.c <==
/**********************************************************
Version 5.53 of 2A25 

FUNCTION: int error_est_3()
SOURCE FILE: error_est_3.c
TITLE: TRMM PR LEVEL 2, 2A-25 OUTPUT ERROR ESTIMATES
PURPOSE: Estimate relative errors in the estimates.
CALLING SEQUENCE:
    (I) float z_est          : Estimated Z-factor in dB 
    (I) float dsigma0_err    : Estimated error in PIA estimate in dB 
    (I) float zr_b           : power in Z-R relation 
    (I) int   stormtyp_o     : rain type from 2A23
    (I) int   rbinBB         : range bin number of the bright band 
    (I) float lprate         : 1/20 of lapse rate per 250 m (one range bin) 
    (I) st_error_p *error_p  : error parameter structure 
    (O) float *error_Z       : Relative error (dB) in Z estimate
    (O) float *error_R       : Relative error (dB) in R estimate
RETURN: normal=0
************************************************************/


==> kzpara_4.c <==
/**********************************************************
Version 5.53 of 2A25 

FUNCTION: int kzpara_4()
SOURCE FILE: kzpara_4.c
TITLE: TRMM PR 2A-25, K-Z COEFFICIENTS
PURPOSE: Calculate k-Z coefficients alpha and beta at the nodes 
    from storm type and height: k=alpha*Z^beta.
CALLING SEQUENCE:
(I) int   *rbinTop        : start range bin number 
(I) int   *rbinBottom     : end range bin number
(I) int   *stormtyp       : rain type from 2A-23 / 10
(I) int   *stormtyp_o     : rain type from 2A-23 (original)
(I) int   *flag_warm      : warm rain flag from 2A-23
(I) int   *rbinBB         : range bin number of bright band from 2A-23
(I) int   *rbin0C         : range bin number of freezing level
(I) float alpha_init[][5] : initial values of alpha
(I) float beta_init[]     : initial values of beta
(I) float lprate          : 1/20 of the lapse rate per 1 range bin (250 m)
(O) int   rbinNode[][5]   : rnage bin numbers of nodes
(O) float alphaNode[][5]  : alpha at nodes
(O) float *beta           : beta 
RETURN: normal=0
************************************************************/
/* Note: stormtyp is the storm type defined in 2A23 divided by 10: 
                        other=0, strat=1, conv=2, other=3.
         raintype is the rain type defined in 2A25: 
                        strat=0, conv=1, others=2.
Do not confuse them. In particular, OTHER=0, but OTHERS=2 */
/*----------------------------------------------------------
V5.53:
Unless a bright-band exists, the k-profle is now constant
around the 0C height in the new routine.
A new variable *stormtyp_o (original storm type from 2A23) is
introduced but not used in this version.  It is anticipated 
that in the next version further classification of k-Z coefficients
according to the fine rain type classification will be used.
-----------------------------------------------------------*/


==> maxInArray.c <==
/**********************************************************
Version 5.1 of 2A25 

FUNCTION: int maxInArray()
SOURCE FILE: maxInArray.c
TITLE: TRMM PR 2A-25, MAXIMUM SEARCH ROUTINE
PURPOSE: Find the maximum in an array within the range of 
    index between nstart and nend.
CALLING SEQUENCE:
    (I) float *data   : input array data
    (I) int    nstart : start index number to look for the maximum
    (I) int    nend   : end index number to look for the maximum
    (O) float *datamax: maximum of data[i] for nstart<=i<nend
    (O) int   *nmax   : index of array for which *datamax = data[nmax]
RETURN: 0=normal      : Maximum occurs inside the interval.
        1             : Maximum occurs at the beginning end point.
        2             : Maximum occurs at the last end point.
NOTE 1: To shorten the process time, I am not going to include 
a routine that checks the possibility that the maximum value is 
taken at more than one points.
NOTE 2: The array index in this routine changes from 
nstart (inclusive) to nend-1 and does not include nend.
************************************************************/

/* File name: maxinarray.c()
This routine return the max value 'datamax' and its index 'nmax' in 
the array data[nstart..(nend-1)].
In orther words, *datamax = max(data) = data[*nmax].
If datamax occurs at more than one points, the least index among them
will be set to nmax.
*/


==> method.c <==
/**********************************************************
Version 5.1 of 2A25 

FUNCTION: int method_p()
SOURCE FILE: method.c
TITLE: TRMM PR 2A-25, METHOD OF RETRIEVAL 
PURPOSE: Indicate the method used in retrieving the rain profile.
CALLING SEQUENCE:
    (I) int   flag_rnr    : rain/no-rain flag
    (I) int   flag_surf   : 0 = ocean, 1 = others
    (I) int   flag_norm   : flag from the constant-Z method
    (I) int   flag_epsi   : epsilon flag
    (I) int   flag_attn   : surface attenuation flag after NUBF correction > 60 dB.
    (I) int   status_nubf : NUBF correction status
    (I) int   status_ifov : IFOV missing data status
    (I) float reliab_s0   : reliability of sigma^0 decrease 
    (I) float nubfCFs     : NUBF correction factor for PIA
    (O) int   *flag_mthd  : output method flag
RETURN: normal=0
************************************************************/
/*-----------------------------------------------------------------
V5.3
    The 15th bit of *flag_rain is set (+16384) if status_ifov=0,
    regardless of the rain condition. 
------------------------------------------------------------------*/
/*-----------------------------------------------------------------
    The definition of the output flag as well as input parameters
    were changed in Version 4.0.
------------------------------------------------------------------*/
            

==> nsd_pia.c <==
/**********************************************************
Version 5.1 of 2A25 

FUNCTION: int nsd_pia()
SOURCE FILE: nsd_pia.c
TITLE: TRMM PR 2A-25, CALCULATION OF NORMALIZED STANDARD
    DEVIATION (NSD) OF ESTIMATED PIA
PURPOSE: Calculate the following quantities from zeta_cr.
    This function calculates 
    estimated PIA      pia_est[i],
    mean               pia_mn[i], 
    standard deviation pia_sd[i], and
    normalized s.d.    nsd_l[i],
    (i=0..48)
    of pia_est=-10*(log10(1.0-zeta_cr))/beta 
    from zeta_cr[0..2][0..48].  
    pia_est is an estimate of the attenuation factor in dB.
    PIA: Path-Integrated Attenuation (2 ways)
CALLING SEQUENCE:
    (I) int   ifirstscan            : first scan number
    (I) int   ilastscan             : last scan number
    (I) int   jscan                 : present scan number
    (I) int   status_ifov[][NANGLE] : input data status of ifov
    (I) float zeta_cr[][NANGLE]     : zeta parameter (corrected)
    (I) float *beta                 : beta in k-Z relation
    (O) float *pia_mn               : mean of pia_est
    (O) float *pia_sd               : standard deviation of pia_est
    (O) float *pia_est              : estimated PIA from zeta_cr 
    (O) float *nsd_l                : normalized standard deviation of PIA
    (O) int   *flag_nsd             : status flag of nsd
RETURN:
    0: no valid data of nsd in the scan
    else: number of valid ifov's for nsd in the scan
************************************************************/


==> nubfFactor4.5.c <==
/**********************************************************
Version 5.5 of 2A25 

FUNCTION: int nubfFactor()
SOURCE FILE: nubfFactor4.5.c
TITLE: NON-UNIFORM BEAM FILLING CORRECTION FACTOR
PURPOSE: Calculate the non-uniform beam filling correction factor.
CALLING SEQUENCE:
    (I) float *pia_est     : first estimate of PIA 
    (I) float *pia_mn      : mean of PIA over 3x3 boxes
    (I) float *nsd_l       : normalized s.d. of PIA (low res.)
    (I) int   *flag_nsd    : flag of nsd_l
    (I) int   *stormtype   : storm type
    (I) float *nsd_cnv     : conversion factor of NSD from l to h
    (I) float *nubf_cf     : conversion coefficients for nubfCFs 
    (O) float *nubfCFs     : NUBF correction factor for surface atten.
    (O) float *nubfCFzr    : NUBF correction factor for Z-R relation
    (O) int   *status_nubf : NUBF correction status
RETURN: normal=0
************************************************************/
/* V5.5: The maximum of the NUBF correction factor for surface
attenuation is reduced to 1.3.
*/


==> pathIntZ_b.c <==
/**********************************************************
Version 5.1 of 2A25

FUNCTION: int pathIntZ_b()
FILE NAME: pathIntZ_b.c
TITLE: CALCULATION OF PATH INTEGRATED ZM
PURPOSE: Calculate the integral of alpha*Zm^beta for a given
   interval [rangebin1, rangebin2].
CALLING SEQUENCE:
    (I) float  *zm          : measured apparent Z factor
    (I) float  *alpha       : k-Z coefficient alpha k=alpha*Z^beta
    (I) float  beta         : k-Z coefficient beta
    (I) int    rangebin1    : range bin Top
    (I) int    rangebin2    : range bin Bottom
    (I) float  h            : range resolution
    (I) float  threshPIZ    : threshold for rbinThPIZ
    (O) float  *pintz       : integral of alpha*Zm^beta
    (O) float  *zeta_beta   : integral of alpha*Zm^beta*ln(Zm)
    (O) int    *rbinThPIZ   : bin where zeta exceeds threshPIZ
RETURN: 0: if the integral does not exceed the threshold.
        1: if the integral exceeds the threshold.
************************************************************/

/***********************************************************
*rbinThPIZ is the range bin number at which the integral of
alpha * zm^beta first exceeds the threshold threshPIZ.
***********************************************************/


==> piastnorm.c <==
/**********************************************************
Version 5.5 of 2A25 

FUNCTION: int piastnorm()
SOURCE FILE: piastnorm.c
TITLE: TRMM PR 2A-25, PATH INTEGRATED ATTENUATION FROM
    THE CONSTANT Z NEAR SURFACE CONDITION.
PURPOSE: Calculate the path integrate attenuation assuming
    that the true Z-factor near the surface is constant.
FILE NAME: piastnorm.c
CALLING SEQUENCE:
    (I) float *zm       : measured Z-factor 
    (I) float *alpha    : alpha in k = alpha*Z^beta 
    (I) float *beta     : beta  in k = alpha*Z^beta 
    (I) int   rangebin1 : start range bin number 
    (I) int   rangebin2 : end reange bin number
    (I) float res       : range resolution
    (O) float *pian     : estimated PIA 
RETURN: 
    0: normal
    1: not enough range bins in rain interval
    2: not enough range bins that continuously exceed the threshold
    3: slope of Zm profile is positive
************************************************************/

/*-------------------------------------------------------------------------- 
    This routine estimates the attenuation near the surface
    by using a bold assumption that the decrease of apparent Z 
    near the surface is totally caused by the attenuation.  
    In other words, the true Z is assumed to be constant near the surface.

    We use NSBIN=5 range bins of data near the surface to fit a straight line.
    If there are not enough data, the attenuation is assumed to be 0.  
    Since PIA is the attenuation factor (=10^(-attenuation(dB)/10)),
    the attenuation factor (PIA) is set to 1 and
    the output flag is set to a non-zero value in such a case.
-----------------------------------------------------------------------------*/
/* A bug was removed on 16 May 1999: 
     slope = (sty/stt)/(2*res); ---> slope = (sty/stt)/res;
because res in this program is 0.25 km from the beginning.
*/


==> quality_f.c <==
/**********************************************************
Version 5.53 of 2A25 

FUNCTION: int quality_flag()
SOURCE FILE: quality_f.c
TITLE: TRMM PR 2A-25, QUALITY FLAG
PURPOSE: Define the quality flag q_flag. 
CALLING SEQUENCE:
    (I) int   flag_rnr      : rain/no-rain flag
    (I) int   flag_ave      : flag from averaging
    (I) int   flag_xi       : xi flag
    (I) int   flag_nsd      : NSD flag
    (I) int   flag_epsi     : epsilon flag
    (I) int   flag_2a21     : reliability of PIA from 2a21
    (I) int   flag_2a23     : reliability flag from 2a23
    (I) int   flag_rbin     : flag from range bin calculation
    (I) int   flag_sidelobe : sidelobe removal
    (I) int   status_ifov   : ifov status flag
    (I) int   status_epsi   : convergence status in epsilon_n3
    (O) int   *q_flag       : output quality flag
RETURN: normal=0
************************************************************/
/*-----------------------------------------------------------------
V5.53
    The 11th bit of *flag_rain is set (+1024) if status_epsi=3
------------------------------------------------------------------*/
/*-----------------------------------------------------------------
V5.3
    The 15th bit of *flag_rain is set (+16384) if status_ifov=0,
    regardless of the rain condition.
------------------------------------------------------------------*/
/*--------------------------------------------------------------
    The sidelobe clutter flag is added at the 10th bit in V5.2.
    "flag_sidelobe" is a new input parameter to this function.

    The definition of the output flag as well as input parameters
    were changed in Version 4.0.

 *q_flag 
       0: normal
      +1: unusual situation in rain average
      +2: mean of zeta too small for NSD (xi) calculation
      +4: NSD of zeta (xi) calculated from less than 6 points
      +8: mean of PIA too small for NSD (PIA) calculation
     +16: NSD of PIA calculated from less than 6 points
     +32: epsilon not reliable (sigma0 marginally reliable)
     +64: 2A21 input data not reliable
    +128: 2A23 input data not reliable
    +256: range bin error
    +512: sidelobe clutter removal

==> rainAverage.c <==
/**********************************************************
Version 5.1 of 2A25 

FUNCTION: int rainAverage()
SOURCE FILE: rainAverage.c
TITLE: TRMM PR 2A-25, RAIN AVERAGE ROUTINE
PURPOSE: Calculate the average rainfall rate betwenn the 
    two specified range bins, nstart and nend.
CALLING SEQUENCE:
    (I) float *rr        : input array of rainfall rate
    (I) int   nstart     : start range bin number of the average interval.
    (I) int   nend       : end range bin number of the average interval. 
    (I) int   rbinBottom : range bin no. of the lowest level processed. 
    (O) float *rainave   : average rainfall rate in the interval
RETURN: 
     0: normal
     1: rbinBottom is above 2 km
     2: no valid data between 2 and 4 km
NOTE 1: The array index in this routine changes from 
nstart (inclusive) to nend-1 and does not include nend.
************************************************************/

            

==> rain_flag.c <==
/**********************************************************
Version 5.5 of 2A25 

FUNCTION: int rain_flag()
TITLE: TRMM PR 2A-25, RAIN FLAG
PURPOSE: Define the output rain flag, flag_rain. 
CALLING SEQUENCE:
    (I) int   flag_rnr   : rain/no-rain flag
    (I) int   flag_ave   : average rain flag
    (I) int   stormtyp   : stormtype from 2a23
    (I) int   rbinBB     : range bin number of BB from 2a23
    (I) int   flag_warm  : warm rain flag from 2a23
    (I) int   flag_th    : PIZ threshold flag
    (I) float zeta       : zeta
    (I) float zeta_th    : threshold for zeta
    (I) float flag_ovf   : rain rate larger than the upper limit 
    (I) int   status_ifov: ifov missing data status
    (O) int   *flag_rain : output rain flag
RETURN: normal=0
************************************************************/
/*-----------------------------------------------------------------
V5.5
    The 11th bit of *flag_rain is set if flag_ovf != 0.
------------------------------------------------------------------*/
/*-----------------------------------------------------------------
V5.3
    The 15th bit of *flag_rain is set (+16384) if status_ifov=0,
    regardless of the rain condition. 
------------------------------------------------------------------*/
/*-----------------------------------------------------------------
    The definition of the output flag as well as input parameters
    were changed in Version 4.0.
------------------------------------------------------------------*/
            

==> rangeBinNum1r4.c <==
/**********************************************************
Version 5.5 of 2A25 

FUNCTION: int rangeBinNum1r4()
SOURCE FILE: rangeBinNum1r4.c
TITLE: RANGE BINS FOR SURFACE, RAIN TOP, and 
       BOTTOM PROCESSED.  
PURPOSE: Obtain the range bins of the rain top, the surface and 
        the lowest height down to which we process the data.
CALLING SEQUENCE:
    (I) L1C_21_SWATHDATA  *L1C21_data 
    (I) int *binStart        : start range bin number in the input data
    (O) int *rbinSurf        : range bin number of the surface
    (O) int *rbinTop_m       : range bin number of the rain top (main)
    (O) int *rbinTop_c       : range bin number of the rain top certain
    (O) int *rbinBottom      : lowest range bin number of valid data
    (O) int *rbinFlag        : error flag from this routine
RETURN: normal=0
NOTE: binSurfPeak is given in 125 m resolution.
      mlclutter is in 250 m resolution.
      rbinBottom is the lowest range bin number down to which
      the data are assumed meaningful and below which the data 
      are possibly contaminated by the main-lobe clutter.
      All output range bin numbers are in 250 m resolution.
Log: The definition of rbinBottom changed on 16 Dec. 1997.
************************************************************/
/* ----------------------------------------------------------
   In v5.5, rbinTop_m[] is introduced. rbinTop_m[] is defined as
2 range bins above rbinTop_c[] (top of the rain certain range).  
This is the top of range processed in the main program in v5.5. 
   The rbinBottom is raised by one if rbinBottom is equal to NRANGE.
This condition should not be met in normal conditions.
This chage was made in order to define Z-R coefficient at
rbinBottom. 
--------------------------------------------------------------*/


==> rangeBinNum2r4.c <==
/**********************************************************
Version 5.5 of 2A25 

FUNCTION: int rangeBinNum2r4()
SOURCE FILE: rangeBinNum2r4.c
TITLE: RANGE BINS FOR BRIGHT BAND, Z MAX, 2 km and 4 km.
PURPOSE: Obtain the range bins of the bright band, measured Z
        maximum, and altitudes 2 km and 4 km, and estimated
        freezing height.
CALLING SEQUENCE:
    (I) L1C_21_SWATHDATA  *L1C21_data
    (I) L2A_23_SWATHDATA  *L2A23_data
    (I) int   *binStart    : start range bin number in the input data
    (I) int   *rbinTop     : range bin number of the rain top
    (I) int   *rbinBottom  : lowest range bin number of valid data 
    (I) float *startDist   : distance to the first sample bin
    (I) float fhcf         : freezing height correction factor
    (I) float z_offset     : offset to be added to 1C21 Z-factor in dB
    (O) int   *rbinEllips  : range bin number of the earth ellipsoid 
    (O) int   *rbinBB      : range bin number of the bright band 
    (O) int   *rbin2km     : range bin number of 2 km above the ellipsoid 
    (O) int   *rbin4km     : range bin number of 4 km above the ellipsoid 
    (O) int   *rbinZmax    : range bin number of Zm max 
    (O) float *zmmax       : maximum value of Zm 
    (O) int   *rbin0C      : range bin number of 0 C estimated 
    (O) int   *rbinAttTh   : range bin number of first Zm > atten. theshold 
    (O) int   *rbinFlag2   : status flag  
RETURN: normal=0
  rbinFlag2=0: normal
  rbinFlag2=        LSB ON: something wrong with the ellipsoid range bin.
  rbinFlag2= second bit ON: zenith angle too large.
  rbinFlag2=  third bit ON: error in rbin2km.
  rbinFlag2= fourth bit ON: error in rbin4km. 
  rbinFlag2=  fifth bit ON: error in rbin0C.
  rbinFlag2=  sixth bit ON: error in rbinBB.
NOTE:
  The freezing height correction factor (fhcf) is introduced here 
because the freezing level from 2A-23 is a rather conservative (low end) 
estimate in order to avoid a wrong identification of warm rain.  
2A-25 uses the freezing estimate to determine the k-Z and Z-R coefficients.  
For this purpose, it is probably better to over-estimate the freezing height 
than to under-estimate it.  The current version of 2A-23 uses 5 deg.C/km as 
the lapse rate for the conservative estimate.  We change it to 6 deg.C/km
in this program. Hence the correction factor is 6/5=1.2.  
    The freezing height correction facotr (fhcf) is now written in the 
parameter file.  It is read in the main() and transfered into this function 
as an argument. 
Log: startDist added on 16 Dec. 1997.
************************************************************/


==> read_error_p_3.c <==
/**********************************************************
Version 5.53 of 2A25

FUNCTION: int read_error_param_3()
SOURCE FILE: read_error_p_3.c
TITLE: READ INITIAL PARAMETERS FOR ERROR ESTIMATION
PURPOSE: Read in the initial error parameters
FILE NAME: read_error_p_3.c
CALLING SEQUENCE:
    (I) int   *init_file    : parameter file name
    (I) FILE  *out_debug    : file pointer of the VI file
    (O) st_error_p *error_p : structure of error paramters
    (O) float *stddev_zeta  : nominal error in zeta in dB
    (O) float *stddev_SRT_O : nominal error in SRT over ocean in dB
    (O) float *stddev_SRT_L : nominal error in SRT over land in dB
    (O) float *stddev_SRT_N : nominal error in SRT in constant-Z method in dB
RETURN: 0
NOTE: Each line in the data file consists of four fields:
    enumeration, parameter value, parameter name, and comments.

    The enumeration number in each line is read, but ignored.  
    It is only for easy reference.  
    The parameter names written in the data file must be exactly the 
    same as those in this file.  Otherwise, TKreportError() is called 
    (in the main routine) and the program stops.  
    Comments are totally ignored.  Anything after the third entry
    in each line are regarded as comments.  You do not need to 
    enclose the comments by special symbols.
************************************************************/
/* ---------------------------------------------------------
V5.53: 
The list of probabilities of correct rain type identification
is removed.
*stddev_zeta, *stddev_SRT_O, *stddev_SRT_L, and *stddev_N
are added.
----------------------------------------------------------- */


==> read_param_3.c <==
/**********************************************************
Version 5.1 of 2A25

FUNCTION: int read_parameters_3()
SOURCE FILE: read_param_3.c
TITLE: READ INITIAL PARAMETERS
PURPOSE: Read in the initial parameters
FILE NAME: read_param_3.c
CALLING SEQUENCE:
    (I) int   *init_file  : parameter file name
    (I) FILE  *out_debug  : file pointer of the VI file
    (I) int   nkzpara     : number of k-Z parameters
    (O) float alpha_init[][5] : alpha in k=alpha*Z^beta
    (O) float beta_init[]  : alpha in k=alpha*Z^beta
    (O) float zr_a_c0[][5]  : a in R = a * Z^b
    (O) float zr_a_c1[][5]  : a = 10^(a_c0+a_c1*x+a_c2*x^2)
    (O) float zr_a_c2[][5]  : where x = log10(epsilon) 
    (O) float zr_b_c0[][5]  : b in R = a * Z^b
    (O) float zr_b_c1[][5]  : b = 10^(b_c0+b_c1*x+b_c2*x^2)
    (O) float zr_b_c2[][5]  : 
    (I) int   nvratio     : number of velocity ratios given
    (O) float *vratio     : velocity ratios at 21 heights
    (O) float *lprate     : 1/20 of lapse rate per 250 m
    (O) float *fhcf       : freezing height correction factor
    (O) float *nsd_cnv    : conv. factors of NSD 
    (O) float *nubf_cf    : conv. coefficients for nubfCFs
    (O) float *threshPIZ  : threshold value for PIZ = 1-(0.5)^beta
    (O) float *zeta_th    : threshold for zeta to judge large att. (10 dB)
    (O) float *z_offset   : offset to be added to 1C21 Z factor in dB
RETURN: 0
NOTE: Each line in the data file consists of four fields:
    enumeration, parameter value, parameter name, and comments.

    The enumeration number in each line is read, but ignored.  
    It is only for easy reference.  
    The parameter names written in the data file must be exactly the 
    same as those in this file.  Otherwise, TKreportError() is called 
    (in the main routine) and the program stops.  
    Comments are totally ignored.  Anything after the third entry
    in each line are regarded as comments.  You do not need to 
    enclose the comments by special symbols.
************************************************************/


==> reliab_vp_r2.c <==
/**********************************************************
Version 5.1 of 2A25 

FUNCTION: int reliab_vp_r2()
SOURCE FILE: reliab_vp_r2.c
TITLE: RELIABILITY FLAG ASSIGNMENT AT EACH RANGE BIN
PURPOSE: Assign a reliability parameter for the estimates
of rainfall rate rr[] and Z-factor z_est at each range bin.
CALLING SEQUENCE:
    (I) int   raingebin1   : top range bin for processing.
    (I) int   raingebin2   : bottom range bin for processing.
    (I) int   nrng         : number of total range bins
    (I) int   rbinTop_c    : top range bin for rain certain.
    (I) int   rangebb      : range bin of the bright band center.
    (I) float zm[NRANGE]   : measured Z-factor.
    (I) int   rbinThPIZ    : first range bin for PIZ > Thereshold.
    (I) int   rbinTop_c    : top range bin for rain certian
    (O) int   *reliab_p    : reliability parameter. 
RETURN: normal=0
Note: This function set the lower 5 bits of the byte.
The upper 3 bits are set in the main program.  They are
 32: below 0 dB after noise subtraction.
 64: clutter or below surface
128: missing data
************************************************************/



==> report_error.c <==
/**********************************************************
Version 5.3 of 2A25

FUNCTIONS: int reportMetaIntError()
           int reportMetaCharError()
           int reportScanError() 
           int reportBinError()
SOURCE FILE: report_error.c
TITLE: REPORT ERROR AND WARNING
PURPOSE: Report errors and warnings to operator and 
        write the status in VI file.
CALLING SEQUENCE:
    This file consists of several functions.
    The calling sequence of each function differs from another.
    In general, it receives the following parameters.

    (I) int  alid          : algorithm ID 
    (I) FILE *out_debug    : pointer to the VI file
    (I) int  jscan         : scan number
    (I) int  dummy         : other parameter(s)
RETURN: normal = 0
************************************************************/
/* In v5.3, reportBinError was modified so that the size of
the output message becomes much smaller than the original format. */
/*
The following two lines were removed from reportBinError()
in Ver. 4.5 to keep the operator in peace.
        TKreportWarning(W_2A25_RANGEBIN1ERROR);
        TKreportWarning(W_2A25_RANGEBIN2ERROR);
*/


==> setStatusIFOV.c <==
/**********************************************************
Version 5.2 of 2A25 

FUNCTION: int setStatsuIFOV()
SOURCE FILE: setStatusIFOV.c
TITLE: SET STATUS FLAG FOR EACH IFOV
PURPOSE: Set the status flag for each IFOV
FILE NAME: setStatusIFOV.c
CALLING SEQUENCE:
    (I) L1C_21_SWATHDATA  *L1C21_data
    (I) int    *rbinTop     : range bin Top
    (I) int    *rbinBottom  : range bin Bottom
    (O) int    *status_ifov : status flag of ifov
RETURN: normal=0
        number of invalid IFOV in the scan.
NOTE: If status_ifov=1 : valid = no data is missing.
      If status_ifov=0 : invalid = some data are missing
      between the rain top and bottom.
************************************************************/
/*----------------------------------------------------------
Nothing is changed in Version 5.0 except for the change of
one of the include file names from 2a25v4.6r2.h to 2a25v5.0.h.
-----------------------------------------------------------*/
/*----------------------------------------------------------
Nothing is changed in Version 4.6r2 except for the change of
one of the include file names from 2a25v4.6.h to 2a25v4.6r2.h.
-----------------------------------------------------------*/
/*----------------------------------------------------------
Nothing is changed in Version 4.6 except for the change of
one of the include file names from 2a25v4.5.h to 2a25v4.6.h.
-----------------------------------------------------------*/
/*----------------------------------------------------------
Nothing is changed in Version 4.5 except for the change of
one of the include file names from 2a25v4.0.h to 2a25v4.5.h.
-----------------------------------------------------------*/
/*----------------------------------------------------------
Changes in Version 4.0
1. Z_MISSING was defined as -327.34 before, now it is -32724.0
   1.0 is added to Z_MISSING when compared with data to avoid rouding error.
2. Include file is now 2a25v4.0.h
3. scanStatus is nolonger checked in this routine since it
is not a status of each IFOV but a status of the scan.
-----------------------------------------------------------*/


==> sidelobe_remove.c <==
/**********************************************************
Version 5.2 of 2A25 

FUNCTION: int sidelobe_remove()
SOURCE FILE: sidelobe_remove.c
TITLE: SIDELOBE REMOVAL BY INTERPOLATION
PURPOSE: Remove sidelobe signals by interpolating the profile
        around the possibly cluttered ranges when the nadir
        surface return in the mainlobe is very large.
CALLING SEQUENCE:
    (I) L1C_21_SWATHDATA  *L1C21_data 
    (I) int *binStart        : start range bin number in the input data
    (O) int *flag_sidelobe    : status flag from this routine
RETURN: normal=0
NOTE: This routine rewrite the input data array.
The original code was given by Dr. Awaka.
************************************************************/

#include <IO.h>
#include <IO_PR.h>
#include "2a25_bin_num.h"


		

==> surfatten.c <==
/**********************************************************
Version 5.1 of 2A25 

FUNCTION: int surfatten()
SOURCE FILE: surfatten.c
TITLE: TRMM PR 2A-25, SURFACE ATTENUATION
PURPOSE: Calculate the surface attenuation with the correction
        for non-uniform beam filling effect.
CALLING SEQUENCE:
    (I) float *satten0   : surface attenuation in dB from 2A-21
    (I) float *nubfCFs   : non-uniform beam filling correction factor
    (O) float *satten    : corrected surface attenuation (dB)
    (O) int   *flag_attn : surface attenuation flag after NUBF corr.
RETURN: normal=0
************************************************************/
/*------------------------------------------------------------
flag_attn was added in Version 4.5.
-------------------------------------------------------------*/
/*------------------------------------------------------------
This function calculates 
As from As0.
As0 is the surface attenuation derived from the surface 
reference technique.
As is an estimate of pintz = \int q \alpha Zm ^ \beta dr from As0.
As is used for correcting pintz calculated from measured Zm. 
If rain is horizontally uniform, As = As0.
------------------------------------------------------------*/

/*------------------------------------------------------------
we use satten0 = - 10 log10 (As0) instead of As0. 
nubfCFs is defined as a multiplicative constant to As in dB. 
------------------------------------------------------------*/



==> zestimate_2.c <==
/**********************************************************
Version 5.21 of 2A25 

FUNCTION: int zestimate()
SOURCE FILE: zestimate_2.c
TITLE: TRMM PR 2A-25, ESTIMATION OF TRUE Z-FACTOR
PURPOSE: Estimate true Z-factors 
CALLING SEQUENCE:
    (I) float *zm          : measured Z-factor in linear unit
    (I) float *alpha       : alpha in k = alpha*Z^beta 
    (I) float *beta        : beta  in k = alpha*Z^beta 
    (I) int   rangebin1    : start range bin number 
    (I) int   rangebin2    : end range bin number
    (I) int   nrng         : total range bin number
    (I) float h            : range resolution (0.25 km)
    (I) float epsilonf     : correction factor epsilonf
    (O) float *z_est       : Estimated Z-factor in linear unit
    (O) float *final_atten : PIA estimate from z_est
RETURN: normal=0
************************************************************/
/* A bug in the calculation of final_atten was fixed in v5.21, Aug. 1998. */
/* 
if(zm[] != 0.0) is changed to if(zm[] > 0.0) in line 48 in ver. 4.
*/


==> zetacalc_d.c <==
/**********************************************************
Version 5.2 of 2A25  

FUNCTION: int zetacalc_d()
SOURCE FILE: zetacalc_d.c
TITLE: CALCULATION OF ZETA
PURPOSE: Calculate zeta for one scan.
FILE NAME: zetacalc_d.c
CALLING SEQUENCE:
    (I) L1C_21_SWATHDATA  *L1C21_data : 1C-21 swath data
    (I) int    *rbinTop        : range bin Top
    (I) int    *rbinBottom     : range bin Bottom
    (I) int    *status_ifov    : statuf of IFOV, 1=valid
    (I) float  alpha[][NRANGE] : k_Z coefficient
    (I) float  *beta           : k = alpha * Z^beta
    (I) float  threshPIZ       : threshold for rbinThPIZ
    (I) float  z_offset        : offset to be added to 1C21 Z
    (O) float  **zm            : measured apparent Z factor
    (O) float  *zeta           : integral of alpha*Zm^beta
    (O) float  *zeta_beta      : integral of alpha*Zm^beta*ln(Zm)
    (O) int    *rbinThPIZ      : bin where zeta exceeds threshPIZ
    (O) int    *flag_th        : whether zeta exceeds threshPIZ or not
RETURN: normal=0
NOTE: This function calls a function pathIntZ().
************************************************************/


==> zetast.c <==
/**********************************************************
Version 5.1 of 2A25 

FUNCTION: int zetast()
SOURCE FILE: zetast.c
TITLE: TRMM PR 2A-25, STATISTICS OF ZETA
PURPOSE: Calculate the following quantities from zeta.
    This function calculates 
    mean               zetam[i], 
    standard deviation zetas[i], 
    deviation          zetadev[i] = zeta[i]-zetam[i], and
    normalized s.d.    xi[i],
    (i=0..48)
    from zeta[0..2][0..48].  
CALLING SEQUENCE:
    (I) int ifirstscan            : first scan number
    (I) int ilastscan             : last scan number
    (I) int jscan                 : present scan number
    (I) int status_ifov[][NANGLE] : input data status of ifov
    (I) float zeta[][NANGLE]      : zeta parameter
    (O) float *zetam              : mean of zeta
    (O) float *zetas              : standard deviation of zeta
    (O) float *zetadev            : deviation of zeta from the mean
    (O) float *xi                 : normalized standard deviation of zeta
    (O) int   *flag_xi            : status flag of xi
RETURN:
    0: no valid data of xi in the scan
    else: number of valid ifov's for xi in the scan
************************************************************/


==> zrpara_4.c <==
/**********************************************************
Version 5.53 of 2A25 

FUNCTION: int zrpara_4()
SOURCE FILE: zrpara_4.c
TITLE: TRMM PR 2A-25, Z-R COEFFICIENTS
PURPOSE: Calculate the coefficients in Z-R relation
FILE NAME: zrpara_4.c
CALLING SEQUENCE:
    (I) int   rbinTop      : range bin number of rain top
    (I) int   rbinBottom   : range bin number of rain bottom
    (I) int   rbinEllips   : range bin number of Earth's ellipsoid
    (I) int   stormtyp     : rain type from 2A-23 /10
    (I) int   stormtyp_o   : rain type from 2A-23 (original)
    (I) int   flag_warm    : warm rain flag from 2A-23
    (I) int   rbinBB       : range bin number of bright band
    (I) int   rbin0C       : range bin number of freezing level
    (I) float zr_a_c0[3][5]: a in R = a * Z^b
    (I) float zr_a_c1[3][5]: a = 10^(a_c0+a_c1*x+a_c2*x^2)
    (I) float zr_a_c2[3][5]: where x = log10(epsilon)
    (I) float zr_b_c0[3][5]: b in R = a * Z^b
    (I) float zr_b_c1[3][5]: b = 10^(b_c0+b_c1*x+b_c2*x^2)
    (I) float zr_b_c2[3][5]: 
    (I) float lprate       : 1/20 of the lapse rate per 1 range bin (250 m)
    (I) float *vratio      : ratio of terminal velocity at every km
    (I) float zenith_angle : zenith angle from 1C-21
    (I) float nubfCFzr     : non-uniform beam filling correction factor
    (I) float epsilonf     : attenuation correction factor
    (I) float wght_ZR_corr : weighting factor for ZR correction 
    (O) int   *rbinZRNode  : node range bin numbers of Z-R coefficients
    (O) float zraNode      : value of a at node
    (O) float zrbNode      : value of b at node
    (O) float *a           : a in R = a*Z^b 
    (O) float *b           : b in R = a*Z^b 
RETURN: normal=0
************************************************************/



==> ztor.c <==
/**********************************************************
Version 5.5 of 2A25 

FUNCTION: int ztor_2()
SOURCE FILE: ztor_2.c
TITLE: TRMM PR 2A-25, Z to R
PURPOSE: Convert Z-factor into R (rainfall rate)
CALLING SEQUENCE:
    (I) float *zest     : Estimated true Z-factor 
    (I) float *a        : a in R = a*Z^b 
    (I) float *b        : b in R = a*Z^b 
    (I) int   rangebin1 : start range bin number 
    (I) int   rangebin2 : end reange bin number
    (O) float *rr       : Rainfall rate
RETURN: normal=0
************************************************************/
/*----------------------------------------------------------
V5.5
   The upper limit of rain rate is set to MAX_RAIN in V5.5.
If the estimated rainfall rate exceeds this value, it is
redefined as MAX_RAIN and the function returns non-zero value.
-----------------------------------------------------------*/

* ------------------------------------------------ */
   Description of input and output variables
   used in TRMM PR algorithm 2A-25, Ver. 5.53
/* ------------------------------------------------ */

Name of contact: 
      Toshio Iguchi
      Communications Research Laboratory 
      Global Environment Division
      4-2-1 Nukui-Kitamachi, Koganei, Tokyo 184-8795, Japan
      Phone: +81-42-327-7543
      Fax:   +81-42-327-6666
      e-mail: iguchi@crl.go.jp

Source files:

    2a25v5.53.c            2A-25 MAIN
    alpha_coef.c           K-Z COEFFICIENTS
    checkMetaData.c        CHECK METADATA
    epsilon_n3.c           SURFACE ATTENUATION CORRECTION FACTOR EPSILON
    error_est_3.c          2A-25 OUTPUT ERROR ESTIMATES
    kzpara_4.c             K-Z COEFFICIENTS
    maxInArray.c           MAXIMUM SEARCH ROUTINE
    method.c               METHOD OF RETRIEVAL
    nsd_pia.c              CALCULATION OF NSD OF ESTIMATED PIA
    nubfFactor4.5.c        NON-UNIFORM BEAM FILLING CORRECTION FACTOR
    pathIntZ_b.c           CALCULATION OF PATH INTEGRATED ZM
    piastnorm.c            PIA FROM THE CONSTANT-Z-NEAR-SURFACE CONDITION
    quality_f.c            QUALITY FLAG
    rainAverage.c          RAIN AVERAGE ROUTINE
    rain_flag.c            RAIN FLAG
    rangeBinNum1r4.c       RANGE BINS FOR SURFACE, RAIN TOP, and BOTTOM
    rangeBinNum2r4.c       RANGE BINS FOR BRIGHT BAND, Z MAX, 2 km and 4 km.
    read_error_p_3.c       READ INITIAL PARAMETERS FOR ERROR ESTIMATION
    read_param_3.c         READ INITIAL PARAMETERS
    reliab_vp_r2.c         RELIABILITY FLAG ASSIGNMENT AT EACH RANGE BIN
    report_error.c         REPORT ERROR AND WARNING
    setStatusIFOV.c        SET STATUS FLAG FOR EACH IFOV
    sidelobe_remove.c      REMOVE SIDELOBE PEAKS IN THE INPUT DATA
    surfatten.c            SURFACE ATTENUATION WITH NUBF CORRECTION
    zestimate_2.c          ESTIMATION OF TRUE Z-FACTOR
    zetacalc_d.c           CALCULATION OF ZETA
    zetast.c               STATISTICS OF ZETA
    zrpara_4.c             Z-R COEFFICIENTS
    ztor.c                 CONVERSION FROM Z TO R

Parameter files:

    param_error_3.dat      Parameter Errors in dB 
    parameters_3.dat       Parameters used in the program

Include files:

    TS_2A25_30.h           Defines error/warning indices
    2a25v5.53.h            Defines function prototypes
    2a25_bin_num.h         Defines bin numbers in 1C-21
    error_p_3.h            Defines sturcture st_error_p
    raintype.h             Defines raintypes matched with 2A-23

Input files:

    1C-21 HDF data file
    2A-21 HDF data file
    2A-23 HDF data file

Output file:

    2A-25 HDF data file
    VI file

Input swath data from 1C-21 which are used in 2A-25:

    binClutterFreeBottom[][]
    binEllipsoid[]
    binStormHeight[][]
    binSurfPeak[]
    geolocation[][]
    minEchoFlag[]
    normalSample[][]
    scanStatus.dataQuality
    scanStatus.missing
    scanStatus.prStatus2
    scanTime
    scLocalZenith[]
    scRange[]
    

Input swath data from 2A-21 which are used in 2A-25:

    pathAtten[]
    reliabFlag[]
    reliabFactor[]
    sigmaZero[]

Input swath data from 2A-23 which are used in 2A-25:

    rainType[]
    warmRain[]
    status[]
    freezH[]
    HBB[]

Input header data used in 2A-25:

    1C21: rayHdr[].rayStart
          rayHdr[].mainlobeEdge
          rayHdr[].sidelobeRange[]


Metadata used in 2A-25:

    Following parameters in terms of TSDIS toolkit  
    are read from 1C-21, 2A-21 and 2A-23

    TK_ORBIT_SIZE
    TK_ALGORITHM_ID
    TK_BEGIN_DATE
    TK_BEGIN_TIME
    TK_END_DATE
    TK_END_TIME
    TK_FIRST_SCAN_UTC_DATE
    TK_FIRST_SCAN_UTC_TIME
    TK_FIRST_SCAN_UTC_MILLISEC
    TK_LAST_SCAN_UTC_DATE
    TK_LAST_SCAN_UTC_TIME
    TK_LAST_SCAN_UTC_MILLISEC

    Following parameters are written in the output of 2A-25

    TK_ALGORITHM_ID
    TK_ORBIT_SIZE

Output data (in alphabetical order):

    attenParmAlpha[][]    k-Z parameter alpha at 5 nodes
    attenParmBeta[]       k-Z parameter beta 
    attenParmNode[][]     bin numbers of 5 nodes for alpha & beta
    correctZFactor[][]    attenuation-corrected Z factor in dBZ
    epsilon[]             final correction factor for SRT
    geolocation[][]       geolocation
    method[]              method used 
    nubfCorrectFactor[][] non-uniform beam filling correcton factors 
    qualityFlag[]         quality flag
    rain[][]              rainfall rate in mm/h.
    rainFlag[]            status flag for rainfall estimate
    rainAve[][]           average rainfall rate between 2 and 4 km
    rangeBinNum[][]       bin numbers of BB, storm top, etc.
    reliab[][]            reliability of the output
    spare[][]             spare (bin number of surface rain and Z and sigma^0 in v5.3)
    scanTime              scanTime
    thickThPIZ[]          range bin number where PIZ > threshPIZ 
    weightW[]             weight for the calculation of epsilonf 
    xi[][]                normalized standard deviation of PIA 
    zeta[][]              integral of alpha*Zm^beta
    zeta_mn[][]           mean of zeta over 3x3 IFOVs
    zeta_sd[][]           standard deviation of zeta
    zmmax[]               maximum of Zm
    ZRParmA[][]           Z-R parameter a in R=a*Z^b at 5 nodes
    ZRParmB[][]           Z-R parameter b in R=a*Z^b at 5 nodes
    ZRParmNode[][]        bin numbers of 5 nodes for a & b
    nearSurfRain[]        estimated rain rate near surface
    nearSurfZ[]           estimated Z near surface
    pia2a25[]             path-integrated attenuation from final Z
    errorRain[]           error estimate of Z near surface in dB
    errorZ[]              error estimate of rain rate near surface in dB


-----------------------------------------------------------------------

         Detailed description of output variables

------------------------------------------------------------------------

Variable type

nray   = 49,
nbin   = 80,
ncell2 = 5,
ncell3 = 6,
ncell4 = 2.

    float32         rain[nray][nbin];
    int8            reliab[nray][nbin];
    float32         correctZFactor[nray][nbin];
    int16           attenParmNode[nray][ncell2];
    float32         attenParmAlpha[nray][ncell2];
    float32         attenParmBeta[nray];
    int16           ZRParmNode[nray][ncell2];
    float32         ZRParmA[nray][ncell2];
    float32         ZRParmB[nray][ncell2];
    float32         zmmax[nray];
    int16           rainFlag[nray];
    int16           rangeBinNum[nray][ncell3];
    float32         rainAve[nray][ncell4];
    float32         weightW[nray];
    int16           method[nray];
    float32         epsilon[nray];
    float32         zeta[nray][ncell4];
    float32         zeta_mn[nray][ncell4];
    float32         zeta_sd[nray][ncell4];
    float32         xi[nray][ncell4];
    int16           thickThPIZ[nray];
    float32         nubfCorrectFactor[nray][ncell4];
    int16           qualityFlag[nray];
    float32         nearSurfRain[nray];
    float32         nearSurfZ[nray];
    float32         pia2a25[nray];
    float32         errorRain[nray];
    float32         errorZ[nray];
    float32         spare[nray][ncell4];

-----------------------------------------------------------

Definitions of the output variables:

----------------------------------------------------------- 

float32  rain[nray][nbin];
REAL*4   rain(nbin,nray)  

    rainfall rate in mm/h

    49 elements in the 2-D array correspond to the angle bins
    and
    80 elements (first argument in FORTRAN convention) in the 
    2-D array correspond to the range bins.

    If the estimated Z-factor is below 0 dBZ, 
    the rainrate is always set to 0.

    If the input radar reflectivity factor Zm is below the noise level,
    the rain estimate there is set to 0.  This procedure does not cause 
    any serious problem except when the measured Zm becomes smaller
    than the noise level by rain attenuation.  In such a case,
    even if some heavy rain exists near the surface, the number
    in this variable is 0.  To know whether such low radar relectivity
    factors are caused by large attenuation or not,
    look at the forth bit of 'reliab' and the forth bit of rainFlag.

    80 range bins are filled with data from top to bottom in height.
    The last element corresponds to the ellipsoid height, i.e.,
    0 m high above the model ellipsoid (not the actual surface).  
    The first element corresponds to the radar resolution cell 
    about 20 km above in slant range along the beam from the 
    footprint on the ellipsoid.  The range resolution is 250 m.

    If the radar data is missing, MISSING value of -99.9 (approximate) is stored.
    This situation may happen at range bins above 15 km high because
    NASDA only guarantees the data collection below 15 km.

    The bin number of the lowest range bin that contains valid rain 
    data is ( rangeBinNum[][1] - 1 in C) or ( rangeBinNum(2,.) - 1 in FORTRAN).
    Below this level, CLUTTER value of -88.9 (approximate) is stored.
    The lowest valid range bin is calculated from the surface 
    range bin and the main-lobe clutter flag.

    If the estimated rainfall rate exceeds 300 mm/h, it is reset to 300 mm/h.

--------------------------------------------------

float32  correctZFactor[nray][nbin];
REAL*4   correctZFactor(nbin,nray)

    Estimated true Z-factor in dBZ.

    If the input radar reflectivity factor Zm is below the noise level,
    or if the estimate is below 0 dB, correctZFactor is set to 0.0.

    Everything else is the same as rain[49][80] (rain(80,49)).

--------------------------------------------------

int8  reliab[nray][nbin];
BYTE  reliab(nbin,nray)

    Reliability parameter at each range bin

    The default value is 0.

    Each bit in the byte indicates the status shown below:

    lowest (first) bit: 0 : measured signal below noise
    lowest (first) bit: rain
    second bit        : rain certain
    third bit         : bright band 
    forth bit         : large attenuation 
    fifth bit         : weak return (Zm < 20 dBZ)
    sixth bit         : estimated Z < 0 dBZ
    seventh bit       : main-lobe clutter or below surface
    eighth bit        : missing data

    For example, if the first bit is 0, i.e., if the number is 
    an even number, then the measured signal in that range bin
    is below the noise level (noise threshold).

    The large attenuation flag is set below the height at which
    the integral of 0.2*ln(10)*beta*alpha*Zm^beta first exceeds
    the given threshold.  In the version 3, the threshold is chosen
    that approximately corresponds to the attenuation of 10 dB.

-------------------------------------------------------

int16  attenParmNode[nray][ncell2];
INTEGER*2 attenParmNode(ncell2,nray);

    Range bin numbers of the nodal points at which the attenuation 
    parameter alpha is given in 
    attenParmAlpha[nray][ncell2] (attenParmAlpha(5,nray)).

    For each angle bin, 5 nodal points are defined.
    These 5 points correspond to the array specified by nray.
    The range bin number is not the same as 1B-21 or 1C-21, but
    the bin number in the array of 80 elements so that it takes 
    a number between 0 and 79.


        attenParmNode[][] gives the range bin numbers of the nodes 
        at which the values of attenuation parameter "alpha" are given 
        in attenParmAlpha[][].  The values of alpha 
        between the nodes are liniearly interpolated.  
        The range of attenParmNode is between 0 and 79. 
        (See the note for rangeBinNum above.)

    For no-rain angle bins, attenParmNode[][] is set to the surface
    range bin number.

----------------------------------------------------------

float32   attenParmAlpha[nray][ncell2];
REAL*4    attenParmAlpha(ncell2,nray)

    Attenuation parameter alpha at nodes.
    k = alpha*Z^beta.

    "alpha" is given at five nodal points.
    alpha values between the nodes are calculated by linear interpolation.
    The range bin numbers of the nodes are stored in 
    attenParmNode[nray][ncell2].

-------------------------------------------------------

float32  attenParmBeta[nray];
REAL*4   attenParmBeta(nray)

    Attenuation parameter beta
    k = alpha*Z^beta.

    beta is given for each angle bin.
    A constant beta is used for all ranges in one angle bin.


---------------------------------------------------------

int16     ZRParmNode[nray][ncell2];
INTEGER*2 ZRParmNode(ncell2,nray);

    Range bin numbers of the nodal points at which the Z-R
    parameters "a" and "b" are given in
    ZRParmA[nray][ncell2] (ZRParmA(ncell2,nray)) and
    ZRParmB[nray][ncell2] (ZRParmB(ncell2,nray)).

    ZRParmNode[][] give the range bin numbers of the nodes at which 
    the Z-R parameters "a" and "b" are given in ZRParmA[][] and 
    ZRParmB[][], respectively.  
    The values of a and b between the nodes are liniearly interpolated.  
    The range of ZRParmNode is between 0 and 79. 
    (See the note for rangeBinNum above.)


    For no-rain angle bins, attenParmNode[][] is set to the ellipsoid
    range bin number (=79).

---------------------------------------------------------

float32   ZRParmA[nray][ncell2];
REAL*4    ZRParmA(ncell2,nray)

    Z-R parameter 'a' at nodal points.

    R = a*Z^b.

    'a' is given at five nodal points.
    These values are stored in the first 5 elements of the array.
    'a' values between the nodes are calculated by linear interpolation.
    The range bin numbers of the nodes are stored in the 
    ZRParmNode[nray][ncell2] (ZRParmNode(ncell2,nray)).


-------------------------------------------------------

float32   ZRParmB[nray][ncell2];
REAL*4    ZRParmB(ncell2,nray)

    Z-R parameter 'a' at nodal points.

    R = a*Z^b.

    'b' is given at five nodal points.
    The nodal points are the same as those for alpha.
    'b' values between the nodes are calculated by linear interpolation.
    The range bin numbers of the nodes are stored in the 
    ZRParmNode[nray][ncell2] (ZRParmNode(ncell2,nray)).

---------------------------------------------------------

float32     zmmax[nray];
REAL*42     zmmax[nray]

        zmmax is the maximum value of measured Z-factor expressed 
        in dBZ at each IFOV.
        The unit is in dBZ or 10 log of mm^6/m^3.
        The range of the variable is between 0 and 100.  
        (Typically between 10 and 60.)

-------------------------------------------------------

int16       rainFlag[nray];
INTEGER*2   rainFlag(nray)

    Rain flag for each angle bin (See flag_rain in Appendix 2.)

    The default value is 0.

    The following meanings are assigned to each bit in the 16-bit integer.

          0: (bit  1) no rain
         +1: (bit  1) rain possible
         +2: (bit  2) rain certain
         +4: (bit  3) zeta^beta > 0.5 (PIA larger than 3 dB)
         +8: (bit  4) large attenuation (PIA larger than 10 dB)
        +16: (bit  5) stratiform
        +32: (bit  6) convective
        +64: (bit  7) BB exist
       +128: (bit  8) warm rain
       +256: (bit  9) rain bottom above 2 km
       +512: (bit 10) rain bottom above 4 km
     +16384: (bit 15) data missing between rain top and bottom
    
      11th to 14th bits are currently not used.
      16th bit (sign bit) is not used either.

    Bits 3 and 4 are set if the integral of 
    0.2*ln(10)*beta*alpha*Zm^beta to the rain bottom exceeds
    the given threshold.  

-------------------------------------------------------

int16    rangeBinNum[nray][ncell3];
REAL*4   rangeBinNum(ncell3,nray)

    rangeBinNum[][0]: the top range bin number of the interval 
                        that is processed as meaningful data in 2A-25.
                        In version 5.53, this is 4 range bins (1 km) above 
                        the rain-certain range bin.
    rangeBinNum[][1]: 1 plus the bottom range bin number of the interval 
                        that is processed as meaningful data in 2A-25.
                      See note below.
    rangeBinNum[][2]: the actual surface range bin number.
    rangeBinNum[][3]: the range bin number of the bright band if it exits.
    rangeBinNum[][4]: the range bin number at which the path-integrated 
                        Z-factor first exceeds the given threshold.
                        If the path-integrated Z-factor does not exceed
                        the threshold, it is set to 79.
    rangeBinNum[][5]: the range bin number at which the measured Z-factor 
                        is maximum. If no rain, it is set to 79.

    All these range bin numbers are indexed vertically from top to bottom
    with 0 as the highest elevation and 79 as the earth ellipsoid.
    (All negative bin numbers are set to 0, and numbers larger than 79
    are set to 79.)

    Exception: If the actual surface is lower than the ellipsoid,
    the number in rangeBinNum[][2] may be larger than 79.

    Range bin numbers are unitless.

    Note: rangeBinNum[][1] contains the ranbe bin number that is the top of
          the possibly surface cluttered ranges. This number is larger than
          the bin number for the bottom of the clutter free ranges by one.

--------------------------------------------------------

float32   rainAve[nray][ncell4];
REAL*4    rainAve(ncell4,nray)

    rainAve[][0] :
    rainAve(1,*) : Average of rainfall rate between 2 and 4 km.

    If the lowest bin processed is higher than 2 km, 
    the average is taken between the lowest altitude and 4 km.
    In this case, 6th bit in the rainFlag is set.
    If the lowest bin processed is higher than 4 km,
    the average is not calculated. In this case, 0 is stored,
    and the seventh bit of the rainFalg is set.

    rainAve[][1] :
    rainAve(2,*) : Integrated rainfall rate from the rain top to the bottom.
                   Unit is mm/h*km.

--------------------------------------------------------

float32   weightW[nray];
REAL*4    weightW(nray)

    Weighting factor in the calculation of epsilon (SRT correction factor)
    in the hybrid method.  The number is always between 0 and 1.

--------------------------------------------------------

int16       method[nray];
INTEGER*2   method(nray)

    Method (rain model) used in the retrieval of vertical profiles of Z and R

    The default value is 0 (including no rain case).

    The following meanings are assigned to each bit in the 16-bit integer.
    (See flag_mthd)

          0: (bit  1) no rain
      if rain
          0: (bit  1) over ocean
          1: (bit  1) over land
          2: (bit  2) over coast
          3: (bit  2) others (inland lake, etc.)
         +4: (bit  3) constant-Z-near-surface method
         +8: (bit  4) rain less than 5 bins
        +16: (bit  5) not enough (<5) succesive rain data
        +32: (bit  6) positive slope near surface
        +64: (bit  7) epsilon >= 2.0
       +128: (bit  8) zeta very small or sigma0 too large.
       +256: (bit  9) NUBF correction very large ( > 2.0)
       +512: (bit 10) No NUBF because NSD unreliable
      +1024: (bit 11) NUBF for Z-R below lower bound
      +2048: (bit 12) NUBF for PIA above upper bound
      +4096: (bit 13) NUBF for PIA below lower bound
      +8192: (bit 14) surface attenuation after NUBF correction > 60 dB
     +16384: (bit 15) data missing between rain top and bottom

      16th bit is currently not used.

    If the surface reference is reliable, a linear weighting is used for the 
    calculation of the weighting factor.  If it is only marginally reliable,
    a quadratic weighting is used so that the surface reference has less weight
    than the reliable case.  In both cases, the larger the attenuation, 
    the larger the weight for the surface reference.

    The constant Z method is used only when the surface reference is unreliable.
    This routine fit a straight line to the lowest 5 successive data in the 
    measured Zm profile that are above the noise level. If there are not 
    enough data points for regression, the sixth or seventh bit is set.
    In this case, no attenuation correction is applied.

--------------------------------------------------------------

float32   epsilon[nray];
REAL*4    epsilon(nray)

    Surface reference correction factor

--------------------------------------------------------------

float32   zeta[nray][ncell4];
REAL*4    zeta(ncell4,nray)

    Integral of 0.2*ln(10)*beta*alpha*Z^beta 

    zeta[][0]: zeta = Integral of 0.2*ln(10)*beta*alpha*Z^beta
                      from the rain top to the bottom 
                      (lowest altitude processed).

    zeta[][1]: PIA_est = -10*(log10(1-zeta_cr))/beta

    zeta is always between 0 and 100, typically between 0 and 2.
    (There is no bound check routine for zeta[][0] in the present version of 
    2A-25, but zeta[][1] is bounded from above by 50/beta which is approximately
    equal to 70.)

    zeta is unitless.

--------------------------------------------------------------

float32   zeta_mn[nray][ncell4];
REAL*4    zeta_mn(ncell4,nray)

    Mean of zeta and PIA in 9 adjacent (3x3) beams.
    At scan edges, mean is calculated in 6 beams.

    zeta_mn[][0]: zeta_mn = mean of zeta 
    zeta_mn[][1]: PIA_mn = mean of PIA_est 

    The range of output value is the same as zeta itself.

    zeta_mn is unitless.

--------------------------------------------------------------

float32   zeta_sd[nray][ncell4];
REAL*4    zeta_sd(ncell4,nray)

    Standard deviation of zeta and PIA_est 
    in 9 adjacent (3x3) beams.
    At scan edges, it is calculated in 6 beams.

    zeta_sd[][0]: zeta_sd = standard deviation of zeta
    zeta_sd[][1]: PIA_sd = standard deviation of pia_est

    Since zeta only takes a positive value, its standard deviation 
    must be less than the maximum of zeta.  In other words, 
    zeta_sd must be between 0 and 100 always.

    zeta_sd is unitless.

--------------------------------------------------------------

float32    xi[nray][ncell4];
REAL*4     xi(ncell4,nray)

    Normalized standard deviation of zeta and PIA_est

    xi[][0]: xi = zeta_sd/zeta_mn
    xi[][1]: nsd_l = normalized standard deviation of pia_est 

    When zeta_mn (or pia_mn) is very small (or 0) and xi (or nsd_l) 
    takes a large number, it is redefined to 99.0 so that xi (or nsd_l) 
    always takes a number between 0 and 99.

    xi is unitless.

--------------------------------------------------------------

int16       thickThPIZ[nray];
INTEGER*2   thickThPIZ[nray];

    'thickThPIZ' is the number of range bins (250 m resolution) 
    between the range at which the measured Zm first exceeds 
    the threshold (now it is set to 30 dBZ) and 
    the range at which the path-integrated Z-factor first
    exceeds the given threshold.  This is an indicator of the 
    rainfall rate or attenuation.
    This is a unitless quantity and its range is between 0 and 79.

    The starting height of counting the thickness is changed from
    the top of the rain certain to the range at which the measured Zm 
    first exceeds the threshold.  Now, it may occasionally gives
    a negative number if there is a thick weak echo layer.
 
-------------------------------------------------------------

float32   nubfCorrectFactor[nray][ncell4];
REAL*4    nubfCorrectFactor(ncell4,nray)

    'nubfCorrectFactor` is the non-uniform beam filling correction factor.

    nubfCorrectFactor[][0] is the correction factor for the k-Z relation
    and its range is between 1.0 and 3.0 in version 3.5 of 2A-25.  

    nubfCorrectFactor[][1] is the correction factor for the Z-R relation
    and its range is between 0.8 and 1.0 in version 3.5 of 2A-25.  

--------------------------------------------------------------

int16      qualityFlag[nray];
INTEGER*2  qualityFlag(nray)

    Quality flag for each angle bin data

    The default value is 0.

    The following meanings are assigned to each bit 

          0: (bit  1) normal
         +1: (bit  1) unusual situation in rain average
         +2: (bit  2) mean of zeta too small for NSD (xi) calculation (flag_xi & 1 = 1)
         +4: (bit  3) NSD of zeta (xi) calculated from less than 6 points (flag_xi & 2 = 2)
         +8: (bit  4) mean of PIA too small for NSD (PIA) calculation
        +16: (bit  5) NSD of PIA calculated from less than 6 points
        +32: (bit  6) epsilon not reliable
        +64: (bit  7) 2A21 input data not reliable 
       +128: (bit  8) 2A23 input data not reliable (flag_2a23.status > 99)
       +256: (bit  9) range bin error
       +512: (bit 10) sidelobe clutter removal
      +1024: (bit 11) convergence failed in epsilon_3()
     +16384: (bit 15) data missing between rain top and bottom
    
      12th to 14th bits are currently not used.
      16th bit (sign bit) is not used either.
      The contents are exact copy of flag_qlty.

--------------------------------------------------------------------

float32   nearSurfRain[nray];
REAL*4    nearSurfRain(nray)

     Near-surface rainfall rate estimate

     "Near-surface" is defined as the lowest point in the clutter free
     ranges in almost all cases. However, if Zm at this point is below 
     the noise level and if the estimated attenuation down to this point 
     is larger than the threshPIZ defined in the parameter file (it is 
     currently set to 3 dB), in other words, 
     if the first bit of reliab[][] = 0 and 
     if the forth bit of reliab[][] = 0,
     then the lowest range bin at which Zm is above the noise threshold
     is chosen as the near-surface range bin. The actual value
     of this near-surface range bin is stored in spare[][0] in v5.3. 
 
     Therefore,
     nearSurfRain[n_anglebin] = rain[n_anglebin][(int)spare[n_anglebin][0]];
     nearSurfRain(n_anglebin) = rain(INT(spare(1,n_anglebin )+1),n_anglebin)

---------------------------------------------------------------------

float32   nearSurfZ[nray];
REAL*4    nearSurfZ(nray)

     Near-surface Z-factor

     See nearSurfRain[] for the definition of "Near-surface".
     nearSurfZ[n_anglebin] = correctZFactor[n_anglebin][(int)spare[n_anglebin][0]];
     nearSurfZ(n_anglebin) = correctZFactor(INT(spare(1,n_anglebin )+1),n_anglebin)

---------------------------------------------------------------------

float32   pia2a25[nray];
REAL*4    pia2a25(nray)

     Path-integrated attenuation from the estimated Z profile

     This attenuation is calculated from the attenuation-corrected
     Z-profile in correctZFactor[][] and adjusted alpha.
     The number represents the two-way attenuation to the surface.
     A proportional factor d1/d2 where
       d1 = distance of the rain top certain to the surface
       d2 = distance of the rain top certain to the bottom of the valid data,
    is multiplied by the attenuation calculated from the Z profile
    (which goes only down to the bottom of the valid data) to obtain
    the estimate the attenuation to the surface. See "spare" below.

---------------------------------------------------------------------

float32   errorRain[nray];
REAL*4    errorRain(nray)

    error estimate of rain near the surface expressed in dB 

    The error is calculated assuming infinitesimal error formulas.
    Therefore, when the estimate is large, it may not be reliable at all.

---------------------------------------------------------------------

float32   errorZ[nray];
REAL*4    errorZ(nray)

    error estimate of correctZFactor near the surface expressed in dB.

---------------------------------------------------------------------

float32   spare[nray][ncell4];
REAL*4    spare(ncell4,nray)

    spare

    spare[nray][0] : The range bin number (0-79) of surface rain rate and Z
       is stored in v5.3, i.e., 
       nearSurfRain = rr[(int)spare[][0]]
       nearSurfZ    = correctZFactor[(int)spare[][0]]
       See the description of "nearSurfRain" for the definition of this number.

    spare[nray][1] : Delta simga~0 from 2A21 is tentatively stored in v5.21.

---------------------------------------------------------------------------

Appendix 1. Output data structure defined in the toolkit

        /****************************************/
        /* Define L2A-25 data structure.        */
        /****************************************/

        typedef struct
        {
        int8            mainlobeEdge;
        int8            sidelobeRange[3];
        } CFLAGS;

        typedef struct
        {
        CFLAGS          clutFlag[CLUTFLAG_TBL_SIZE];
        } CLUTTER_FLAGS;

        typedef struct
        {
        float64         scanTime;
        float32         geolocation[49][2];
        PR_SCAN_STATUS  scanStatus;
        NAVIGATION      navigate;
        int16           rain_scale[49][80];
        float32         rain[49][80];
        int8            reliab[49][80];
        int16           correctZFactor_scale[49][80];
        float32         correctZFactor[49][80];
        int16           attenParmNode[49][5];
        int16           attenParmAlpha_scale[49][5];
        float32         attenParmAlpha[49][5];
        int16           attenParmBeta_scale[49];
        float32         attenParmBeta[49];
        int16           ZRParmNode[49][5];
        int16           ZRParmA_scale[49][5];
        float32         ZRParmA[49][5];
        int16           ZRParmB_scale[49][5];
        float32         ZRParmB[49][5];
        float32         zmmax[49];
        int16           rainFlag[49];
        int16           rangeBinNum[49][6];
        int16           rainAve_scale[49][2];
        float32         rainAve[49][2];
        int16           weightW_scale[49];
        float32         weightW[49];
        int16           method[49];
        float32         epsilon[49];
        float32         zeta[49][2];
        float32         zeta_mn[49][2];
        float32         zeta_sd[49][2];
        float32         xi[49][2];
        int16           thickThPIZ[49];
        float32         nubfCorrectFactor[49][2];
        int16           qualityFlag[49];
        float32         spare[49][2];
        } L2A_25_SWATHDATA;


/*---------------------------------------------------------------------
        Appendix 2.  Flags used in the main program
-----------------------------------------------------------------------*/

/* ------- Variables related to status flags --------------     
    For most flags, 0 indicates the normal status.
-------------------------------------------------------- */

int   flag_rnr;                  /* rain/no-rain flag */ 
    0: no rain
    1: rain possible
    2: rain certain

int   flag_norm;                 /* const.-Z-near-surface condition used */ 
    0: normal
    1: not enough range bins in rain interval
    2: not enough range bins that continuously exceed the threshold
    3: slope of Zm profile is positive

int   flag_ave;                  /* average rain status flag */
    0: normal
    1: rbinBottom is above 2 km
    2: no valid data between 2 and 4 km

int   flag_xi[NANGLE];           /* xi status flag */
    0: normal
   +1: (first bit is set) zeta_mean too small (less than SMALLZETA = 0.01)
   +2: (second bit is set) valid number of data points less than 6
    3: 1 and 2 (first and second bits are set)

int   flag_nsd[NANGLE];          /* nsd_l status flag */
    0: normal
    1: (first bit is set) nsd_mean too small (less than SMALLPIA = 0.1)
    2: (second bit is set) valid number of data points less than 6
    3: 1 and 2 (first and second bits are set)

int   flag_surf;                 /* surface condition flag */
    0: ocean
    1: land
    2: coastline
    4: inland lake
    8: no surface information

int   flag_epsi;                 /* epsilon status flag */
    0: normal
    1: epsilon larger than 2
    2: zeta very small or dsigma0 very large
    3: minimization routine fails to converge

int   flag_attn[NANGLE];         /* surface attenuation flag */
    0: normal
    1: attenuation from 2A21 less than 0
    2: surface attenuation after NUBF correction becomes larger than 60 dB

int   flag_th[NPOL][NANGLE];     /* PIZ exceeds threshold */ 
    0: zeta does not exceed the threshold.
    1: zeta exceeds the threshold. (attenuation larger than 3 dB)
       The threshold value is actually defined in the parameter file.

int   rbinFlag1[NPOL][NANGLE];   /* flag from rangeBinNum1()  */
    0: (bit 1) normal
   +1: (bit 1) range bin number of surface in 1C-21 out of interval [0,140].
   +2: (bit 2) range bin number of rain bottom in 1C-21 out of interval [0,140].
   +4: (bit 3) rain top in 1C-21 lower than rain bottom.
   +8: (bit 4) range bin number of rain top in 1C-21 less than 0.

int   rbinFlag2[NPOL][NANGLE];   /* flag from rangeBinNum2()  */
    0: (bit 1) normal
   +1: (bit 1) range bin number of ellipsoid in 1C-21 out of interval [0,140].
   +2: (bit 2) local zenith angle too large. (theta > 0.5 radian) 
   +4: (bit 3) range bin number of 2 km out of interval [0,140].
   +8: (bit 4) range bin number of 4 km out of interval [0,140].
  +16: (bit 5) range bin number of freezing (0C) height out of interval [0,140].
  +32: (bit 6) bright band exists and below rain bottom or out of interval [0,140].

int   flag_rbin[NPOL];           /* flag from range bin calculations */
    0: normal
    1: at least one error in rangeBinNum1() or rangeBinNum2().

int   flag_2a21;                 /* 2a21 status flag */
    flag_2a21 =  L2A21_dummy[jpol].reliabFlag[i]/1000
                 -(L2A21_dummy[jpol].reliabFlag[i]/10000)*10;

int   flag_2a23;                 /* 2a23 status flag */
    flag_2a23 = (int)L2A23_dummy[jpol].status[i];

int   flag_warm[NPOL][NANGLE];   /* 2a23 warm rain flag */
      flag_warm[jpol][i] = L2A23_dummy[jpol].warmRain[i];
    (g) int8 warmRain[49]:   Warm rain flag
    0: no warm rain
    1: Maybe warm rain
    2: Warm rain (with confidence)
  -88: no rain
  -99: data missing

int   status_ifov[NMTX][NANGLE]; /* input status of IFOV */
    0: invalid data between the rain top and bottom.
    1: valid data = no data is missing between the rain top and bottom.

int   status_scan[NMTX];         /* input data status of scan: 0=valid  */
     0: normal
     1: some of the data in the scan are missing or corrupted.
       (L1C21_dummy[jpol].scanStatus.missing != SS_MISSING ||
        L1C21_dummy[jpol].scanStatus.dataQuality != SS_DataQuality)

int   status_nubf[NANGLE];        /* status of NUBF correction  */
     0: NUBF correction
     1: no NUBF correction because NSD is not reliable
    +2: NUBF for Z-R relation is below the lower bound ( < 0.8)
    +4: NUBF for PIA is above the upper bound ( > 3.0)
    +8: NUBF for PIA is below the lower bound ( < 1.0)

int   flag_rain;                 /* output rain flag */
      0: (bit  1) no rain
     +1: (bit  1) rain possible
     +2: (bit  2) rain certain
     +4: (bit  3) zeta^beta > 0.5 (PIA larger than 3 dB)
     +8: (bit  4) large attenuation (PIA larger than 10 dB)
    +16: (bit  5) stratiform
    +32: (bit  6) convective
    +64: (bit  7) BB exist
   +128: (bit  8) warm rain
   +256: (bit  9) rain bottom above 2 km
   +512: (bit 10) rain bottom above 4 km
 +16384: (bit 15) data missing between rain top and bottom

  11th to 14th bits are currently not used.
  16th bit (sign bit) is not used either.

int   flag_mthd;                 /* output method flag */
      0: (bit  1) no rain
  if rain
      0: (bit  1) over ocean
      1: (bit  1) over land
      2: (bit  2) over coast
      3: (bit  2) others (inland lake, etc.)
     +4: (bit  3) constant-Z-near-surface method
     +8: (bit  4) rain less than 5 bins
    +16: (bit  5) not enough (<5) succesive rain data
    +32: (bit  6) positive slope near surface
    +64: (bit  7) epsilon >= 2.0
   +128: (bit  8) zeta very small or sigma0 too large 
   +256: (bit  9) NUBF correction very large ( > 2.0)
   +512: (bit 10) No NUBF because NSD unreliable
  +1024: (bit 11) NUBF for Z-R below lower bound
  +2048: (bit 12) NUBF for PIA above upper bound
  +4096: (bit 13) NUBF for PIA below lower bound
  +8192: (bit 14) surface attenuation after NUBF correction > 60 dB
 +16384: (bit 15) data missing between rain top and bottom

  16th bit is currently not used.

int   flag_qlty;                 /* output quality flag */
      0: (bit  1) normal
     +1: (bit  1) unusual situation in rain average
     +2: (bit  2) mean of zeta too small for NSD (xi) calculation (flag_xi & 1 = 1)
     +4: (bit  3) NSD of zeta (xi) calculated from less than 6 points (flag_xi & 2 = 2)
     +8: (bit  4) mean of PIA too small for NSD (PIA) calculation
    +16: (bit  5) NSD of PIA calculated from less than 6 points
    +32: (bit  6) epsilon not reliable
    +64: (bit  7) 2A21 input data not reliable 
   +128: (bit  8) 2A23 input data not reliable (flag_2a23.status > 99)
   +256: (bit  9) range bin error
   +512: (bit 10) sidelobe clutter removal
  +1024: (bit 11) convergence failed in epsilon_n3()
 +16384: (bit 15) data missing between rain top and bottom

  12th to 14th bits are currently not used.
  16th bit (sign bit) is not used either.

int  flag_sidelobe[NPOL][NANGLE]; 
/* sidelobe correction is made if this is set to 1 */

----------------------------------------------------------------------------
                    END
----------------------------------------------------------------------------
******************************
Major changes in version 5.53
******************************
   1. New routine to find the best correction factor, epsilon.
   2. Parameter files are modified.
   3. The models of vertical profiles for stratiform rain 
      without bright band and convective rain are modified.
   4. Errors are estimated in accordance with the new 
      epsilon routine.
   5. The maximum rainfall rate is limited to 300 mm/h.
   6. The DSD model was changed from the Darwin model to 
      a global-average model.
   7. Z-R coefficients are adjusted in accordance with the
      alpha-adjustement.
   8. The default value for Z when it turns out less than 0 dBZ
      is changed to 0.0 from -77.77.
   9. Only rain certain angle bins are processed.
  10. The processing starts at 1 km above the rain certain
      height. (It started from the rain possible height before.)
  11. The thickness is now measured from the height at which
      the Z first exceeds 30 dBZ.
  12. The convergence status of the minimization routine
      in epsilon_n3 is added in the quality flag.
  13. A new flag (bit 11) is added in output variable qualityFlag[].
  14. The meanings of two bits (bits 7 and 8) of method[] are changed.
  15. The new algorithm no longer accepts level 1 data processed by
      version 3 or earlier.

*****************************
Major changes in version 5.3
*****************************

28 August 1998

The algorithm version number and the product version number are written 
in the metadata block by the source code itself if the parameter EOC_OR_TSDIS
is set to a non-zero value.

If the dataQuality flag of the scanStatus in 1C21 is non-zero, the whole scan
of data are treated as missing data.

If the range bin number of the surface peak or the ellipsoid is out of 
the bounds for the data array, the data in that angle bin are treated as missing.
Accordingly, a new argument is added to function zetacalc_d().

nearSurfRain and nearSurfZ are taken from the lowest position among 
the positive Zm in 1C21 if Zm in 1C21 at the clutterFreeBottom bin is 
below the noise threshold and if this low Zm is caused by a large attenuation. 
(If it is not caused by a large atttenuation, 0 or missing value is assigned.)


*****************************
Major changes in version 5.21
*****************************

09 August 1998

The output format of 2A25 was changed in toolkit 4.7.
Five new fields were added.  They are
        float32         nearSurfRain[49];
        float32         nearSurfZ[49];
        float32         pia2a25[49];
        float32         errorRain[49];
        float32         errorZ[49];
The definitions of these fields can be found in
        2a25_variables.txt

The k-Z and Z-R coefficients the parameter file were changed. The original 
coefficients were based on the drop size distribution (DSD) measured at Kashima.  
The new coefficients are based on the DSD data at Darwin, Australia.
As a result, the rain estimate increases for convective rain and
decreases somewhat for stratiform rain compared with the data
processed with the original parameter file.

The non-uniform beam filling (NUBF) correction for attenuation is made 
only up to the extent that the corrected Z profile does not increase
toward the surface near the surface.  If the Z profile increases
near the surface without NUBF correction, no correction is made.

When the surface reference is used, the ratio d2/d1 where
       d1 = distance of the rain top certain to the surface
       d2 = distance of the rain top certain to the bottom of the valid data,
is multiplied by the delta sigma0 from 2A21 to compensate the
attenuation between the bottom of the processed range and the surface range.

The weighting function was changed.
The weighing function for reliable surface reference is now
    1-(1-x)*(1-x) = 2x - x^2
and that for marginally reliable case is
    x
where x is the attenuation estimate from radar signal or zeta in 2A25.
The formulas for error estimates were accordingly modified.

The weighting function is selected according to the reliability flag
from 2A21 now.  In the previous verion, the attenuation estimate was
used.

The ellipsoid range bin, surface range bin and clutter range bins are
now all imported directly from 1C21.

Peaks at the range bin whose absolute distance corresponds to the nadir
surface distance were suppressed to remove sidelobes when the sidelobe
flag in 1C21 (scanStatus.prStatus2) is set.

/**********************************************************
V5.2: The major changes from v5.0:
   The ellipsoid range bins are taken from 1C21.
   The bottom range bin for data processing is now
   taken from the new parameter binClutterFreeBottom in 1C21.
   The form of weighting function has been changed.
   Accordingly, the formulas for the error estimates are
   changed.
   The sidelobe clutter is removed when status2 is set in 1C21.
   The sidelobe clutter flag is added in the output "quality_flag".
   The k-Z and Z-R parameters in the parameter file (parameters_2.dat)
   are changed. Now, they are based on the drop size distrituions
   measured at Darwin, Australia.
   The non-uniform beam filling correction for attenuation
   was applied with the upper bound which is the equivalent
   surface attenuation that would make the corrected Z-profile
   near the surface vertically constant when it is used
   as the surface reference.
************************************************************/

/**********************************************************
V5.0: The major change in v5.0:
   Five new output fields are added: They are
   nearSurfRain, nearSurfZ, pia2a25, errorRain, and errorZ.
************************************************************/

*****************************
Major changes in version 4.5
*****************************

08/09/97

A new flag, flag_attn[NANGLE], was introduced to indicate 
excessively large attenuation correction after the NUBF correction.
The status of this flag is included in flag_mthd and in method[NANGLE]
of the output structure.  This change affected surfatten.c, method.c,
2a25v4.5.c, and 2a25v4.5.h (and, of course, document files).

TKreportWarning with W_2A25_FAIL_SCAN_HEADER_COPY is no longer used.
Accordingly, the corresponding lines were erased in TS_2A25_30.h and
TS_30.

Some misspellings and expressions were changed in TS_30.


05/09/97

One TKreportWarning() line was removed in 2A25v4.5.c and 
two TKreportWarning() lines were removed in report_error.c
to keep the operator in peace.

Functions reportWarnMetaInt(), reportWarnMetaChar(), and
reportWarnScan() were renamed as reportMetaIntError(),
reportMetaCharError(), and reportScanError(), respectively.

Version 4.5 was developed on a Solaris machine.
(Up to ver. 4.0 I used SUNOS414.)
Run time tested with /usr/5bin/time is as follows:
iguchi@uiro [273] % /usr/5bin/time 2a25v4.5 ../data/1C21.970317.00100 
    ../data/L2A21_970317.hdf ../data/2A23.970317.100.1.HDF 
    ../data/2A25.970317.00100.hdf ../data/2A25.970317.00100.vi

real        8.4
user        6.7
sys         1.4

real     9.4 (for 970318.00100)    8.9 (for 970319.00100)
user     6.5 (for 970318.00100)    6.4 (for 970319.00100)
sys      1.5 (for 970318.00100)    1.3 (for 970319.00100)

Document files are up-dated.

04/09/97

"TKerrorCodes.h" was removed from include statements in 2a25v4.5.c,
checkMetaData.c and report_error.c.

*****************************
Major changes in version 4.0
*****************************

08/05/97

The lines inserted for diagnosis were removed.

The unused variables in error_est.c were deleted.

The wrong definition of NPARAM was corrected. Now it is 31.

The values of p_10 ... P_30 in param_error.dat were changed.

The values of nsd_cnv[0], nsd_cnv[1] and nsd_cnv[2] in parameters.dat 
were changed.


14/04/97

Run time tested with /usr/5bin/time is as follows:
> /usr/5bin/time 2a25v4.0 PRL1C_SCN150_970314.hdf PRL2A21_SCN150_970314.hdf.n 
			 PRL2A23_SCN150_970314.hdf PRL2A25_SCN150_970314.hdf.nzen VI.txt

real     1:46.0
user     1:36.7
sys         3.4

Run time test with time is as follows:
96.400u 3.320s 1:43.88 95.9% 0+709k 0+714io 0pf+0w



11/04/1997

The following 5 warning messages were changed to error massages.
W_2A25_INCONSISTENTORBITSIZE is now E_2A25_INCONSISTENTORBITSIZE.
W_2A25_INCONSISTENTBGDATE    is now E_2A25_INCONSISTENTBGDATE.
W_2A25_INCONSISTENTBGTIME    is now E_2A25_INCONSISTENTBGTIME.
W_2A25_INCONSISTENTENDDATE   is now E_2A25_INCONSISTENTENDDATE.
W_2A25_INCONSISTENTENDTIME   is now E_2A25_INCONSISTENTENDTINE.

Errors in kzpara() and zrpara() were corrected.  rbinBB --> rbin0C when BB does not exist.

kzpara(), zrpara() and error_est() were modified according to 
the new definitions of rain types from 2A-23.

Probabilities of misidentification of rain type defined in param_error.dat 
were modified.  Accordingly, error_p.h and read_error_p.c were modified.

Output flags (rainFlag, method, qualityFlag) were redefined.
Accordingly, functions rain_flag(), mehtod_p(), and quality_flag() 
were rewitten.

02/04/1997

Bounds for rangeBinNum[][] are checked and redefined if
they are out of the proper ranges.

Copying the metadata in 1C-21 to 2A-25 is skipped since
the toolkit automatically copy them.

ScanTime, geolocation, scanStatus, and navigation are now 
copied from 1C-21 to 2A-25 by using the toolkit routine 
TKcopyScanHeader().

"scanStatus.dataQuality" is now checked agaist 100 instead
of 0.

The last line of main() was changed from
	return 0;
to
	exit(0);
to comform with the TSDIS policy.



/*-----------------------------------------------------------
All 2A-25 source files are written in such a way that each
line of text fits in a 84 character line if the tab size is
set to 4 characters or less.
------------------------------------------------------------*/
/**********************************************************
V4.0: The major change from v3.5 is that a few bugs in the 
output range bins (bounds) have been corrected.
************************************************************/

/**********************************************************
V3.5: The major change from v3.2 is that an error estimation
routine is added.  The errors are expressed in dB.
************************************************************/

/**********************************************************
V3.2: The major change from v3.1 is that the NUBF correction 
factor is now calculated from the estimate of zeta after the 
surface reference correction, i.e., epsilon * original zeta.
Because of the change, the processing is more complicated 
than before.
************************************************************/


/* ------------------------------------------------ */
   CAVEATS for TRMM PR algorithm 2A-25, Ver. 5.53
/* ------------------------------------------------ */

Name of contact: 
      Toshio Iguchi
      Communications Research Laboratory 
      Global Environment Division
      4-2-1 Nukui-Kitamachi, Koganei, Tokyo 184-8795, Japan
      Phone: +81-42-327-7543
      Fax:   +81-42-327-6666
      e-mail: iguchi@crl.go.jp

1. 2A25 produces many output variables.  Please read '2a25_variables.txt'
   carefully before using them. For example, negative numbers are stored
   in rain[][] and correctedZFactor[][] when the data are missing or in the
   possibly cluttered ranges.

   (IMPORTANT)
   If the input radar reflectivity factor Zm is below the noise level,
   the rain estimate there is set to 0.  This procedure does not cause 
   any serious problem except when the measured Zm becomes smaller
   than the noise level by rain attenuation.  In such a case,
   even if some heavy rain exists near the surface, and the actual rain
   rate there is rather large, the number in rain[][] is 0.  
   To know whether such low radar reflectivity factors are caused by  
   large attenuation or not, look at the forth bit of 'reliab' and 
   the forth bit of 'rainFlag'.

2. The error estimates in 'rain' and 'correctZFactor' are given in
   'errorRain[]' and 'errorZ[]'.  However, these estimates indicate
   only very crude estimates.  Because only the first order terms in the
   Taylor expansion is used in the calculation, the error estimates
   are not reliable at all when they are large.

3. 2A25 processes data in 'rain certain' angle bins only.
   It processes all data downward from 1 km above the height at which 
   the first 'certain' rain echo is detected.
   This is a new policy starting in version 5.5.

4. Over some area with a very high surface reflectivity, sidelobe clutters may
   appear in the radar signal and they are sometimes misidentified as 
   rain echoes.  The new sidelobe clutter rejection routine in 1B21 and 2A25 
   removes some of the sidelobe clutters internally, but not all sidelobe 
   signals are completely removed.

5. 2A25 relies on the output of 1C21 to separate the surface cluttered ranges 
   from the clutter free ranges.  Because the clutter identification routine 
   used in 1B21 is not perfect (it never can be), some surface clutter 
   (mainlobe clutter) may be occasionally misidentified as rain echo in 2A25,
   particularly in mountain regions.  It is strongly suggested that you
   look at the vertical profile if the surface clutter seems present in 
   the data.

6. The range bin numbers in the output of 2A25 are all relative to the Earth's
   ellipsoid with the ellipsoid range bin corresponding to 79.  For example,
   if the range bin number is 75, its height from the ellipsoid is 
   (79-75)*0.25 = 1.0 km. This number is NOT the height above the actual surface.

7. In version 5.53, the value of alpha in the k-Z relationship 
   (k = alpha * Z^beta) and the value of a in the R-Z relationship 
   (R = a * Z^b) used in the final calculations of correctZFactor[][] 
   and rain[][] are given in attenParmAlpha[][], attenParmBeta[], ZRParmA[][].
   and ZRParmB[][]. 

8. The rain rate estimate from a given reflectivity factor depends
   on the storm type and the phase of precipitating particles.
   2A25 essentially uses only two types of storm; stratiform or 
   convective.  Since the classification of storm types may not be
   perfect, since there are intermediate states between stratiform
   and convective rain, and since the estimate of the zero-degree C 
   height and the phase classification are rather crude, 
   the estimates of rain rate may include large errors.