Puppi idl routines

Last modified: Thu Mar 16 13:07:10 2023.


List of Routines


Routine Descriptions

PUPFAVG - AVERAGE PUPPI FITS FILE ROW(S)

[Next Routine] [List of Routines]
NAME:
pupfavg - average puppi fits file row(s)
SYNTAX: bavg=pupfavg(hsubint,b,median=median)
ARGS:
hsubint : {}   sub int header. from desc.hsubint
b[n]    : {}   puppi fits file data n=1 to n
KEYWORDS:
median :       if set then compute median rather than average
RETURNS:
bavg   :  {}   averaged data.
DESCRIPTION
	Input a puppi fits file record(s). Average over the nsblk of each
rec as well as over multiple rows (if input). Do not average the pols.
	The bavg.data  will be dimensioned nchan,npol
Warning: if using the median. be careful passing in an array of recs
 too largee (since it will do the median by chan over all the data.
Example:
   istat=pupfget(desc,b1)
   istat=pupfget(desc,b2)
   b=[b1,b2]
	bavg=pupfavg(desc.hsubint,b)
 
Warning: the routine does not update the header locations
         eg. tsubint 

(See /pkg/rsi/local/libao/phil/pupi/pupfavg.pro)


PUPFCLOSE - CLOSE A PUPPI PSRFITS FILE FOR I/O

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

SYNTAX: pupfclose,desc,all=all 

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

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

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

(See /pkg/rsi/local/libao/phil/pupi/pupfclose.pro)


PUPFFILELIST - GET LIST OF PUPPI FILES

[Previous Routine] [Next Routine] [List of Routines]
NAME:
pupffilelist - get list of puppi files 
SYNTAX: nfiles=pupffilelist(dirBase,flist,seqI,yymmdd=yymmdd,$
				mjd=mjd,src=src ,seqNum=seqNum

ARGS:
   dirBase: char    base directory to start search
                    if '' then use default /share/pdata

KEYWORDS:
 yymmdd   : long    date for data you want (this is an AST date)
    mjd   : long    mjd for data (instead of yymmdd)
    src   : string  limit to this source name
  seqNum  : long    limit to this seq num puppi_mjd_src_seqnum
              
RETURNS:
   nfiles    : long  number of .fits files found
flist[nfiles]: string  array of filenames
  seqI[nseq] : {} seq info for each sequence

 
DESCRIPTION:
   Search for puppi psrfits files.
 Example:
   Assume files in "/local/data/phil/puppi/"
  n=pupffilelist(dir,flist,yymmdd=120309,src='1713+0747')


(See /pkg/rsi/local/libao/phil/pupi/pupffilelist.pro)


PUPFGET - INPUT NEXT PUPPI FITS ROW FROM DISC

[Previous Routine] [Next Routine] [List of Routines]
NAME:
pupfget - input next puppi fits row from disc

SYNTAX: istat=pupfget(des,b,row=row,hdronly=hdronly,avg=avg,$
				   drms=drms)

ARGS:
    desc:{descpupf}  from pupfopen();

RETURNS:
     b: structure holding the hdr and data input
 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.
       avg   : if set then average the spectra in 1 row before returning.
               This forces the returned datatype to be float.  
     drms    : if provided then compute rms by chan and return in 
               drms[nchan]. do this before any averaging
               this is only available for search data.

DESCRIPTION:

   Read the next row from a pupf fits datafile pointed to by desc.
  If keyword row is present, position to row  before reading.
  For non search data the data on file is  nbins,nchan,npol
  we want to switch this to nchan,pol,nbin
Note:
	I'm not applying dat_scl.
    for i,q,u,v data,  dat_scl is .5 for u,v.. i'm ignoring  it.

(See /pkg/rsi/local/libao/phil/pupi/pupfget.pro)


PUPFOPEN - OPEN PUPPI PSRFITS FILE FOR READING

[Previous Routine] [Next Routine] [List of Routines]
NAME:
pupfopen - open puppi psrfits file for reading
SYNTAX: istat=pupfopen(filename,desc)
ARGS:
   filename: string    filename 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 pupfits file.
   For  data order is nphasBin,freqbin,pol,smp/blk
   we will want to store it : freqbin,npol,smp/blk or nbins s
   so we have to shuffle a bit.
  The search data comes back at bytes. Since idl's byte is
 unsigned, the get routine  will convert it to floats.
 The desc. will hold a struct that has all the row info up to the
 data. the get routine will then dynamically append the float data to
 this array
 mods:
 180505 - added chan_dm to hpri header

(See /pkg/rsi/local/libao/phil/pupi/pupfopen.pro)


PUPRCHANFREQ - COMPUTE CFR FREQ EACH PUPPI GPU

[Previous Routine] [Next Routine] [List of Routines]
NAME:
puprchanfreq - compute cfr freq each puppi gpu
SYNTAX: puprchanfreq,rfcfr,bwTot,nchan,gpucfr,chancfr,verb=verb,gpunames=gpunames
ARGS:
   rfcfr: double rf center freq on sky (Mhz)
   bwTot: double total bw (Mhz) of observation.
                 us -n if band is flipped.
   nchan: int    total number of puppi channels
              -1 , or not present --> input next block
KEYWORDS:
verb    : int   if true then also print results to stdout

RETURNS:
   gpuCfr[8]:double center freq (Mhz) each gpu.
 chanCfr[nchan/8,8] - cfr Mhz  each chan. The first index
                      goes over a gpu, the 2nd index of gpus 
 gpuNames[8]:strarr   name of each gpu

DESCRIPTION:
	Given apuppi configuration(total bandwidth, rfcfr, total number of channels)
compute the center frequency for each gpu (this should be the value in the
gpu header) as well as the center frequency of each channel.

 If Nchan 0.n-1 then dc goes to the center of chan N/2

(See /pkg/rsi/local/libao/phil/pupi/puprchanfreq.pro)


PUPRCLOSE - CLOSE A RAW PUPPI FILE FOR I/O

[Previous Routine] [Next Routine] [List of Routines]
NAME:
puprclose - close a raw puppi file for i/o

SYNTAX: puprclose,desc,all=all 

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

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

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

(See /pkg/rsi/local/libao/phil/pupi/puprclose.pro)


PUPRGET - READ IN A BLOCK OF PUPPI RAW DATA

[Previous Routine] [Next Routine] [List of Routines]
NAME:
puprget - read in a block of puppi raw data
SYNTAX: blkNum=puprget(desc,d,blkreq=blkreq,nsmp=nsmp,npol=npol,nchan=nchan)
ARGS:
    desc: {} returned by pupropen
KEYWORDS: 
    blk: int   block number to input, count from 1 
              -1 , or not present --> input next block
RETURNS:
     blkNum: >=1 block number we input. 
             blkNum-1 is index into desc.hdrI[blkNum-1]
             0 eof on input (no data)
          : -1,-2,-3  some type of i/o error or bad data found.
     nsmp:long   .. number of sample points per channel
     npol:long   .. number of polsample points per channel
     nchan:long   .. number of channels
  d[nsmp,npol,nchan]:complex   data returned

(See /pkg/rsi/local/libao/phil/pupi/puprget.pro)


PUPROPEN - OPEN PUPPI RAW FILE FOR READING

[Previous Routine] [List of Routines]
NAME:
pupropen - open puppi raw file for reading
SYNTAX: istat=pupropen(filename,desc,verb=verb)
ARGS:
   filename: string    filename to open
KEYWORDS:
   verb:     if set then print out header numbers we read them
RETURNS:
   istat: 1 ok
           0 hit eof reading ascii header
          -1 could not open file.
          -2 no header info in file
          -3 no END header card after 1000 cards
   desc : {}  file descriptor to pass to the i/o routines.
DESCRIPTION:
 	open  an ao puppi raw file. It will scan the file to find
the start of each block (with it's headers).

(See /pkg/rsi/local/libao/phil/pupi/pupropen.pro)