wapp idl routines

Last modified: Wed Oct 25 13:19:36 2017.


List of Routines


Routine Descriptions

AWAPPEXAMPLES - USING THE WAPP PULSAR ROUTINES.

[Next Routine] [List of Routines]
NAME:
awappexamples - Using the wapp pulsar routines.

   Starting idl.
   - To use the wapp routines you need to tell idl where to
     look to get these procedures. You can do it manually each
     time you run idl, or you can put it in an idl startup file.
     Manually:
       idl
       @phil
       @wappinit

     Using a idl setup file:
       Suppose your home directory is ~jones.
       create the file ~jones/.idlstartup
       add the lines        
          !EDIT_INPUT=500
          @phil
          @wappinit
       to this file.
       In your .cshrc file (if you run csh) add the line
           setenv IDL_STARTUP ~/.idlstartup
       You can then run idl with :
           idl
       
INTRO.

   The wapp consists of up to 4 cpus (wapp1,wapp2,wapp3,wapp4). During
datataking each cpu will write a separate file. The files will change
after 2.2 gb or the start of a new observation.

   The gui (cima) will write the names of these files to a logfile. This
file is normally called: /share/obs4/usr/pulsar/'projid'/'projid'.cimalog
The routines wappgetfileinfo() or wapplistfileinfo will scan these
files and create a structure holding the filenames and header info
for every file found. These can be used to access the files. It is 
also possible to open an single file and process it.

   The routines read in data, normalize the acf's, compute the spectra,
and scale to total power. No level correction is done yet. Cross
spectra are not yet implemented/returned..

0. MISC..
   - to access a procedures documentation:
     or http://www.naic.edu/~phil,-->software document..-->idl wapp documenation
   - ctrl-c:             
     if you ctrl-c out of a routine, you may have to type retall to get
     back to the main level (i'm stilll debugging some routines and they
     don't all do it automatically).
   - generic routines:
     idl routines that are not wapp specific are documented under
     idl generic routines.

1. Input/list  all datafiles in a logfile:
   You can input or input and list all of the file info for the datafiles
   in a logfile. The information includes the filenames and the headers.
   Any files no longer on disc are skipped.
   A. To input without listing:
      1. logfile='/share/obs4/usr/pulsar/p1770/p1770.cimalog'
      2. nsets=wappgetfileinfo(lun,wappI,logfile=logfile)
      The info is returned in wappI.. (help,wappI,/st)

   B. To input and list the datafiles in the logfile.
      1. logfile='/share/obs4/usr/pulsar/p1770/p1770.cimalog'
      2. wapplistfileinfo(wappI,logfile=logfile)
      The info is returned in wappI.. (help,wappI,/st)

2. Accessing a single datafile:

   The sequence is:
   1. open the file (or let wappgethdr() open it)
   2. call wappgethdr() to read the header
   3. wappget()  input data (one or more records).

   EXAMPLE:
   1. openr,lun,'/share/wapp11/B1737+13_north.wapp.52776.000',/get_lun
   2. istat=wappgethdr(lun,hdr)
   3. nrecs=wappget(lun,hdr,d,nrec=1000)
   4. help,d,/st
      D  FLOAT = Array[256, 2, 1000]
      256 channels by 2 pol by 1000 records (the cross pol were not returned)
   .. call free_lun,lun when done with i/o

   or
   1. logfile='/share/obs4/usr/pulsar/p1770/p1770.cimalog'
   2. wapplistfileinfo,wappI,logfile=logfile
   3. Open the 6th entry in wappI
      istat=wappgethdr(lun,hdr,wappcpuI=wappI[5].wapp[0])
   4. nrecs=wappget(lun,hdr,d,nrec=1000)
   .. call free_lun,lun when done with i/o

   The nrec= keyword lets you move around in the file. By default the 
   access is sequential. 

   Beware using: 
     rew,lun
     nrecs=wappget(lun,hdr,d,nrec=1000)
   This will fail since wappget() is positioned at the header, not the
   first datarecord. In this example
     rew,lun
     nrecs=wappget(lun,hdr,d,nrec=1000,posrec=1)
   will work.

3. monitoring file via images.
   You can make a continuous set of images of datasets using
   wappmonimg()

   A. looking at a single file:
      1. openr,lun,'/share/wapp11/B1737+13_north.wapp.52776.000',/get_lun
      2. istat=wappgethdr(lun,hdr)
      3. clip=[-.5,.5]         scale lut to these data values
      4. xloadct               adjust the lut.
      5. img=wappmonimg(lun,hdr,pol=12,clip=clip)
         You an adjust the clip level by quitting, and then plotting
         the returned img..
         window,0
         plot,img

   B. looking at all datatfiles in a logfile.
      1. logfile='/share/obs4/usr/pulsar/p1770/p1770.cimalog'
      2. clip=[-.1,.1]         scale lut to these data values
      3. xloadct               adjust the lut.
      4. img=wappmonimg(lun,hdr,pol=12,clip=clip,logfile=logfile)
         You can select different boards/files in logfile using the
         menu in wappmonimg (hit any key for it to appear).

4. DISCLAIMERS:
   This is currently being written so lots of things may not work. 
Let me know what troubles you have (phil@naic.edu).

(See /pkg/rsi/local/libao/phil/wapp/awappexamples.pro)


COR3LVL - 3 LEVEL CORRECT ACF'S

[Previous Routine] [Next Routine] [List of Routines]
NAME:
cor3lvl - 3 level correct acf's
SYNTAX: acfCor=cor3lvl(acfinp,nlags,nacfs,bias,double=double,ads=ads)

ARGS:
acfinp[nlags,nacfs] float  acf's to correct.
   nlags:  long    number of lags each acf
   nacfs:  long    number of acfs to process
   bias :  float   bias to remove and scale by.
KEYWORDS:
  double:          if set then process in double precision

 RETURNS:
   acfCor[nlags,nacfs]: float  3 level corrected acfs. The 0 lags are
                   normalized to unity.
ads[nacfs]:float   alpha/sigma computed for each acf.

DESCRIPTION:
   Perform the 3 level correction and return the corrected data in acfCor.
The user inputs the raw acfs, the number of lags for each acf, the number of
acfs, and the bias. If more than one acf is input, they must all have
the same number of lags, bias, etc.. The clippinglevel/sigma is
returned (for each acf) in ads. 

   The routine does the following:
1. remove the bias and divide by the bias
2. compute the clippingLevel/sigma using the number of zeros
   and the inverse error function.
3. perform the 3 level correction using the algorithm of
   kulkarni and heiles astron. J. 85(10) oct 1980.
4. The acfs are returned with the 0 lag normalized to unity. The
   power info can be found in ads^2.

(See /pkg/rsi/local/libao/phil/wapp/cor3lvl.pro)


COR9LVL - 9 LEVEL CORRECT ACF'S

[Previous Routine] [Next Routine] [List of Routines]
NAME:
cor9lvl - 9 level correct acf's
SYNTAX: acfCor=cor9lvl(acfinp,nlags,nacfs,bias,double=double,ads=ads)

ARGS:
acfinp[nlags,nacfs] float  acf's to correct.
   nlags:  long    number of lags each acf
   nacfs:  long    number of acfs to process
   bias :  float   bias to remove and scale by.
KEYWORDS:
  double:          if set then process in double precision

 RETURNS:
   acfCor[nlags,nacfs]: float  3 level corrected acfs. The 0 lags are
                   normalized to unity.
ads[nacfs]:float   alpha/sigma computed for each acf.

DESCRIPTION:
   Perform the 3 level correction and return the corrected data in acfCor.
The user inputs the raw acfs, the number of lags for each acf, the number of
acfs, and the bias. If more than one acf is input, they must all have
the same number of lags, bias, etc.. The clippinglevel/sigma is
returned (for each acf) in ads. 

   The routine does the following:
1. remove the bias and divide by the bias
2. compute the clippingLevel/sigma using the number of zeros
   and the inverse error function.
3. perform the 3 level correction using the algorithm of
   kulkarni and heiles astron. J. 85(10) oct 1980.
4. The acfs are returned with the 0 lag normalized to unity. The
   power info can be found in ads^2.

*DESCRIPTION
*Compute the 9 level correction a la murray lewis 14feb97 memo.
*The high/low acfs should have already been combined and the bias removed
*including the divide by 16..
*
*Murray computed his corrections without removing the factor of 16. so
*i but it back in then take it out again so the data remains
*.2 for optimum value.
*
*The resolution is float. The coeff are done as doubles then moved to
*a float array. eventually things will probably be changed to double.
*
*Note
*   Murrays fits only work for correlation up to 39/40 (normalized to unity).
*In particular if you plug the zero lag in, it comes out to be 1.02 instead
*of unity.
*

(See /pkg/rsi/local/libao/phil/wapp/cor9lvl.pro)


SP_DEDISP - DEDISPERSE A WAPP DATA FILE.

[Previous Routine] [Next Routine] [List of Routines]
NAME:
sp_dedisp - dedisperse a wapp data file.
SYNTAX: npnts=sp_dedisp,file,dm,dedisp,refRf=refRf,hdr=hdr,$
               maxSmp=maxSmp)
ARGS:
   file: string    name of file to de disperse
    dm : double  dispersion measure to use

KEYWORDS:
   refRf:double   reference frequency to use for dedispersion. The default
                  is the first bin of each band.
   maxSmp:long    Maxium number of samples to return
  flip   :        if set then flip the frequency direction from
                  whatever the header says it is (use this if there
                  is a bug in the header values for iflo_flip).
 _extra:          parameters passed to wappget(). /lvlcor,/han) 

RETURNS:
   npnts:long     the number of samples in the dedispersed time series
   dedispA[npnts,nspc]float dedispersed series. Npnts total power by
                  the number of spectra per sample for this wapp board
                  it can be 1, 2, or 4
   hdr  :{wapphdr} the header from the first wapp file.

DESCRIPTION:
   Dedisperse a wapp pulsar data file. The user passes in the
file name and the dispersion measure. The dedispersed time series
is passed back in dedispA (polA) and dedispB (polB). If the file 
contains  polarization data then the cross spectra are ignored (some day
i'll get to that..). The header can be returned in the keyword  hdr=hdr.

   By default the reference frequency is the high frequency edge of the
band. The user can change this with the refRf keyword. 

NOTES:
  1. The code was borrowed from duncan lorimers sigproc() (so sp_). Hopefully
     I haven't added too many bugs.
  2. The first dedispersed point will include power that belongs in any
     time samples before the first sample. At the first sample, all
     frequencies below the reference frequency belong in the first sample
     or previous samples (depending on the dm and freq).
  3. This returns the dedispersed time series for the entire file
     (or maxsmp). Make sure that the buffers is not too big.
  4. This needs to be updated to processes multiple files and 
     write the data directly to disc (but then you should probably just use
     dunc's sigproc routines)...
SEE ALSO:
   sp_dedisp1,sp_dmdelay,sp_dmshift,wappget.

(See /pkg/rsi/local/libao/phil/wapp/sp_dedisp.pro)


SP_DEDISP1 - DEDISPERSE A BUFFER OF WAPP DATA.

[Previous Routine] [Next Routine] [List of Routines]
NAME:
sp_dedisp1 - dedisperse a buffer of wapp data.
SYNTAX: sp_dedisp1,spc,f1,df,dm,timeSmp,smpOff,dedisp,refRf=refRf
ARGS:
 spc[nchn,nspcSmp,nsmp]:float Spectra to dedisperse. If 2 dimensions then
                 assume just 1 spectra per sample
   f1  :double   center frequency of first channel (Mhz).
   df  :double   Channel width (Mhz). The sign tells whether spc[*,]
                 is increasing frequency (unflipped) or decreasing
                 frequency (flipped).
    dm : double  dispersion measure
   tmSmp:double  time between samples (secs)
 smpOff :long    The sample number that spc starts at. This is for use when
                 the routine is called multiple times

KEYWORDS:
   refRf:double   reference frequency to use for dedispersion. The default
                  is the first bin of each band.

RETURNS:
   shiftAr[nchans]:long    shift values for each channel.
   dedispA[n,nspcSmp]:float   the deddisped time series by spectra persample
 The dedisp  should be allocated to hold the max number of samples +
                 the maxium sample delay across the band

DESCRIPTION:
   Dedisperse one input buffer of spectra (usually from wappget). f1,df,dm,
timeSmp and optionally  refRf determine how to dedisperse spc. If you
set f1 to be the highest frequency bin, then make df negative.

   The dedispersed data is returned in dedisp[nsmp,Nspc]. You should
dimension dedisp large enough to hold all of the dedispered data
for however many calls you will make to sp_dedisp1. smpOff points
to the offset in dedispwhere the first time sample of spc goes. The
code checks the indices so that all dedispersed power before smpOff=0
is thrown into smpOff=0. You need to dimension dedisp to hold any
extra data at the end of the last time sample (from freq channels 
above the reference frequency). 

   This routine is normally calledl by sp_dedisp().

SEE ALSO:
   sp_dedsip,sp_dmdelay,sp_dmshift

NOTES: this code was borrowed from duncan lorimer's sigproc routines.
HISTORY:
26MAY06:- changed arguments dedispA,dedispB to deDisp[nsmp,Nspc] to allow
         for alfa data when you have multiple beams coming back from
         1 board (1,2, or 4).

(See /pkg/rsi/local/libao/phil/wapp/sp_dedisp1.pro)


SP_DMDELAY - DELAY IN SECS BETWEEN TWO SKY FREQ

[Previous Routine] [Next Routine] [List of Routines]
NAME:
sp_dmdelay -  delay in secs between two sky freq
SYNTAX: delay=sp_dmdelay(f1,f2,dm)
ARGS:
   f1: double   frequency 1 Mhz
   f2: double   frequency 2 Mhz
   DM: double   dispersion measure 
RETURNS:
   delay:double in seconds

DESCRIPTION:
   Compute the delay f2-f1 for dispersion measure dm. 
Positive numbers means that f1 arrives after f2 (f1 is the lower freq)

NOTES:
 I stole this from dunc's sigproc routine

(See /pkg/rsi/local/libao/phil/wapp/sp_dmdelay.pro)


SP_DMSHIFT - COMPUTE THE SHIFT VALUES FOR DEDISPERSION.

[Previous Routine] [Next Routine] [List of Routines]
NAME:
sp_dmshift - compute the shift values for dedispersion.    
SYNTAX: shiftAr=sp_dmshift(f1,df,nchans,dm,tmSample,refRf=refRf,
                           nbands=nbands)
ARGS:
   f1  :double   center frequency of first channel (Mhz).
   df  :double   Channel width (Mhz)   
 nchans:int      total number of channels
    dm : double  dispersion measure
tmSample: double time samples (secs)

KEYWORDS:
   refRf:double   reference frequency to use for dedispersion. The default
                  is the first bin of each band.
  nbands:long     number of dedispersed bands to return. default=1
                  nbands must divided evenly into nchans

RETURNS:
   shiftAr[nchans]:long    shift values for each channel.

DESCRIPTION:
   Compute the shift values for each frequency channel to use when
dedispersing a time series.

NOTES:
   Stole from dunc's sigproc routine.

(See /pkg/rsi/local/libao/phil/wapp/sp_dmshift.pro)


WAPPADS - COMPUTE ALPHA/SIGMA FOR 3, 9 LEVEL SAMPLING

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wappads - compute alpha/sigma for 3, 9 level sampling
SYNTAX: wappads,lag0,bias,level9,ads,pwrratio 
                       han=han)
ARGS:
  lag0[n:  float   lag 0 values (bias already removed).
  bias  :  float   bias value
 level9 :  int     true if 9 level
RETURNS:
  ads[n]:  float   alpha/sigma (dig threshold / rms voltage)
pwrratio[n]: float   optimumPower/(measured power)

DESCRIPTION:
   compute digitizerthreshold/signalVoltage for 3 or 9 level 
samples wapp data. Also return the ratio of the measured
power to the optimum power. 
   The 0 lags should already have had the bias removed.

(See /pkg/rsi/local/libao/phil/wapp/wappads.pro)


WAPPALFABMPOS - COMPUTE ALFA BEAM POSITIONS FROM WAPP HDR

[Previous Routine] [Next Routine] [List of Routines]
NAME: 
wappalfabmpos - compute alfa beam positions from wapp hdr
SYNTAX: wappalfabmpos,fileinp,fileout,inplist=inplist
  ARGS:
   fileinp: string inpfile to use. wappfilename or name of list file
                   see inplist keyword
   fileout: string file to write output to (in ascii).
                  of the day.
KEYWORDS:
   inpList:        if set then the fileinp contains a list of wapp
                   files to process.
                   use the default value.
DESCRIPTION:
   wappalfabmpos will compute the ra,dec (J2000) for the 7 alfa beams
given a wapp pulsar data file. It reads the header, finds the az,za, and
start time, and finally computes the ra, dec from these. For now it
is using the default orientation of the alfa array.

The output format is ascii is:
basename of wappfile
beamNum raHrs decDeg hh:mm:ss dd:mm:ss 

for beams 0 thru 6 

(See /pkg/rsi/local/libao/phil/wapp/wappalfabmpos.pro)


WAPPFILESIZEI - GET FILE/ RECORD SIZE INFO

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wappfilesizei - get file/ record size info
SYNTAX: istat=wappfilesizei(lun,hdr,fszI,gethdr=gethdr)
ARGS:
   lun:    long      logical unit number for file to read
   hdr:    {wapphdr} wapp header user passes in (see wappgethdr)
RETURNS:
   stat:   0  trouble with file, 1 got file size info ok
   fszI: {fileszI}   return file sizeinfo structure

DESCRIPTION:
   Get the file size info for the file pointed to by lun. The user
passes in the lun that is opened to the file of interest and the 
hdr of this file (setting the keyword gethdr will read the header for
you). The return info is:
   fszI.bytesTot   - total bytes in the file
   fszI.byteshdr   - bytes start of file to start of data.
   fszI.bytesData  - total data bytes in the file
   fszI.byresRec   - number of bytes in 1 rec
   fszI.nrecs      - total number of samples in the file

(See /pkg/rsi/local/libao/phil/wapp/wappfilesizei.pro)


WAPPFRQ - RETURN FREQ ARRAY FOR WAPP DATA.

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wappfrq - return freq array for wapp data.
SYNTAX: frq=wappfrq(h,decrease=decrease)
ARGS:
 hdr:  {}  wapp header
RETURNS:
   frq[n]: float freq array for the wapp data.
 decrease: int  0 data in increasing freq order,
                1 data in decreasing freq order

DESCRIPTION:
   Return the frequency array for the wapp data. It will have the
same number of channels as the data. It will be in increasing or
decreasing frequency order depending on the data (it does not
assume that the data has already been put in increasing freq order).

(See /pkg/rsi/local/libao/phil/wapp/wappfrq.pro)


WAPPGET - INPUT WAPP DATA

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wappget - input wapp data
SYNTAX: istat=wappget(lun,hdr,d,nrec=nrec,posrec=posrec,retpwr=retpwr,raw=raw,$
                       han=han,avg=avg,lvlcor=lvlcor)
ARGS:
   lun:    long      logical unit number for file to read
   hdr:    {wapphdr} wapp header user passes in (see wappgethdr)
  d[] :    float     return data here   

KEYWORDS:
   nrec:   long    number of acfs/spectra to input
 posrec:   long    position to this spectra before reading(count from 1) 
                   if posrec is not supplied (or equals 0) then no 
                   positioning is done.
 retpwr:           if set then just return total power (0lags)
                   d[npol,nrecs] where npol is 1 or 2 (ignore crosspol)
    raw:           just return the data read from disc, no processing
    han:           if set then hanning window before transforming.
    avg:           if set and nrec is greater than 1, then average the data 
                   before returning. This is done in the time domain so
                   it can speed up the processing (since fewer ffts needed)
   lvlc:           If set then do the level correction for the lags
                   (for now it only works for 3 level)
RETURNS:
   istat: > 0 number of recs found
          -1 illegal lag format found

DESCRIPTION:
   Input wapp data from the logical unit number LUN. The user must have
already input the file header and stored it in the hdr variable (see 
wappgethdr). By default the routine will read from the current position
in the file. You can use the posrec keyword to position to a particular
record in the file. By default 1 record (integration)  of data will be input.
You can input multiple records using the nrec keyword.

   For acf data the routine will remove the bias, normalize the acf,
compute the spectral density (SPD), and then scale the SPD to the
mean power in the acf/nlags. There is currently no 3 or nine level correction.

   The  data is returned in the d array as float numbers. 
It is dimensioned as d[nlags,npol,nrecs] where nrecs are just the consecutive
spectra (or acfs'). 

EXAMPLES:
   file='/share/wapp25/adleo.wapp2.52803.049'
   openr,lun,file,/get_lun
   istat=wappgethdr(lun,hdr)
   nrec=wappget(lun,d,nrec=50)         ; read 50 records
;  d is now dimensioned:  d[128,2,50]   
   nrec=wappget(lun,d,nrec=1000,/avg)  ; read in 1000 recs, average
   d is now dimensioned:  d[128,2]  and is the average of 1000 samples

NOTES:
   Not all wapp modes are supported. Things that won't work:
1. It does not correct for lagtruncation.
2. spectral total power mode has not been checked out.
3. in stokes mode, only the two auto correlations are returned.
4. No 9 level correction is done. 

   Be careful with file positioning. The following will cause problems:

 istat=wappgethdr(lun,hdr)             ok
 nrec=wappget(lun,hdr,d,nrec=50)       ok

 rew,lun                               positioned at hdr not data..
;  the line below returns bad data. It is positioned at the hdr, not
;  the first record of data.
 nrec=wappget(lun,hdr,d,nrec=50)       bad data returned.

 In the above case use:
 rew,lun
 nrec=wappget(lun,hdr,d,nrec=50,posrec=1)

(See /pkg/rsi/local/libao/phil/wapp/wappget.pro)


WAPPGETFILEINFO - GET THE LIST OF FILENAMES FROM THE LOG FILE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wappgetfileinfo - get the list of filenames from the log file 

SYNTAX: nentry=wappgetfileinfo(lunLog,wappI,projid=projid,maxentry=maxentry,
                              logfile=logfile,newdir=newdir,badf=badf,$
                               limdir=limdir)

ARGS:
 lunLog:    long      logical unit number for logfile

KEYWORDS:
  projid:  string  if supplied then program will use the logfile in the online
                   user directory: /share/obs4/usr/pulsar/projid/profid.cimalog
                   comments below for logfile apply...
maxentry:  int     maximum number of file sets to hold. 
                   the default is 500.
 logFile:  string  if present (or projid supplied), then the routine will use 
                   logfile rather than lunLog for the logfile to search. 
                   The routine will open,read, and then close the file.
                   In this case lunLog is ignored
newdir[4]: string  a set of new directories to search in case the file locactions
                   in the log file have been changed. include everything
                   up to the basename: '/dat/wapp/a1840/wapp1/'
limdir   :  string limit directories to search:
                   "online" :  online or user supplied newdir 
                   "proj"   :  only proj directory

RETURNS:
      nentry: long  number of file sets found
    wappI[n]:{wappfileinfo} 1 entry per file set found.
     badf[m]: string array of filenames that did not have mjd.seqnum format

TERMINOLOGY:
   file set:   the wapp will concurrenlty write 1 to 4 files (depending
               on the number of wapps selected). These 1 to 4 files
               are called a set.
observation:   an observation starts when the user presses the observe
               button on the gui and stops when the integration ends.
               It can generate multple file sets if files grow larger than 
               2.2 gb during the observation.

DESCRIPTION: 
   The wapp consists of up to 4 cpus (wapp1 thru wapp4). Each cpu writes
it's data to a separate directory/file. Each observation starts a new file
set. A single observation can create multiple file sets if more that 
2.2 gigaBytes of data are taken per observation.

   The gui will write the names of the various output files to the
current logfile. This file is located in
/share/obs4/usr/pulsar/"projid"/"projid".cima.log 

   This routine will scan the logfile and create a structure containing
information for all of the files found. There is 1 entry per file set.

   Each entry contains:

IDL> help,wappI,/st
** Structure WAPPFILEINFO, 4 tags, length=9168, data length=9166:
   ASTSEC          LONG             57453  startTm SecFromMidnite AST
   NWAPPS          INT              4      number of wapps used
   WAPPUSED        INT       Array[4]      1,0 if wapp used,notused
   WAPP            STRUCT    -> WAPPFILECPU Array[4] info for each wapp

IDL> help,wappI.wapp,/st
** Structure WAPPFILECPU, 3 tags, length=2288, data length=2288:

   DIR             STRING    '/share/wapp11/'              dir for file
   FNAME           STRING    'adleo_calon.wapp.52803.015'  filename
   filesize            0d       file size in bytes
   HDR             STRUCT    -> HDRWAPP Array[1]           hdr for file

   So the complete dir filename for wapp1 would be:
   file=wappI[0].wapp[0].dir+wappI[0].wapp[0].fname

   The routine reads in the header so it must be able to locate the 
files on disc using the filename in the logfile. Any files that are
missing are skipped.

EXAMPLE:
   logfile='/share/obs4/usr/pulsar/a1730/a1730.cimalog'
   openr,lunlog,file,/get_lun
   nsets=wappfilegetinfo(lunlog,wappI)
   free_lun,lunlog

   projid='a1730'
   nsets=wappfilegetinfo(lunlog,wappI,projid=projid)

NOTES:
   If the files have been moved to some none standard directory,then 
used the newdir keyword.

(See /pkg/rsi/local/libao/phil/wapp/wappgetfileinfo.pro)


WAPPGETFILIST - GET FILEINFO STRUCTURE FROM FILE LIST

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wappgetfilist - get fileinfo structure from file list
SYNTAX: nentry=wappgetFIlist(filelist,wappI,verbose=verbose,$
                 missingfiles=missingfiles,nmissing=nmissing)
ARGS:
 filelist[n]: string   list of wapp datafiles to read.
KEYWORDS:
   verbose:        if set then print out some info while running.

RETURNS:
      nentry   : long  number of file sets found
    wappI[n]   :{wappfileinfo} 1 entry per file set found.
missingfiles[m]: string list of files that were not found or could not
                        be read correctly
nmissing       : int    number of missing files.

TERMINOLOGY:
   file set:   the wapp will concurrenlty write 1 to 4 files (depending
               on the number of wapps selected). These 1 to 4 files
               are called a set.
observation:   an observation starts when the user presses the observe
               button on the gui and stops when the integration ends.
               It can generate multple file sets if files grow larger than
               2.2 gb during the observation.

DESCRIPTION:
   The wapp consists of up to 4 cpus (wapp1 thru wapp4). Each cpu writes
it's data to a separate directory/file. Each observation starts a new file
set. A single observation can create multiple file sets if more that
2.2 gigaBytes of data are taken per observation.

   The user inputs a list of wapp datafile names (including the directory).
This routine creates a wappI structure for each file set found.
The structure contains:

IDL> help,wappI,/st
** Structure WAPPFILEINFO, 4 tags, length=9168, data length=9166:
   ASTSEC          LONG             57453  startTm SecFromMidnite AST
   NWAPPS          INT              4      number of wapps used
   WAPPUSED        INT       Array[4]      1,0 if wapp used,notused
   WAPP            STRUCT    -> WAPPFILECPU Array[4] info for each wapp

IDL> help,wappI.wapp,/st
** Structure WAPPFILECPU, 3 tags, length=2288, data length=2288:

   DIR             STRING    '/share/wapp11/'              dir for file
   FNAME           STRING    'adleo_calon.wapp.52803.015'  filename
   filesize             0d                                 bytes in file
   HDR             STRUCT    -> HDRWAPP Array[1]           hdr for file

   So the complete dir filename for wapp1 would be:
   file=wappI[0].wapp[0].dir+wappI[0].wapp[0].fname

   The routine reads in the header so it must be able to locate the
files on disc using the filenames provided. Any files that can not be
processed are skipped. They are also recorded in nmissing and 
missingfiles[].

EXAMPLE:
   flist=[$
    '/proj/p1555/P1555.1904+0412.wapp1.52884.0001',$
    '/proj/p1555/P1555.1904+0412.wapp1.52884.0002']
   nsets=wappgetFIlist(flist,wappI)

(See /pkg/rsi/local/libao/phil/wapp/wappgetfilist.pro)


WAPPGETFIPROJ - GET THE LIST OF FILENAMES FOR A PROJECT

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wappgetFIproj - get the list of filenames for a project

SYNTAX: nentry=wappgetFIproj(projid,wappI,badhdr=badhdr,online=online,$
                             yymmdd=yymmdd)

ARGS:
 projid: string       project id to search for

KEYWORDS:
   online:     if set then try searching the online discs (if they are
               mounted.
yymmdd[2]:long  limit search to this date range [yymmdd1,yymmdd2] (ast)

RETURNS:
      nentry: long  number of file sets found
    wappI[n]:{wappfileinfo} 1 entry per file set found.
     badhdr[m]: string array of filenames that did not have valid headers

TERMINOLOGY:
   file set:   the wapp will concurrenlty write 1 to 4 files (depending
               on the number of wapps selected). These 1 to 4 files
               are called a set.
observation:   an observation starts when the user presses the observe
               button on the gui and stops when the integration ends.
               It can generate multple file sets if files grow larger than 
               2.2 gb during the observation.

DESCRIPTION: 
   The wapp consists of up to 4 cpus (wapp1 thru wapp4). Each cpu writes
it's data to a separate directory/file. Each observation starts a new file
set. A single observation can create multiple file sets if more that 
2.2 gigaBytes of data are taken per observation.

   The gui will write the names of the various output files to the
current logfile. This file is located in
/share/obs4/usr/pulsar/"projid"/"projid".cima.log 

   This routine will scan the logfile and create a structure containing
information for all of the files found. There is 1 entry per file set.

   Each entry contains:

IDL> help,wappI,/st
** Structure WAPPFILEINFO, 4 tags, length=9168, data length=9166:
   ASTSEC          LONG             57453  startTm SecFromMidnite AST
   NWAPPS          INT              4      number of wapps used
   WAPPUSED        INT       Array[4]      1,0 if wapp used,notused
   WAPP            STRUCT    -> WAPPFILECPU Array[4] info for each wapp

IDL> help,wappI.wapp,/st
** Structure WAPPFILECPU, 3 tags, length=2288, data length=2288:

   DIR             STRING    '/share/wapp11/'              dir for file
   FNAME           STRING    'adleo_calon.wapp.52803.015'  filename
   HDR             STRUCT    -> HDRWAPP Array[1]           hdr for file

   So the complete dir filename for wapp1 would be:
   file=wappI[0].wapp[0].dir+wappI[0].wapp[0].fname

   The routine reads in the header so it must be able to locate the 
files on disc using the filename in the logfile. Any files that are
missing are skipped.

EXAMPLE:
   nsets=wappfileFIproj(proj,wappI)
   free_lun,lunlog

   projid='a1730'
   nsets=wappfilegetinfo(lunlog,wappI,projid=projid)

NOTES:
   If the files have been moved to some none standard directory,then 
used the newdir keyword.

(See /pkg/rsi/local/libao/phil/wapp/wappgetfiproj.pro)


WAPPGETHDR - READ A WAPP HEADER FROM THE START OF A FILE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wappgethdr - read a wapp header from the start of a file

SYNTAX: istat=wappgethdr(lun,hdr,dataswapped,wappcpuI=wappcpuI,hdrb=hdrb)

ARGS:
    lun: int   file number to read
keywords: 
wappcpuI: {wappcpuinfo} use wappcpuI for the file to use. It will
                        open the file,scan the header, and return
                        the lun in lun. see wappgetfileinfo().
    hdrb: {wapphdrb}    header input before massaging (bytes converted to 
                        strings,etc)

RETURNS:
   istat:int       1-gothdr, 0 not a wapp file or we don't support this
                   version.
     hdr:{wapphdr} wapp header input
dataswapped: int   1 we had to swap the header, 0 we did not have to 
                   swap it.

DESCRIPTION:
   Read the wapp header from the start of the file into the 
hdr variable. The routine will position to the start of the file
before reading. It will leave the file positioned at the start of the first
data record. The variable dataswapped will be set to one if the
the routine had to swap the data on input (little/big endian). If the
file does not contain a wapp hdr then 0 will be returned in istat.

EXAMPLE:
1. 
   file='/share/wapp25/adleo.wapp2.52803.049'
   openr,lun,file,/get_lun
   istat=wappgethdr(lun,hdr)
2. scan the logfile, use the wappI structure to select a cpuhdr to open.
   logfile='/share/obs4/usr/pulsar/a1730/a1730.cimalog'
   nsets=wappgetfileinfo(lun,wi,logfile=logfile)
   istat=wappgethdr(lun,hdr,wappcpuI=wi[0].wapp[0])

THE WAPPHDR CONTAINS:

    header_version  : 5L    ,$; header revision currently 5
    header_size     : 0L    ,$; bytes in binary hdr (nom 2048)
    obs_type        : ''    ,$;what kind of observation this is
                                  PULSAR_SEARCH
                                  PULSAR_FOLDING
                                  SPECTRA_TOTALPOWER

    The following are obtained from current telescope status display
    note that start AST/LST are for reference purposes only and should
    not be taken as accurate time stamps. The time stamp can be derived
    from the obs_date/start_time variables further down in the structure.

    src_ra          : 0.D   ,$; req ra  J2000 hhmmss.sss
    src_dec         : 0.D   ,$; req dec J2000 ddmmss.sss
    start_az        : 0.D   ,$; deg az start of scan
    start_za        : 0.D   ,$; deg za start of scan
    start_ast       : 0.D   ,$; AST at start of scan (secs)
    start_lst       : 0.D   ,$; LST at start of scan (secs)

    cent_freq       : 0.D   ,$; CFR on sky Mhz (coord sys topo??)
    obs_time        : 0.D   ,$; usr req period of observation secs
    samp_time       : 0.D   ,$; usr req sample time usecs
    wapp_time       : 0.D   ,$; actual sample time. usrreq + dead time
    bandwidth       : 0.D   ,$; total bandwidth mhz for this obs 50 or 100

    num_lags        : 0L    ,$; usrReq lags per dump per spectrum
    scan_number     : 0L    ,$; year + daynumber + 3 digitnumber (*100,1000??)

    src_name        : ''    ,$;srcname
    obs_date        : ''    ,$;yyyymmdd
    start_time      : ''    ,$;utsecs from midnite (start on 1 sec tick)
    proj_id         : ''    ,$;user supplied ao proposal number
    observers       : ''    ,$;user supplied observers names

    nifs            : 0L        ,$;number of IF'S 1,2, 4=fullstokes
    level           : 0L        ,$;1=3level, 2=9level quantization
    sum             : 0L        ,$;1=Summation 2ifs (pols?), 0--> no
    freqinversion   : 0L        ,$;1=yes, 0=no
    timeoff         : 0LL       ,$;# of reads between obs start and snap block
;                                  tm offsetStart of observation.
;                                  wapp_time*numrecs. usecs??
    lagformat       : 0L        ,$;0=16bit uint lags, 1=32bit uint lags
;                                  2=32bit float lags, 3=32bit float spectra
   lagtrunc        : 0L        ,$;we truncate data (0 no trunc)
;                                  for 16 bit lagmux modes, selects which
;                                  16 bits of the 32 are included as data
;                                   0 is bits 15-0 1,16-1 2,17-2...7,22-7
;
    firstchannel    : 0L        ,$;0 polA first, 1 if polB is first
    nbins           : 0L        ,$;# of time bins for pulsar folding mode
;                                    doubles as maxrecs for snap mode
    dumptime        : 0.D       ,$;folded integrations for this period of time
    power_analog    : dblarr(2) ,$; power measured by analog detector
;
;    In the following, pulsar-specific information is recorded for use
;    by folding programs e.g. the quick-look software. This is passed to
;    WAPP by psrcontrol at the start of the observation.
;
;    The apparent pulse phase and frequency at time "dt" minutes with
;    respect to the start of the observation are then calculated as:
;
;    phase = rphase + dt*60*f0 + coeff[0] + dt*coeff[1] + dt*dt*coeff[2] + ...
;    freq(Hz) = f0 + (1/60)*(coeff[1] + 2*dt*coeff[2] + 3*dt*dt*coeff[3] + ...)
;
;    where the C notation has been used (i.e. coeff[0] is first coefficient etc)
;    for details, see TEMPO notes (http://www.naic.edu/~pulsar/docs/tempo.txt)

    psr_dm          : 0.D       ,$;dispersion measure (pc/cm^3)
    rphase          : dblarr(16) ,$;reference phase of pulse 0-1
    psr_f0          : dblarr(16) ,$;pulse freq at referenche epoch (hz)
    poly_tmid       : dblarr(16) ,$;midpnt of polyco (in MJD)
    coef            : dblarr(192),$;polynomial coef calculated by tempo [9,16]
    num_coef        : lonarr(16)  ,$;number of coefficients
    hostname        : bytarr(24)  ,$; filler to get to 2048
;
;   additions for idl processing
;
    obs_type_code   : 0L          ,$;1-srch,2=fold,3=spctoppwr, -1 unknown
    byteOffData     : 0L          ,$; byte offset start of data.
    needSwap        : 0L          ,$; 1 if data needs to be swapped.
    filler          : 0L          } ;  

(See /pkg/rsi/local/libao/phil/wapp/wappgethdr.pro)


WAPPGETPOL- INPUT WAPP DATA TAKEN IN POLARIZATION MODE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wappgetpol- input wapp data taken in polarization mode
SYNTAX: istat=wappgetpol(lun,hdr,d,nrec=nrec,posrec=posrec,retpwr=retpwr,$
               raw=raw,han=han,avg=avg,lvlcor=lvlcor)
ARGS:
   lun:    long      logical unit number for file to read
   hdr:    {wapphdr} wapp header user passes in (see wappgethdr)
  d[] :    float     return data here   

KEYWORDS:
   nrec:   long    number of time samples to input
 posrec:   long    position to this spectra before reading(count from 1) 
                   if posrec is not supplied (or equals 0) then no 
                   positioning is done.
 retpwr:           if set then just return total power (0lags)
                   d[npol,nrecs] where npol is 1 or 2 (ignore crosspol)
    raw:           just return the data read from disc, no processing
    han:           if set then hanning window before transforming.
    avg:           if set and nrec is greater than 1, then average the data 
                   before returning. This is done in the time domain so
                   it can speed up the processing (since fewer ffts needed)
   lvlc:           If set then do the level correction for the lags
                   (for now it only works for 3 level)
RETURNS:
   istat: > 0 number of recs found
          -1 illegal lag format found

DESCRIPTION:
   Input wapp polarization  data from the logical unit number LUN. 
The user must have already input the file header and stored it in the hdr
variable (see wappgethdr). By default the routine will read from the current 
position in the file. You can use the posrec keyword to position to a 
particular record in the file. By default 1 record (integration)  of data
will be input. You can input multiple records using the nrec keyword.

   For each record requested the two acf's (pola,polb) followed by the
2 cross correlations are input. The processing is:

 let d[nlags,4] be a time sample with:
   0=polA,1=polB,2=polaxpolb, 3 polBxpolA (i'm not sure of the order of
   that last two since it's done in the hardware .. i guess i could
   check it...)

 1. do the 3 level correction if requested. This should scale the acfs
    so that the 0lag=1.
 2. zero extend the acf's and do a forward transform to get the
    spectra.
 3. scale the normalized spectra (since acf was set to 1) so that the 
    power units are measured/optimum power for the level sampling used
    (This comes from the [1./(digThreshold/Sigma)]^2 you compute using
    the inverse error function (at least for the 3 level case).

 4. combine the cross correlations placing the first in the lower
    nlags, and a flipped version of bxa in the upper nlags-1 (don't repeat
    the first element). Interpolate the missing value.
 5. compute the cross spectra. Scale it to (digThreshA/sigmaA)*
    (digThreshB/sigmaB) . This is the product of Va*Vb in the units of the
    spectra.

   The  data is returned in the d array as float numbers. 
It is dimensioned as d[nlags,4,nrecs] where nrecs are just the consecutive
time samples. 

EXAMPLES:
   file='/share/wapp25/adleo.wapp2.52803.049'
   openr,lun,file,/get_lun
   istat=wappgethdr(lun,hdr)
   nrec=wappgetpol(lun,d,nrec=50,/lvlcor)         ; read 50 records
;  d is now dimensioned:  d[128,4,50]   

NOTES:
1. This only works for polarization data. For none pol data use wappget().
2. It does not work correctly with lagtruncation.
3. It is probably a good idea to do the level correction for
   3 levels (i'm a little hazy on the scaling for the none level correction
   case).
4. No 9 level correction is supported (yet). The scaling factors for the
   xspectra you get back in this case  should be checked.
5. You might want to take a close look at the scaling of the
   cross correlations. 
   Be careful with file positioning. The following will cause problems:

 istat=wappgethdr(lun,hdr)             ok
 nrec=wappgetpol(lun,hdr,d,nrec=50)       ok

 rew,lun                               positioned at hdr not data..
;  the line below returns bad data. It is positioned at the hdr, not
;  the first record of data.
 nrec=wappgetpol(lun,hdr,d,nrec=50)       bad data returned.

 In the above case use:
 rew,lun
 nrec=wappgetpol(lun,hdr,d,nrec=50,posrec=1)

(See /pkg/rsi/local/libao/phil/wapp/wappgetpol.pro)


WAPPLISTFILEINFO - LIST THE FILEINFO STRUCTURE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wapplistfileinfo - list the fileinfo structure

SYNTAX: wapplistfileinfo,wappI,cpu=cpu,projid=projid,logfile=logfile,lunOut=lunOut

ARGS:
wappI[]:  {wappfileInfo} The data to list (unless logfile is used).

KEYWORDS:  
     cpu:    int       List only this cpu (1..4). The default is all.
 projid :   string     If present then create logfile name for this projid.
                       comments for logfile keyword also apply..
 logfile:   string     If present call wappgetfileinfo to scan this
                       logfile. Load wappI with the results and then 
                       list it.
  lunOut:    int       logical unit number to write the data. The default
                       is standard out. If lunout is supplied then the
                       first line header is not written (to make it easier
                       to parse the data
RETURNS
   wappI[n]{wappfileInfo} If logfile keyword is used then the new
                       wappfileInfo will be retured in wappI
DESCRIPTION:
   List the contents of a wappfileInfo array. The user passes in the 
array via wappI unless the logfile keyword is used. In this case, the
routine will scan the file, load wappI with the data, and then list it.
   The user can list a single cpu with the cpu keyword. The lunOut
keyword will write the data to lunout rather then stdout.

EXAMPLES:
1. Read a logfile and list it to terminal.

   projid='p1770'
   wapplistfileinfo,wi,projid=projid

Find StartAst wapp nifs lagC mode   fname
  1  02:35:16   1   d    d   Search B1737+13_north.wapp.52776.000
                2        Search  B1737+13_north.wapp2.52776.001
                3         Search  B1737+13_north.wapp3.52776.001
                4         Search  B1737+13_north.wapp4.52776.000
  2  02:36:02   1         Search  B1737+13.wapp.52776.001
                2   Search  B1737+13.wapp2.52776.002
                3   Search  B1737+13.wapp3.52776.002
                4   Search  B1737+13.wapp4.52776.001

2. List the contents of wi and write it to junk.out
   openw,lunOut,'junk.out',/get_lun
   wapplistfileinfo,wi,lunOut=lunOut     
   free_lun,lunOut

SEE ALSO:
   wappgetfileinfo

(See /pkg/rsi/local/libao/phil/wapp/wapplistfileinfo.pro)


WAPPMONIMG - MONITOR WAPP FILE VIA IMAGES

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wappmonimg - monitor wapp file via images

SYNTAX: img=wappmonimg(lun,hdr,projid=projid,logfile=logfile,wapptouse=wapptouse,
                     posrec=posrec,nrec=nrec,pol=pol,han=han,lvlcor=lvlcor,
                     clip=clip,nsigclip=nsigclip,zx=zx,zy=zy,col=col,hist=hist,
                     flipforce=flipforce,noldlut=noldlut,han=han)
TERMINOLOGY:
   file set:   the wapp will concurrenlty write 1 to 4 files (depending
               on the number of wapps selected). These 1 to 4 files
               are called a file set.
    logfile:   the online gui writes a logfile of the datataking to 
               /share/obs4/usr/pulsar/projid/projid.cimalog. This file
               can be used to locate all of the wapp files taken for this
               project (that are currently on disc). See the logfile
               keyword and the l,f menu options.
   
ARGS:
   lun:    long      logical unit number for file to read
   hdr:    {wapphdr} wapp header user passes in (see wappgethdr)
NOTE:      In logfile mode, lun and hdr are ignored. just pass in dummies.

KEYWORDS:
  projid:    string  create logfile name for projid. Comments for logfile below
                     also apply.
  logfile:   string  if provided, then ignore lun, and get the files to
                     monitor from the logfile
wapptouse:   int     if logfile included, then start with this wapp 1..4.
                     default is first available board.

   posrec:   long    position to record posrec before starting (count from 1).
                     Use the p menu option to position while running.
     nrec:   long    number of spectra to plot per image. The default is 700.
      pol:   int     polization to plot:
                     1  - first pol (if more than 1)
                     2  - 2nd   pol (if more than 1)
                     12 - both pols (side by side if more than 1)
      han:           if set then hanning smooth the data
   lvlcor:           if set then level correct the data (currently only
                     works for 3 level data).

 nsigclip:   float   if supplied then clip the images to nsigmaclip sigmas.
                     This is computed for the first image displayed.
  clip[2]:   float   fraction of tsys to clip image (min,max)
                     The default is to use the full range of each image.
       zx:   int     zoom in the x (freq) direction using pixel replication.
                     numbers gt 1 make it bigger
                     numbers lt -1 make it smaller
                     Note that any negative zoom factors must divide 
                     evenly into the dimension.
       zy:   int     zoom in the y (time) direction using pixel replication.
                     same constraints as zx.
    col[]:   int     cols (channels) to use to flatten image in time direction
                     (count from 0). default is no flattening.
     hist:           if set, then histogram equalize the image
flipforce:   intarr[4]if set then force the freq band to be flipped.
  noldlut:           If set then do not load a linear ramp into the 
                     lookup table. This allows you to adjust the lookup
                     table (via xloadct) and then use that setting. The
                     default is to load a linear ramp into the color
                     lkup table.
newdir[4]:   string  string of alternate directory names to use
                     incase the files have been moved (1 for each wapp).

RETURNS:
       img[] float   the last image displayed

DESCRIPTION:
   Input data from a wappfileset and display an image of the data. The image
will be nrec samples long. The routine will continue reading the file set
creating new images until eof is hit. 
   The processing for each image is:
   1. Input the acf's, remove bias, normalize, compute spectra, scale
      to power. no level correction is done. (see wappget()).
   2. scale the image to the mean image and then subtract 1.
      img[nchn]= img[nchn]/mean(img[nchn]) - 1 ..we are now in tsys units.
   3. scale the lut (look up table) so that clip[0] clip[1] is 0 to 255.
On exit from wappmonimg() the last image (before scaling to 0 to 255)
is returned.

   The routine can be run in two modes: 
1. no logfile supplied. This will scan lun from the current position
   making images till eof is hit. The routine will then return.
   Only one board is available (the one that lun points at).
2. supply a logfile from the observation. In this case the 
   program will scan the logfile, finding all of the file sets that
   were created (see wappgetfileInfo()). It will then start at the
   first fileset creating images of nrecs per image till the end of the
   fileset. At the end of the file the user can use the menu (hit any key)
   to move to the next (or another) fileset.

   While processing the images, the user can hit any key to pause
processing and display a selection menu. The menu includes:

 command       function
curFile dir/adleo_calon.wapp3.52803.013 startTm:15:57:33(AST) fileInd:  1
b             board (1..4)
f  fileInd    move to fileset fileInd (1 to  maxfileset)
l             list all filesets
n             next fileset (or quit if 1 file)
p sec         position to second SEC in file
q             to quit
s 0 1         step mode 1-on,0-off (currently:off)

Further command description.
b          display a different wapp board. Choices are 1 to 4
f  fileInd If you are using a logfile, then you can skip to another 
           fileset by inputting the fileInd to jump to. Use the
           l command to list the filesets with their file indices.
l          If in logfile mode, list all of the filesets with there 
           file indices.
n          Move to the next file set.
p  sec     Move to a new position within the current fileset. Start the
           image at sec seconds from the start of the file.
s  0,1     single step mode. This will stop after each image is displayed.
           1 starts single step, 0 stops it.

Hitting return will exit the menu and return to processing. 

EXAMPLES:
   1. use logfile mode. display both polarizations and zoom in the 
      x direction by 2.

   logfile='/share/obs4/usr/pulsar/a1730/a1730.cimalog'        
   zx=2            ; zoom by 2 in x direction
   xloadct         ; adjust the lookup table for a grey scale ramp.
   img=wappmonimg(lun,hdr,logfile=logfile,zx=zx,pol=12)

   2. just scan a single file. Position to first rec on startup

   file='/share/wapp25/adleo.wapp2.52802.036'
   openr,lun,file,/get_lun
   istat=wappgethdr(lun,hdr)
   xloadct         ; adjust the lookup table for a grey scale ramp.
   img=wappmonimg(lun,hdr,zx=2,pol=12,posrec=1)

NOTES:
1. The routine will only display complete images of nrec samples.
   Any leftover points at the end of the file are not displayed.
2. When using logfile mode, the first key you hit just brings up
   the menu. You need to enter a 2nd key (followed by return) for the
   menu command.

SEE ALSO:
   wappgethdr,wappgetfileinfo,wappget

(See /pkg/rsi/local/libao/phil/wapp/wappmonimg.pro)


WAPPMONIMGP - MONITOR WAPP FILE VIA IMAGES

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wappmonimgp - monitor wapp file via images

SYNTAX: img=wappmonimgp(lun,hdr,projid=projid,wapptouse=wapptouse,
                    posrec=posrec,nrec=nrec,pol=pol,han=han,lvlcor=lvlcor,
                    clip=clip,nsigclip=nsigclip,zx=zx,zy=zy,col=col,hist=hist,
                    flipforce=flipforce,noldlut=noldlut,yymmdd=yymmdd)
TERMINOLOGY:
   file set:   the wapp will concurrenlty write 1 to 4 files (depending
               on the number of wapps selected). These 1 to 4 files
               are called a file set.
ARGS:
   lun:    long      logical unit number for file to read
   hdr:    {wapphdr} wapp header user passes in (see wappgethdr)
NOTE:      In projid mode, lun and hdr are ignored. just pass in dummies.

KEYWORDS:
  projid:    string  search for files using the projid passed in (eg 
                     'p1777'. It will look in the offline directories:
                     /proj/projid. If the /online keyword is included,
                     it will also look in the online directories.
wapptouse:   int     if projid included, then start with this wapp 1..4.
                     default is first available board.

   posrec:   long    position to record posrec before starting (count from 1).
                     Use the p menu option to position while running.
     nrec:   long    number of spectra to plot per image. The default is 700.
      pol:   int     polization to plot:
                     1  - first pol (if more than 1)
                     2  - 2nd   pol (if more than 1)
                     12   - both pols (side by side if more than 1)
                     1234 - 2pols, 2 boards  if alfa. 4 plots B1aB1bB2aB2b

      han:           if set then hanning smooth the data
   lvlcor:           if set then level correct the data (currently only
                     works for 3 level data).
 nsigclip:   float   if supplied then clip the images to nsigmaclip sigmas.
                     This is computed for the first image displayed.
  clip[2]:   float   fraction of tsys to clip image (min,max)
                     The default is to use the full range of each image.
       zx:   int     zoom in the x (freq) direction using pixel replication.
                     numbers gt 1 make it bigger
                     numbers lt -1 make it smaller
                     Note that any negative zoom factors must divide 
                     evenly into the dimension.
       zy:   int     zoom in the y (time) direction using pixel replication.
                     same constraints as zx.
    col[]:   int     cols (channels) to use to flatten image in time direction
                     (count from 0). default is no flattening.
     hist:           if set, then histogram equalize the image
flipforce:   intarr[4]if set then force the freq band to be flipped.
  noldlut:           If set then do not load a linear ramp into the 
                     lookup table. This allows you to adjust the lookup
                     table (via xloadct) and then use that setting. The
                     default is to load a linear ramp into the color
                     lkup table.
yymmdd[2]:  long     if provided,then limit data to this ast date range

RETURNS:
       img[] float   the last image displayed

DESCRIPTION:
   Input data from a wappfileset and display an image of the data. The image
will be nrec samples long. The routine will continue reading the file set
creating new images until eof is hit. 
   The processing for each image is:
   1. Input the acf's, remove bias, normalize, compute spectra, scale
      to power. no level correction is done. (see wappget()).
   2. scale the image to the mean image and then subtract 1.
      img[nchn]= img[nchn]/mean(img[nchn]) - 1 ..we are now in tsys units.
   3. scale the lut (look up table) so that clip[0] clip[1] is 0 to 255.
On exit from wappmonimg() the last image (before scaling to 0 to 255)
is returned.

   The routine can be run in two modes: 
1. no projid supplied. This will scan lun from the current position
   making images till eof is hit. The routine will then return.
   Only one board is available (the one that lun points at).
2. supply a projid from an observation. In this case the 
   program will scan the directories looking for all files that match:
   projid*wappn*.nnnn. It checks uppler and lowercse for the first character
   of projid: (P1770 and p1770). The directory search is in 
   /proj/projid . If the user includes /online then the online directories
   will also be searched (your computer will need read access to the online
   computer such as observer2, buye..).
    
   It will then start at the first fileset creating images of nrecs per image 
   till the end of the fileset. At the end of the file the user can use the 
   menu (hit any key) to move to the next (or another) fileset.

   While processing the images, the user can hit any key to pause
   processing and display a selection menu. The menu includes:

 command       function
curFile dir/adleo_calon.wapp3.52803.013 startTm:15:57:33(AST) fileInd:  1
b             board (1..4)
f  fileInd    move to fileset fileInd (1 to  maxfileset)
l             list all filesets
n             next fileset (or quit if 1 file)
p sec         position to second SEC in file
q             to quit
s 0 1         step mode 1-on,0-off (currently:off)

Further command description.
b          display a different wapp board. Choices are 1 to 4
f  fileInd If you are using a projid, then you can skip to another 
           fileset by inputting the fileInd to jump to. Use the
           l command to list the filesets with their file indices.
l          If in projid mode, list all of the filesets with there 
           file indices.
n          Move to the next file set.
p  sec     Move to a new position within the current fileset. Start the
           image at sec seconds from the start of the file.
s  0,1     single step mode. This will stop after each image is displayed.
           1 starts single step, 0 stops it.

Hitting return will exit the menu and return to processing. 

EXAMPLES:
   1. use projid mode. display both polarizations and zoom in the 
      x direction by 2.

   projid='p1770'
   zx=2            ; zoom by 2 in x direction
   xloadct         ; adjust the lookup table for a grey scale ramp.
   img=wappmonimgp(lun,hdr,projid=projid,zx=zx,pol=12)

   2. just scan a single file. Position to first rec on startup

   file='/share/wapp25/adleo.wapp2.52802.036'
   openr,lun,file,/get_lun
   istat=wappgethdr(lun,hdr)
   xloadct         ; adjust the lookup table for a grey scale ramp.
   img=wappmonimg(lun,hdr,zx=2,pol=12,posrec=1)

NOTES:
1. The routine will only display complete images of nrec samples.
   Any leftover points at the end of the file are not displayed.
2. When using projid mode, the first key you hit just brings up
   the menu. You need to enter a 2nd key (followed by return) for the
   menu command.

SEE ALSO:
   wappgethdr,wappgetfiproj,wappget,wappmonimg

(See /pkg/rsi/local/libao/phil/wapp/wappmonimgp.pro)


WAPPMONP2030 - MONITOR P2030 DATA

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wappmonp2030 - monitor p2030 data 
SYNTAX - wappmonp2030,yymmdd,online=online,clip=clip,img=img
ARGS:
  yymmdd: long     date to monitor. This is the ast date. It will include
                   2 mjd days.
KEYWORDS: 
  online:          if set (online=1) then also search online data files.
                   WARNING: this should not be used if people are using the
                   wapps. Default is 0
 clip[2]: float    min,max value for clipping data in units of Tsys. Default
                   is clip=[-.2,.2]
wappmonimgp        Any other parameters used by wappmonimgp can also
                   be used (except for pol,lvlcor,han which are set by
                   this routine.
RETURNS: 
img[npnts,2]:float last image displayed. first index is sample points,
                   2nd index is the 2 boards of the wapp displayed.
DESCRIPTION:
   monitor p2030 pulsar data using dynamic spectra. It calls the
routine wappmonimgp() to do the display. Hitting any key while running
brings up a selection menu. See wappmonimgp for a further description .

EXAMPLE:
   wappmonp2030,050411

will display the data for 11apr05

SEE ALSO:
   wappmonimgp

(See /pkg/rsi/local/libao/phil/wapp/wappmonp2030.pro)


WAPPTPFILE - GET TOTAL POWER FROM FILE (OPT DEDISP)

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wapptpfile - get total power from file (opt dedisp)
SYNTAX: npts=wapptpfile(filename,tp,dm=dm,maxsmp=maxsmp,hdr=hdr)

ARGS:
filename:  string  filename to process
KEYWORDS:
      DM:   float  if supplied then dedisperse the data with this dm.
  maxsmp:   long   number of time samples to return. Default is the
                   entire file.
RETURNS:
   npts:    long    number of time points returned
 tp[npts,nspc] float The total power series. There will be npts time samples.
                    nspc will depend on how many spectra (acfs) were taken
                    per time sample (1 2, or 4)
  hdr{}:            wapp header structure for this file

DESCRIPTION:
   Input the total power time series for a file. If the dm keyword is 
supplied then dedisperse the time series first. There will be one
set of time samples for each acf/spectra type in the file: 1,2pol, 4 2polsalfa

SEE ALSO sp_dedisperse

(See /pkg/rsi/local/libao/phil/wapp/wapptpfile.pro)


WAPPTPRUN - COMPUTE TOTAL POWER FOR A SCAN FOR ALL WAPPS USED

[Previous Routine] [Next Routine] [List of Routines]
NAME:
wapptprun - compute total power for a scan for all wapps used
SYNTAX: npts=wapptprun(wi,tp,wappsUsed=wappsused,polsum=polsum,hdr=hdr,
                   removeb7=removeb7,verb=verb
ARGS:
   wi[n]: {wi}   wapp info for the files to process. They should come
                 from 1 scan. See wappgetfiproj(),wappgetfilist().
KEYWORDS:
   removeb7:     if set then don't returne beam 7 (this is just a 
                 duplicate of beam 6 for alfa.
   verb:         print out names of files as we start
RETURNS:
   tp[npts,7/8]  :float total power.  for summed pols
                                 if /removeb7 then last beam not returned
   tp[npts,2,7/8]: float total power. for not summed pols

DESCRIPTION:
   compute total power for all wapps used. Probably works best for alfa.
If sumPols is set then the data is: [timesamples,beam]
If not sumPols is set then the data is: [timesamples,pols=2,beam]
 It is not setup to work with nsbc/beam (single pixel).
sumpol config.. 

(See /pkg/rsi/local/libao/phil/wapp/wapptprun.pro)


WARCH_GETTBL - INPUT TABLE OF SCANS FROM WAPP ARCHIVE

[Previous Routine] [List of Routines]
NAME:
warch_gettbl - input table of scans from wapp archive
SYNTAX: nsets=warch_gettbl(yymmdd1,yymmdd2,warchI,rcvnum=rcvnum,
                            freq=freq,proj=proj)
ARGS: 
    yyyymmdd1  :long   year,month,day of first day to get (utc)
    yyyymmdd2  :long   year,month,day of last  day to get (utc)

KEYWORDS:
       rcvnum  :long   receiver number to extract:
                        1=327,2=430,3=610,5=lbw,6=lbn,7=sbw,8=sbw,9=cb,$
                        10=xb,12=sbn,100=430ch
       freq[2] :float  Require cfr of band to be between freq[0] and freq[1]
                       in Mhz. At least 1 sbc of scan must match this.
       proj    :string project number to match (eg. 'p1473')

RETURNS:
   nsets       :long   number of data sets found
 warchI[nscans]:{wapparchI}  wapp archive info structure

TERMINOLOGY:
   data set: The wapps can create 1 to 4 files imultaneously (depending
             on many wapps are used). A data set is one of these sets of
             files. Each file can not be greater than 2.2 gb.
   scan    : A scan is one continuous integration. It can contain one
             or more datasets (depending on the i/o rate and length of the
             integration.

DESCRIPTION:
   This routine will scan the wapp pulsar archive and return a table 
(an array of wapparchI structures) for all datasets in the archive that meet 
the requested criteria.

   The array contains one entry for each wapp dataset found. 
The data structure contains a part that is independent of the 
4 wapps and then a portion that is different for each wapp. The data
structure is:

 --------------------------------------------------------------------------
IDL> help,warchI,/st
** Structure WAPPARCHI, 21 tags, length=436, data length=392:
   PROJID          STRING 'P1555'   ; project id for this set
   SCAN            LONG   318911152 ; generated from start time 1st wapp
                                    ; format : ydddnnnnn 
   JD              DOUBLE 2452828.6 ; JulDay start time 1st wapp used
   OBS_CODE        BYTE   1         ; 1-search,2-folding data
   SRC_RAHR        DOUBLE 18.898889 ; starting ra  of scan in Hrs (alfapix 0)
   SRC_DECD        DOUBLE 13.081389 ; starting dec of scan in deg (alfapix 0)
   START_AZ        FLOAT  283.687   ; starting az  of scan in deg (alfapix 0)
   START_ZA        FLOAT  18.3252   ; starting za  of scan in deg (alfapix 0)
   START_AST       FLOAT  83129.0   ; starting seconds from Midnite (ast) 
   START_LST       FLOAT  17.6855   ; starting lst of scan seconds
   OBS_TIME        FLOAT  900.096   ; requested seconds for scan
   WAPP_TIME       FLOAT  64.00     ; wapp sample time usecs
   TIMEOFF         LONG64 0         ; usecs from start of scan for start of
                                    ; this datasets (for scans with more 
                                    ; than 1 dataset
   RFNUM           BYTE   0         ; feed number. alfa=17
   ALFA_ANG        FLOAT  0.00      ; alfa rotation angle (deg)
   SYN1            DOUBLE 0.00      ; 1st lo (mhz)
   SYNFRQ          DOUBLE Array[4]  ; 2nd lo's (Mhz) if not alfa
   NWAPPS          BYTE   1         ; number of wapps used (1 to 4)
   WAPPUSED        BYTE   Array[4]  ; 1--> this wapp used, 0--> not used
   IND1ST          BYTE   0         ; index into wappused for first wappused
                                    ; (0 to 3).
   WAPP            STRUCT  -> WAPPARCHICPU Array[4] ; wapp specific info

 There are always 4 entries for the wapp[] array. The wappused[4]
array tells which of these were in use.

   IDL> help,warchI.wapp,/st
** Structure WAPPARCHICPU, 15 tags, length=76, data length=67:
   DIR             STRING '/proj/p1555/' ; directory for file
   FNAME           STRING 'P1555.1853+1308A.wapp1.52828.0000'; filename
   ONDISC          BYTE    1             ; 1--> on disc (last we checked)
   FILESIZE        DOUBLE  2.1463117e+09 ; file size in bytes
   JD              DOUBLE  2452828.6     ; julian day start this wapp
   WAPPNO          BYTE    1             ; wappnumber 1 thru 4
   CENT_FREQ       DOUBLE  1400.0000     ; center frequency this wapp
   BANDWIDTH       FLOAT   100.000       ; bandwidth in Mhz.
   NUM_LAGS        LONG    128           ; number of lags used
   LEVEL           BYTE    1             ; level used: 1-3,2-9 ??
   SUM             BYTE    0             ; 1--> sum polarizations
   LAGFORMAT       BYTE    0             ; 0 - 16 bit unsigned ints acf
                                         ; 1 - 32 bit unsigned ints acf
                                         ; 2 - 32 bit floats        acf
                                         ; 3 - 32 bit float spectra
   NBINS           LONG    0             ; number of bins if folding
   NIFS            BYTE    2             ; number of IF's 1,2 , 4=stokes
   ISFOLDING       BYTE    0             ; 1 if folding mode
 --------------------------------------------------------------------------

EXAMPLES

   The following examples will read the warchI array for all the data
between jan03 and dec04 (that is in the archive). The examples will then 
select different pieces of information that are in this warchI array. 

;get tbl for all data we have from 2003 thru apr 2005

 nscans=warch_gettbl(20030101,20050431,warchI)
;
; get the starting ra,decs for each integration and plot them
;
   raHr=warchI.src_RaHr        ; start ra  in hours
   decD=warchI.src_DecD        ; start dec in degrees

   plot,raHr,decD,psym=2

; find all of the p2030 data and see what ra/dec they have covered
; (this is just plotting the starting ra/dec of each scan.

   ind=where(warchI.projid eq 'p2030')
   ver,0,38 & hor , 0,24
   plot,raHr[ind],decD[ind],psym=2

NOTE:
   The recording of the archive started in apr05. It contains info  on
all of the data on disc at that time (29 terabytes) and all data taken
after that.

(See /pkg/rsi/local/libao/phil/wapp/warch_gettbl.pro)