Overview

This tutorial shows you how to use the fit.pro and oldfit.pro libraries to work with fitted ACF data stored in fitacf and fit files. The fitacf files are the replacements to the fit 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 fitacf Files

The example program presented below does the simple task of reading records from a fitacf file and plots the velocity measurements.

pro readfitacf

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

  openr,inp,'test.fitinx',/GET_LUN,/STDIO,/SWAP_IF_BIG_ENDIAN
  s=FitLoadInx(inp,inx)
  free_lun,inp
 


; Open the raw file for read only 
 
  inp=FitOpen('test.fitacf',/read)
 

;  Search for a specific time in the file

  s=FitSeek(inp,2002,12,19,0,30,10,inx,atme=atme)
  while FitRead(inp,prm,fit) ne -1 do begin
     print, prm.time.hr,prm.time.mt,prm.time.sc
     plot,fit.v[0:prm.nrang-1]
     stop
  endwhile
  free_lun,inp

end

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

The fitacf 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 FitRead returns two structures, the first is the radar parameter block and the second is the fitted ACF data. The contents of these structures are documented in RFC #0020 and RFC #0022

Reading fit Files

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

pro readfit

  
; Open the fit file

  fitfp=OldFitOpen('test.fit','test.inx')


;  Search for a specific time in the file

  s=OldFitSeek(fitfp,2002,12,19,1,30,10,atme=atme)

  while OldFitRead(fitfp,prm,fit) ne -1 do begin
     print, prm.time.hr,prm.time.mt,prm.time.sc
     plot,fit.v[0:prm.nrang-1]
     stop
 endwhile
 s=OldFitClose(fitfp)
end

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

The fit file may have an associated index file that should be past as the second argument to OldFitOpen. The index file greatly speeds up searching for specific records, if the index file is not supplied a much slower manual search is performed.

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

Writing fitacf Files

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

pro writefitacf

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

  openr,inp,'test.fitinx',/GET_LUN,/STDIO,/SWAP_IF_BIG_ENDIAN
  s=FitLoadInx(inp,inx)
  free_lun,inp
 
; Open the raw file for read only 
 
  inp=FitOpen('test.fitacf',/read)
  out=FitOpen('test2.fitacf',/write)

;  Search for a specific time in the file

  s=FitSeek(inp,2002,12,19,0,30,10,inx,atme=atme)
  while FitRead(inp,prm,fit) ne -1 do begin
     print, prm.time.hr,prm.time.mt,prm.time.sc
     
     s=FitWrite(out,prm,fit)
  endwhile
  free_lun,inp
  free_lun,out

end

Writing fit Files

Writing fit files is slightly more complicated as the file format includes a header record and each record has a record number and the data file has an associated index file.

Once the index file has been written out, a call is made to OldFitInxClose to make sure that the index contains the start and end time of the file.

pro writefit

  openw,out,'test2.fit',bufsize=0,/get_lun,/stdio
  openw,inx,'test2.inx',bufsize=0,/get_lun,/stdio

  fitfp=OldFitOpen('test.fit','test.inx')

  irec=1L
  drec=2L
  dnum=0L

  s=OldFitSeek(fitfp,2002,12,19,1,30,10,atme=atme)

  while OldFitRead(fitfp,prm,fit) ne -1 do begin

   print, prm.time.hr,prm.time.mt,prm.time.sc
    tprm=prm
    if (drec eq 2) then s=OldFitWriteHeader(out,prm,fit)
    if (irec eq 1) then s=OldFitInxWriteHeader(inx,prm)
    dnum=OldFitWrite(out,prm,fit)
    s=OldFitInxWrite(inx,drec,dnum,prm)
    drec+=dnum
    irec++
 endwhile

 s=OldFitInxClose(inx,tprm,irec-1)

 s=OldFitClose(fitfp)
 free_lun,inx
 free_lun,out

end

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