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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)