rdev idl routines

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


List of Routines


Routine Descriptions

RDEV0INTRO - INTRO TO USING RDEV ROUTINES.

[Next Routine] [List of Routines]
NAME:
rdev0Intro - Intro to using rdev routines.
   
       rdev is the radar processing version of jeff mocks pdev spectrometer.
   Data is sampled, filtered, packed, and then output to disc. The disc
   format consists of a 1024 byte header followed by packed binary data.
       The header contains the standard pdev header:

hdr.h1:{pdev_hdrpdev ,$
    magic_num   : "deadbeef"XUL,$ ; unsigned long
    magic_sp    : 0L          ,$ ; magic number for sp unsigned long
    adcf        : 0L          ,$  ; adc clock freq Hz.
    byteswapCode: 0L          ,$  ;
    blkSize     : 0L          ,$  ; size of each block (integration)
    nblksdumped : 0L          ,$  ; number of blocks dumped
    beam        : 0L          ,$  ; from [pdev] section
    subband     : 0L          }   ; 0,1 from [pdev] section

   It is followed by the rdev specific header (this is currently being defined)

 aug11
  aug11 format
a={rdev_hdrsp ,$
           decF  : 0U   ,$; 1=5 dec, 2=4 dec, 3=8 dec, 4=16 dec,5=32 dec
;                           6=64,7=160
         roundEna:0U  ,$; 0,1 enabled (now implemented)
           tuner : 0U   ,$; tune word for mixing..2^16*(fout/fclock)
        shiftMixer:0U   ,$; upshift before filter. 4 bits maxval
           d1cntL: 0U   ,$; lower /upper 16 bits of samples to take
           d1cntU: 0U   ,$; data block 1 (tx)


           s2cntL: 0U   ,$; lower /upper 16 bits of samples to skip before
           s2cntU: 0U   ,$;  height  sampling count from rf pulse

           d2cntL: 0U   ,$; lower /upper 16 bits of samples to take
           d2cntU: 0U   ,$; data block 2 (data)

           s3cntL: 0U   ,$; lower /upper 16 bits of samples to skip before
           s3cntU: 0U   , $; start
           d3cntL: 0U   ,$; lower /upper 16 bits of samples to skip before
           d3cntU: 0U    $; start

    shift_fir_32m: 0U    $;
    shift_fir_20m: 0U    $;
    shift_fir_10m: 0U    $;
     shift_fir_5m: 0U    $;
   shift_fir_2_5m: 0U    $;
     shift_fir_1m: 0U    $
   }


IDL BASICS:

;  starting idl.. init rdev routines:
;
   idl
   @phil
   @rdevinit
;
;  some basic routines:
;
  hor ,0,1000      ; this will limit horizontal to 0 to 1000
  hor              ; with no args this resets to auto scaling
  ver ,-100,100    ; this will limit vertical scale to -100 to 100
  ver              ; with no args this resets to auto scaling
  !p.multi=[0,1,2] ; make 3 plot areas in the plot window (vertically)
  !p.multi=0       ; reset to 1 plot in the window
  plot,d           ; plot the array d
  plot,frq,d       ; plot d versus frq
;
; To label a plot...
;
  plot,frq,d,title='This is the title',xtitle='freq',ytitle='volts'
;
;  to send the plot of x,y data to the postscript file:testfile.ps
;
   pscol,'testfile.ps',/full
   plot,x,y
   hardcopy
   x
;
; to print the values in an array;
;
 print,d[0:99]      ; first 100 pnts

USING THE RDEV ROUTINES: 

   idl             ; start idl
   @phil           ; connect to phils routines
   @rdevinit       ; initialize the rdev routines
;
; print info on the rdev routines:
;
  explain,rdevdoc     ; list of all the routines
  explain,rdevopen    ; rdev documentation.
;
;  define the file to use
;
   file='/share/pdata/pdev/sp_tamara.20070423.b0a.00000.pdev'
;
;  open the file.. returns lun, and the header h.
   lun=rdevopen(file,hdr)
;
;  look at the header
;
   help,hdr.h1,/st
   print,hdr.h2
;
;  read 16384 samples: 
;    returns number of points actually read in: npnts
;    returns data in int array d[npnts]
;
   pntsRequested=16384L
   npnts=rdevget(lun,hdr,pntsRequested,d)
;
; plot the first 1000 points of the data
;
   hor,0,1000
   plot,d[*,0]   ;; I dig polA
   oplot,d[*,1],col=colph[2]  ;; Q dig polA
;
;  plot a histogram of the data
;
    rdevhist,hdr,d

;   input data, compute spectra and plot it
;
   naccum=rdevspc(lun,hdr,fftlen,spc,toavg=10,/plot)

(See /pkg/rsi/local/libao/phil/rdev/rdev0intro.pro)


RDEVBW - RETURN BANDWIDTH OF OBSERVATION

[Previous Routine] [Next Routine] [List of Routines]
NAME:
rdevbw - return bandwidth of observation
SYNTAX: bwMhz=rdevbw(desc)
ARGS:
 desc: {} 	from rdevopen.
RETURNS:
bwMhz: float        band in Mhz of observation
DESCRIPTION:
	Return the bandwidth of the observation. The routine decodes the
 h2.decf decimation factor. The clock is hardcoded to 160 Mhz.

(See /pkg/rsi/local/libao/phil/rdev/rdevbw.pro)


RDEVCLOSE - CLOSE A RDEV FILE FOR I/O

[Previous Routine] [Next Routine] [List of Routines]
NAME:
rdevclose - close a rdev file for i/o

SYNTAX: rdevclose,desc,all=all 

ARGS:
   desc: {rdevdescr} - descriptor to close (returned by rdevopen)
KEYWORDS:
    all:              if set then close all open descriptors.

DESCRIPTION:
   Files opened with rdevopen() need to be closed with rdevclose() so that
the resources are freed up.

EXAMPLE:
   filename='/share/pdata/pdev/phil/071106//testdata.20071107.00000.pdev'
   istat=rdevopen(filename,desc)
   .. process the data in the file
   rdevclose,desc   .. this closes the file when done with the processing.

(See /pkg/rsi/local/libao/phil/rdev/rdevclose.pro)


RDEVCLP - DECODE RDEV CLP DATA

[Previous Routine] [Next Routine] [List of Routines]
NAME:
rdevclp - decode rdev CLP data
SYNTAX: n=rdevclp(desc,avgspc,nipps=nipps,baudUsec=baudUsec,$
                     codeLenUsec=codeLenUsec,fftlen=fftlen,$
                     txSmpSkip=txSmpSkip,heights=heights,$
                     posIpp=posIpp,clpi=clpi,verb=verb
ARGS:
 desc: {} 	from rdevopen.
KEYWORDS:
	nipps: long	number of ipps to decode. def=1
baudUsec: float       baud in usecs. Def=1.
codeLenUsec:float    code len in usec. def=440.
fftlen     :long     length fft to do (def:16384)
txSmpSkip  :long     samples to skip at start of tx samples
heights[2] :long     1st hght,nhghts to process
					  if dim=1 then first height(cnt 0) , nhghts=1
                     default=[0,(datasmpIpp-(fftlen-1))/(dataSamples1baud)
posIpp     :long     position to this ipp before start. cnt from 0
clpI       :{}       structure returning info on the computation.
verb       :int      if set then print start of each ipp as we go
RETURNS:
nippsaccum: long     number of ipps we accumulated
avgSpc[fftlen,nhghts]: float height spc avged over nipps
                             dcchan=fftlen/2 (count from 0) 
clpI{}    :          struct holding info on clp data
DESCRIPTION:
	Decode then compute spectra for the requested heights.
The height spacing is set to the baudLen. 
	The routine returns the average of the ipps. 

(See /pkg/rsi/local/libao/phil/rdev/rdevclp.pro)


RDEVFINDIPPS - FIND WHICH DATASET IPPS BELONG TO IN A FILE.

[Previous Routine] [Next Routine] [List of Routines]
NAME:
rdevfindipps - find which dataset ipps belong to in a file.
SYNTAX   [npwr,nmracf,nclp,ntopsid]=rdevfindipps(desc,pwr=iipwr,mracf=iimracf,clp=iiclp,$
                           topsid=iitopsid,txSkipUsec=txSkipUsec,$
                           bad=iibad,nbad=nbad 
                     
ARGS:
  desc : {}     returned from rdevopen()
KEYWORDS:
minval    : float	minvalue for a tx Sample to be high
                   abs(txVal)  in counts
txSkipUsec: float	number of usecs to skip at start of txpulse
                   So you start at the rising edge of first baud.
					default is 1.56 usecs
 notopsid:         If set then the file contains no topsid data
 notclp  :         if set then the file contains no clp data.

RETURNS:
 nipps[4] : long number for each experiment
 iipwr[]  : long	 return indices for power profile
 iimracf[]: long	 return indices for mracf
 iiclp[]  : long return indices for clp
 iitopsid[]:long return indices for topsid
 iibad[]  : long return indeics for ipps that don't fit into a dataset
 nbad     : long number of bad ipps


DESCRIPTION:
   Scan a file and find the ipp indices for each requested dataset

(See /pkg/rsi/local/libao/phil/rdev/rdevfindipps.pro)


RDEVGET - INPUT PDEV RADAR DATA

[Previous Routine] [Next Routine] [List of Routines]
NAME:
rdevget - input pdev radar data
SYNTAX   psmp=rdevget(desc,nSmpReq,d,pos=pos,cmplx=cmplx,rawbuf=rawbuf,$
					   dec=dec)
                     
ARGS:
  desc : {}     returned from rdevopen()
nSmpReq:long number of sample points requested. This is the decimated
                count.
KEYWORDS:
 pos   : long 	if set then start reading this many datasamples from the
               front of the file. It skips the header automatically
               < 0 --> use current position
cmplx  :       if set then return complex data (default is int)
rawbuf:   int  if set then return the raw input buffer here (before
               negative correction or byteswapping.
dec   : long   decimate the input by this amount using a boxcar.
               0,1 --> no decimation.

RETURNS:
   nsmp: long samples we read
   d[nsmp,2*npol]: float   returned data [*,IA/QA,IB,QB] if not /cmplx
   d[nsmp,npol]:   complex if /cmplx is set

DESCRIPTION:
   Input sampled data from pdev radar processor. You need to call
rdevopen() once to open the file before using this routine.
   The returned data is floats  unless /cmplx is set. In that case
the return value is complex.
 If 2 pols are available then the 2nd dimension of d holds :
 polAI,polAQ,polBI,polBQ.
History:
26feb08: swapped i,q to get correct sign
         switched to return float or complex.. no more ints

(See /pkg/rsi/local/libao/phil/rdev/rdevget.pro)


RDEVGETIPP - INPUT 1 RDEV IPP OF DATA

[Previous Routine] [Next Routine] [List of Routines]
NAME:
rdevgetipp - input 1 rdev ipp of data
SYNTAX   psmp=rdevgetipp(desc,d,dtx,nipps=nipps,posipp=posipp,cmplx=cmplx)
                     
ARGS:
KEYWORDS:
 posipp: long 	position to this ipp before starting. Count from start of
               this file (for now)
               < 0 --> use current position
cmplx  :       if set then return complex data (default is int)

RETURNS:
   nsmp: long samples we read
   d[2,nsmp]: float   returned data [IA/QA,nspmp] if not /cmplx
   d[nsmp]:   complex if /cmplx is set

DESCRIPTION:
   Input nipps of rdev data from the requested file. You need to call
rdevopen() once to open the file before using this routine.
   The returned data is floats  unless /cmplx is set. In that case
the return value is complex.
	If the file is a continuation of a previous file (see rdevopen descprev=), then
the routine will position to the start of the first ipp in the file (files do not
have integral number of ipps).

History:
10jan10: fixed some of the documentation, updated to position in secondary files
         correctly
26feb08: swapped i,q to get correct sign
         switched to return float or complex.. no more ints

(See /pkg/rsi/local/libao/phil/rdev/rdevgetipp.pro)


RDEVGRAPTXSMP - GRAP TXSAMPLES FROM A FILE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
rdevgraptxsmp - grap txSamples from a file
SYNTAX   nipps=rdevgraptxsmp(desc,txTims,nsamples,txAr)
                     
ARGS:
  desc : {}     returned from rdevopen()
txTimes[m]:float offsets from start of txipp in usecs for samples to return
nsamples:  int   number of samples at each tx offset to return
KEYWORDS:
txOff:	float	

RETURNS:
   nipps                 : long number of ipps we found
 txDat[nsamples,nipps,m] : complex    the data

DESCRIPTION:
   Scan a file extracting individual txsamples from a file. This
can be used to determine where different observation types start:
eg. clp has data out to 440 usecs, while topside goes out to 
 For each ipp:
    for each element of txTims, extract nsamples complex samples.

(See /pkg/rsi/local/libao/phil/rdev/rdevgrabtxsmp.pro)


RDEVHIST - MAKE A HISTOGRAM OF RDEV DATA.

[Previous Routine] [Next Routine] [List of Routines]
NAME:
rdevhist - make a histogram of rdev data.
SYNTAX: rdevhist,hdr,d
ARGS:
 hdr : {} header read in with rdropen()
 d[n]: int data read in via rdevget()
KEYWORDS:
 tit: string   title for plot
plot keywords.. you can enter keywords to plot and they will be included.
 
DESCRIPTION:
   Plot a histogram of the sampled data as well as the bit usage. The top
plot is the histogram of the data. The horizontal axis is the values the
data can take. The vertical axis is the fraction of total counts taken.
   The bottom plot is a plot of the fraction of time each of the n bits
were a 1.

(See /pkg/rsi/local/libao/phil/rdev/rdevhist.pro)


RDEVOPEN - OPEN A PDEV RADAR DATA FILE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
rdevopen - open a pdev radar data file
SYNTAX: istat=rdevopen(filename,desc,descprev=descprev,filenum=filenum)

ARGS:
filename: string file to open

KEYWORDS:
descprev: {}	descriptor from previous file
fileNum : long if supplied then this is Nth file of a 
               multi file sequence.
               The first file that contains the header should be 0.
               NOTE - This is not the filenumber in the file. It just
               counts 0..N-1 . 
               eq. Suppose you have a multi file sequence with the
               header file having filenum: 00200.pdev
               To access the 2nd file (00201) you would set
               filenum=1 (since we count from 0);
               filenum of a sequence (count from 0).
RETURNS:
 istat: int  1 open ok, 0 error
 desc: {}   holds open info

DESCRIPTION:
   Open a radar file and read the header. After returning from this routine
you are positioned to read the first data same (with rdevget()).

NOTE: descprev:
To read an 2..n file of a multi file sequence:
1. pass descprev=desc where desc is the descriptor for the
   current file open (do not close it).
2. The routine will close it and compute the sample offset for the
   start of the new file.
3. If the open is successful the previous descriptor will be closed.

(See /pkg/rsi/local/libao/phil/rdev/rdevopen.pro)


RDEVPOSIPP - POSITION TO START OF IPP IN FILE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
rdevposipp - position to start of ipp in file
SYNTAX istat=rdevposipp(desc,ipp)
                     
ARGS:
  desc : {}     returned from rdevopen()
    ipp:long    ipp in file to compute position for. Count from 0.
RETURNS:
   istat:ulong  0 position ok, -1 error

DESCRIPTION:
   Position to the start of the requested ipp in the file.
Ipps are counted from 0. This is the ipp number in the file, not the ipp 
number from the start of the observation.

(See /pkg/rsi/local/libao/phil/rdev/rdevposipp.pro)


RDEVSPC - COMPUTE THE SPECTRUM OF THE DATA

[Previous Routine] [List of Routines]
NAME:
rdevspc - compute the spectrum of the data
SYNTAX: naccum=rdevspc(desc,fftlen,spc,spcTx=spcTx,freq=freq,toavg=toavg,plot=plot,$
                       _extra=e,pos=pos
ARGS:
  desc: {}        from rdevopen()
  fftlen:long    length of fft to perform
   d[npol,n]: int The data read in via rdevget()
Keywords:
	toavg: long		number of spectra to avg. default is 1
  plot  :          if set the plot spectra
    _e  :          pass to plot routine.. ytitle=ytitle, etc..
    pos :  long    Ipp in file to position to before starting.
                   (count from 0). null or -1 --> read next ipp available
RETURNS:
 naccum: long     number of power spectra we averaged.
 spc[fftlen]: float The frequency array for the spectrum (in Mhz). 
 spctx[fftlen]: float if supplied then also return the tx spectra
     freq[fftlen]: float  freq array Mhz

DESCRIPTION:
   Input and compute spectra for rdev data. toavg keyword allows you to average 
multiple spectra. The spectra is returned. it will also return via keywords the number
of pols (npol), the frequency array (freq).
	The /plot keyword will plot the spectra before returning.
EXAMPLE:

 file='/share/pdata/pdev/sasdr_2010.20100123.b0a.00100.pdev'
 istat=rdevopen(file,desc)
; set each plot in a separate window
 naccum= rdevspc(desc,spc,freq=freq,/plot)

history:
 25jan10 .. updated to new rdev format
 04mar08 .. switched to new decF coding

(See /pkg/rsi/local/libao/phil/rdev/rdevspc.pro)