Using IDL To Work With Raw ACF Data

Overview

This tutorial shows you how to use the raw.pro and oldraw.pro libraries to work with raw ACF data stored in rawacf and dat files. The rawacf files are the replacements to the dat files. Although the two file types are very different, the IDL interfaces are very similar and return the same data structures regardless of the file being read.

The libraries consist of functions written both in native IDL and functions that act as wrappers and use theCALL_EXTERNAL function to call the C libraries. The native IDL functions are the most portable, but are considerably slower than using the C libraries. The libraries contain a third set of functions that automatically determine whether the native IDL or C library functions should be used; you don't need to worry about which set of functions to use.

Reading rawacf Files

The example program presented below does the simple task of reading records from a rawacf file and plots the lag-zero power measurements.

pro readrawacf

; Open the raw index file and load it into the inx structure 

  openr,inp,'test.rawinx',/GET_LUN,/STDIO,/SWAP_IF_BIG_ENDIAN
  s=RawLoadInx(inp,inx)
  free_lun,inp
 
; Open the raw file for read only 
 
  inp=RawOpen('test.rawacf',/read)
 

;  Search for a specific time in the file

  s=RawSeek(inp,2002,12,19,0,30,10,inx,atme=atme)
 
  while RawRead(inp,prm,raw) ne -1 do begin
     print, prm.time.hr,prm.time.mt,prm.time.sc
     plot,raw.pwr0[0:prm.nrang-1]
     stop
  endwhile
  free_lun,inp
end

The file is opened using the call to RawOpen if successful, this function returns the logical unit number associated with the file.

The rawacf files can have an optional, associated index file that greatly speeds up searching for specific records. If this file is not available, then a much slower manual search is performed.

The read routine RawRead returns two structures, the first is the radar parameter block and the second is the raw ACF data. The contents of these structures are documented in RFC #0020 and RFC #0021

Reading dat Files

The example program presented below does the simple task of reading records from a dat file and plots the lag-zero power measuremens.

pro readraw
  
; Open the raw file

  rawfp=OldRawOpen('test.dat')


;  Search for a specific time in the file

  s=OldRawSeek(rawfp,2002,12,19,1,30,10,atme=atme)

  while OldRawRead(rawfp,prm,raw) ne -1 do begin
     print, prm.time.hr,prm.time.mt,prm.time.sc
     plot,raw.pwr0[0:prm.nrang-1]
     stop
 endwhile
 s=OldRawClose(rawfp)
end

The file is opened using the call to OldRawOpen if successful, this function returns a structure containing the dat file pointer.

The dat files do not have an associated index file, so the search routine is performed manually.

When the file is finished with, you should call OldRawClose to close the file and to free up any memory resources used.

Writing rawacf Files

The program presented below is a simple extension to the read program that uses the RawWrite function to write the data to a new file.

pro writerawacf

; Open the raw index file and load it into the inx structure 

  openr,inp,'test.rawinx',/GET_LUN,/STDIO,/SWAP_IF_BIG_ENDIAN
  s=RawLoadInx(inp,inx)
  free_lun,inp
 
; Open the raw file for read only 
 
  inp=RawOpen('test.rawacf',/read)
  out=RawOpen('test2.rawacf',/write)

;  Search for a specific time in the file

  s=RawSeek(inp,2002,12,19,0,30,10,inx,atme=atme)
 
  while RawRead(inp,prm,raw) ne -1 do begin
     print, prm.time.hr,prm.time.mt,prm.time.sc
     s=RawWrite(out,prm,raw)
  endwhile
  free_lun,inp
  free_lun,out
end

Writing dat Files

Writing dat files is slightly more complicated as the file format includes a header record and each record has a record number. The program below uses the counter rn to track the record number and to output the file header using OldRawWriteHeader when the first record is written out.

pro writeraw
 
; Open the raw file for reading

  infp=OldRawOpen('test.dat')
  
  openw,outfp,'test2.dat',/get_lun

;  Search for a specific time in the file

  s=OldRawSeek(infp,2002,12,19,1,30,10,atme=atme)

  rn=1

  while OldRawRead(infp,prm,raw) ne -1 do begin
     print, prm.time.hr,prm.time.mt,prm.time.sc
     raw.pwr0[0:prm.nrang-1]=raw.pwr0[0:prm.nrang-1]-10
     if (rn eq 1) then s=OldRawWriteHeader(outfp,prm,raw)
     s=OldRawWrite(outfp,prm,raw,rn)
     rn++
 endwhile
 s=OldRawClose(infp)
 free_lun,outfp
end

Unlike the read routines which use a structure as the file pointer, writing of dat files is done using standard IDL logical unit numbers.