This file describes Samuel Haimov's (haimov@uwyo.edu) WCRTOOLS library. Wcrtools library provides idl routines to work with the WCR raw data files, UW KingAir data files, NCAR C130 aircraft, and WCR data archived in netCDF files before October 2009. It is expected that this library and the authors of the routines used will be acknowledged by the users if the results of this use are published. In addition to my routines it includes routines developed by or in collaboration with other colleagues. In particular the Airborne Dual-Doppler analysis package was developed by Rick Damiani (rickdami@uwyo.edu) and myself. All contributions are highly appreciated. Generally, the use of this library requires Sam Haimov's idltools idl library and Ray Sterner's jhuapl idl library. You need to set the IDL path to include the IDL directories for wcrtools, idltools and jhuapl. Following is a list of the available idl routines with short descriptions. The same information is accessable within idl by executing wcrtools.pro routine (IDL> wcrtools). Every routine includes a keyword HELP providing additional information. More general information is available in the Readme file in idltools library. ________________________________________________________________________________ ************************************************************************ **************** Routines for handling WCR raw data ******************** ************************************************************************ clearwcr - Initilize wcr common blocks: wcrparams and wcrdata closewcrf - Close WCR file. commonwcrinclude - Set wcr common blocks as include file in other wcrtools routines commonwcrset - Set wcr common blocks in the current workspace openwcrf - Open 'SPPMAG' , 'PPMAG' or 'FFT' WCR file openwcrm - Main program that set wcr common blocks and open a WCR file plotwcrcalm - Plot test data or corner reflector calibration data for selected files plotwcrcalm1 - Make isolation plots (plotwcrcocr) only plotwcrcocr - Plot received power ratios: hh/vv, vh/hh, hv/vv plotwcrcr - Plot CR hh, vv, hv, vh at the range gate of max reflec. plotwcrcrm - Plot test data or corner reflector calibration data plotwcrfft - Plot fftps at given range, ffttx and fftnoise. plotwcrfftm - Plot fft data for test purposes plotwcrnoise - Plot noise and leakage vars and calc. corr. coeffs. plotwcrtest - Plot noise, leakage, 0, 1 and last range gate data plotwcrtestm - Plot noise, leakage, 0, 1 and last range gate data for multiple files printwcrprms - Print radar parameters for a opened raw wcr data file printwcrstat - Print min, max, mean, std (in dBm) and varc=std/mean (%) for WCR noise, leak, and isolation of a given WCR file printwcrstamp- Prints WCR file parameters and statistics at the bottom of a page. Prints datestamp at the page upper left corner readwcrall - Load into the memory all radar data from a wcr file (this routine is obsolete for data after 1996, use readwcrdata) readwcrdata - Load into the memory all radar data from a wcr file readwcrfftspec - Read wcr fft data (this routine is obsolete for data after 1996, use readwcrdata) readwcrnoise - Read wcr noise and cal. data (this routine is obsolete for data after 1996, use readwcrdata) readwcrpowerpp - Read wcr radar power and pulse pair data (this routine is obsolete for data after 1996, use readwcrdata) readwcrraw - Load array of structures with the raw WCR data readwcrtb - Read wcr time and profile recordings (this routine is obsolete for data after 1996, use readwcrdata) showwcrprms - Show wcr parameters and variables wcrcalcoeff - Calculate calibration coeff. from corner reflector measurements wcrcalcoref - Calibrate co-reflectivity,hh,vv,abs(pp). Allow additional pre-calibration profile/range averaging. wcrcalcrref - Calibrate cross-reflectivity,vh,hv. Allow additional pre-calibration profile/range averaging. wcrcalinfo - Show calibration constants for different experiments or returns calibration constants for a particular experiment. wcrdisp - Widget controled WCR real-time display; this program is obsolete and replaced by wcrdisplay wcrdisplay - Widget controled WCR data display. Similar to wcrdisp plus option to correct Doppler velocity for the platform motion. It could be used as WCR data browser. This routine is obsolete for data after July 2004. wcrdopvel - Calclulate (uncorrected) Mean Doppler velocity wcrdvsnr - Calculate mean and standard deviation of the error in the measured WCR Doppler velocity as a function of SNR wcrhcor - Linear correction of H receiver data; WCR internal lookup table adjustment for data before 1999 wcrleak - Return the mean and the standard deviation fltarr(nrg,2) of the Tx power leak contribution along the given nrg range gates, starting from 0th gate, in the WCR received power wcrproc - idl batch program for data-quality/quicklook processing wcrproc_s - process corner reflector data and calculate calibration coeff wcrscope - Create PS file with WCR transmitted power samples wcrtfp1scor- Correct a specific problem with the WCR Time (IRIG) card The problem appears as one or more 1 second negative jumps at the top of a second followed by a single recovery positive jump. The problem is intermittent and appears in some of the WCR data collected in year 2002. wcrtfppjfix- Correct a specific problem with the WCR Time (IRIG) card. The problem is intermittent and appears in some of the data collected during CIFEX in 2004. wcrvcor - Linear correction of V receiver data (WCR internal lookup table adjustment for data before 1999 wcrvps - Create PS file of corrected Doppler velocity(max 3 plots/page) wcrvpsm - Create PS files of corrected Doppler velocity from one day flight data wcrzps - Create a reflectivity PS file from a WCR file wcrzpsm - Create reflectivity PS files from one day flight wcr data wcrzpsm1 - Create reflectivity PS files from one day flight wcr data (similar to wcrzpsm but first does incoherent profile averaging for SPPmag and PPMag modes only) writewcrraw - Write raw WCR wcr data to a new file wcrzoomprof - Determine indexes of the wcr file profiles or time wcrzoomrange - Return indices of the requested range gates ************************************************************************ ******* Routines for creating WCR NetCDF files from WCR raw data ******* ************************************************************************ wcrcdl2nc - Generate WCR netcdf file from a prototype cdl file (ncgen utility) wcrcdv2nc - Write corrected for platform motion, Doppler velocity and related variables to the corresponding WCR netcdf file wcrcreatenc- Create a netcdf file from a given cdl file, WCR raw data file, and optional WCR platform motion (aircraft) navigational data file wcrwrite1nc- Write WCR time and dimension related variables, calculated reflectivity, uncorrected Doppler velocity and associated attributes to an existing netcdf file matching loaded WCR raw data wcrwrite2nc- Calculate and write corrected for platform motion, Doppler velocity and related variables to the corresponding WCR netcdf file wcrupdatenc- Update reflectivity or Doppler velocity variables of WCR netcdf file(s) as well as some other associated variables and attributes wcrncproc - idl batch program for wcr netcdf processing wcrncupdate- idl batch file for wcr netcdf re-processing of existing netcdf ************************************************************************ **** Routines associated with WCR Doppler correction for AC motion **** ************************************************************************ ac2wcr - Interpolates an aircraft variable time dimension to match WCR time dimension (profiles) or WCR variable profile dimension to match AC time ac2gt - Returns single precision AC (aircraft) to EARTH or EARTH to AC coordinate transformation matrix. wcracvel - Returns AC velocity contribution w.r.t. ground into the WCR beam. Positive contribution means is away from the radar. wcracvelm - Returns AC velocity contribution w.r.t. ground into the WCR beam. This routine uses acloadins to load the appropriate data and then wcracvel to calculate the AC velocity contribution. Positive contribution means away from the radar. wcracwind - Returns aircraft (AC) measured wind contribution (fltarr(n) in m/s) into the WCR beam. Positive contribution means away from the radar. wcrbeam - Returns WCR antenna beam coordinates in Earth or aircraft coordinate system. wcrbeamcal - Analyze wcr antenna beam angles in aircraft reference frame The results are used to establish (calibrate) the beam angles for all 4 wcr antennas wcrbeamfind- Finds unit vector (pointing angles in aircraft, AC,coordinate system) of a wcr antenna beam from wcr surface returns wcrdopcor - Returns WCR radial Doppler velocity corrected for AC motion. Positive velocity is toward the radar. wcrdopcorm - Returns WCR radial Doppler velocity corrected for AC motion. Positive velocity is toward the radar. This routine uses wcrdopvel to calculate uncorrected Doppler velocity wcracvelm to calculate AC velocity contribution to the beam. The corrected Doppler velocity is calculated using wcrdopcor routine. wcrtimeoff - Calculates time offset between WCR time stamps and N2UW KingAir data system time stamps. It also returns the corresponding correlation coefficient. wcrwunfold - Returns shifted/unfolded WCR Doppler corrected for AC motion velocity around given wind value component into the WCR beam ************************************************************************ ***************** WCR Dual-Doppler Processing Routines ***************** ************************************************************************ wcrdd - Perform dual-Doppler analysis using airborne WCR dual-beam data and aircraft(AC) supplemental data. This is the main program the user needs to call to execute the complete dual- Doppler processing. wcrdd2tplot- Write an ascii file with selected Dual-Doppler outputs suitable for 2-D/3-D visualization by TecPlot (preplot utility). wcrddacdisp- Display aircraft attitude angles and ground track. This routine is not stand alone and is used by wcrddgrid0 and wcrddgrid1.pro as part of the WCR airborne Dual-Doppler analysis package wcrdd. wcrdddata - Prepare input for WCR dual-doppler analysis from a WCR raw data file and an aircraft (AC) data file (netcdf, N2UW KingAir or NCAR C130). wcrdddoc - Information routine providing web link to a pdf file with detail description of the Dual-Doppler software and methodology wcrdddv - Calculate the 3-D velocity vector along the grid coordinates from the available doppler velocity measurements of two WCR beams. The procedure uses external data to pre-condition the system (due to lack of 3rd dimension measurements). External estimate of the winds is used to calculate the component of the velocity/wind perpendicular to the best-fit plane of the two beams. wcrddecho - Print the values of the parameters used for dual-Doppler analysis in a file. Statistics of selected aircraft(AC) attitude parameters and processing results are also printed. wcrddgrid0 - Generates a 3-D grid to be used for the dual-Doppler calculations (wcrddproc0) assuming a straight-leg flight pattern. wcrddgrid1 - Generates a 3-D grid (aircraft curtain-leg pattern) to be used for the dual-Doppler calculations (wcrddproc1) wcrddinit - Read/create dual-Doppler input parameters file and outputs data structures necessary to perform dual-Doppler analysis wcrddlatlon- Calculate lat/lon for all grid cell center points given lat/lon of grid first row center points. This routine is not stand alone and is used by wcrddproc1 as part of the WCR airborne Dual-Doppler analysis package wcrdd. wcrddproc0 - Calculate dual-Doppler velocities using straight leg grid. wcrddproc1 - Calculate dual-Doppler velocities using curtain leg grid. wcrddwext - Determines external info on winds. Winds given as U,V,W in the UFRS, for every cell in the grid. wcrddwhts - Set of weighting functions used by the dual-Doppler analysis (wcrdd). Returns weights to the Doppler velocity measurements associated with each grid cell of a Dual-Doppler grid generated by wcrddgrid0/1. Note: Additional information about the package and the methodology used is available in the wcrdddoc.pdf documentaion file ************************************************************************ ******** Reading variables from AC, WCR or WCR/AC NetCDF files ********* ************************************************************************ acloadnc - Returns AC data variable from an AC netCDF data file. acloadins - Returns UW KingAir or NCAR C130 selected INS data variables from a netCDF file. kawcrmirror - Returns time array for the KA radar wing mirror position (associated with side/up pointing antenna; 0-side, 1-up). kawcrmirrorprint - Create an ascii file containing times of radar mirror position changes for a given flight. kawcrreform - Returns a reformed WCR variable from a KA/WCR netcdf file by megring 'profiles' and 'time' dimensions. (for KA/WCR merged netcdf files before March 2004) wcrloadnc - Load variables from a WCR netcdf file. This version of the WCR netcdf file uses 'profile' dimension instead of 'time' dimension. There is no time dimension for these type of WCR data files and profile dimension represents non-regularly sampled radar data in time. The time stamps matching the profiles can be composed from the netcdf file variables time or base_time and time_offset (both obsolete after 2007). wcrzrgnc - Returns thresholded reflectivity for given rangegates and beam from a WCR processed netcdf file. This is a fltarr(m,n), where m=rangagate, n=profile ************************************************************************* ******** Miscelaneous routines related to WCR and AC NetCDF data ******** ************************************************************************* wcrcalthreshnc - Return thresholded reflectivity in dBZ and optional thresholded Doppler velocity field wcrplotnc - Display reflectivity(Z) and Doppler velocity(DV) for selected WCR netcdf files. wcrthreshnc - Return range adjusted reflectivity threshold, fltarr(rangegates,profile), given radar range gates in meters and reflectivity noise standard deviation in equivalent dBZ@1km wcrud2altnc - Returns WCR up(beam1), down(beam1), or down&up(beam1&beam2) reflectivity(or velocity) resampled into the vertical plane and adjusted for the radar altitude. Deviations of the beam(s) in the horizontal plane are ignored (horizontal homogeneity is assumed). If beam(s) pointing angles are not given assume no deviation from vertical (straight leg, small attitude angles). wcrud2udnc - Returns the combined reflectivity or velocity field (nrg, nrpofs). from the 'up' and the 'down' WCR beams. The ranges added in the gap between the first valid 'up' and 'down' gates are filled with missing values. The missing values of the output are always NaN. wcrwdvnc - Adjust the airborne radar radial Doppler velocity from the Up/Down-pointing antenna for horizontal wind contribution. The routine uses Doppler velocity already corrected for the aircraft motion contribution. h2omwir - Returns complex refraction index of pure water/ice for a given microwave frequency in GHz and temperature in degree Celsius ________________________________________________________________________________ ________________________________________________________________________________ Wcrtools routines dealing with WCR raw data use two main common blocks. WCRPARAMS contains all radar parameters saved in the radar wcr profile headers plus some useful auxiliary parameters: common wcrparams, alg,aspectratio,averages,datablocksize,datarate,dftalg,$ dspsync,fftalg,fftbins,fftwindow,fileidstr,filenamel,$ fstblocknum,headersize,iffilter,interrupts,kaspeed,lambda,$ lstblocknum,maxvel,noisesamples,npulse,numrec,polh,polv,$ pp4alg,pp6alg,pp8alg,ppstrpol,prf,pulselength,rangegates,$ rangegatedelay,rangegatespacing,rxsequence,sppalg,starttime,$ stoptime,tcorrection,timelength,timeinterval,tnumrec,$ txsequence,txstrpol,wcrdate,wcrfile,wcrflag,noiseflag,$ filehdrsz,irigflag,acqtime,rxch,activebeams WCRDATA contains all the radar measurements. Since there are several different modes of radar operation, not all variables are defined at the same time: common wcrdata, vvnoise, hhnoise, ppnoise, fftnoise, $ vvtx, hhtx, vvlk, hhlk, pptx, ffttx, $ hh, vv, vh, hv, pp, fftps, $ time, prof, begtime, endtime, radrng, $ velo, hcorrection, vcorrection, timemode,$ basetime, hhprt, vvprt, hnoiseflag, vnoiseflag All raw radar parameters and measured variables are described in SHOWWCRPRMS.PRO The internal calibration loops were disabled after 1996 and the variables vvtx, hhtx, vvlk, hhlk, pptx, and ffttx now represent the leakage from the transmitted pulses. Many of the wcrtools routines include one or both of the wcr common blocks either explicitly (via commonwcrinclude.pro) or implicitly (common block calls without parameters). ________________________________________________________________________________ DISCLAIMER: The above described routines may be used, copied, or redistributed as long as they are not sold and the copyright notice (included in the routine) is reproduced on each copy made. If results using these routines are published appropriate acknowledgment is expected. The software routines are provided as is and without any expressed or implied warranties whatsoever. All warranties including, but not limited to, performance, merchantability or fitness for a particular purpose are hereby disclaimed. You assume the entire risk and liability of using the software to include use in compliance with any third party rights. You are advised to test the software thoroughly before relying on it. In no event shall Samuel Haimov or UWyo/DAS be held responsible for any direct, indirect, consequential or inconsequential damages or lost profits arising out of the use or inability to use the software.