atm tec idl routines

• TEC0INTRO - INTRO TO USING THE ATM TEC ROUTINES.
• TECASTHR - RETURN AST HR OF DAY FOR EACH POINT
• TECBYDATE - SETUP FOR PLOTTING BY DATE
• TECCHK - RETURN INDICES OF GOOD DATA
• TECGET - GET TEC DATA FROM THE ARCHIVE
• TECPLTTECEL - PLOT TEC AND ELEVATION VS HOUR
• TECSATLIST - RETURN LIST OF ALL TEC SATELLITE NAMES
• TECSATNM - MAP SATELLITE CODE TO SATELLITE NAME
• TECSATNMTOCODE - MAP SATELLITE NAME TO SATELLITE CODE
• TECVER - CONVERT FROM SLANT TO VERTICAL TEC

Routine Descriptions

NAME:
tec0intro - Intro to using the atm tec routines.
   
   The  tec (Total Electron Cnt) data is recorded from a receiver
at the lidar lab. It receives a dual frequency beacon from a number
of satellites and converts this info to tec. Data is processed and stored
once a second for each satellite pass. Routines are used to move this data
to an idl archive where it can be extracted and plotted with the tec
idl routines.
   Each pass of a satellite will last a few hundred seconds. The processed
data is stored in an idl structure at 1 second intervals. This data
structure contains the data from the processed file  (the interpretation of
some of the elements is still waiting on hien).

 help,tar,/st
 JD       DOUBLE   2454161.7 ; julian date for sample to 1 sec resolution
 TEC      FLOAT    0.686000  ; slant relative tec for this second.
 SAT      INT      6         ; satellite code (see tecsatnm(code) for name)
 PH       INT      20        ; phase flag ??
 UHF      INT      0         ; uhf flag
 VHF      INT      4         ; vhf flag
 PASSNUM  LONG     18        ; unique number for each pass of a satellite
 AZ       FLOAT    318.140   ; azimuth of satellite from ao
 EL       FLOAT    19.5100   ; elevation of the satellite from ao.
 FLAT     FLOAT    23.4100   ; lattitude where ao-sat pierces fregion
 FLON     FLOAT    -71.9000  ; longitude where ao-sat pierces fregion
 ELAT     FLOAT    20.0500   ; lattitude where ao-sat pierces eregion
 ELON     FLOAT    -68.5100  ; longitude where ao-sat pierces eregion


=========================
 Notes on the dataset:
=========================
 -  The data set started on 20dec06. 
 -  It looks like the tec data has not been range corrected.
 -  There has been no data quality filtering. There are a bunch of 
    elevations < 0.


=========================
 Using  the tec idl routines:
=========================
   - starting idl:
   idl
   @phil
   @tecinit

   - inputting a range of tec data (say 28jan07 thru 31jan07);

   yymmdd1=070128
   yymmdd2=070131
   npnts=tecget(yymmdd1,yymmdd2,tar)

   - converting from slant tec to vertical tec for 300 km:
     hght=300.
     tecV=tecver(tar,hght)k

   - plotting:
     - the tecvalue
     plot,tar.tec
     - the tec value by date:
     xtickf=tecbydate()
     plot,tar.jd,tar.tec,xtickf=xtickf

     - tec value by ast hour
       hr=tecasthr(tar)            ; convert to ast hr
       plot,hr,tar.tec,psym=1      ; put a cross at each point

   - help
     explain,tecdoc    .. list tec routines
     explain,tec0intro .. list this help
     explain,tecget    .. list tecget doc

(See /pkg/rsi/local/libao/phil/tec/tec0intro.pro)

NAME:
tecasthr - return ast hr of day for each point
SYNTAX: hr=tecasthr(tar)
ARGS:
   tar[n]: {}  structure holding tec info returned by tecget()
RETURNS:
hr[n]  : double ast hr for each point.
DESCRIPTION:
   Convert the julian date of each point to AST hr from midnite.

(See /pkg/rsi/local/libao/phil/tec/tecasthr.pro)

NAME:
tecbydate - setup for plotting by date
SYNTAX: xtickf=tecbydate(formatCodes)
ARGS:
formatCode: string format codes to use on x axis. The default is:
                   dayMonYr. see idl routine label_date() for a list of 
                   the codes to use.
                   %M month name
                   %N month number (2 digits)
                   %D day number of month (2 digits)
                   %Y year (4 digits)
                   %Z year (2 digits)
                   %H hour (2 digits)
                   %I minutes (2 digits)
RETURNS:
   xtickf: string  variable to pass to xtickformat=xtickf keyword when
                   calling plot:

EXAMPLE:
; suppose we want the xaxis to be labeled as: yymmdd:hh
   formatcodes='%Z%N%D:%H'
   xtickf=tecbydate(formatCodes)
   plot,tar.jd,tar.tec,xtickf=xtickf 

(See /pkg/rsi/local/libao/phil/tec/tecbydate.pro)

NAME:
tecchk - return indices of good data
SYNTAX: ngood=tecchk(tar,indgood,elmin=elmin)
ARGS:
 tar[]: {}  array of tec structures
KEYWORDS:
 elMin: float  minimum elevation to allow. Default is 0.
RETURNS:
ngood  : long number of good points in indgood
indgood[ngood]: long indices into tar for the good points.
DESCRIPTION:
   Check the data quality. A good point must have:
1. tar.el between minEl and 90 deg
2. tar.flat between -10 and 50
3. tar.vhf lt 49.5 (seems to saturate at vhf=50??)

(See /pkg/rsi/local/libao/phil/tec/tecchk.pro)

NAME:
tecget - get tec data from the archive
SYNTAX: npnts=tecget(yymmdd1,yymmdd2,tecAr)
ARGS:
 yymmdd1: long first day to get
 yymmdd2: long last day to include
RETURNS:
npnts       : long number of points found.
tecAr[npnts]: {}   tecAr holding all data samples in the requested range
DESCRIPTION:
   Return all of the tec info between the specified dates. 
A sample is included if the ast time of the first point
in the satellite pass falls within the date range (including the last day).

(See /pkg/rsi/local/libao/phil/tec/tecget.pro)

NAME:
tecplttecel - plot tec and elevation vs hour
SYNTAX: tecplttecel,tecAr,tecv=tecv,lsat=lsat,ldate=ldate,title=title,
                    cs=cs
ARGS:
 tecAr[n]: {}  array of tec strucutures from tecget();
KEYWORDS:
   tecv:   if set then call tecver() to convert to "vertical" tec..
 lsat  :   if set then include satellite name in the title
 ldate :   if set then include the AST start time in the title
 title : string   title to include in first plot of each page.
   cs  : float   characiter size for the labels (as passed to plot).

DESCRIPTION:
   Plot tec vs hour and overplot elevation vs hour for each pass in the
array tecAr. The elevation is overplotted in red with the elevation axis
plotted on the right side of each plot. 
   You can add the satellite name and date/time for start of the pass with
the keywords /lsat and /ldate (all times are AST). 
   The horizontal scale should be set to autoscaling (use hor). The vertical
scale can be left to autoscale or you could set a fixed value for the
tec plots using ver (the elevation scale is always 0 to 90). 
   You can place multiple plots on the page using !p.multi= system 
variable.

EXAMPLE:
   plot all of the passes between 23mar07 and 25mar07. Place two plots
per page.
   yymmdd1=070323
   yymmdd2=070325
   npnts=tecget(yymmdd1,yymmdd2,tar)
;   throw out  bad elevations..
   ngood=tecchk(tar,indgood)
   tar=tar[indgood]
   !p.multi=[0,1,2]            ; 1 column, 2 rows per page
   cs=1.                       ; default scale for labels
   ver,0,20                    ; limit tec range to 0,20
;  make the plots
   tecplttecel,tar,/lsat,/ldate,title='23-25mar07',cs=cs

(See /pkg/rsi/local/libao/phil/tec/tecplttecel.pro)

NAME:
tecsatlist - return list of all tec satellite names
SYNTAX: satNmAr=tecsatlist()
RETURNS:
   satNmAr[]: strarr  array of all satellite names
DESCRIPTION:
   return list of all satellite names we know about.
To map from a tec.sat to these names use:
 satNm=satNmAr[tec[i].sat -1] .. (the codes start counting from 1).

(See /pkg/rsi/local/libao/phil/tec/tecsatlist.pro)

NAME:
tecsatnm - map satellite code to satellite name
SYNTAX: istat=tecsatnm(satCode,satNm,satList=satList)
ARGS:
satCode: int   satellite code stored in tecAr.sat
RETURNS:
istat: int     1 found satellite name
               0 illegal satCode
satList[]: strarr array holding all of the satellite names we know of.

(See /pkg/rsi/local/libao/phil/tec/tecsatnm.pro)

NAME:
tecsatnmtocode - map satellite name to satellite code
SYNTAX: satcode=tecsatnmtocode(satNam)
ARGS:
satNam: string satellite name (as defined in the data files).
RETURNS:
satcode:  int      satellite code number for satNam
                   0 if there if this sat name is not in the list

(See /pkg/rsi/local/libao/phil/tec/tecsatnmtocode.pro)

NAME:
tecver - convert from slant to vertical tec
SYNTAX: tecv=tecver(tAr,Hght,oblAng=oblang,freg=freg,ereg=ereg);
ARGS:
   tar[n]: {}    array of tec structures from tecget
   hght  : float the height in the atmosphere for the vertical measure
                  (units are kilometers).
KEYWORDS:
freg     :      if set, ignore altitude, use hght of 350 km.
ereg     :      if set, ignore altitude, use hght of 110 km.
RETURNS;
tecv[n]  : float    the vertical tec
oblAng[n]: float    the obliquity angle for each tec value used for the 
                    correction.
DESCRIPTION:
   Compute the obliquity angle:
   oblAng=(Re + Hght) / (sqrt((Re + Hght)^2 - (Re*cos(el))^2)
   
   where:
     Re is the radius of the earth : 6376.5 meters (from tempo).
   Hght is the atmospheric height passed in (in km).
   el   is the elevation of the satellite from ao for each sample. 

 The corrected tec is then
  tecV= tecS/oblAng

(See /pkg/rsi/local/libao/phil/tec/tecver.pro)