psrfits idl routines

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


List of Routines


Routine Descriptions

APSRFEXAMPLE - USING AO PSRFIT IDL ROUTINES.

[Next Routine] [List of Routines]
NAME:
apsrfexample - Using ao psrfit idl routines.
   
   The pdev/mock spectrometers can generate psrfits fits files. The
psrfxxxx idl routines let you input and look at the data in idl.

USING the routines.
   0. If not at AO, install phil's idl routines at your site
       http://www.naic.edu/~phil/download/download.html
       --> idlroutines to analyz ao data.
   1. start idl
      - at ao  idl or idl70
      @phil    .. to include path to phil's routine in the search path
      @psrfinit .. include the psrf and mas routines.

   2. Open a single file and look at it:
      filename='dir/x107.20090607.b0531+21.b0s1g0.03500.fits'
      istat=psrfopen(filename,desc,fnmI=fnmi)
;     look at contents of descriptor structure:
      help, desc,/st
** Structure , 14 tags, length=3129776, data length=3129721, refs=1:
   LUN             LONG               101
   FILENAME        STRING    '/share/pdata1/pdev/x107.20090607.b0531+21.b0s'...
   NEEDSWAP        BYTE         1
   BYTESROW        LONG           1052268
   TOTROWS         LONG                60
   CURROW          LONG                32
   BYTEOFFREC1     LONG             28800
   BYTEOFFNAXIS2   LONG             20400
   HPRI            STRUCT    ->  Array[1] .. primary fits header
   HAOGEN          STRUCT    ->  Array[1] .. ao generic header
   HPDEV           STRUCT    ->  Array[1] .. pdev header
   HSUBINT         STRUCT    ->  Array[1] .. subint header
   ROWSTR          STRUCT    ->  Array[1]
   ROWSTRF         STRUCT    ->  Array[1]

   3. input 1 row of file:
       istat=psrfget(desc,b)
;          look at contents of b
      help,b,/st
  IDL> help,b,/st
   TSUBINT         DOUBLE           1.0000000
   OFFS_SUB        DOUBLE          0.50000000
   LST_SUB         DOUBLE           18175.386
   RA_SUB          DOUBLE           83.632679
   DEC_SUB         DOUBLE           22.014512
   GLON_SUB        DOUBLE           184.55724
   GLAT_SUB        DOUBLE          -5.7846698
   FD_ANG          FLOAT           0.00000
   POS_ANG         FLOAT           0.00000
   PAR_ANG         FLOAT          -65.5061
   TEL_AZ          FLOAT           242.726
   TEL_ZEN         FLOAT           8.38640
   DAT_FREQ        FLOAT     Array[512]
   DAT_WTS         FLOAT     Array[512]
   DAT_OFFS        FLOAT     Array[512]
   DAT_SCL         FLOAT     Array[512]
   DATA            INT       Array[512, 1000]
   STAT            STRUCT    -> PDEV_HDRDUMP Array[1000]

; Notes:
;   - each row has multiple spectra (in this case 1000).
;   - the freq is stored in data_freq (these are the centers of each bin)
;   - stat structure has info on each spectra. In particular the number of 
;     integrations that went into the accummulated spectra (stat.fftaccum)

; 
;  4. plot 1 spectra
  plot,b.dat_freq,b.data[*,0]   
 
   5.  monitor set of files with dynamic spectra
      - Use psrfmonimg()
        .. the routine can automatically cycle through a set of files for one project
           in 1 day..
      - specifying where the files are at..
       .. At AO the data files are stored by default in 
          /share/pdataN/pdev   where N is 1..7 for beams 0..6
          The routine can find these files by default, all you specify is the
          date and projid.
       .. If files are somewhere else (or another institution) then:
          - files for different beams need the following directory structure:
             /xx/yyyN/  where N is beamnumber +1
          - then use the dirI[2] keyword
              dirI[0] is the prefix, dirI[1] is the suffix of the directory
              path with N 1..7 stuck in between:
             suppose data in /data/ao/psrf/beam[1..7]
             dirI[0]='/data/ao/psrf/beam'
             dirI[1]='/'
             This will generate searches in /data/ao/psrf/beam[1-7]/ for the datafiles

       - calling the routine:
         date=20090607
         projid='x107'
;        If at ao
         psrfmonimg,projid=projid,date=date
;        If not at ao..
            dirI[0]='/data/ao/psrf/beam'
            dirI[1]='/'
         psrfmonimg,projid=projid,date=date,dirI=dirI

       - In the routine.
         - hitting a key  brings up a menu to choose from
         - It starts with the last file of a day. 
           Using the l keyword in the menu list the files for this beam
           Using the fnum keyword moves to another file for the day
           Using the date keyword changes date
           Using the band keyword switches between the 2 bands
           Using the beam keword swithces between the 2 beams.

       - Misc notes.
         - by default the routine maps the number of spectra in a row to the image using
           congrid which resamples the data set (interpolation, not averaging).
         - You can stretch the image (by grabbing an edge) to get more pixels in the image
         - Using the zx=-n,zy=-m keyword on the call ti psrfmonimg() will shrink the image by
           factors m,n using averaging so you get an increased signal to noise. 
         - check out some of the other keyword calls and menu items in psrfmonimg()

  6. Closing a file
     psrfclose,desc,/all  
         .. using the /all keyword closes all open files

(See /pkg/rsi/local/libao/phil/psrfits/apsrfexample.pro)


PSRFAVGFILE - AVG SPECTRA IN A FILE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
psrfavgfile - avg spectra in a file

SYNTAX: n=psrfavgfile(fname,bavg,brms=brms,desc=desc,fnmI=fnmI,$
					    maxrows=maxrows,minrows=minrows)

ARGS:
    fname: string	name of file
KEYWORDS:
maxrows: long		max number of rows to input
minrows: long		if file has less then minrows, then donot process it
                   (use to skip cals)
	fnmI:  {}       structure from masfilelist for file to use
					In this case ignore fname
RETURNS:
 bavg:  struct    standard struct from psrfget() with data replaced by the averaged data.
                  the other elements come from the first record of the file
 brms:  struct    if present then return rms for the file.
                  this is computed on the avg of each row.
                  The rms is normalized by the average spectra giving delT/T

 desc        : struct  from psrfopen(). This contains the various headers.
						the will have been aleady closed.
 n:   >=0 number of spectra avged
      < 0  error

DESCRIPTION:
   average the spectra in a file. Return the averaged spectra in b.
 It will be the standard structure returned from psrfget on the first reccord except
 that the .data element will contain the averaged data.
 Note: currenly blanking is ignored..
 - the rms on u,v is a factor of 2 low.. this is from the mock
   scaling of the u,v differently then pola,B

(See /pkg/rsi/local/libao/phil/psrfits/psrfavgfile.pro)


PSRFCLOSE - CLOSE A PSRFITS FILE FOR I/O

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

SYNTAX: psrfclose,desc,all=all 

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

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

EXAMPLE:
   filename='/share/pdata/pdev/phil/071106//testfits.20071107.b0s0.00000.fits'
   istat=psrfopen(filename,desc)
   .. process the data in the file
   psrfclose,desc   .. this closes the file when done with the processing.

(See /pkg/rsi/local/libao/phil/psrfits/psrfclose.pro)


PSRFFILESUM - GET SUMMARY INFO FOR PSRFITS FILES

[Previous Routine] [Next Routine] [List of Routines]
NAME:
psrffilesum - get summary info for psrfits files
SYNTAX: nsum=psrffilesum(flist,sumI,desc=desc,fnmI=fnmI,list=list)

ARGS:
 flist[n]:strarr filenames for summary. Includes directory.
KEYWORDS:
desc   :{}       descriptor returned from psrfopen. If supplied then ignore flist
                 and use desc as the file to look at.
fnmI[n]:{}       structure returned by masfilelist. If this keyword is
                 present then ignore flist and use fnmI for the files
                 to use.
list   :         if set then output oneline summary to stdout of file
RETURNS:
    nsum: long    number of summaries we return. Don't count files that had trouble being read
 sumI[n]: {}      summary info for mas files.
DESCRIPTION:
   Return summary info for a list of files. You can specify the files with
 the argument flist or the keyword fnmI. 
   The returned summary info contiains:
 help,sumI,/st
   OK      INT    1
  FILENAME        STRING    '/share/pdata1/pdev/a2675.20120311.J0651+28.b0s1g0.00000.fits'
   NEEDSWAP        BYTE         1
   BYTESROW        LONG           4136556
   TOTROWS         LONG                85
   CURROW          LONG                 0
   BYTEOFFREC1     LONG             28800
   BYTEOFFNAXIS2   LONG             20400
   HPRI            STRUCT    psrfits primary header
   HAOGEN          STRUCT    ao generic header
   HPDEV           STRUCT    pdev header
   HSUBINT         STRUCT    psrfits subint header
   hrow            struct    header from first row
                             excludes the array info (freq,wts,off,scl,data,stat)

EXAMPLE:

1. get 1 file
fname='/share/pdata1/pdev/a2675.20120311.B0611+22.b0s1g0.00000.fits'
nsum=psrffilesum(fname,sumI)

2. Get all the a2675 files under /share/pdata1 (online files) for 11mar2012
   list a 1 line summary of each file as they are read

n=masfilelist(junk,fnmI,projid="a2675",yymmdd=20120311,/appbm,/psrfits)
nsum=psrffilesum(junk,sumI,fnmI=fnmI,/list)

NOTE:
   nsum will always equal the number of elements in flist or fnmI. You need
to check sumI.ok eq 1 to see if the data is ok. This lets you keep track
of bad files (say with 0 rows).

(See /pkg/rsi/local/libao/phil/psrfits/psrffilesum.pro)


PSRFGET - INPUT NEXT PSRFITS ROW FROM DISC

[Previous Routine] [Next Routine] [List of Routines]
NAME:
psrfget - input next psrfits row from disc

SYNTAX: istat=psrfget(des,b,row=row,hdronly=hdronly,blankcor=blankcor,avg=avg,$
                          tp=tp)

ARGS:
    desc:{descpsrf}  from psrfopen();

RETURNS:
     b: structure holding the hdr and data input
  tp[ndump,npol]: float  if tp provided (and averge set) then also
                 return the total power for each time sample
 istat: 1 ok
      : 0 hiteof
      :-1 i/o error..bad hdr, etc..


KEYWORDS:
     row     : if set then position to row before reading (count from 1)
               if row=0 then ignore row keyword
     hdronly : if set then just return the row header. no status or data.
    blankcor : if set then correct for any blanking.. the forces the
               returned dataset to be floats
       avg   : if set then average the spectra in 1 row before returning.
               This forces the returned datatype to be float.  
               this will automatically do the blankcor (since it normalizes
               the sum to the total number of ffts accumulated * the 
               integration period std value.

DESCRIPTION:

   Read the next row from a psrf fits datafile pointed to by desc.
  If keyword row is present, position to row  before reading.

(See /pkg/rsi/local/libao/phil/psrfits/psrfget.pro)


PSRFIMGDISP - DISPLAY A SET OF PSRFITS RECORDS AS AN IMAGE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
psrfimgdisp - display a set of psrfits records as an image
SYNTAX: img=psrfimgdisp(desc,b,nsigclip=nsigclip,clip=clip,pollist=pollist,col=col,$
                  toavg=toavg,median=median,bpc=bpc,ravg=ravg,nobpc=nobpc,$
                  win=win,wxlen=wxlen,wylen=wylen,wxpos=wxpos,wypos=wypos,$
                  samewin=samewin,zx=zx,zy=zy,$
                        rddesc=rddesc,maxrecs=maxrecs,mytitle=mytitle,$
                   hlind=hlind,hlval=hlval,hldash=hldash,hlvlines=hlvlines,$
                   useind=useind,ln=ln,chn=chn,cs=cs)
ARGS:
     desc : {}     from psrfopen open
   b[nrecs]: {corget} correlator data to make image of 
RETURNS:
   img[nchns,nrecs]: float image of last sbc displayed (before clipping).

KEYWORDS:
                  
    nsigClip:float if suppled then clip data to [-sig,sig]*nsigClip
                   This is done after any averaging for -zx,-zy.
                   If this is supplied, then clip= is ignored.
     clip[]: float  value to clip the normalized data to. Default is
                    .02 (of Tsys). If clip has 1 value then 
                    normalize to (img > (-clip)) < clip. If two value are
                    provided, then they will the [min,max].
    pollist: long   A single number whose decimal digits specify the pols  
                    to display. eg 1,12,1234 .. pols,3,4 are stokes u,v
                    The default is pola,polb.
        win: int window number to plot in. default is 1.
      wxlen: int xlen of window. default 700
      wylen: int ylen of window. default 870
      wxpos: int xpos of lower left edge of window.default 445
      wypos: int ypos of lower left edge of window.default:35
    samewin:     if set then use the current dimension for the image win.
                 If you are calling psrfimgdisp in a loop then setting this
                 (after the first call) lets the user dynamically adjust the
                 window size,position.
         zx: int ..-3,-2,2,3,4 zoom factor x dimension. Negative numbers 
                   shrink the image positive numbers expand. Negative number 
                   must divide evenly into the number of channels.
         zy: int ..-3,-2,2,3,4 zoom factor y dimension (same format as zx)
     rddesc:       if true then read data using descrtipor. returns
                   data read in in b.
     col[2]: int .. x columns to use to flatten the image in the time
                    direction. count 0..numberoflags-1. If multiple sbc 
                    plotted then the same cols are used for all sbc. The
                    default is no flattening in the time direction.
        chn:        if set then plot vs channel number rather than freq
        bpc:{masget} if supplied then this data will be used to do the
                    bandpass correction. The default is to average over
                    all of the nrecs.
      nobpc:        if set then no bandpass correction is done.
     median:        if set and bpc not provided, then bandpass correct using
                    the median of the nrecs rather than the average.
       ravg: long   bandpass correct with a running average of ravg spectra
                    for polB). You can change this with the numspc keyword 
      numspc: int   number of spectra to display from b (or to read from the
                    file. The default if b is provided is the entire array.
                    If reading from the file then we will use about 600 spc.
                    This will be the count prior to any averaging (see toavg)
      toavg: long   average this many spectra together before making image.
                     (zy will to the averaged array).
   mytitle:string    user supplied tittle instead of scan,srcname,az,za
                     az,za at top of the plot.
   hlind[]: ind      index into img array (2nd dimension) to draw
                     horizontal lines.
   hlval  : float    value to use for horizontal lines (in img units)
                     default is clip value.
   hldash : int      The dash lengths to used for the horizontal lines.
                     2*ldash must divide into x dimension.default is 4
   hlvlines:int      Number of engths to used for the horizontal lines.
                     default=1
   useind[2]:int     if provided then use these indices from data array
                     0 .. lengthsbc -1
                     default=1
   ln       :int     linenumber for title..0..33 def:3
   extra_=e          this allows you to input keywords that will be
                     passed to the plotting routine. eg title=title..
  
DESCRIPTION:
   psrfimgdisp will display a set of psrf spectra as an image.
By default it will make a separate image for each polA and polB.
The polList keyword lets you specify polA or polB (and someday maybe
stokes U,V.
   You can input the data outside of this routine (eg with psrfget)  by
setting the keyword rddesc=1 (by default the user passes the data in
 in b.

   By default, the image is bandpass normalized by the average of all the
records (sbc/avg(pol) - 1). If the median keyword is used then
 avg(sbc) is replaced by median(pol). The bpc keyword allows you to input
a separate mas record to use as the normalization.
   The col keyword lets you also flatten the image in the time 
dimension by specifying the first/last columns to average and then divide 
into all of the other columns (the columns are counted from 0). By default
this is not done.

   After bandpass correction and flattening in the time dimension, the
image is clipped (by default) to +/- .02 (tsys) and then scaled
from 0 to 256 for the image display. The clip  keyword lets you change the
clipping value.

   The zx,zy keywords let you scale the image in the x and y dimensions by
integral amounts. Negative numbers will shrink it by that amount (Note:
the negative numbers must divide evenly into the number of channels in
each sbc). -1,0,1 do no scaling. This scaling is only applied for the single
pol displays. The multiple pol displays are always scaled to fit 
inside the window (700 by 870 pixels).

   The desc and numspc keywords can be used to input the data directly from
a file. In this case the desc comes from the psrfopen() routine and numspc
is the number of spectra to put in the image.

   After displaying the image, use xloadct to manipulate the color table.

   The routine returns the last image displayed (before clipping).

EXAMPLES:
   input data and make an image
   istat=masgetm(desc,30,b,/han0  .. input 30 rows with hanning smoothing
                                  .. assume there are 10 spec/row
1. display the image of pola and polB
   img=psrfimgdisp(b)
2. display only polB, scale y by 2, and x by -2
   img=psrfimgdisp(b,pol=0,zx=-2,zy=2)
3. display pola,polB, clip to .015 Tsys , median filter the
   bandpass correction:
   img=psrfimgdisp(b,/median,clip=[.015])
This routine calls imgflat, and imgdisp for the image scaling and display.

NOTE:

SEE ALSO:
   imgdisp,imgflat

(See /pkg/rsi/local/libao/phil/psrfits/psrfimgdisp.pro)


PSRFMONIMG - MONITOR PSRFITS FILES VIA DYNAMIC SPECTRA.

[Previous Routine] [Next Routine] [List of Routines]
NAME:
psrfmonimg - monitor psrfits files via dynamic spectra.
SYNTAX: psrfmonimg,bsg=bsg,num=num,projid=projid,date=date,dirI=dirI,$
                 nspc=nspc,pollist=pollist,desc=desc,zx=zx,zy=zy,$
				  blankcor=blankcor,pixwin=pixwin
ARGS: none
KEYWORDS: 
    bsg: string beam,band,group to monitor. Format is bBsSgG where:
                B =0..6 is the beam 
                S =0..1 is the band (0=1450 band, 1=1300 band)
                G =0..1 is the group.
                default:'b0s0g0'
    num: int    the file number to start with. (The default is the most recent)
 projid: string project id (first part of filename) to monitor. The default
                is the most recent one written.
 date  : long   The date (in the filename) to start monitoring. The
                default is the most current (and still matches the other
                criteria.) The format is yyyymmdd.
 dirI : strarr(2): directory info. If the files are in a non standard place
                then pass in location in dirI
                dirI[0]=prefix  for dir: /share/pdata
                        Num 1..n goes here
                dirI[1]=postfix for dir: /pdev
 IMAGE:
    nspc: int   the number of spectra for each image. The default is 
                500 (or the max number in the file). It will try and 
			 	 round the number to a multiple of spectra per row.
 pollist: int   pols for image. 1,2,12, -1 --> all pols available
                if stokes, it does not plot u,v
  zx    : int   if single pol then zoom (=n) or contract (-n) x axis by this
                amount.
  zy    : int   if single pol then zoom (=n) or contract (-n) y axis by this
                amount.
blankcor:       if set then correct for adc blanking.
pixwin  :       if set then use a pixwin to switch between images (
				 stops the flashing.
RETURNS:
 desc  : {}     You can return from masmon with the current file still
                open (using the x command from the menu). The file descriptor
                will be returned here (this is actually a structure used by the
                masxx routines). It is then your responsibility to close the
                file via masclose,desc or masclose,/all.

 -----------------------------------------------------------------------------
DESCRIPTION:
   Monitor online and offline psrfitst files by making a dynamic spectra of 
 the data. The files to monitor can be selected by:
1. if no arguments are supplied, use the most recent files from 
   beam0,band0,group0.
2. Specify the projid,date using the startup keywords.
3. Use the menu inside masmon to select a different set of files to monitor.
   - Enter the menu once masmon is started by hitting any key. 

 -----------------------------------------------------------------------------
EXAMPLES:

   psrfmonimg - start monitoring most recent file for b0s0g0
   psrfmonimg,bsg=b0s1g0     .. start with beam0, band1 , group0
   psrfmonimg,projid='a2130' .. use a2130 files
   psrfmonimg,pollist=1     .. images of only polA 
 -----------------------------------------------------------------------------
USING THE INTERNAL MENU:

   Enter the internal memory by hitting any key.
The menu is:

Cmd CurVal    function

 -->  IMAGES:
 p   12         pols for images (1,2,12)
 h   low high   set horizontal range for images (freq low,hihg), blank --> all
 nspc 500       number of spectra per image. blank--> auto
 c   .02        clip value for data
 delay secs     secs to delay between images..

 -->  FILE POSITIONING:
 bsg  b0s0g0     beam,band,grp to use (change all at once)
 bm   0          beam to plot
 band 0          band to display (0 = 1450, 1=1300)
 d    20081011   date to use. First number of data displayed
 num  00801      number.. file number to display
 r       1       position to row. maxRows:  99
 l    (all)      list files this date (all --> all dates)

 -->  MISC:
 hdr            display last header read
 s      0       step mode. 1-on,0-off
 z              stop in procedure (for debugging)
 q              to quit
 x              quit leaving the current file open. return description in desc keyword
otherKeys       continue plotting

 Enter the cmd and a possible value. The program will then continue. 
The menu options are:

 p 12        .. pols for image. By default both pols are used (but in stokes mode
                u,v are note used.
             .. The pols are numbered: 1-polA,2-polB. Any combination 
             .. of the pols can be displayed (entered as a one number eg 12..)
   Example:
     p 12    .. use pols a and polB.
 h           .. change the frequency range of the image. Units are Mhz. The default
                is the entire frequency range.
   Example:
     h 1400 1450 display frequencies 1400 thru 1450 (if they are in the band)
 delay       .. secs to delay between plots. Use if the plotting is going
                too fast.
   Example:
     delay .1   Delay .1 seconds between plots

 bsg b0s0g0  .. Select the beam,band,group to display. 
             .. By default beam0,band0,grp0 is displayed.
   Example:
     bsg b0s1g0   .. will display the band centered at 1300 Mhz.

 d  20080826 .. Move to first file on this date using the current 
                project id.
  
 n   100     .. Move to this filenumber for the current date and project id.
                If the number does not exist, you remain on the current file.
 l  (all)    .. list files for this projid, data. If all is included then 
                list files for this projid for all dates.
 r  1        .. position to a row in the current file (count from 1)

 hdr         .. print last header read
 s  0/1      .. step mode will stop and display the menu after each spectra is
                plotted. s 1 turns on step mode. s 0 turns it off.
 z           .. stop in masmon routine (for debugging)
 q           .. exit masmon.

(See /pkg/rsi/local/libao/phil/psrfits/psrfmonimg.pro)


PSRFOPEN - OPEN PSRFITS FILE FOR READING

[Previous Routine] [Next Routine] [List of Routines]
NAME:
psrfopen - open psrfits file for reading
SYNTAX: istat=psrfopen(filename,desc,fnmI=fnmI)
ARGS:
   filename: string    filename to open (unless fnmI is specified)
KEYWORDS:
   fnmI    : {]        returned from psrffilelist. if provided,
                       then ignore filename and use this as the
                       file to open.
RETURNS:
   istat: 0 ok
          -1 could not open file.
   desc : {}  file descriptor to pass to the i/o routines.
DESCRIPTION:
 	open  an ao psrfits file.

(See /pkg/rsi/local/libao/phil/psrfits/psrfopen.pro)


PSRFTPFILE - COMPUTE TOTAL POWER FOR FILE

[Previous Routine] [List of Routines]
NAME:
psrftpfile - compute total power for file

SYNTAX: n=psrftpfile(fname,tp,fnmI=fnmI,hdr=hdr,maxrows=maxrows,blankcor=blankcor)

ARGS:
    fname: string	name of file
    fname: string	name of file
KEYWORDS:
maxrows: long		max number of rows to input
	fnmI:  {}       structure from masfilelist for file to use
					In this case ignore fname
blankcor:          If set the correct for adc blanking
RETURNS:
  tp[n,npols]: float total power
 hdr         : struct primary and extension headers

 n:   >=0 number of sample points returned
      < 0  error

DESCRIPTION:
   Read in a file and compute the total power

(See /pkg/rsi/local/libao/phil/psrfits/psrftpfile.pro)