----------------------------------------------------------------------------------- The GBT Data Analysis Package in IDL v3.0 June 2004 T. M. Bania, Institute for Astrophysical Research v3.1 July 2004 Boston University v3.2 21 July 2004 ----------------------------------------------------------------------------------- IDL comments ----------------------------------------------------------------------------------- * IDL commands are NOT case sensitive so 'show' and 'SHOW' do the same thing. * Below is the list of IDL special characters. Do not use them unless you know IDL. ! ' ; $ " . & : * @ ? -> * To spawn a Unix command from within IDL: $pwd $cp file1 file2 To execute an IDL script batch file: @file_name_of_script To execute several IDL commands on a single command line: cmd1 & cmd2 & cmd3 & * Commands in this package are IDL procedures (proc_name.pro). Execute any command by inputing proc_name at the IDL command line. Arguments to IDL commands must be delimited by commas: proc_name,arg1,arg2,arg3, etc. * This package uses a great many IDL system variables, !sys_var_names, which have global scope to interconnect the procedures (commands). * If a procedure abends, always issue an IDL 'retall' "return all" command This is the equivalent of the CLASS necessity of issuing a lot of "quit" commands to ensure that you return back to the top level of execution * If you change a procedure, make sure to recompile it explicity via the command: .compile full-path-name/xxx.pro to recompile procedure xxx IDL will NOT dynamically recompile any procedure whose name matches that of an already compiled procedure, so you must force things with an explicit recompilation. If your Unix setenv IDL_PATH is OK, then .compile xxx.pro is OK... N.B. IDL has a strange relationship between saved .pro files. Sometimes it will not pick up the changed file during a recompilation. If this happends, exit and restart IDL. * To learn about what has been compiled try: 'help' at the command line for all procs 'help,prc_name' for a specific command do NOT expect too much =================================================================================== ----------------------------------------------------------------------------------- | The 3_Helium GBT Data Reduction System in IDL by T. M. Bania | ----------------------------------------------------------------------------------- v1.0 04 Feb 2004 v2.0 15 May 2004 v3.0 20 Jun 2004 v3.1 8 Jul 2004 v3.2 21 Jul 2004 =================================================================================== * The system has been written to look and feel as much as possible like the 3_Helium procs in UNIPOPS. When in doubt, pretend that the command does the same thing. * In IDL the only straightforward way for variables to have global scope is to define them to be system variables. We have the following intrinsic data structures defined as system variables: defsysv,'!b',replicate({gbt_data}, 15) ; define 16 system buffers ; each is the {gbt_data} structure format ; each holds a header and a spectrum ; defsysv,'!rec',replicate({gbt_data}, 1) ; a global for a single {gbt_data} structure * All the analysis is done with the !b[] buffers. This means that one can easily define other {data} structures and all the procedures will work if {data} contains certain required elements. ; ; !b[0] -- working buffer: everything invokes what is in here ; !b[1] -- BMODEL and GMODEL buffer ; !b[2] -- copy of !b[0] during BASE and GAUSS ; !b[3] -- ACCUM buffer ; !b[4] -- AVE buffer: copy of last AVE ; !b[5] -- ON buffer: copy of ON scan ; !b[6] -- OFF buffer: copy of OFF scan ; !b[7] -- PSW buffer: copy of (ON-OFF)/OFF ; !b[8] -- SMOOTH buffer: copy of data before any smoothing operation ; GAUSS: difference between DATA - GMODEL ; !b[9] -- SHOW buffer: copy of latest SHOW ; ; buffers 10 to 15 are scratch buffers at present. use them freely. ; ----------------------------------------------------------------------------------------------- * The package is started via the procedure START_GBT,fname where fname is an input FITS data file. --------------- * The GBT data are converted from this FITS file made by the program SDFITS to an internal IDL data structure format named {gbt_data} and written to an external file. V3.2 expects the SDFITS data to be avg.acs.fits data (-mode=avg -backends=acs) ------------ This is done at startup via the command MAKE_ONLINE which creates the ONLINE data file. This file is direct accessed in the package using the IDL ASSOCIATE command. * Initially the package scans the SDFITS FITS file and determines the size of the data array for the spectra. In this realization, only a *single* data array size is supported in order for the ASSOCIATE files to have a fixed length. One can analyze different data file sizes by exiting and then reentering the package. * After the data array size is determined, at startup the internal data structure {gbt_data} is defined as is the rest of the package: global variables are defined, an IDL journal file session is started, and one is given the opportunity to create an ONLINE data file containing the SDFITS FITS data in {gbt_data} format as well as an NSAVE file which allows one to save processed spectra in an external NSAVE file in {gbt_data} format. This latter feature makes the package fully re-entrant. * One can also create an OFFLINE data file which has {gbt_data} format data by definition. This allows one to use the ATTACH command to use all the package SELECT search capability to search for and process data from different observing runs. One toggles between ONLINE and OFFLINE data files via just those commands. * Finally, GBT_IDL v3.2 allows for continuum processing capability during the same session as spectral line processing. Toggle between via LINE and CONT. The CONTinuum data are packed into the {gbt_data} structure and operate on FITS files created via SDFITS for the GBT's DCR continuum backend via the -mode=cal -backends=dcr processing options. -------------------------------------------------------------------------------------------------- The current definition of {gbt_data} is: ; ; Define the basic 3-Helium internal data structure format ; ; IDL single dish package requires at least these variables ; total ; v3.1 8 July 2004 ; variables passed via SDFITS v1.1 release ; ; gbt = {gbt_data, $ ; # bytes -> # bytes source:bytarr(32), $ ; 32 32 source name observer:bytarr(32), $ ; 32 64 observer ID obsid:bytarr(32), $ ; 32 96 observation description scan_num:0L, $ ; 4 100 scan number last_on:0L, $ ; 4 104 last ON scan: PS last_off:0L, $ ; 4 108 last OFF scan: PS procseqn:0L, $ ; 4 112 procedure sequence # procsize:0L, $ ; 4 116 # scans in procedure pol_id:bytarr(4), $ ; 4 120 polarization ID string line_id:bytarr(32), $ ; 32 152 line ID via corr sampler scan_type:bytarr(32), $ ; 32 184 scan type ON/OFF etc lst:0.0D, $ ; 8 192 LST at scan start in sec date:bytarr(32), $ ; 32 224 date/time string frontend:bytarr(16), $ ; 16 240 frontend ID string ra:0.0D, $ ; 8 248 RA in degrees dec:0.0D, $ ; 8 256 DEC in degrees epoch:2000.0D, $ ; 8 264 EPOCH of ra/dec l_gal:0.0D, $ ; 8 272 l_gal in degrees b_gal:0.0D, $ ; 8 280 b_gal in degrees hor_offset:0.0D, $ ; 8 288 map horizontal offset pos'n ver_offset:0.0D, $ ; 8 296 map vertical offset position az:0.0D, $ ; 8 304 AZIMUTH in degrees el:0.0D, $ ; 8 312 ELEV in degrees vel:0.0D, $ ; 8 320 Source velocity m/sec sky_freq:0.0D, $ ; 8 328 center frequency Hz rest_freq:0.0D, $ ; 8 336 rest frequency at band center ref_ch:0.0D, $ ; 8 344 reference ('center') channel delta_x:0.0D, $ ; 8 352 delta freq of x-axis in Hz vel_def:bytarr(8), $ ; 8 360 velocity reference frame ID vframe:0.0D, $ ; 8 368 frame radial velocity m/sec rvsys:0.0D, $ ; 8 376 Vsource - Vtelescope m/s bw:0.0D, $ ; 8 384 bandwidth in Hz tsys:0.0D, $ ; 8 392 system temperature in Kelvin tsys_on:0.0D, $ ; 8 400 Tsys ON source/freq tsys_off:0.0D, $ ; 8 408 Tsys OFF source/freq tcal:0.0D, $ ; 8 416 cal value in Kelvin tintg:0.0D, $ ; 8 424 effective integ. time sec feed:0.0D, $ ; 8 432 signal feed number srfeed:0.0D, $ ; 8 440 reference feed number beamxoff:0.0D, $ ; 8 448 beam XEL offset in degrees beameoff:0.0D, $ ; 8 456 beam EL offset in degrees freqoff:0.0D, $ ; 8 464 sideband:bytarr(4), $ ; 4 468 resulting sideband U/L data_points:!data_points, $ ; 4 472 # data points in spectrum history:bytarr(552), $ ; 552 1024 annotation string data:fltarr(!data_points) $ ; 16,384 17,408 ; ; --> uses !data_points value to set size of data array ; --> size = 4bytes * !data_points : 4 x 4096 = 16,384 bytes ; --> SDFITS sends data as single float values ; ; --> correlator has 32,768 channels maximum = 64 x 512 ; 4 x 32,768 = 131,072 bytes ; } ; end of definition ; ; unformated read/write files and the ASSOC IDL command all need for ; the data to have fixed length records for maximum utility ; ; thus all string variables from SDFITS are stored here as byte ; arrays of ASCII codes with one ASCII character coded by each ; byte. note that we are keeping this structure aligned on ; 16 byte boundaries for obvious reasons ; ; all declariations match SDFITS precision ; ; ---------------------------------------------------------------------------------------- Version 3.2 defines the following procedures: Descriptions of the procedures are in the file: ~/idl/v3.2/DOCS/PROCEDURES_LIST_V3.2 ==> There is an IDL-doc library .html file in ~/idl/v3.2/DOCS/ <== THIS FILE GIVES WEB BROWSER ACCESS TO ALL OF THIS DOCUMENTATION: ==> ../v3.2/DOCS/gbt_idl_v3.2.html <== FOR INFORMATION ANENT THE LIBRARIES INVOKED BY V3.2: ==> ../v3.2/DOCS/gbt_idl_libs.html <== ======================================================================================== The following procedures are defined in this system. N.B. Other procedures are also invoked and defined, but they should be transparent to the user. ================================================================================ ================================================================================ ACCUM ADD ADDEM ATTACH AVE AVGSTK AZXX B BB BBB BIAS BMARK BSEARCH BOXCAR CAT CCC CHAN CLEARSET CLRSTK COMMENT CLOSE_DATAFILE CONDAR CONTINFO CONT COPY CUROFF CURON CGBT_WIN CGG DATE DEF_AXIS DCSUB DCOFF DCON DECX DISP DIV DISPLAY ELXX FETCH FIND_FILE FILES FLAG FLAGOFF FLAGON FLG_ID FREEX FREEXY FREEY FREQ G GAUSS GBTRESTORE GBTSAVE GBT_WIN GET GETNS GETOFF GETON GETONLINE GETOFFLINE GET_SCAN GG GGG H115 H91 H92 HDR HE3 HLINE IDCHAN INFO INIT_DATA INIT_NSAVE KILLWIN KONDAR KSR KURSOR LASTX LASTY LASTXY LINE LIST LOOK LOOKAV MAKE_DATA MAKE_NSAVE MAKE_CDATA MAKE_ONLINE MULT MASK MGAUSS MINUS MK MRDFITS MRSET NROFF NRON NRSET NSOFF NSON NSLOG NRFI ONLINE OFFLINE ORTHOFIT PLTG PLTHDR PLUS PRINTOFF PRINTON PROCS PS PLTCHDR PSOFF PSON PSPLOT PUTNS QAV QLOOK QLOOK4 QQQ RADIOM RAXX REC_INFO RESHOW RMS RXIDREC RFI SCALE SD_HDR SD_TO_GBT SD2CGBT SELECT SET SETID SETCOLORS SETPLOT SETRANGE SETREC SETSCAN SETSRC SETTYPE SETPOL SETXY SETX SETY SHOW SMO SMOOTH SRCVL SRCVLON SRCVLOFF SUB SYMS START_GBT SETPRINTER TAGID TAGTYPE TAGPOL TELLSTK TH_RMS UNMK UPDATE VELO WRESET XROLL XX ZLINE ZLOFF ZLON ================================================================================ ================================================================================ all procedures operate on the data in the !b[0] buffer some use the other buffers for temporary use and/or results of fits Documentation is in the directory: ~/idl/v3.2/DOCS/ Procedures are in the directory: ~/idl/v3.2/ ............................................................................ INSTALL_V3.2 tells you how to install this package on your local system. ............................................................................ ............................................................................ OVERVIEW gives general information about using IDL together with a global view of the structure of this software package. ............................................................................ ............................................................................ COOK_BOOK gives you a user-friendly tutorial on how to use the package. To fully utilize the recipes you will need to have access to the sample 3He data set it uses. In Green Bank this SDFITS file is named '/users/tbania/idl/data/Feb04.avg.acs.fits'. To access this file, after IDL is started issue the command: start_gbt,'/users/tbania/idl/data/Feb04.avg.acs.fits' ............................................................................ ............................................................................ COMMANDS lists all the commands of v3.2 and gives a short description of their function. The commands are grouped according to their functionality. ............................................................................ ............................................................................ PROCEDURES_LIST_V3.2 gives a full description of all the commands in v3.0 listed alphabetically. ............................................................................ ............................................................................ CONTINUUM describes the procedures needed to analyze DCR continuum data. ............................................................................ ............................................................................ FLAGS describes the Boolean flags used by the v3.2 package to control various behaviors of the commands. ............................................................................ ............................................................................ PRINTING tells you how to get hardcopy output from this package. ............................................................................ ............................................................................ NOTES_V3.0 describes v3.0 changes from previous versions of this software. ............................................................................ Ditto for other NOTES **************************************************************************** **************************************************************************** HTML HELP EXISTS: SEE ../v3.2/DOCS/ **************************************************************************** **************************************************************************** In ../v3.2/DOCS/ there are two .html pages of great utility which allow you to use your web browser to view documentation and procedures for the v3.2 GBT_IDL package: 1. gbt_idl_v3.2.html Provides hypertext links to all the text documents in the ../v3.2/DOCS directory. It also provides hypertext links to all the GBT_IDL commands as well as links to the .pro procedure files themselves. 2. gbt_idl_libs.html Provides hypertext links to all JHU ASTROLIB procedures as well as the TeXtoIDL package procedures. These files are generated by the following procedures: mk_html_v3_2.pro create_v3_2.pro mk_html_libs.pro create_libs.pro SEE INSTALL_V3.2 FOR DIRECTIONS ON HOW TO MODIFY THESE PROCEDURES FOR YOUR LOCAL INSTALLATION.