%!PS %%Title: The Funtools Help Facility %%Creator: html2ps version 1.0 beta5 %%EndComments save 2000 dict begin /d {bind def} bind def /D {def} d /t true D /f false D /FL [/Times-Roman /Times-Italic /Times-Bold /Times-BoldItalic /Courier /Courier-Oblique /Courier-Bold /Courier-BoldOblique /Helvetica /Helvetica-Oblique /Helvetica-Bold /Helvetica-BoldOblique] D /WF t D /WI 0 D /F 1 D /IW 471 F div D /IL 621 F div D /PS 791 D /EF [0 1 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 2 2] D /EZ [11 9 19 17 15 13 12 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 8 8] D /Ey [0 0 2 2 2 2 2 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0] D /EG [-1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1] D /Tm [1 1 0.8 0.8 0.8 0.8 0.8 0.8 0 0 0 0 0 0 0.5 1 1 1 1 0 0 1.3 0 0] D /Bm [1 1 0.5 0.5 0.5 0.5 0.5 0.5 0 0 0 0 0 0 0.5 1 1 1 1 0 0 1 0 0] D /Lm [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 2 2 0 0 2 0 0 0] D /Rm [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0] D /EU [-1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 0 0] D /NO t D /YY [[{()}1][{()}0][{()}2]] D /ZZ [[{()}1][{()}0][{()}2]] D /Ts EZ 0 get D /TU f D /Xp t D /AU t D /SN 0 D /Cf f D /Tp f D /Fe f D /TI 1 Ts mul D /Fm 14 D /xL 71 D /xR 71 D /yL 706 D /yR 706 D /Wl 471 F div D /Wr 471 F div D /hL 621 F div D /hR 621 F div D /FE {newpath Fm neg Fm M CP BB IW Fm add Fm L IW Fm add IL Fm add neg L CP BB Fm neg IL Fm add neg L closepath} D /LA {PM 0 eq{/IW Wl D /IL hL D}{/IW Wr D /IL hR D}ie /W IW D /LL W D /LS W D TU PM 0 eq and{IW 56 F div add SA{Sf div}if 0 translate} {PM 0 eq{xL yL}{xR yR}ie translate F SA{Sf mul}if dup scale CS CF FS Cf{CA CL get VC}if /Bb f D}ie 0 0 M TF not Tc or {Cf{gsave SA{1 Sf div dup scale}if Cb VC FE fill grestore}if}if}D /Pi 0 Ts mul D /SG [0.8 1 1] D /Ab 15 D /J 0 D /Tc t D /NH 6 D /Nf f D /Pa f D /LH 1.2 D /XR f D /Xr {/pN E D ( [p ) WB pN WB (] )WB} D /Db [16#FF 16#FF 16#FF] D /Dt [16#00 16#00 16#00] D /eA f D /Fi f D /bT f D /Lc t D /Dl [16#00 16#00 16#00] D /LX f D /Br 0.25 D /IA ([IMAGE]) D /DS {/PF f D()WB NL NP()pop RC ZF} D /Gb f D /Mb t D /Hc [16#00 16#00 16#00] D /Bl 3 D /MI -15.2 D /DX (DRAFT) D /Di 0 D /Tt 113.385826771654 D /Th {()2 Al()BR ( ) 0 1 -1 H()4 FZ Ti ES()EH ( ) 0 2 -1 H() ME 0 get join EH()Ea()BR()} D /tH {()0 1 -1 H (Table of Contents) EH()} D /FD 2 D /Dy 2 D /cD [16#F0 16#F0 16#F0] D /FW 0.6 D /FU [16#00 16#00 16#00] D /ET {/RM f D /A0 0 D /PN SN D /OU t D /Ou t D /W IW D /LL W D D1 Ms not TP and{Ip}if /TF f D} D [{true statusdict/setduplexmode get exec} stopped cleartomark %-- End of variable part -- /MySymbol 10 dict dup begin /FontType 3 D /FontMatrix [.001 0 0 .001 0 0 ] D /FontBBox [25 -10 600 600] D /Encoding 256 array D 0 1 255{Encoding exch /.notdef put}for Encoding (e) 0 get /euro put /Metrics 2 dict D Metrics begin /.notdef 0 D /euro 651 D end /BBox 2 dict D BBox begin /.notdef [0 0 0 0] D /euro [25 -10 600 600] D end /CharacterDefs 2 dict D CharacterDefs begin /.notdef {} D /euro{newpath 114 600 moveto 631 600 lineto 464 200 lineto 573 200 lineto 573 0 lineto -94 0 lineto 31 300 lineto -10 300 lineto closepath clip 50 setlinewidth newpath 656 300 moveto 381 300 275 0 360 arc stroke -19 350 moveto 600 0 rlineto -19 250 moveto 600 0 rlineto stroke}d end /BuildChar{0 begin /char E D /fontdict E D /charname fontdict /Encoding get char get D fontdict begin Metrics charname get 0 BBox charname get aload pop setcachedevice CharacterDefs charname get exec end end}D /BuildChar load 0 3 dict put /UniqueID 1 D end definefont pop /Cd {aload length 2 idiv dup dict begin {D} repeat currentdict end} D /EX {EC cvx exec} D /DU {} d /BB {pop pop}d /ie {ifelse} d /E {exch} d /M {moveto} d /R {rmoveto} d /L {lineto} d /RL {rlineto} d /CP {currentpoint} d /SW {stringwidth} d /GI {getinterval} d /PI {putinterval} d /Sg {setgray} d /LW {setlinewidth} d /S {dup () ne OU and{0 Co R AT 3 eq LB and HF not and A1 0 ne A2 0 ne or and {A2 0 32 A1 0 6 -1 roll awidthshow}{show}ie 0 Co neg R}{pop}ie OU PH 3 eq or{/Ms t D}if} D /U {OU{gsave CP currentfont /FontInfo get /UnderlinePosition get 0 E currentfont /FontMatrix get dtransform E pop add newpath M dup SW pop CJ 0 RL stroke grestore}if} D /B {OU Br 0 gt and{CP Ts neg Ts .33 mul R gsave 0 Sg CP newpath Ts Br mul 0 360 arc closepath UI 2 mod 0 eq{stroke}{fill}ie grestore M CP E Ts Br 1 add mul sub E BB /Ms t D}if}D /NP {Ms TP not or PA and OU and{TP{OR}if f1{mF k2 /mF E D /YC 0 D}if TP TU not PM 0 eq or and{showpage}if DU Ip TE not{LA}if 0.6 LW /CI 0 D /TP t D /Hs f D /hl 6 D /Hv 6 D /HI hi D /Ms f D}if Bs XO BO M} D /Np {LE sub CP E pop gt PL 0 eq and{NP}if}D /Ip {/PN PN 1 add D /Pn RM{1}{4}ie PN Ns D /PM PN SN sub 2 mod D} D /GP {E dup 3 -1 roll get PN 1 add 2 mod get dup type /integertype eq {get 0 get}{E pop}ie}d /Fc {dup 2 GP exec SW pop /S1 E D dup 1 GP exec SW pop /S2 E D 0 GP exec SW pop /S3 E D S1 0 gt{S2 2 mul S1 add S3 2 mul S1 add 2 copy lt{E}if pop}{0}ie S2 S3 add 2 copy lt{E}if pop IW .9 mul div dup 1 gt{1 E div}{pop 1}ie}D /OR {Df{Sd}if tp not{gsave SA{1 Sf div dup scale}if Fe{Cf{FU VC}if FW LW 1 setlinejoin FE stroke}if /YO {60 F div dup 40 gt{pop 40}if}D /cs CS D /cf CF D /CF 0 D /pf PF D /PF f D /Fn FN D /At AT D /AT 0 D /FN EF Hf 1 add get D Fz Fs FS ZZ Fc Fz mul Fs FS EU Hf 1 add get dup type /arraytype eq Cf and{VC}{pop 0 Sg}ie IW IL neg YO sub M ZZ 1 GP exec dup SW pop neg 0 R Sh 0 IL neg YO sub M ZZ 0 GP exec Sh ZZ 2 GP exec dup SW pop IW E sub 2 div IL neg YO sub M Sh Fz Fs FS NO{/AW IW Pn SW pop sub D AW 2 div IL neg YO sub S1 0 gt S2 AW .45 mul gt or S3 AW .45 mul gt or{Fz 2 mul sub}if M Pn Sh}if EU Hf get dup type /arraytype eq Cf and{VC}{pop 0 Sg}ie YY Fc /FN EF Hf get D Hz mul HS FS IW YO M YY 1 GP exec dup SW pop neg 0 R Sh 0 YO M YY 0 GP exec Sh YY 2 GP exec dup SW pop IW E sub 2 div YO M Sh /FN Fn D /AT At D t Pb XO SZ SL get neg R /PF pf D grestore /CF 0 D cs cf FS}if}D /Sh {dup () ne{CP Hz 4 div sub BB show CP CS add BB}{pop}ie}D /Pb {/OU E D /Ou OU D /PB t D 0 0 M Ba{/Sa save D /BP t D /Fl t D RC /PL 0 D /PH 0 D /W IW D /LE IL .7 mul D /EO 0 D SI ZF /YA 0 D /BO 0 D /C1 () D BA 0 Ts neg R Bb{Xl Yl Xh Yh}if Bb CP Sa restore M {/Yh E D /Xh E D /Yl E D /Xl E D}if /Fl t D}if BL /OU t D /HM f D /Ou t D /PB f D} D /Bs {/BP Ba not D}D /reencodeISO { dup dup findfont dup length dict begin{1 index /FID ne{D}{pop pop}ie}forall /Encoding ISOLatin1Encoding D currentdict end definefont} D /ISOLatin1Encoding [ /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /space/exclam/quotedbl/numbersign/dollar/percent/ampersand/quoteright /parenleft/parenright/asterisk/plus/comma/hyphen/period/slash /zero/one/two/three/four/five/six/seven/eight/nine/colon/semicolon /less/equal/greater/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N /O/P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash/bracketright /asciicircum/underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m /n/o/p/q/r/s/t/u/v/w/x/y/z/braceleft/bar/braceright/asciitilde /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/space/exclamdown/cent/sterling/currency/yen/brokenbar /section/dieresis/copyright/ordfeminine/guillemotleft/logicalnot /hyphen/registered/macron/degree/plusminus/twosuperior/threesuperior /acute/mu/paragraph/periodcentered/cedilla/onesuperior/ordmasculine /guillemotright/onequarter/onehalf/threequarters/questiondown /Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE/Ccedilla /Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex /Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis /multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute /Thorn/germandbls/agrave/aacute/acircumflex/atilde/adieresis /aring/ae/ccedilla/egrave/eacute/ecircumflex/edieresis/igrave /iacute/icircumflex/idieresis/eth/ntilde/ograve/oacute/ocircumflex /otilde/odieresis/divide/oslash/ugrave/uacute/ucircumflex/udieresis /yacute/thorn/ydieresis ] D [128/backslash 129/parenleft 130/parenright 141/circumflex 142/tilde 143/perthousand 144/dagger 145/daggerdbl 146/Ydieresis 147/scaron 148/Scaron 149/oe 150/OE 151/guilsinglleft 152/guilsinglright 153/quotesinglbase 154/quotedblbase 155/quotedblleft 156/quotedblright 157/endash 158/emdash 159/trademark] aload length 2 idiv 1 1 3 -1 roll{pop ISOLatin1Encoding 3 1 roll put}for /colorimage where{pop}{ /colorimage { pop pop /Pr E D {/Cv Pr D /Gr Cv length 3 idiv string D 0 1 Gr length 1 sub {Gr E dup /i E 3 mul D Cv i get 0.299 mul Cv i 1 add get 0.587 mul add Cv i 2 add get 0.114 mul add cvi put}for Gr} image} D }ie /pdfmark where{pop}{userdict /pdfmark /cleartomark load put}ie WF{FL{reencodeISO D}forall}{4 1 FL length 1 sub{FL E get reencodeISO D}for}ie /Symbol dup dup findfont dup length dict begin {1 index /FID ne{D}{pop pop}ie}forall /Encoding [Encoding aload pop] dup 128 /therefore put D currentdict end definefont D /SF {/CS E D SZ SL CS put FO SL FN put /YI CS LH neg mul D dup ST cvs ( ) join CS ST cvs join C1 E join ( NF ) join /C1 E D CS NF /Wf WF FN 0 gt or D /BW Wf{( ) SW pop}{0}ie D}D /NF {/cS E D /cF E D cF 0 ge{FL cF get}{cF -1 eq{/Symbol}{/MySymbol}ie}ie findfont cS scalefont setfont} D /FS {CF or /CF E D FR SL CF put CF CF 0 ge{FN 4 mul add}if E SF} D /PC {SH /BP f D fin not GL not and{NL}if /HM t D /LL LS D} D /BS {/TX E D Wf{/fin f D /CW 0 D /LK 0 D /SC 0 D /RT TX D {RT ( ) search{/NW E D pop /RT E D /WH NW SW pop D CW WH add LL gt {TX SC LK SC sub 1 sub NN GI GL{SH cF cS OC 2 copy cS ne E cF ne or{NF}{pop pop}ie}{PC /CW WH BW add D}ie /SC LK D} {GL{JC}if /CW CW WH add BW add D /HM t D}ie /GL f D /Ph f D /LK LK NW length 1 add add D}{pop exit}ie}loop /fin t D TX SC LK SC sub GI SH RT () ne{GL not{CC}if}if /LC TX length D /WH RT SW pop D CW WH add Hy{HC SW pop add}if LL gt {RT GL{SH cF cS OC 2 copy cS ne E cF ne or{NF}{pop pop}ie Hy{/Ph t D}if /LL LS D}{NL /LL LS D SH}ie} {RT PC Hy{CC}if /Ph Ph Hy or D}ie RT () ne{/GL t D /HM t D}if} {TX SW pop LL le{TX SH}{/NW () D 0 2 TX length 1 sub {/CW E D TX 0 CW GI dup SW pop LL gt{pop NW SH /HM t D NL/LL W XO sub MR sub D /CW CW 2 sub NN D /TX TX CW TX length CW sub GI D TX BS exit} {/NW E D}ie}for}ie}ie /HM t D}D /CC {C0 length 0 gt{JC}if /C0 [C1 L1 YA YB Mf NS NB TB AF Bw] D /C1 () D /L0 L1 D /YA 0 D /YB 0 D /Mf 0 D /NS 0 D /NB 0 D}D /JC {C0 aload length 0 gt{pop pop pop NB add /NB E D NS add /NS E D dup Mf gt{/Mf E D}{pop}ie dup YB gt{/YB E D}{pop}ie dup YA gt{/YA E D}{pop}ie pop C1 join /C1 E D /C0 [] D}if}D /OC {C0 length 0 gt{C1 L1 L0 sub YA YB Mf NS NB TB AF Bw GL C0 aload pop /Bw E D /AF E D /TB E D /NB E D /NS E D /Mf E D /YB E D /YA E D /C0 [] D /L1 E D /C1 E D Ph{HC SH}if NL /GL E D /Bw E D /AF E D /TB E D /NB E D /NS E D /Mf E D /YB E D /YA E D /L1 E D /LL W L1 sub XO sub MR sub WH sub D /CW 0 D C1 E join /C1 E D}if}D /BT {/LB t D dup length string copy RS dup dup () ne E ( ) ne and {/CI 0 D /LS LL D /LL W L1 sub XO sub MR sub D BS} {dup ( ) eq{/GL f D}if dup () eq L1 0 eq or{pop}{SH /BP f D /Ph f D}ie}ie /LB f D} D /BL {CP E pop XO E M} D /NL {JC /GL f D /SK W XO sub MR sub L1 sub TB{Bw add}if D /YA LF{Mf HM Fl not and PF or{LH mul}if}{0 /LF t D}ie YA 2 copy lt{E}if pop D C1 () ne{/FB YB Mf SA{Sf mul}if 4 div 2 copy lt{E}if pop D}if Fl{/Ya YA D}if CP E pop YA sub YB sub LE neg lt Fl not and PB not and{NP}if NT TL BL OU PF not and PB or{/RE L1 TB{Bw sub}if W XO sub MR sub div YA YB add LE BO add div 2 copy lt{E}if pop D RE 1 gt{BL 1 RE div dup scale}if}if AT 2 le{SK AT mul 2 div YA neg R}if AT 3 eq{0 YA neg R TB{/NB NB 1 sub D /NS NS 1 sub D}if /NB NB 1 sub NN D /A3 NS 6 mul NB add D NS NB add 0 eq {/A1 0 D /A2 0 D} {NS 0 eq{/A1 SK NB div dup J gt{pop 0}if D /A2 0 D}{J A3 mul SK lt {/A1 J D /A2 SK J NB mul sub NS div dup Ab gt{/A1 0 D pop 0}if D} {/A1 SK A3 div D /A2 A1 6 mul D}ie}ie}ie /A1 A1 NN D /A2 A2 NN D}if AT 4 eq{0 YA neg R PH 2 le{PD 0 lt{/PD L1 D}if PD M1 gt{/M1 PD D}if L1 PD sub M2 gt{/M2 L1 PD sub D}if}{DV ID 1 sub get 0 ge{Lo 0 R}if}ie}if F0 cF ne Cs cS ne or{F0 Cs NF}if /ms Ms D /Ms f D CP FB sub C1 cvx exec XO EO sub L1 add TB{BW sub}if dup LM gt{/LM E D}{pop}ie PH 0 eq PH 4 eq or Ms and{HF not{/PO t D /AH t D}if BB CP YA add E AT 3 eq LB and{A1 sub}if TB{BW sub}if E BB} {pop pop}ie Ms HM PH 3 eq and or{/BP f D /Fl f D}if /Lo 0 D /L1 0 D /F0 cF D /Cs cS D BP not{0 YB NN neg R}if OU f1 and mF not and{k2 /f1 f D}if OU PF not and PB or{RE 1 gt{RE dup scale}if}if /Ms ms Ms or D /C1 AF{(Cp )}{()}ie D /YA 0 D /YB 0 D BL AT 4 eq LB not and PH 3 ge and {ID DV length lt{DV ID get dup 0 ge{DO E sub /Lo E D /L1 Lo D}{pop}ie /ID ID 1 add D}if}if /T t D CD{/LN LN 1 add D PD}if /PD -1 D /NS 0 D /NB 0 D /TB f D /Ph f D /Mf 0 D /HM f D} D /RS {/TM E D /CN 0 D TM{10 eq{TM CN ( ) PI}if /CN CN 1 add D}forall /CN 0 D /BK HM EN and{0}{1}ie D TM {dup 32 ne{TM CN 3 2 roll put /CN CN 1 add D /BK 0 D} {pop BK 0 eq{TM CN 32 put /CN CN 1 add D}if /BK 1 D}ie}forall TM 0 CN GI dup dup () ne E ( ) ne and {dup CN 1 sub get 32 eq{/EN f D}{/EN t D}ie}if} D /join {2 copy length E length add string dup 4 2 roll 2 index 0 3 index PI E length E PI}d /WR {(\n) search{dup () ne BP not or {Li 4 le CP E pop YI Li mul add LE add 0 lt and PL 0 eq and{NP}if SH NL pop /Li Li 1 sub D WR}{pop pop WR}ie}{SH}ie /CI 0 D /BP f D} D /SH {dup dup () ne E ( ) ne and PF or CS Mf gt and{/Mf CS D}if T not Wf and{( ) E join /T t D}if dup BP{/MF CS D}if AT 3 eq{2 copy length dup 0 gt{/NB E NB add D {( ) search{/NS NS 1 add D pop pop}{pop exit}ie}loop}{pop pop}ie}if CD PD 0 lt and{dup DC search{SW pop /PD E L1 add D pop pop}{pop}ie}if 0 Np dup SW pop L1 add /L1 E D dup () ne {C1 (\() join E join (\)) join AU AF and UF or Wf and{( U ) join}if sF{( s ) join}if ( S ) join /C1 E D dup length 1 sub get 32 eq /TB E D /Bw BW D}{pop pop}ie} D /BG {AI LG BC add add 0 eq} D /ON {OU{Ty AR AI NN get dup 1 add Ln Ns Ty 2 mod 0 eq{(. )}{(\) )}ie join dup SW pop neg 0 R CP E 0 lt{0 E M}{pop}ie CP BB show /Ms t D}if} D /Ln {AR AI 3 -1 roll put}D /SP {dup CI lt BP not and{dup CI sub 0 E R /CI E D}{pop}ie} D /BN {PF{WR /HM f D}{BT NL}ie} D /NN {dup 0 lt{pop 0}if} D /h {(h) HI ST cvs join cvx exec dup 1 get E Nf{0 get E join}{pop}ie} D /H {/fn FN D /Hi E 1 add D 1 sub /HL E D /H2 HL 2 add D /GS EZ H2 get D E Tm H2 get GS mul BE dup 0 gt{1 sub}{pop EG H2 get dup 0 lt{pop AT}if}ie NA WW Np /SL SL 1 add D /FN EF H2 get D GS Ey H2 get FS EU H2 get Sc Hs not HL Hl lt and Hs HL hl lt and or Hi 0 eq or {/HI Hi D /Hs t D /hl HL D /Hv HL D}if HL Hl lt{/hi Hi D}if Nf HI 0 gt and{(h) Hi ST cvs join cvx exec 0 get WB}if /HF t D /AH f D /PO f D} D /EH {Bm H2 get GS mul BE OA /SL SL 1 sub NN D /CF 0 D /FN fn D SZ SL get FR SL get FS /HF f D /GS Ts D ()Ec} D /P {E PF{WR}{PO{EP}{BN}ie Ts 4 mul Np AE not{Tm 0 get Ts mul neg SP}if dup 0 ge AH and{Pi Pd}if}ie 1 sub dup 0 lt{pop AV AL get}if /AT E D /PO t D} D /EP {PF{WR}{BN Ts 4 mul Np}ie AE not{Bm 0 get Ts mul neg SP}if /AT AV AL get D /PO f D} D /BE {E PO{EP}{BN}ie Ts 4 mul Np neg SP} D /HR {/Aw W EO sub D /RW E dup 0 gt{Aw mul}{neg}ie dup Aw gt{pop Aw}if D /RZ E D E BN Ts neg SP 1 sub 2 div Aw RW sub mul EO add CP E pop M PF{0 Ps neg R}if 0 Np OU{gsave RZ LW Cf{Hc VC}{0 Sg}ie CP BB RW 0 RL CP BB stroke grestore}if /CI 0 D /BP f D PF not{Ts neg SP}if /Ms t D} D /AD {I NL EG 14 get dup 0 lt{pop AT}if NA /AE t D Tm 14 get Ts mul neg SP Cf{EU 14 get dup -1 eq{pop CA CL get}if Sc}if} D /DA {BN ()ES OA /AE f D ()Ec Bm 14 get Ts mul neg SP} D /PR {/MW E D /Li E D Tm 1 get Ps mul BE 0 NA /FN Fp D /PF t D SI /SL SL 1 add D /CF 0 D Ps CS mul Ts div MW WC mul CS mul Ts div dup LL gt PL 0 eq and {LL div div}{pop}ie Ey 1 get FS CP E pop LE add YI neg div cvi dup Li lt AH and{4 lt YI Li mul 5 mul LE add 0 gt or PL 0 eq and{NP}if}{pop}ie EU 1 get Sc /GS Ps D}D /RP {WR NL () /PF f D SI /FN 0 D ES Bm 1 get Ps mul neg SP OA /GS Ts D} D /SI {/XO Lm 15 get BC NN mul Lm 16 get AI UI sub NN mul add Lm 17 get UI NN mul add Lm 20 get LG NN mul add Ts mul PF{Lm 1 get Ps mul add}if EO add D /MR Rm 15 get BC NN mul Rm 16 get AI UI sub NN mul add Rm 17 get UI NN mul add Rm 20 get LG NN mul add Ts mul PF{Rm 1 get Ps mul add}if D /LL W XO sub MR sub D} D /DT {/cC E D BN /LG LG 1 sub D SI /LG LG 1 add D WW 2 div Np BL} D /DD {WB Cc 0 eq cC 0 eq and L1 0 eq or Lm 20 get Ts mul L1 sub TB{BW add}if Ts 2 div lt or NL /LF E D SI BL /cC 0 D} D /DL {Dc LG Cc put /Cc E D BG{Tm 18 get Ts mul BE}{BN}ie /LG LG 1 add D BL} D /LD {BN LG 0 gt{/LG LG 1 sub D}if /Cc Dc LG get D SI BG{()Bm 18 get Ts mul BE}if BL} D /UL {BG{Tm 17 get Ts mul BE}{BN}ie NR AI NN 0 put /UI UI 1 add D /AI AI 1 add D SI BL} D /LU {BN /UI UI 1 sub D /AI AI 1 sub D SI BG{()Bm 17 get Ts mul BE}if BL} D /OL {E BG{Tm 16 get Ts mul BE}{BN}ie TR AI NN Ty put /Ty E D NR AI NN 1 put /AI AI 1 add D SI BL 1 Ln} D /LO {BN /AI AI 1 sub D /Ty TR AI get D SI BG{()Bm 16 get Ts mul BE}if BL} D /LI {E BN -1 SP /BP f D /CI 0 D 0 Np NR AI 1 sub NN get 1 eq {dup dup 0 gt E 4 le and{/Ty E D}{pop}ie /L1 L1 Ty AR AI NN get Ns SW pop XO sub dup 0 lt{pop 0}if add D ( ON )} {pop ( B )}ie C1 E join /C1 E D CS Mf gt{/Mf CS D}if BL} D /BQ {Tm 15 get Ts mul BE /BC BC 1 add D SI BL} D /QB {Bm 15 get Ts mul BE /BC BC 1 sub D SI BL} D /Al {E EP 1 sub dup 0 lt{pop AV AL get}if NA} D /Ea {EP OA} D /WB {PF{WR}{BT}ie} D /F1 {WB /FN 0 D CS 0 FS} D /F2 {WB /FN WI D CS 0 FS} D /HY {/Hy t D WB /Hy f D} D /YH {WB} D /A {/LT E D LT 1 eq{/RN E D}if /Lh E D WB /C1 C1 ( Cp ) join D Lc AF not and{Cl Sc}if /AF t D} D /EA {Lc AF and{Ec}{WB}ie TL Pa AF and Lh 0 ne and {( \() Lh join (\)) join /AF f D WB}if /AF f D} D /TL {C1 ( Tl ) apa /C1 E D} d /apa {AF OU and Lh 0 ne LT 1 eq or and{LT 1 eq{RN ( /) E ST cvs join} {(\() Lh join (\)) join}ie E join join}{pop}ie} d /Cp {/Xc CP /Yc E D D} D /SS {Cf{dup 0 ge{EU E get dup -1 eq{pop CA CL get}if}{pop CA CL get}ie Sc} {pop}ie SZ SL get /SL SL 1 add D} D /I {WB 8 SS 1 FS} D /EM {WB 8 SS /CF CF 1 xor D 0 FS} D /BD {WB 9 SS 2 FS} D /TT {WB 10 SS /FN Fp D 0 FS} D /KB {WB 11 SS /FN Fp D 2 FS} D /CT {WB 12 SS 1 FS} D /SM {WB 13 SS /FN Fp D 0 FS} D /Q {/QL QL 1 add D QO QL 2 mod get La get join WB} D /EQ {QC QL 2 mod get La get join WB /QL QL 1 sub D} D /RO {WB -1 SS /CF 0 D 0 FS} D /SY {WB -1 SS -1 FS} D /MY {WB -1 SS -2 FS} D /ES {WB /SL SL 1 sub NN D /CF 0 D /FN FO SL get D SZ SL get FR SL get FS ()Ec}D /FZ {3 sub 1.2 E exp GS mul E WB TL /C1 C1 ( Cp ) join D /SL SL 1 add D 0 FS} D /Ef {WB TL ()ES /C1 C1 ( Cp ) join D} D /BZ {dup /Bf E D FZ}D /Sc {dup -1 ne Cf and{/CL CL 1 add D dup 0 eq{pop [0 0 0]}if dup CA E CL E put VS ( VC ) join C1 E join /C1 E D}{pop}ie} D /Ec {WB Cf{/CL CL 1 sub NN D CA CL get VS ( VC ) join C1 E join /C1 E D}if} D /VS {dup type /arraytype eq{([) E {ST cvs join ( ) join}forall (]) join}if} D /VC {{255 div}forall setrgbcolor} D /Sl {dup type /integertype ne{Ds}if /La E D WB}d /UN {WB /UF t D} D /NU {WB /UF f D} D /SE {WB /sF t D} D /XE {WB /sF f D} D /sM {/C1 C1 ( k1 ) join D}d /eM {/C1 C1 ( k2 ) join D}d /k1 {/YC CP E pop Ts add D /mF t D /f1 t D}d /k2 {gsave 3 LW -9 CP E pop Ts 0.2 mul sub M -9 YC L stroke grestore /mF f D}d /Ac {/AC E D WB}d /Ca {eA{( \()join AC join(\) )join}if WB}d /s {OU{gsave 0 CS .25 mul R dup SW pop CJ 0 RL stroke grestore}if}D /CJ {AT 3 eq LB and{E dup dup length 1 sub A1 mul E {( ) search{pop pop E A2 add E}{pop exit}ie}loop 3 -1 roll add W CP pop sub 2 copy gt{E}if pop}if}D /So {/Co E D} D /SO {C1 Yo ST cvs join ( So ) join /C1 E D (j) SW pop 2 div Pd} D /Se {E WB CS E div Pd}D /Pd {dup type /stringtype eq{SW pop}if dup /L1 E L1 add D ST cvs ( 0 R ) join C1 E join /C1 E D} D /Sp {0.35 CO} D /Sb {-0.2 CO} D /CO {OV Io Yo put /Yo E CS mul Yo add D /Io Io 1 add D -1.5 Io mul 3 add FZ SO CS Yo add dup YA gt{/YA E D}{pop}ie Yo neg dup YB gt{/YB E D}{pop}ie} D /Es {ES /Io Io 1 sub NN D /Yo OV Io get D SO} D /SB {/N2 0 D 0 1 NI{/N E D{IX N2 get 0 lt{/N2 N2 1 add D}{exit}ie}loop /K WS N get FC N get mul D /NY AY N2 get D /BV NY array D 0 1 NY 1 sub{/TM K string D currentfile TM readhexstring pop pop BV E TM put} for BM N BV put /N2 N2 1 add D}for} D /IC [{/MA E D /MB 0 D}{2 div /MA E D /MB MA D}{/MB E CS sub D /MA CS D} {pop /MA YS AB mul D /MB 1 AB sub YS mul D}{pop /MA 0 D /MB 0 D}] D /IP {BV N get /N N 1 add D} D /II {/K E D IX K get 0 lt{/EC E D}if /TY E D TY 4 eq{/Y E D /X E D}if TY 3 eq{/AB E D}if /XW AX K get D /YW AY K get D /IS SG IT K get get D /XS XW IS mul D /YS YW IS mul D YS IC TY get exec /MA MA Fl not{3 add}if D} D /IM {II /ty TY D /xs XS D /ys YS D /ya YA D /yb YB D /ma MA D /mb MB D /k K D /ec EC D /BP f D /CI 0 D WB TL L1 xs add dup XO add MR add W gt {pop /ma ma Fl{3 add}if D NL /YA ma D /YB mb D /YS ys D /L1 xs D} {/L1 E D ma YA gt{/YA ma D}if mb YB gt{/YB mb D}if}ie /TB f D OU{CP E pop YS sub LE neg lt Fl not and PB not and{NP /YA ma D /YB mb D}if /BP f D ty ST cvs ( ) join IX k get 0 lt{(\() join ec join (\) ) join}if k ST cvs join ty 3 eq{AB ST cvs ( ) join E join}if ty 4 eq{X ST cvs ( ) join Y ST cvs join ( ) join E join}if C1 E join ( DI ) join FP 2 eq FP 1 eq AF and or{( FM ) join}if ( Il Cp ) apa /C1 E D /EN f D}if /HM t D /T f D} D /DI {II /Xc CP /Yc E D D /YN YW neg D /HM t D /CI 0 D /K2 IX K get D gsave TY 4 eq{OX X IS mul add OY FY add YS sub Y IS mul sub} {/FY YS D CP MB sub 2 copy /OY E D /OX E D}ie translate K2 0 ge{/DP AZ K2 get D /BV BM K2 get D XS YS scale /N 0 D XW YW DP [XW 0 0 YN 0 YW] {IP} FC K2 get 1 eq{image}{f 3 colorimage}ie} {EX}ie grestore XS 0 R /Ms t D} D /FM {gsave 0 Sg CP MB sub translate XS neg 0 M 0 YS RL XS 0 RL 0 YS neg RL XS neg 0 RL stroke grestore} D /NA {/AT E D /AL AL 1 add D AV AL AT put} D /OA {AL 0 gt{/AL AL 1 sub D /AT AV AL get D}if} D /D1 {/BR {CP E pop E BN Mb{CP E pop eq{0 YI R}if}{pop}ie} D /Sn {OU{C1 E ST cvs join ( Ld ) join /C1 E D}{pop}ie} D} D /D1 {/BR {BN} D /Sn {OU {C1 E ST cvs join ( Ld ) join /C1 E D} {pop} ie} D} D /TC {/TF t D /ML 0 D HN{SW pop dup ML gt{/ML E D}{pop}ie}forall NP /RM RM not D RC /OU Tc D Ep /PN 0 D Ms not TP and{Ip}if /W IW ML sub Ts sub D /A0 0 D TH{/BR {( ) join BT} D /Sn {pop} D /Au () D}if} D /TN {0 eq{E EA PF HF or not XR and{HN E get Xr}{pop}ie} {OU{Tn 0 ge{() BN}if /Tn E D}{pop}ie WB}ie} D /NT {OU LB not and Tn 0 ge and{PL 0 eq{Ms not{CS CF FS}if CP dup /y E YA sub D W 9 sub CS -1.8 mul XO L1 add 2 add{y M (.) show}for HN Tn get dup SW pop IW E sub y M show CP BB M}if /Tn -1 D}if} D /Ld {/DN E D HN DN Pn put [/View [/XYZ -4 Fl{PS}{CP YA add US E pop}ie null] /Dest DN ST cvs cvn /DEST pdfmark} D /C {ND 1 eq{1 sub}if TI mul /XO E D NL Nf not{pop()}if 0 3 -1 roll 1 A} D /OP {BP not{NP}if PN 2 mod 0 eq{/Ms t D NP}if}D /Ep {Xp PN 2 mod 0 eq and OU and{/Pn (-) D showpage /PM 1 D LA}if}D /Dg [73 86 88 76 67 68 77] D /Rd [0 [1 1 0][2 1 0][3 1 0][2 1 1][1 1 1][2 2 1][3 3 1][4 4 1][2 1 2]] D /Ns {/m E D /c E 32 mul D /j m 1000 idiv D /p j 12 add string D c 96 le m 0 gt and{c 32 le {/i 0 D /d 77 D /l 100 D /m m j 1000 mul sub D j -1 1 {pop p i d c add put /i i 1 add D}for 4 -2 0 {/j E D /n m l idiv D /m m n l mul sub D /d Dg j get D n 0 gt {/x Rd n get D x 0 get -1 1 {pop p i d c add put /i i 1 add D}for p i x 1 get sub Dg x 2 get j add get c add put}if /l l 10 idiv D }for p 0 i GI} {/i ST length 1 sub D m {1 sub dup 0 ge{dup 26 mod c add 1 add ST i 3 -1 roll put 26 idiv dup 0 eq{pop exit}if}if /i i 1 sub D}loop ST i ST length i sub GI}ie} {m p cvs}ie} D /US {matrix currentmatrix matrix defaultmatrix matrix invertmatrix matrix concatmatrix transform} D /GB {Gb{US}if}D /Tl {/Rn E D Xc CP pop ne{ [/Rect [Xc 1 sub Yc cS 0.25 mul sub GB CP E 1 add E cS 0.85 mul add GB] /Subtype /Link /Border [0 0 Cf Lc and LX and AU or{0}{1}ie] Rn type /nametype eq {/Dest Rn}{/Action [/Subtype /URI /URI Rn] Cd}ie /ANN pdfmark}if} D /Il {/Rn E D [/Rect [Xc Yc GB Xc XS add Yc YS add GB] /Subtype /Link /Border [0 0 0] Rn type /nametype eq{/Dest Rn} {/Action [/Subtype /URI /URI Rn] Cd}ie /ANN pdfmark} D /XP {[{/Z Bz 2 div D Z 0 R Z Z RL Z neg Z RL Z neg Z neg RL Z Z neg RL Fi cH 1 eq and{fill}if} {Bz 0 RL 0 Bz RL Bz neg 0 RL 0 Bz neg RL Fi cH 1 eq and{fill}if} {0 -5 R Bz 0 RL 0 21 RL Bz neg 0 RL 0 -21 RL}]} D /MS {/Sm E D WB}D /O {BN()Sm BX} D /O {BN()0 Sm BX} D /BX {/Bt E D Bt 2 lt{/Ch E D CS 0.8 mul}{11 mul}ie W XO sub MR sub 2 copy gt{E}if pop /HZ E D Bt 2 eq{Fi not{pop()}if ( )E join /Ft E D TT /PF t D /MW 1 D /Li 1 D /Fw Ft SW pop D Fw HZ gt{/HZ Fw 8 add D}if HZ ST cvs( )join}{WB Ch ST cvs( )join}ie L1 HZ add XO add MR add W gt{NL}if Bt 2 eq{Ft ES Fw neg HM{CS sub}if Pd}if Bt ST cvs join( Bx )join Bt 2 eq HM and{CS Pd}if C1 E join /C1 E D /L1 L1 HZ add D /T f D ( ) Pd /PF f D Bt 2 lt{YA CS .8 mul lt{/YA CS .8 mul D}if} {YB 5 lt{/YB 5 D}if YA 21 lt{/YA 21 D}if}ie /CI 0 D} D /Bx {dup 2 eq{E /Bz E D}{E /cH E D /Bz CS .8 mul D}ie OU {gsave 0 Sg XP E get exec stroke grestore}{pop}ie Bz 0 R /Ms t D}D /SD {FD 4 mul Dy add DZ NF newpath 0 0 M DX t charpath pathbbox 3 -1 roll sub /DY E D E dup /X1 E D sub WM mul WX DY mul add WM DG mul E div /DF E D /DR WX DF mul DY mul WM div 2 div D} d /Sd {gsave 0 IL Di mul neg translate IL IW atan Di 0 eq{neg}if rotate FD 4 mul Dy add DZ NF DR X1 sub DY 2 div neg M cD VC DX show grestore} d /Pt {/tp t D Tp{NP /Pn (TP) D 0 Tt neg R Th BN NP Ep ET RC ZF}if /tp f D} D /RC {/AI 0 D /LG 0 D /BC 0 D /UI 0 D /PF f D /Cc 0 D /cC 0 D /Dc 10 array D /NR [0 1 9{pop 0}for] D /La Ds D /AR 10 array D /TR 10 array D /AV 30 array D SI /AL -1 D /AT A0 D AT NA /OV 9 array D /Yo 0 D /Co 0 D /Io 0 D /Hy f D /Ph f D /CL -1 D Ct Sc}D /ZF {/FR [0 1 30{pop 0}for] D /SZ [0 1 30{pop 0}for] D /FO [0 1 30{pop 0}for] D /SL 0 D /CF 0 D /FN 0 D 0 Ts SF}D /QO [[(\234)(\233)(\253\240)(\232)(\273)(\253)][(')(`)(\253\240)(\231)(\273)(\253)]] D /QC [[(\234)(\234)(\240\273)(\233)(\253)(\273)][(')(')(\240\273)(`)(\253)(\273)]] D /Hf EF length 2 sub D /Hz EZ Hf get D /HS Ey Hf get D /Fz EZ Hf 1 add get D /Fs Ey Hf 1 add get D /LE IL D /Ps EZ 1 get D /Fp EF 1 get D /XO 0 D /YI 0 D /CI 0 D /FP 0 D /WW Ts 7 mul D /Mf 0 D /YA 0 D /YB 0 D /Cs Ts D /GS Ts D /F0 0 D /NS 0 D /NB 0 D /N 0 D /C0 [] D /C1 () D /Lo 0 D /L1 0 D /LM 0 D /PH 0 D /EC 0 D /Lh 0 D /LT 0 D /CH 1 string D /ST 16 string D /CA 9 array D /HC (\255) D /HM f D /PF f D /EN f D /TB f D /UF f D /sF f D /AE f D /AF f D /BP t D /CD f D /PA t D /GL f D /T t D /HF f D /AH f D /SA f D /PB f D /f1 f D /mF f D /OX 0 D /OY 0 D /FY 0 D /EO 0 D /FB 0 D /PL 0 D /Bw 0 D /PD -1 D /TP f D /tp f D /TH f D /Ty 4 D /Tn -1 D /Fl t D /LB t D /PM 1 D /Ms f D /Ba f D /Bb f D /Hl 3 D /hl 6 D /Hv 6 D /Hs f D /HI 0 D /hi 0 D /PO t D /TE f D /LF t D /BO 0 D /Sm 1 D /Bf 3 D /A1 0 D /A2 0 D /Ds 1 D /QL -1 D /Cb Db D /Ct Dt D /Cl Dl D [/Creator (html2ps version 1.0 beta5) /Author () /Keywords () /Subject () /Title (The Funtools Help Facility) /DOCINFO pdfmark /ND 18 D /HN [(1) (1) (1) (1) (8) (9) (19) (21) (28) (30) (33) (37) (38) (41) (42) (45) (48) (51) (53) (??) (54) (56) (56) (87) (57) (58) (60) (62) (64) (65) (76) (77) (66) (73) (75) (82) (85) (78) (80) (86) (87) (57) (91) (91) (92) (92) (94) (102) (111) (95) (96) (100) (117) (123) (127) (136) (152) (157) (161) (164) (165) (167) (171) (1) (1) (1) (3) (1) (1) (1) (8) (9) (19) (21) (28) (30) (33) (37) (38) (41) (42) (45) (48) (50) (51) (51) (51) (51) (52) (53) (53) (53) (53) (53) (54) (56) (56) (57) (57) (58) (60) (62) (64) (65) (66) (73) (75) (76) (77) (80) (82) (85) (86) (87) (87) (87) (88) (90) (91) (98) (91) (91) (91) (91) (92) (92) (94) (95) (96) (98) (99) (100) (101) (102) (102) (102) (102) (102) (103) (104) (105) (105) (108) (109) (110) (111) (111) (111) (111) (111) (111) (112) (113) (114) (114) (115) (116) (116) (116) (117) (119) (119) (120) (120) (120) (117) (117) (117) (117) (119) (119) (120) (120) (120) (121) (122) (123) (123) (123) (123) (126) (127) (127) (127) (127) (127) (129) (129) (130) (131) (131) (132) (132) (133) (135) (136) (136) (136) (136) (146) (151) (152) (152) (152) (152) (156) (157) (157) (157) (157) (157) (158) (159) (160) (161) (161) (161) (161) (161) (161) (162) (162) (163) (164) (164) (164) (164) (164) (165) (165) (165) (165) (165) (166) (167) (167) (167) (167) (170) (171) (171) (171) (171) (171) (172) (172) (172) (175) (178) (178) (179) (180) (181) (181) (182) (182) (183) (183) (184) (184) (184) (184) (185) (185) (185) (186) (187) (187)] D /h0 [()(Table of Contents)] D /h1 [(0.1\240\240)(Funtools: FITS Users Need Tools)] D /h2 [(0.2\240\240)(Summary)] D /h3 [(0.3\240\240)(Description)] D /h4 [(0.3.0.0.1\240\240)(Last updated: January 6, 2006)] D /h5 [(0.4\240\240)(Funtools Programs)] D /h6 [(0.5\240\240)(Summary)] D /h7 [(0.6\240\240)(funcalc - Funtools calculator \(for binary tables\))] D /h8 [(0.7\240\240)(funcen - find centroid \(for binary tables\))] D /h9 [(0.8\240\240)(funcnts - count photons in specified regions, with bkgd subtraction)] D /h10 [(0.9\240\240)(funcone - cone search of a binary table containing RA, Dec columns)] D /h11 [(0.10\240\240)(fundisp - display data in a Funtools data file)] D /h12 [(0.11\240\240)(funhead - display a header in a Funtools file)] D /h13 [(0.12\240\240)(funhist - create a 1D histogram of a column \(from a FITS binary table or raw event file\) or an image)] D /h14 [(0.13\240\240)(funimage - create a FITS image from a Funtools data file)] D /h15 [(0.14\240\240)(funindex - create an index for a column of a FITS binary table)] D /h16 [(0.15\240\240)(funjoin - join two or more FITS binary tables on specified columns)] D /h17 [(0.16\240\240)(funmerge - merge one or more Funtools table files)] D /h18 [(0.17\240\240)(funsky - convert between image and sky coordinates)] D /h19 [(0.18\240\240)(funtable - copy selected rows from a Funtools file to a FITS binary table)] D /h20 [(0.19\240\240)(funtbl - extract a table from Funtools ASCII output)] D /h21 [(0.19.0.0.1\240\240)(Last updated: April 1, 2007)] D /h22 [(0.20\240\240)(FunDS9: Funtools and DS9 Image Display)] D /h23 [(0.21\240\240)(Summary)] D /h24 [(0.22\240\240)(Description)] D /h25 [(0.22.0.0.1\240\240)(Last updated: November 16, 2005)] D /h26 [(0.23\240\240)(FunLib: the Funtools Programming Interface)] D /h27 [(0.24\240\240)(Summary)] D /h28 [(0.25\240\240)(Introduction to the Funtools Programming Interface)] D /h29 [(0.26\240\240)(Funtools Programming Tutorial)] D /h30 [(0.27\240\240)(Compiling and Linking)] D /h31 [(0.28\240\240)(A Short Digression on Subroutine Order)] D /h32 [(0.29\240\240)(Funtools Programming Examples)] D /h33 [(0.30\240\240)(The Funtools Programming Reference Manual)] D /h34 [(0.31\240\240)(FunOpen - open a Funtools data file)] D /h35 [(0.32\240\240)(FunImageGet - get an image or image section)] D /h36 [(0.33\240\240)(FunImagePut - put an image to a Funtools file)] D /h37 [(0.34\240\240)(FunImageRowGet - get row\(s\) of an image)] D /h38 [(0.35\240\240)(FunImageRowPut - put row\(s\) of an image)] D /h39 [(0.36\240\240)(FunColumnSelect - select Funtools columns)] D /h40 [(0.37\240\240)(FunColumnActivate - activate Funtools columns)] D /h41 [(0.38\240\240)(FunColumnLookup - lookup a Funtools column)] D /h42 [(0.39\240\240)(FunTableRowGet - get Funtools rows)] D /h43 [(0.40\240\240)(FunTableRowPut - put Funtools rows)] D /h44 [(0.41\240\240)(FunParamPut - put a Funtools param value)] D /h45 [(0.42\240\240)(FunInfoGet - get information from Funtools struct)] D /h46 [(0.43\240\240)(FunInfoPut - put information into a Funtools struct)] D /h47 [(0.44\240\240)(FunFlush - flush data to output file)] D /h48 [(0.45\240\240)(FunClose - close a Funtools data file)] D /h49 [(0.46\240\240)(FunRef: the Funtools Reference Handle)] D /h50 [(0.47\240\240)(Summary)] D /h51 [(0.48\240\240)(Description)] D /h52 [(0.48.0.0.1\240\240)(Last updated: December 1, 2005)] D /h53 [(0.49\240\240)(FunFiles: Funtools Data Files)] D /h54 [(0.50\240\240)(Summary)] D /h55 [(0.51\240\240)(Description)] D /h56 [(0.52\240\240)(Supported Data Formats)] D /h57 [(0.53\240\240)(FITS Images and Binary Tables)] D /h58 [(0.54\240\240)(Non-FITS Raw Event Files)] D /h59 [(0.55\240\240)(Non-FITS Array Files)] D /h60 [(0.56\240\240)(Specifying Image Sections)] D /h61 [(0.57\240\240)(Binning FITS Binary Tables and Non-FITS Event Files)] D /h62 [(0.58\240\240)(Table and Spatial Region Filters)] D /h63 [(0.59\240\240)(Disk Files and Other Supported File Types)] D /h64 [(0.60\240\240)(Lists of Files)] D /h65 [(0.60.0.0.1\240\240)(Last updated: February 15, 2006)] D /h66 [(0.61\240\240)(Funtext: Support for Column-based Text Files)] D /h67 [(0.62\240\240)(Summary)] D /h68 [(0.63\240\240)(Description)] D /h69 [(0.64\240\240)(Standard Text Files)] D /h70 [(0.65\240\240)(Comments Convert to Header Params)] D /h71 [(0.66\240\240)(Multiple Tables in a Single File)] D /h72 [(0.67\240\240)(TEXT\(\) Specifier)] D /h73 [(0.68\240\240)(Text\(\) Keyword Options)] D /h74 [(0.69\240\240)(Environment Variables)] D /h75 [(0.70\240\240)(Restrictions and Problems)] D /h76 [(0.70.0.0.1\240\240)(Last updated: August 3, 2007)] D /h77 [(0.71\240\240)(Funview: Database View Support for Tables)] D /h78 [(0.72\240\240)(Summary)] D /h79 [(0.73\240\240)(Description)] D /h80 [(0.74\240\240)(Database Views)] D /h81 [(0.75\240\240)(Funtools View Attributes)] D /h82 [(0.76\240\240)(Invoking a Funtools View \(in Place of an Input File\))] D /h83 [(0.77\240\240)(Basic View Matching Rules)] D /h84 [(0.78\240\240)(More on View Matching Rules: Single vs. Multiple Matches)] D /h85 [(0.79\240\240)(View Lists: Applying a View to Any File)] D /h86 [(0.80\240\240)(Overriding Values Associated with a View)] D /h87 [(0.81\240\240)(Environment Variables)] D /h88 [(0.82\240\240)(Restrictions and Problems)] D /h89 [(0.82.0.0.1\240\240)(Last updated: August 3, 2007)] D /h90 [(0.83\240\240)(Funfilters: Filtering Rows in a Table)] D /h91 [(0.84\240\240)(Summary)] D /h92 [(0.85\240\240)(Description)] D /h93 [(0.86\240\240)(Filter Expressions)] D /h94 [(0.87\240\240)(Separators Also Are Operators)] D /h95 [(0.88\240\240)(Range Lists)] D /h96 [(0.89\240\240)(Math Operations and Functions)] D /h97 [(0.90\240\240)(Include Files)] D /h98 [(0.91\240\240)(Header Parameters)] D /h99 [(0.92\240\240)(Examples)] D /h100 [(0.92.0.0.1\240\240)(Last updated: November 17, 2005)] D /h101 [(0.93\240\240)(Funidx: Using Indexes to Filter Rows in a Table)] D /h102 [(0.94\240\240)(Summary)] D /h103 [(0.95\240\240)(Description)] D /h104 [(0.95.0.0.1\240\240)(Last updated: August 3, 2007)] D /h105 [(0.96\240\240)(Regions: Spatial Region Filtering)] D /h106 [(0.97\240\240)(Summary)] D /h107 [(0.98\240\240)(Description)] D /h108 [(0.99\240\240)(Region Expressions)] D /h109 [(0.100\240\240)(Columns Used in Region Filtering)] D /h110 [(0.101\240\240)(Region Algebra)] D /h111 [(0.102\240\240)(Region Separators Also Are Operators)] D /h112 [(0.103\240\240)(Region Exclusion)] D /h113 [(0.104\240\240)(Include Files)] D /h114 [(0.105\240\240)(Global and Local Properties of Regions)] D /h115 [(0.106\240\240)(Coordinate Systems)] D /h116 [(0.107\240\240)(Specifying Positions, Sizes, and Angles)] D /h117 [(0.107.0.0.1\240\240)(Last updated: November 17, 2005)] D /h118 [(0.108\240\240)(RegGeometry: Geometric Shapes in Spatial Region Filtering)] D /h119 [(0.109\240\240)(Summary)] D /h120 [(0.110\240\240)(Geometric shapes)] D /h121 [(0.111\240\240)(Region accelerators)] D /h122 [(0.111.0.0.1\240\240)(Last updated: March 12, 2007)] D /h123 [(0.112\240\240)(RegAlgebra: Boolean Algebra on Spatial Regions)] D /h124 [(0.113\240\240)(Summary)] D /h125 [(0.114\240\240)(Description)] D /h126 [(0.114.0.0.1\240\240)(Last updated: November 17, 2005)] D /h127 [(0.115\240\240)(RegCoords: Spatial Region Coordinates)] D /h128 [(0.116\240\240)(Summary)] D /h129 [(0.117\240\240)(Pixel coordinate systems)] D /h130 [(0.118\240\240)(World Coordinate Systems)] D /h131 [(0.119\240\240)(WCS Positions and Sizes)] D /h132 [(0.120\240\240)(NB: The Meaning of Pure Numbers Are Context Sensitive)] D /h133 [(0.120.0.0.1\240\240)(Last updated: November 17, 2005)] D /h134 [(0.121\240\240)(RegBounds: Region Boundaries)] D /h135 [(0.122\240\240)(Summary)] D /h136 [(0.123\240\240)(Description)] D /h137 [(0.124\240\240)(Image boundaries : radially-symmetric shapes \(circle, annuli, ellipse\))] D /h138 [(0.125\240\240)(Image Boundaries: non-radially symmetric shapes \(polygons, boxes\))] D /h139 [(0.126\240\240)(Row Boundaries are Analytic)] D /h140 [(0.127\240\240)(Image Boundaries vs. Row Boundaries: Practical Considerations)] D /h141 [(0.127.0.0.1\240\240)(Last updated: November 16, 2005)] D /h142 [(0.128\240\240)(RegDiff:Differences Between Funtools and IRAF Regions)] D /h143 [(0.129\240\240)(Summary)] D /h144 [(0.130\240\240)(Description)] D /h145 [(0.130.0.0.1\240\240)(Last updated: November 16, 2005)] D /h146 [(0.131\240\240)(FunCombine: Combining Region and Table Filters)] D /h147 [(0.132\240\240)(Summary)] D /h148 [(0.133\240\240)(Comma Conventions)] D /h149 [(0.133.0.0.1\240\240)(Last updated: November 16, 2005)] D /h150 [(0.134\240\240)(FunEnv: Funtools Environment Variables)] D /h151 [(0.135\240\240)(Summary)] D /h152 [(0.136\240\240)(Description)] D /h153 [(0.136.0.0.1\240\240)(Last updated: November 16, 2005)] D /h154 [(0.137\240\240)(Funtools ChangeLog)] D /h155 [(0.138\240\240)(Patch Release 1.4.5 \(internal ds9 release\))] D /h156 [(0.139\240\240)(Patch Release 1.4.4 \(internal ds9 release\))] D /h157 [(0.140\240\240)(Patch Release 1.4.3 \(internal ds9 release\))] D /h158 [(0.141\240\240)(Patch Release 1.4.2 \(internal ds9 release\))] D /h159 [(0.142\240\240)(Patch Release 1.4.1 \(internal ds9 release\))] D /h160 [(0.143\240\240)(Public Release 1.4.0 \(15 August 2007\))] D /h161 [(0.144\240\240)(Release 1.3.0b[n] \(mainly internal SAO beta releases\))] D /h162 [(0.145\240\240)(Patch Release 1.2.4 \(internal SAO and beta release only\))] D /h163 [(0.146\240\240)(Patch Release 1.2.3 \(12 January 2004\))] D /h164 [(0.147\240\240)(Patch Release 1.2.3b1 \(19 August 2003\))] D /h165 [(0.148\240\240)(Patch Release 1.2.2 \(18 May 2003\))] D /h166 [(0.149\240\240)(Patch Release 1.2.1 \(24 April 2003\))] D /h167 [(0.150\240\240)(Public Release 1.2.0 \(24 March 2003\))] D /h168 [(0.151\240\240)(Beta Release 1.2.b3 \(4 February 2003\))] D /h169 [(0.152\240\240)(Beta Release 1.2.b2 \(7 October 2002\))] D /h170 [(0.153\240\240)(Beta Release 1.2.b1 \(24 September 2002\))] D /h171 [(0.154\240\240)(Public Release 1.1.0 \(22 April 2002\))] D /h172 [(0.155\240\240)(Pre-Release 1.1.0e \(10 April 2002\))] D /h173 [(0.156\240\240)(Pre-Release 1.1.0e \(19 March 2002\))] D /h174 [(0.157\240\240)(Pre-Release 1.1.0e \(27 February 2002\))] D /h175 [(0.158\240\240)(Pre-Release 1.1.0e \(11 February 2002\))] D /h176 [(0.159\240\240)(Beta Release 1.0.1b5 \(31 January 2002\))] D /h177 [(0.160\240\240)(Beta Release 1.0.1b4 \(26 January 2002\))] D /h178 [(0.161\240\240)(Beta Release 1.0.1b3 \(4 January 2002\))] D /h179 [(0.162\240\240)(Beta Release 1.0.1b2 \(14 November 2001\))] D /h180 [(0.163\240\240)(Beta Release 1.0.1b1 \(6 November 2001\))] D /h181 [(0.164\240\240)(Public Release 1.0.0 \(31 July 2001\))] D /h182 [(0.164.0.0.1\240\240)(Last updated: 22 April 2002)] D /Hr [-63 63 64 65 -66 -66 66 -67 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 -83 -83 83 -85 85 86 87 -88 -88 88 -91 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 -117 -117 117 -120 120 121 122 123 124 125 126 127 128 129 130 131 -132 -132 132 -134 134 135 136 137 138 139 140 141 142 143 -144 -144 144 -146 146 147 148 149 150 151 152 153 154 155 156 157 -158 -158 158 -165 165 166 167 168 169 170 171 172 173 174 -175 -175 175 -177 177 178 179 -180 -180 180 -182 182 183 184 185 186 187 188 189 190 191 192 193 -194 -194 194 -196 196 197 198 199 -200 -200 200 -202 202 203 204 -205 -205 205 -207 207 208 209 210 211 212 -213 -213 213 -215 215 216 217 218 219 220 221 -222 -222 222 -224 224 225 226 -227 -227 227 -230 230 231 232 -233 -233 233 -235 235 236 237 -238 -238 238 -239 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 -267 -267 267]D /HV [1 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 2 2 2 3 4 5 1 2 2 2 2 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 4 5]D /Cn [3 0 0 1 1 1 0 16 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 3 0 0 1 1 1 0 26 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 12 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 10 0 0 0 0 0 0 0 0 0 1 1 1 0 12 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 10 0 0 0 0 0 0 0 0 0 1 1 1 0 3 0 0 1 1 1 0 12 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 4 0 0 0 1 1 1 0 3 0 0 1 1 1 0 6 0 0 0 0 0 1 1 1 0 7 0 0 0 0 0 0 1 1 1 0 3 0 0 1 1 1 0 3 0 0 1 1 1 0 3 0 0 1 1 1 0 28 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0]D Hr length 0 gt{[/PageMode /UseOutlines /DOCVIEW pdfmark}if /Hn 1 D 0 1 Hr length 1 sub{ /Bn E D [Cn Bn get dup 0 gt{/Count E HV Bn get Bl ge{neg}if}{pop}ie /Dest Hr Bn get dup abs ST cvs cvn E 0 ge{(h)Hn ST cvs join cvx exec dup 1 get E Nf{0 get E join}{pop}ie /Hn Hn 1 add D}{()}ie /Title E dup length 255 gt{0 255 getinterval}if /OUT pdfmark}for ZF /FN Fp D Ps 0 FS /WC Wf{( )}{}ie SW pop D ET RC ZF /Df f D /R1 (http://hea-www.harvard.edu/saord/ds9/index.html) D /R2 (http://hea-www.harvard.edu/saord/xpa/index.html) D /R3 (ftp://cfa-ftp.harvard.edu/pub/gsc/WCSTools/home.html) D /R4 (http://tdc-www.harvard.edu/software/wcstools/) D /R5 (http://hea-www.harvard.edu/RD/funtools/changelog.html) D /R6 (http://hea-www.harvard.edu/RD/funtools/changelog_beta.html) D /Ba f D /BO 0 D Bs /UR (help.html) D /Ti (The Funtools Help Facility) D /Au () D /Df f D /ME [()] D TC /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc /Ba f D /BO 0 D Bs /UR (help.html) D /Ti (The Funtools Help Facility) D /Au () D /Df f D /ME [()] D TC NP RC ZF ()1 Sl()WB 0 Sn( )0 2 0 H(Funtools:)WB 63 Sn()WB 1 Sn( FITS Users Need Tools)EA()EH( )0 2 1 H(Summary)WB 64 Sn()EH( This document is the Table of Contents for Funtools. )0 2 2 H(Description)WB 65 Sn()EH( Funtools, is a "minimal buy-in" FITS library and utility package developed at the the High Energy Astrophysics Division of SAO. The Funtools library provides simplified access to a wide array of file types: standard astronomical FITS images and binary tables, raw arrays and binary event lists, and even tables of ASCII column data. A sophisticated region filtering library \201compatible with ds9\202 filters images and tables using boolean operations between geometric shapes, support world coordinates, etc. Funtools also supports advanced capabilities such as optimized data searching using index files. The main goal of the Funtools project has been to develop a minimal buy-in FITS library for researchers who are occasional \201but serious\202 coders. In this case, "minimal buy-in" means "easy to learn, easy to use, and easy to re-learn next month". We have tried to achieve this goal by emphasizing two essential capabilities. The first is the ability to develop FITS programs without knowing much about FITS, i.e., without having to deal with the arcane rules for generating a properly formatted FITS file. The second is to support the use of already-familiar C/Unix facilities, especially C structs and Unix stdio. Taken together, these two capabilities should allow researchers to leverage their existing programming expertise while minimizing the need to learn new and complex coding rules. )0 P(Choose from the following topics: )0 P()UL()-1 LI()0 2 1 A(Funtools User Programs)2 1 TN TL()Ec /AF f D( )UL()-1 LI()0 3 1 A(funcalc: Funtools calculator \201for binary tables\202)3 1 TN TL()Ec /AF f D( )-1 LI()0 4 1 A(funcen: find centroid \201for binary tables\202)4 1 TN TL()Ec /AF f D( )-1 LI()0 5 1 A(funcnts: count photons in specified regions)5 1 TN TL()Ec /AF f D( )-1 LI()0 6 1 A(funcone: cone search on RA, Dec columns)6 1 TN TL()Ec /AF f D( )-1 LI()0 7 1 A(fundisp: display data in a Funtools data file)7 1 TN TL()Ec /AF f D( )-1 LI()0 8 1 A(funhead: display a header in a Funtools file)8 1 TN TL()Ec /AF f D( )-1 LI()0 9 1 A(funhist: create a 1D histogram of a column)9 1 TN TL()Ec /AF f D( )-1 LI()0 10 1 A(funimage: create a FITS image from a Funtools data file)10 1 TN TL()Ec /AF f D( )-1 LI()0 11 1 A(funindex: create an index on a column in a binary table)11 1 TN TL()Ec /AF f D( )-1 LI()0 12 1 A(funjoin: join two or more FITS binary tables on specified columns)12 1 TN TL()Ec /AF f D( )-1 LI()0 13 1 A(funmerge: merge one or more Funtools table files)13 1 TN TL()Ec /AF f D( )-1 LI()0 14 1 A(funsky: convert between image and sky coordinates, using WCS info from a FITS header)14 1 TN TL()Ec /AF f D( )-1 LI()0 15 1 A(funtable: copy selected rows from a Funtools file to a FITS binary table)15 1 TN TL()Ec /AF f D( )-1 LI()0 16 1 A(funtbl: extract a table from Funtools ASCII output)16 1 TN TL()Ec /AF f D( )-1 LI()0 17 1 A(funtools and ds9 image display)17 1 TN TL()Ec /AF f D( )LU( )-1 LI()0 18 1 A(Funtools Programming)18 1 TN TL()Ec /AF f D( )UL()-1 LI()0 19 1 A(Funtools Programming Summary)19 1 TN TL()Ec /AF f D( )-1 LI()0 20 1 A(Funtools Programming Tutorial)20 1 TN TL()Ec /AF f D( )-1 LI()0 21 1 A(A Short Digression on Subroutine Order)21 1 TN TL()Ec /AF f D( )-1 LI()0 22 1 A(Compiling and Linking)22 1 TN TL()Ec /AF f D( )-1 LI()0 23 1 A(The Funtools Reference Handle)23 1 TN TL()Ec /AF f D( )-1 LI()0 24 1 A(The Funtools Programming Reference Manual)24 1 TN TL()Ec /AF f D( )UL()-1 LI( )0 25 1 A(FunOpen: open a Funtools file)25 1 TN TL()Ec /AF f D( )-1 LI()0 26 1 A(FunImageGet: retrieve image data)26 1 TN TL()Ec /AF f D( )-1 LI()0 27 1 A(FunImagePut: output image data)27 1 TN TL()Ec /AF f D( )-1 LI()0 28 1 A(FunImageRowGet: retrieve image data by row)28 1 TN TL()Ec /AF f D( )-1 LI()0 29 1 A(FunImageRowPut: output image data by row)29 1 TN TL()Ec /AF f D( )-1 LI()0 30 1 A(FunTableRowGet: retrieve rows from a table)30 1 TN TL()Ec /AF f D( )-1 LI()0 31 1 A(FunTableRowPut: output rows to a table)31 1 TN TL()Ec /AF f D( )-1 LI()0 32 1 A(FunColumnSelect: select columns in a table for access)32 1 TN TL()Ec /AF f D( )-1 LI()0 33 1 A(FunColumnActivate: activate columns in a table for read/write)33 1 TN TL()Ec /AF f D( )-1 LI()0 34 1 A(FunColumnLookup: lookup info about the columns in a table)34 1 TN TL()Ec /AF f D( )-1 LI()0 35 1 A(FunInfoGet: get info about an image or table)35 1 TN TL()Ec /AF f D( )-1 LI()0 36 1 A(FunInfoPut: put info about an image or table)36 1 TN TL()Ec /AF f D( )-1 LI()0 37 1 A(FunParamGet: get header param)37 1 TN TL()Ec /AF f D( )-1 LI()0 38 1 A(FunParamPut: put header param)38 1 TN TL()Ec /AF f D( )-1 LI()0 39 1 A(FunFlush: flush I/O in a Funtools file)39 1 TN TL()Ec /AF f D( )-1 LI()0 40 1 A(FunClose: close a Funtools file)40 1 TN TL()Ec /AF f D( )LU( )-1 LI()0 41 1 A(Funtools Programming Examples)41 1 TN TL()Ec /AF f D( )UL( )-1 LI()0 2 A(evmerge: merge new columns with existing columns)EA( )-1 LI()0 2 A(evcols: add column and rows to binary tables)EA( )-1 LI()0 2 A(imblank: blank out image values below a threshold)EA()LU()LU( )-1 LI()0 42 1 A(Funtools Data Files)42 1 TN TL()Ec /AF f D( )UL( )-1 LI()0 43 1 A(Supported Data Formats)43 1 TN TL()Ec /AF f D( )UL()-1 LI()0 44 1 A(FITS File and Extensions)44 1 TN TL()Ec /AF f D( )-1 LI()0 45 1 A(Non-FITS Raw Event Files)45 1 TN TL()Ec /AF f D( )-1 LI()0 46 1 A(Non-FITS Array Files)46 1 TN TL()Ec /AF f D( )-1 LI()0 47 1 A(Column-based Text \201ASCII\202 Files)47 1 TN TL()Ec /AF f D( )-1 LI()0 48 1 A(Database Views of Tables)48 1 TN TL()Ec /AF f D()LU( )-1 LI()0 49 1 A(Image Sections and Blocking)49 1 TN TL()Ec /AF f D( )-1 LI()0 50 1 A(Binning FITS Binary Tables and Non-FITS Event Files)EH( )-1 LI()0 51 1 A(Disk Files and Other Supported File Types)50 1 TN TL()Ec /AF f D()LU( )-1 LI(Funtools Data Filtering )UL()-1 LI()0 52 1 A(Table Filtering)51 1 TN TL()Ec /AF f D( )-1 LI()0 53 1 A(Fast Table Filtering using Indexes)52 1 TN TL()Ec /AF f D( )-1 LI()0 54 1 A(Spatial Region Filtering)53 1 TN TL()Ec /AF f D( )UL()-1 LI()0 55 1 A(Region Geometry)54 1 TN TL()Ec /AF f D( )-1 LI()0 56 1 A(Region Algebra)55 1 TN TL()Ec /AF f D( )-1 LI()0 57 1 A(Region Coordinates)56 1 TN TL()Ec /AF f D( )-1 LI()0 58 1 A(Region Boundaries)57 1 TN TL()Ec /AF f D( )-1 LI()0 59 1 A(Differences Between Funtools and IRAF Regions)58 1 TN TL()Ec /AF f D( )LU( )-1 LI()0 60 1 A(Combining Table and Region Filters)59 1 TN TL()Ec /AF f D( )LU( )-1 LI( Miscellaneous )UL()-1 LI()0 61 1 A(Funtools Environment Variables)60 1 TN TL()Ec /AF f D( )-1 LI()0 62 1 A(Funtools ChangeLog)61 1 TN TL()Ec /AF f D()LU( )LU( )0 5 3 H(Last)WB 66 Sn( updated: January 6, 2006)EH( )WB NL NP Ep ET /Tc f D /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (programs.html) D /Ti (Funtools Programs) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 2 Sn( )0 2 4 H(Funtools)WB 67 Sn( Programs)EH( )0 2 5 H(Summary)WB 68 Sn()EH( )0 P() 27 129 PR()0 3 1 A(funcalc)3 0 TN TL()Ec /AF f D( [-n] [-a argstr] [-e expr] [-f file] [-l link] [-p prog] [-u] [oname [columns]] )0 4 1 A(funcen)4 0 TN TL()Ec /AF f D( [-i] [-n iter] [-t tol] [-v lev] )0 5 1 A(funcnts)5 0 TN TL()Ec /AF f D( [switches] [source_region] [bkgd_file] [bkgd_region|bkgd_cnts] )0 6 1 A(funcone)6 0 TN TL()Ec /AF f D( [-n] [-x|-X|-j|-J] [[-l|-L] list] [-r ra_col] [-d dec_col] [columns] )0 7 1 A(fundisp)7 0 TN TL()Ec /AF f D( [-f format] [-l] [-n] [-T] [columns|bitpix=n] )0 8 1 A(funhead)8 0 TN TL()Ec /AF f D( [-a] [-l] [-s] [-t] [-L] [oname ename] )0 9 1 A(funhist)9 0 TN TL()Ec /AF f D( [-n|-w|-T] [column] [[lo_edge:hi_edge:]bins] )0 10 1 A(funimage)10 0 TN TL()Ec /AF f D( [-a] [-l] [-p x|y] [bitpix=n] )0 11 1 A(funindex)11 0 TN TL()Ec /AF f D( [oname] )0 12 1 A(funjoin)12 0 TN TL()Ec /AF f D( [switches] ... )0 13 1 A(funmerge)13 0 TN TL()Ec /AF f D( ... )0 14 1 A(funsky)14 0 TN TL()Ec /AF f D( [switches] [ ] )0 15 1 A(funtable)15 0 TN TL()Ec /AF f D( [-a] [-i|-z] [-m] [-s cols] [columns] )0 16 1 A(funtbl)16 0 TN TL()Ec /AF f D( [-c cols] [-h] [-n table] [-p prog] [-s sep] [-T] )RP( )0 2 6 H(funcalc)WB 69 Sn()WB 3 Sn( - Funtools calculator \201for binary tables\202)EA()EH( )BD() 1 90 PR(funcalc [-n] [-a argstr] [-e expr] [-f file] [-l link] [-p prog] [oname [columns]])RP()ES( )0 P() 7 73 PR( -a argstr # user arguments to pass to the compiled program -e expr # funcalc expression -f file # file containing funcalc expression -l libs # libs to add to link command -n # output generated code instead of compiling and executing -p prog # generate named program, no execution -u # die if any variable is undeclared \201don't auto-declare\202)RP( )0 P()BD(funcalc)ES( is a calculator program that allows arbitrary expressions to be constructed, compiled, and executed on columns in a Funtools table \201FITS binary table or raw event file\202. It works by integrating user-supplied expression\201s\202 into a template C program, then compiling and executing the program. )BD(funcalc)ES( expressions are C statements, although some important simplifications \201such as automatic declaration of variables\202 are supported. )0 P()BD(funcalc)ES( expressions can be specified in three ways: on the command line using the )BD(-e [expression])ES( switch, in a file using the )BD(-f [file])ES( switch, or from stdin \201if neither )BD(-e)ES( nor )BD(-f)ES( is specified\202. Of course a file containing )BD(funcalc)ES( expressions can be read from stdin. )0 P(Each invocation of )BD(funcalc)ES( requires an input Funtools table file to be specified as the first command line argument. The output Funtools table file is the second optional argument. It is needed only if an output FITS file is being created \201i.e., in cases where the )BD(funcalc)ES( expression only prints values, no output file is needed\202. If input and output file are both specified, a third optional argument can specify the list of columns to activate \201using )0 33 1 A(FunColumnActivate\201\202)33 0 TN TL()Ec /AF f D(\202. Note that )BD(funcalc)ES( determines whether or not to generate code for writing an output file based on the presence or absence of an output file argument. )0 P(A )BD(funcalc)ES( expression executes on each row of a table and consists of one or more C statements that operate on the columns of that row \201possibly using temporary variables\202. Within an expression, reference is made to a column of the )BD(current)ES( row using the C struct syntax )BD(cur->[colname])ES(, e.g. cur->x, cur->pha, etc. Local scalar variables can be defined using C declarations at very the beginning of the expression, or else they can be defined automatically by )BD(funcalc)ES( \201to be of type double\202. Thus, for example, a swap of columns x and y in a table can be performed using either of the following equivalent )BD(funcalc)ES( expressions: ) 4 18 PR( double temp; temp = cur->x; cur->x = cur->y; cur->y = temp;)RP( or: ) 3 18 PR( temp = cur->x; cur->x = cur->y; cur->y = temp;)RP( When this expression is executed using a command such as: ) 1 40 PR( funcalc -f swap.expr itest.ev otest.ev)RP( the resulting file will have values of the x and y columns swapped. )0 P(By default, the data type of the variable for a column is the same as the data type of the column as stored in the file. This can be changed by appending ":[dtype]" to the first reference to that column. In the example above, to force x and y to be output as doubles, specify the type 'D' explicitly: ) 3 20 PR( temp = cur->x:D; cur->x = cur->y:D; cur->y = temp;)RP( Data type specifiers follow standard FITS table syntax for defining columns using TFORM: )UL()-1 LI(A: ASCII characters )-1 LI(B: unsigned 8-bit char )-1 LI(I: signed 16-bit int )-1 LI(U: unsigned 16-bit int \201not standard FITS\202 )-1 LI(J: signed 32-bit int )-1 LI(V: unsigned 32-bit int \201not standard FITS\202 )-1 LI(E: 32-bit float )-1 LI(D: 64-bit float )-1 LI(X: bits \201treated as an array of chars\202)LU( Note that only the first reference to a column should contain the explicit data type specifier. )0 P(Of course, it is important to handle the data type of the columns correctly. One of the most frequent cause of error in )BD(funcalc)ES( programming is the implicit use of the wrong data type for a column in expression. For example, the calculation: ) 1 43 PR( dx = \201cur->x - cur->y\202/\201cur->x + cur->y\202;)RP( usually needs to be performed using floating point arithmetic. In cases where the x and y columns are integers, this can be done by reading the columns as doubles using an explicit type specification: ) 1 47 PR( dx = \201cur->x:D - cur->y:D\202/\201cur->x + cur->y\202;)RP( Alternatively, it can be done using C type-casting in the expression: ) 1 75 PR( dx = \201\201double\202cur->x - \201double\202cur->y\202/\201\201double\202cur->x + \201double\202cur->y\202;)RP( )0 P(In addition to accessing columns in the current row, reference also can be made to the )BD(previous)ES( row using )BD(prev->[colname])ES(, and to the )BD(next)ES( row using )BD(next->[colname])ES(. Note that if )BD(prev->[colname])ES( is specified in the )BD(funcalc)ES( expression, the very first row is not processed. If )BD(next->[colname])ES( is specified in the )BD(funcalc)ES( expression, the very last row is not processed. In this way, )BD(prev)ES( and )BD(next)ES( are guaranteed always to point to valid rows. For example, to print out the values of the current x column and the previous y column, use the C fprintf function in a )BD(funcalc)ES( expression: ) 1 46 PR( fprintf\201stdout, "%d %d\200n", cur->x, prev->y\202;)RP( )0 P(New columns can be specified using the same )BD(cur->[colname])ES( syntax by appending the column type \201and optional tlmin/tlmax/binsiz specifiers\202, separated by colons. For example, cur->avg:D will define a new column of type double. Type specifiers are the same those used above to specify new data types for existing columns. )0 P(For example, to create and output a new column that is the average value of the x and y columns, a new "avg" column can be defined: ) 1 36 PR( cur->avg:D = \201cur->x + cur->y\202/2.0)RP( Note that the final ';' is not required for single-line expressions. )0 P(As with FITS TFORM data type specification, the column data type specifier can be preceded by a numeric count to define an array, e.g., "10I" means a vector of 10 short ints, "2E" means two single precision floats, etc. A new column only needs to be defined once in a )BD(funcalc)ES( expression, after which it can be used without re-specifying the type. This includes reference to elements of a column array: ) 2 41 PR( cur->avg[0]:2D = \201cur->x + cur->y\202/2.0; cur->avg[1] = \201cur->x - cur->y\202/2.0;)RP( )0 P(The 'X' \201bits\202 data type is treated as a char array of dimension \201numeric_count/8\202, i.e., 16X is processed as a 2-byte char array. Each 8-bit array element is accessed separately: ) 2 24 PR( cur->stat[0]:16X = 1; cur->stat[1] = 2;)RP( Here, a 16-bit column is created with the MSB is set to 1 and the LSB set to 2. )0 P(By default, all processed rows are written to the specified output file. If you want to skip writing certain rows, simply execute the C "continue" statement at the end of the )BD(funcalc)ES( expression, since the writing of the row is performed immediately after the expression is executed. For example, to skip writing rows whose average is the same as the current x value: ) 4 41 PR( cur->avg[0]:2D = \201cur->x + cur->y\202/2.0; cur->avg[1] = \201cur->x - cur->y\202/2.0; if\201 cur->avg[0] == cur->x \202 continue;)RP( )0 P(If no output file argument is specified on the )BD(funcalc)ES( command line, no output file is opened and no rows are written. This is useful in expressions that simply print output results instead of generating a new file: ) 5 73 PR( fpv = \201cur->av3:D-cur->av1:D\202/\201cur->av1+cur->av2:D+cur->av3\202; fbv = cur->av2/\201cur->av1+cur->av2+cur->av3\202; fpu = \201\201double\202cur->au3-cur->au1\202/\201\201double\202cur->au1+cur->au2+cur->au3\202; fbu = cur->au2/\201double\202\201cur->au1+cur->au2+cur->au3\202; fprintf\201stdout, "%f\200t%f\200t%f\200t%f\200n", fpv, fbv, fpu, fbu\202;)RP( In the above example, we use both explicit type specification \201for "av" columns\202 and type casting \201for "au" columns\202 to ensure that all operations are performed in double precision. )0 P(When an output file is specified, the selected input table is processed and output rows are copied to the output file. Note that the output file can be specified as "stdout" in order to write the output rows to the standard output. If the output file argument is passed, an optional third argument also can be passed to specify which columns to process. )0 P(In a FITS binary table, it sometimes is desirable to copy all of the other FITS extensions to the output file as well. This can be done by appending a '+' sign to the name of the extension in the input file name. See )BD(funtable)ES( for a related example. )0 P()BD(funcalc)ES( works by integrating the user-specified expression into a template C program called )0 2 A(tabcalc.c)EA(. The completed program then is compiled and executed. Variable declarations that begin the )BD(funcalc)ES( expression are placed in the local declaration section of the template main program. All other lines are placed in the template main program's inner processing loop. Other details of program generation are handled automatically. For example, column specifiers are analyzed to build a C struct for processing rows, which is passed to )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( and used in )0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D(. If an unknown variable is used in the expression, resulting in a compilation error, the program build is retried after defining the unknown variable to be of type double. )0 P(Normally, )BD(funcalc)ES( expression code is added to )BD(funcalc)ES( row processing loop. It is possible to add code to other parts of the program by placing this code inside special directives of the form: ) 3 26 PR( [directive name] ... code goes here ... end)RP( The directives are: )UL()-1 LI()BD(global)ES( add code and declarations in global space, before the main routine. )-1 LI()BD(local)ES( add declarations \201and code\202 just after the local declarations in main )-1 LI()BD(before)ES( add code just before entering the main row processing loop )-1 LI()BD(after)ES( add code just after exiting the main row processing loop)LU( Thus, the following )BD(funcalc)ES( expression will declare global variables and make subroutine calls just before and just after the main processing loop: ) 16 62 PR( global double v1, v2; double init\201void\202; double finish\201double v\202; end before v1 = init\201\202; end ... process rows, with calculations using v1 ... after v2 = finish\201v1\202; if\201 v2 < 0.0 \202{ fprintf\201stderr, "processing failed %g -> %g\200n", v1, v2\202; exit\2011\202; } end)RP( Routines such as init\201\202 and finish\201\202 above are passed to the generated program for linking using the )BD(-l [link directives ...])ES( switch. The string specified by this switch will be added to the link line used to build the program \201before the funtools library\202. For example, assuming that init\201\202 and finish\201\202 are in the library libmysubs.a in the /opt/special/lib directory, use: ) 1 47 PR( funcalc -l "-L/opt/special/lib -lmysubs" ...)RP( )0 P(User arguments can be passed to a compiled funcalc program using a string argument to the "-a" switch. The string should contain all of the user arguments. For example, to pass the integers 1 and 2, use: ) 1 22 PR( funcalc -a "1 2" ...)RP( The arguments are stored in an internal array and are accessed as strings via the ARGV\201n\202 macro. For example, consider the following expression: ) 11 60 PR( local int pmin, pmax; end before pmin=atoi\201ARGV\2010\202\202; pmax=atoi\201ARGV\2011\202\202; end if\201 \201cur->pha >= pmin\202 && \201cur->pha <= pmax\202 \202 fprintf\201stderr, "%d %d %d\200n", cur->x, cur->y, cur->pha\202;)RP( This expression will print out x, y, and pha values for all rows in which the pha value is between the two user-input values: ) 11 51 PR( funcalc -a '1 12' -f foo snr.ev'[cir 512 512 .1]' 512 512 6 512 512 8 512 512 5 512 512 5 512 512 8 funcalc -a '5 6' -f foo snr.ev'[cir 512 512 .1]' 512 512 6 512 512 5 512 512 5)RP( )0 P(Note that it is the user's responsibility to ensure that the correct number of arguments are passed. The ARGV\201n\202 macro returns a NULL if a requested argument is outside the limits of the actual number of args, usually resulting in a SEGV if processed blindly. To check the argument count, use the ARGC macro: ) 12 42 PR( local long int seed=1; double limit=0.8; end before if\201 ARGC >= 1 \202 seed = atol\201ARGV\2010\202\202; if\201 ARGC >= 2 \202 limit = atof\201ARGV\2011\202\202; srand48\201seed\202; end if \201 drand48\201\202 > limit \202 continue;)RP( )0 P(The macro WRITE_ROW expands to the FunTableRowPut\201\202 call that writes the current row. It can be used to write the row more than once. In addition, the macro NROW expands to the row number currently being processed. Use of these two macros is shown in the following example: ) 7 41 PR( if\201 cur->pha:I == cur->pi:I \202 continue; a = cur->pha; cur->pha = cur->pi; cur->pi = a; cur->AVG:E = \201cur->pha+cur->pi\202/2.0; cur->NR:I = NROW; if\201 NROW < 10 \202 WRITE_ROW;)RP( )0 P(If the )BD(-p [prog])ES( switch is specified, the expression is not executed. Rather, the generated executable is saved with the specified program name for later use. )0 P(If the )BD(-n)ES( switch is specified, the expression is not executed. Rather, the generated code is written to stdout. This is especially useful if you want to generate a skeleton file and add your own code, or if you need to check compilation errors. Note that the comment at the start of the output gives the compiler command needed to build the program on that platform. \201The command can change from platform to platform because of the use of different libraries, compiler switches, etc.\202 )0 P(As mentioned previously, )BD(funcalc)ES( will declare a scalar variable automatically \201as a double\202 if that variable has been used but not declared. This facility is implemented using a sed script named )0 2 A(funcalc.sed)EA(, which processes the compiler output to sense an undeclared variable error. This script has been seeded with the appropriate error information for gcc, and for cc on Solaris, DecAlpha, and SGI platforms. If you find that automatic declaration of scalars is not working on your platform, check this sed script; it might be necessary to add to or edit some of the error messages it senses. )0 P(In order to keep the lexical analysis of )BD(funcalc)ES( expressions \201reasonably\202 simple, we chose to accept some limitations on how accurately C comments, spaces, and new-lines are placed in the generated program. In particular, comments associated with local variables declared at the beginning of an expression \201i.e., not in a )BD(local...end)ES( block\202 will usually end up in the inner loop, not with the local declarations: ) 8 69 PR( /* this comment will end up in the wrong place \201i.e, inner loop\202 */ double a; /* also in wrong place */ /* this will be in the the right place \201inner loop\202 */ if\201 cur->x:D == cur->y:D \202 continue; /* also in right place */ a = cur->x; cur->x = cur->y; cur->y = a; cur->avg:E = \201cur->x+cur->y\202/2.0;)RP( Similarly, spaces and new-lines sometimes are omitted or added in a seemingly arbitrary manner. Of course, none of these stylistic blemishes affect the correctness of the generated code. )0 P(Because )BD(funcalc)ES( must analyze the user expression using the data file\201s\202 passed on the command line, the input file\201s\202 must be opened and read twice: once during program generation and once during execution. As a result, it is not possible to use stdin for the input file: )BD(funcalc)ES( cannot be used as a filter. We will consider removing this restriction at a later time. )0 P(Along with C comments, )BD(funcalc)ES( expressions can have one-line internal comments that are not passed on to the generated C program. These internal comment start with the )BD(#)ES( character and continue up to the new-line: ) 7 56 PR( double a; # this is not passed to the generated C file # nor is this a = cur->x; cur->x = cur->y; cur->y = a; /* this comment is passed to the C file */ cur->avg:E = \201cur->x+cur->y\202/2.0;)RP( )0 P(As previously mentioned, input columns normally are identified by their being used within the inner event loop. There are rare cases where you might want to read a column and process it outside the main loop. For example, qsort might use a column in its sort comparison routine that is not processed inside the inner loop \201and therefore not implicitly specified as a column to be read\202. To ensure that such a column is read by the event loop, use the )BD(explicit)ES( keyword. The arguments to this keyword specify columns that should be read into the input record structure even though they are not mentioned in the inner loop. For example: ) 1 17 PR( explicit pi pha)RP( will ensure that the pi and pha columns are read for each row, even if they are not processed in the inner event loop. The )BD(explicit)ES( statement can be placed anywhere. )0 P(Finally, note that )BD(funcalc)ES( currently works on expressions involving FITS binary tables and raw event files. We will consider adding support for image expressions at a later point, if there is demand for such support from the community. )0 2 7 H(funcen)WB 70 Sn()WB 4 Sn( - find centroid \201for binary tables\202)EA()EH( )BD() 1 56 PR(funcen [-i] [-n iter] [-t tol] [-v lev] )RP()ES( )0 P() 4 64 PR( -i # use image filtering \201default: event filtering\202 -n iter # max number of iterations \201default: 0\202 -t tol # pixel tolerance distance \201default: 1.0\202 -v [0,1,2,3] # output verbosity level \201default: 0\202)RP( )0 P()BD(funcen)ES( iteratively calculates the centroid position within one or more regions of a Funtools table \201FITS binary table or raw event file\202. Starting with an input table, an initial region specification, and an iteration count, the program calculates the average x and y position within the region and then uses this new position as the region center for the next iteration. Iteration terminates when the maximum number of iterations is reached or when the input tolerance distance is met for that region. A count of events in the final region is then output, along with the pixel position value \201and, where available, WCS position\202. )0 P(The first argument to the program specifies the Funtools table file to process. Since the file must be read repeatedly, a value of "stdin" is not permitted when the number of iterations is non-zero. Use )0 42 1 A(Funtools Bracket Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions and filters. )0 P(The second required argument is the initial region descriptor. Multiple regions are permitted. However, compound regions \201accelerators, variable argument regions and regions connected via boolean algebra\202 are not permitted. Points and polygons also are illegal. These restrictions might be lifted in a future version, if warranted. )0 P(The )BD(-n)ES( \201iteration number\202 switch specifies the maximum number of iterations to perform. The default is 0, which means that the program will simply count and display the number of events in the initial region\201s\202. Note that when iterations is 0, the data can be input via stdin. )0 P(The )BD(-t)ES( \201tolerance\202 switch specifies a floating point tolerance value. If the distance between the current centroid position value and the last position values is less than this value, iteration terminates. The default value is 1 pixel. )0 P(The )BD(-v)ES( \201verbosity\202 switch specifies the verbosity level of the output. The default is 0, which results in a single line of output for each input region consisting of the following values: ) 1 30 PR( counts x y [ra dec coordsys])RP( The last 3 WCS values are output if WCS information is available in the data file header. Thus, for example: ) 5 47 PR( [sh] funcen -n 0 snr.ev "cir 505 508 5" 915 505.00 508.00 345.284038 58.870920 j2000 [sh] funcen -n 3 snr.ev "cir 505 508 5" 1120 504.43 509.65 345.286480 58.874587 j2000)RP( The first example simply counts the number of events in the initial region. The second example iterates the centroid calculation three times to determine a final "best" position. )0 P( Higher levels of verbosity obviously imply more verbose output. At level 1, the output essentially contains the same information as level 0, but with keyword formatting: [sh] funcen -v 1 -n 3 snr.ev "cir 505 508 5" event_file: snr.ev initial_region: cir 505 508 5 tolerance: 1.0000 iterations: 1 events: 1120 x,y\201physical\202: 504.43 509.65 ra,dec\201j2000\202: 345.286480 58.874587 final_region1: cir 504.43 509.65 5)RP( Level 2 outputs results from intermediate calculations as well. )0 P(Ordinarily, region filtering is performed using analytic \201event\202 filtering, i.e. that same style of filtering as is performed by )BD(fundisp)ES( and )BD(funtable)ES(. Use the )BD(-i)ES( switch to specify image filtering, i.e. the same style filtering as is performed by )BD(funcnts)ES(. Thus, you can perform a quick calculation of counts in regions, using either the analytic or image filtering method, by specifying the )BD(-n 0)ES( and optional )BD(-i)ES( switches. These two method often give different results because of how boundary events are processed: ) 5 46 PR( [sh] funcen snr.ev "cir 505 508 5" 915 505.00 508.00 345.284038 58.870920 j2000 [sh] funcen -i snr.ev "cir 505 508 5" 798 505.00 508.00 345.284038 58.870920 j2000)RP( See )0 58 1 A(Region Boundaries)58 0 TN TL()Ec /AF f D( for more information about how boundaries are calculated using these two methods. )0 2 8 H(funcnts)WB 71 Sn()WB 5 Sn( - count photons in specified regions, with bkgd subtraction)EA()EH( )BD() 1 86 PR(funcnts [switches] [source_region] [bkgd_file] [bkgd_region|bkgd_value])RP()ES( )0 P() 16 79 PR( -e "source_exposure[;bkgd_exposure]" # source \201bkgd\202 FITS exposure image using matching files -w "source_exposure[;bkgd_exposure]" # source \201bkgd\202 FITS exposure image using WCS transform -t "source_timecorr[;bkgd_timecorr]" # source \201bkgd\202 time correction value or header parameter name -g # output using nice g format -G # output using %.14g format \201maximum precision\202 -i "[column;]int1;int2..." # column-based intervals -m # match individual source and bkgd regions -p # output in pixels, even if wcs is present -r # output inner/outer radii \201and angles\202 for annuli \201and pandas\202 -s # output summed values -v "scol[;bcol]" # src and bkgd value columns for tables -T # output in starbase/rdb format -z # output regions with zero area)ES()RP( )0 P()BD(funcnts)ES( counts photons in the specified source regions and reports the results for each region. Regions are specified using the )0 54 1 A(Spatial Region Filtering)54 0 TN TL()Ec /AF f D( mechanism. Photons are also counted in the specified bkgd regions applied to the same data file or a different data file. \201Alternatively, a constant background value in counts/pixel**2 can be specified.\202 The bkgd regions are either paired one-to-one with source regions or pooled and normalized by area, and then subtracted from the source counts in each region. Displayed results include the bkgd-subtracted counts in each region, as well as the error on the counts, the area in each region, and the surface brightness \201cnts/area**2\202 calculated for each region. )0 P(The first argument to the program specifies the FITS input image, array, or raw event file to process. If "stdin" is specified, data are read from the standard input. Use )0 42 1 A(Funtools Bracket Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions, image sections, and filters. )0 P(The optional second argument is the source region descriptor. If no region is specified, the entire field is used. )0 P(The background arguments can take one of two forms, depending on whether a separate background file is specified. If the source file is to be used for background as well, the third argument can be either the background region, or a constant value denoting background cnts/pixel. Alternatively, the third argument can be a background data file, in which case the fourth argument is the background region. If no third argument is specified, a constant value of 0 is used \201i.e., no background\202. )0 P(In summary, the following command arguments are valid: ) 5 77 PR( [sh] funcnts sfile # counts in source file [sh] funcnts sfile sregion # counts in source region [sh] funcnts sfile sregion bregion # bkgd reg. is from source file [sh] funcnts sfile sregion bvalue # bkgd reg. is constant [sh] funcnts sfile sregion bfile bregion # bkgd reg. is from separate file)RP( )0 P(NB: unlike other Funtools programs, source and background regions are specified as separate arguments on the command line, rather than being placed inside brackets as part of the source and background filenames. This is because regions in funcnts are not simply used as data filters, but also are used to calculate areas, exposure, etc. If you put the source region inside the brackets \201i.e. use it simply as a filter\202 rather than specifying it as argument two, the program still will only count photons that pass the region filter. However, the area calculation will be performed on the whole field, since field\201\202 is the default source region. This rarely is the desired behavior. On the other hand, with FITS binary tables, it often is useful to put a column filter in the filename brackets, so that only events matching the column filter are counted inside the region. )0 P(For example, to extract the counts within a radius of 22 pixels from the center of the FITS binary table snr.ev and subtract the background determined from the same image within an annulus of radii 50-100 pixels: ) 33 82 PR( [sh] funcnts snr.ev "circle\201502,512,22\202" "annulus\201502,512,50,100\202" # source # data file: snr.ev # degrees/pix: 0.00222222 # background # data file: snr.ev # column units # area: arcsec**2 # surf_bri: cnts/arcsec**2 # surf_err: cnts/arcsec**2 # background-subtracted results reg net_counts error background berror area surf_bri surf_err ---- ------------ --------- ------------ --------- --------- --------- --------- 1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001 # the following source and background components were used: source region\201s\202 ---------------- circle\201502,512,22\202 reg counts pixels ---- ------------ --------- 1 4382.000 1513 background region\201s\202 -------------------- annulus\201502,512,50,100\202 reg counts pixels)WR( ---- ------------ --------- all 8656.000 23572)RP( The area units for the output columns labeled "area", "surf_bri" \201surface brightness\202 and "surf_err" will be given either in arc-seconds \201if appropriate WCS information is in the data file header\201s\202\202 or in pixels. If the data file has WCS info, but you do not want arc-second units, use the )BD(-p)ES( switch to force output in pixels. Also, regions having zero area are not normally included in the primary \201background-subtracted\202 table, but are included in the secondary source and bkgd tables. If you want these regions to be included in the primary table, use the )BD(-z)ES( switch. )0 P(Note that a simple sed command will extract the background-subtracted results for further analysis: ) 6 79 PR( [sh] cat funcnts.sed 1,/---- .*/d /^$/,$d [sh] sed -f funcnts.sed funcnts.out 1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001)RP( )0 P(If separate source and background files are specified, )BD(funcnts)ES( will attempt to normalize the the background area so that the background pixel size is the same as the source pixel size. This normalization can only take place if the appropriate WCS information is contained in both files \201e.g. degrees/pixel values in CDELT\202. If either file does not contain the requisite size information, the normalization is not performed. In this case, it is the user's responsibility to ensure that the pixel sizes are the same for the two files. )0 P(Normally, if more than one background region is specified, )BD(funcnts)ES( will combine them all into a single region and use this background region to produce the background-subtracted results for each source region. The )BD(-m)ES( \201match multiple backgrounds\202 switch tells )BD(funcnts)ES( to make a one to one correspondence between background and source regions, instead of using a single combined background region. For example, the default case is to combine 2 background regions into a single region and then apply that region to each of the source regions: ) 35 82 PR( [sh] funcnts snr.ev "annulus\201502,512,0,22,n=2\202" "annulus\201502,512,50,100,n=2\202" # source # data file: snr.ev # degrees/pix: 0.00222222 # background # data file: snr.ev # column units # area: arcsec**2 # surf_bri: cnts/arcsec**2 # surf_err: cnts/arcsec**2 # background-subtracted results reg net_counts error background berror area surf_bri surf_err ---- ------------ --------- ------------ --------- --------- --------- --------- 1 3101.029 56.922 136.971 1.472 23872.00 0.130 0.002 2 725.375 34.121 418.625 4.500 72959.99 0.010 0.000 # the following source and background components were used: source region\201s\202 ---------------- annulus\201502,512,0,22,n=2\202 reg counts pixels ---- ------------ --------- 1 3238.000 373 2 1144.000 1140 background region\201s\202 -------------------- annulus\201502,512,50,100,n=2\202)WR( reg counts pixels ---- ------------ --------- all 8656.000 23572)RP( Note that the basic region filter rule "each photon is counted once and no photon is counted more than once" still applies when using The )BD(-m)ES( to match background regions. That is, if two background regions overlap, the overlapping pixels will be counted in only one of them. In a worst-case scenario, if two background regions are the same region, the first will get all the counts and area and the second will get none. )0 P(Using the )BD(-m)ES( switch causes )BD(funcnts)ES( to use each of the two background regions independently with each of the two source regions: ) 36 82 PR( [sh] funcnts -m snr.ev "annulus\201502,512,0,22,n=2\202" "ann\201502,512,50,100,n=2\202" # source # data file: snr.ev # degrees/pix: 0.00222222 # background # data file: snr.ev # column units # area: arcsec**2 # surf_bri: cnts/arcsec**2 # surf_err: cnts/arcsec**2 # background-subtracted results reg net_counts error background berror area surf_bri surf_err ---- ------------ --------- ------------ --------- --------- --------- --------- 1 3087.015 56.954 150.985 2.395 23872.00 0.129 0.002 2 755.959 34.295 388.041 5.672 72959.99 0.010 0.000 # the following source and background components were used: source region\201s\202 ---------------- annulus\201502,512,0,22,n=2\202 reg counts pixels ---- ------------ --------- 1 3238.000 373 2 1144.000 1140 background region\201s\202 -------------------- ann\201502,512,50,100,n=2\202)WR( reg counts pixels ---- ------------ --------- 1 3975.000 9820 2 4681.000 13752)RP( )0 P(Note that most floating point quantities are displayed using "f" format. You can change this to "g" format using the )BD(-g)ES( switch. This can be useful when the counts in each pixel is very small or very large. If you want maximum precision and don't care about the columns lining up nicely, use )BD(-G)ES(, which outputs all floating values as %.14g. )0 P(When counting photons using the annulus and panda \201pie and annuli\202 shapes, it often is useful to have access to the radii \201and panda angles\202 for each separate region. The )BD(-r)ES( switch will add radii and angle columns to the output table: ) 37 122 PR( [sh] funcnts -r snr.ev "annulus\201502,512,0,22,n=2\202" "ann\201502,512,50,100,n=2\202" # source # data file: snr.ev # degrees/pix: 0.00222222 # background # data file: snr.ev # column units # area: arcsec**2 # surf_bri: cnts/arcsec**2 # surf_err: cnts/arcsec**2 # radii: arcsecs # angles: degrees # background-subtracted results reg net_counts error background berror area surf_bri surf_err radius1 radius2 angle1 angle2 ---- ------------ --------- ------------ --------- --------- --------- --------- --------- --------- --------- --------- 1 3101.029 56.922 136.971 1.472 23872.00 0.130 0.002 0.00 88.00 NA NA 2 725.375 34.121 418.625 4.500 72959.99 0.010 0.000 88.00 176.00 NA NA # the following source and background components were used: source region\201s\202 ---------------- annulus\201502,512,0,22,n=2\202 reg counts pixels ---- ------------ --------- 1 3238.000 373 2 1144.000 1140 background region\201s\202)WR( -------------------- ann\201502,512,50,100,n=2\202 reg counts pixels ---- ------------ --------- all 8656.000 23572)RP( )0 P(Radii are given in units of pixels or arc-seconds \201depending on the presence of WCS info\202, while the angle values \201when present\202 are in degrees. These columns can be used to plot radial profiles. For example, the script )BD(funcnts.plot)ES( in the funtools distribution\202 will plot a radial profile using gnuplot \201version 3.7 or above\202. A simplified version of this script is shown below: ) 74 79 PR( #!/bin/sh if [ x"$1" = xgnuplot ]; then if [ x`which gnuplot 2>/dev/null` = x ]; then echo "ERROR: gnuplot not available" exit 1 fi awk ' BEGIN{HEADER=1; DATA=0; FILES=""; XLABEL="unknown"; YLABEL="unknown"} HEADER==1{ if\201 $1 == "#" && $2 == "data" && $3 == "file:" \202{ if\201 FILES != "" \202 FILES = FILES "," FILES = FILES $4 } else if\201 $1 == "#" && $2 == "radii:" \202{ XLABEL = $3 } else if\201 $1 == "#" && $2 == "surf_bri:" \202{ YLABEL = $3 } else if\201 $1 == "----" \202{ printf "set nokey; set title \200"funcnts\201%s\202\200"\200n", FILES printf "set xlabel \200" radius\201%s\202\200"\200n", XLABEL printf "set ylabel \200"surf_bri\201%s\202\200"\200n", YLABEL print "plot \200"-\200" using 3:4:6:7:8 with boxerrorbars" HEADER = 0 DATA = 1 next } } DATA==1{)WR( if\201 NF == 12 \202{ print $9, $10, \201$9+$10\202/2, $7, $8, $7-$8, $7+$8, $10-$9 } else{ exit } } ' | gnuplot -persist - 1>/dev/null 2>&1 elif [ x"$1" = xds9 ]; then awk ' BEGIN{HEADER=1; DATA=0; XLABEL="unknown"; YLABEL="unknown"} HEADER==1{ if\201 $1 == "#" && $2 == "data" && $3 == "file:" \202{ if\201 FILES != "" \202 FILES = FILES "," FILES = FILES $4 } else if\201 $1 == "#" && $2 == "radii:" \202{ XLABEL = $3 } else if\201 $1 == "#" && $2 == "surf_bri:" \202{ YLABEL = $3 } else if\201 $1 == "----" \202{ printf "funcnts\201%s\202 radius\201%s\202 surf_bri\201%s\202 3\200n", FILES, XLABEL, YLABEL HEADER = 0 DATA = 1 next } })WR( DATA==1{ if\201 NF == 12 \202{ print $9, $7, $8 } else{ exit } } ' else echo "funcnts -r ... | funcnts.plot [ds9|gnuplot]" exit 1 fi)RP( Thus, to run )BD(funcnts)ES( and plot the results using gnuplot \201version 3.7 or above\202, use: ) 1 75 PR( funcnts -r snr.ev "annulus\201502,512,0,50,n=5\202" ... | funcnts.plot gnuplot)RP( )0 P(The )BD(-s)ES( \201sum\202 switch causes )BD(funcnts)ES( to produce an additional table of summed \201integrated\202 background subtracted values, along with the default table of individual values: ) 51 82 PR( [sh] funcnts -s snr.ev "annulus\201502,512,0,50,n=5\202" "annulus\201502,512,50,100\202" # source # data file: snr.ev # degrees/pix: 0.00222222 # background # data file: snr.ev # column units # area: arcsec**2 # surf_bri: cnts/arcsec**2 # surf_err: cnts/arcsec**2 # summed background-subtracted results upto net_counts error background berror area surf_bri surf_err ---- ------------ --------- ------------ --------- --------- --------- --------- 1 2880.999 54.722 112.001 1.204 19520.00 0.148 0.003 2 3776.817 65.254 457.183 4.914 79679.98 0.047 0.001 3 4025.492 71.972 1031.508 11.087 179775.96 0.022 0.000 4 4185.149 80.109 1840.851 19.786 320831.94 0.013 0.000 5 4415.540 90.790 2873.460 30.885 500799.90 0.009 0.000 # background-subtracted results reg counts error background berror area surf_bri surf_err ---- ------------ --------- ------------ --------- --------- --------- --------- 1 2880.999 54.722 112.001 1.204 19520.00 0.148 0.003 2 895.818 35.423 345.182 3.710 60159.99 0.015 0.001 3 248.675 29.345 574.325 6.173 100095.98 0.002 0.000 4 159.657 32.321 809.343 8.699 141055.97 0.001 0.000 5 230.390 37.231 1032.610 11.099 179967.96 0.001 0.000 )WR( # the following source and background components were used: source region\201s\202 ---------------- annulus\201502,512,0,50,n=5\202 reg counts pixels sumcnts sumpix ---- ------------ --------- ------------ --------- 1 2993.000 305 2993.000 305 2 1241.000 940 4234.000 1245 3 823.000 1564 5057.000 2809 4 969.000 2204 6026.000 5013 5 1263.000 2812 7289.000 7825 background region\201s\202 -------------------- annulus\201502,512,50,100\202 reg counts pixels ---- ------------ --------- all 8656.000 23572)RP( )0 P(The )BD(-t)ES( and )BD(-e)ES( switches can be used to apply timing and exposure corrections, respectively, to the data. Please note that these corrections are meant to be used qualitatively, since application of more accurate correction factors is a complex and mission-dependent effort. The algorithm for applying these simple corrections is as follows: ) 9 63 PR( C = Raw Counts in Source Region Ac= Area of Source Region Tc= Exposure time for Source Data Ec= Average exposure in Source Region, from exposure map B= Raw Counts in Background Region Ab= Area of Background Region Tb= \201Exposure\202 time for Background Data Eb= Average exposure in Background Region, from exposure map)RP( Then, Net Counts in Source region is ) 1 37 PR( Net= C - B * \201Ac*Tc*Ec\202/\201Ab*Tb*Eb\202)RP( with the standard propagation of errors for the Error on Net. The net rate would then be ) 1 27 PR( Net Rate = Net/\201Ac*Tc*Ec\202)RP( The average exposure in each region is calculated by summing up the pixel values in the exposure map for the given region and then dividing by the number of pixels in that region. Exposure maps often are generated at a block factor > 1 \201e.g., block 4 means that each exposure pixel contains 4x4 pixels at full resolution\202 and )BD(funcnts)ES( will deal with the blocking automatically. Using the )BD(-e)ES( switch, you can supply both source and background exposure files \201separated by ";"\202, if you have separate source and background data files. If you do not supply a background exposure file to go with a separate background data file, )BD(funcnts)ES( assumes that exposure already has been applied to the background data file. In addition, it assumes that the error on the pixels in the background data file is zero. )0 P(NB: The )BD(-e)ES( switch assumes that the exposure map overlays the image file )BD(exactly)ES(, except for the block factor. Each pixel in the image is scaled by the block factor to access the corresponding pixel in the exposure map. If your exposure map does not line up exactly with the image, )BD(do not use)ES( the )BD(-e)ES( exposure correction. In this case, it still is possible to perform exposure correction )BD(if)ES( both the image and the exposure map have valid WCS information: use the )BD(-w)ES( switch so that the transformation from image pixel to exposure pixel uses the WCS information. That is, each pixel in the image region will be transformed first from image coordinates to sky coordinates, then from sky coordinates to exposure coordinates. Please note that using )BD(-w)ES( can increase the time required to process the exposure correction considerably. )0 P(A time correction can be applied to both source and background data using the )BD(-t)ES( switch. The value for the correction can either be a numeric constant or the name of a header parameter in the source \201or background\202 file: ) 2 74 PR( [sh] funcnts -t 23.4 ... # number for source [sh] funcnts -t "LIVETIME;23.4" ... # param for source, numeric for bkgd)RP( When a time correction is specified, it is applied to the net counts as well \201see algorithm above\202, so that the units of surface brightness become cnts/area**2/sec. )0 P(The )BD(-i)ES( \201interval\202 switch is used to run )BD(funcnts)ES( on multiple column-based intervals with only a single pass through the data. It is equivalent to running )BD(funcnts)ES( several times with a different column filter added to the source and background data each time. For each interval, the full )BD(funcnts)ES( output is generated, with a linefeed character \201^L\202 inserted between each run. In addition, the output for each interval will contain the interval specification in its header. Intervals are very useful for generating X-ray hardness ratios efficiently. Of course, they are only supported when the input data are contained in a table. )0 P(Two formats are supported for interval specification. The most general format is semi-colon-delimited list of filters to be used as intervals: ) 1 73 PR( funcnts -i "pha=1:5;pha=6:10;pha=11:15" snr.ev "circle\201502,512,22\202" ...)RP( Conceptually, this will be equivalent to running )BD(funcnts)ES( three times: ) 3 50 PR( funcnts snr.ev'[pha=1:5]' "circle\201502,512,22\202" funcnts snr.ev'[pha=6:10]' "circle\201502,512,22\202" funcnts snr.ev'[pha=11:15]' "circle\201502,512,22\202")RP( However, using the )BD(-i)ES( switch will require only one pass through the data. )0 P(Note that complex filters can be used to specify intervals: ) 1 64 PR( funcnts -i "pha=1:5&)SY(\160)ES(=4;pha=6:10&)SY(\160)ES(=5;pha=11:15&)SY(\160)ES(=6" snr.ev ...)RP( The program simply runs the data through each filter in turn and generates three )BD(funcnts)ES( outputs, separated by the line-feed character. )0 P(In fact, although the intent is to support intervals for hardness ratios, the specified filters do not have to be intervals at all. Nor does one "interval" filter have to be related to another. For example: ) 1 75 PR( funcnts -i "pha=1:5;pi=6:10;energy=11:15" snr.ev "circle\201502,512,22\202" ...)RP( is equivalent to running )BD(funcnts)ES( three times with unrelated filter specifications. )0 P(A second interval format is supported for the simple case in which a single column is used to specify multiple homogeneous intervals for that column. In this format, a column name is specified first, followed by intervals: ) 1 65 PR( funcnts -i "pha;1:5;6:10;11:15" snr.ev "circle\201502,512,22\202" ...)RP( This is equivalent to the first example, but requires less typing. The )BD(funcnts)ES( program will simply prepend "pha=" before each of the specified intervals. \201Note that this format does not contain the "=" character in the column argument.\202 )0 P(Ordinarily, when )BD(funcnts)ES( is run on a FITS binary table \201or a raw event table\202, one integral count is accumulated for each row \201event\202 contained within a given region. The )BD(-v "scol[;bcol]")ES( \201value column\202 switch will accumulate counts using the value from the specified column for the given event. If only a single column is specified, it is used for both the source and background regions. Two separate columns, separated by a semi-colon, can be specified for source and background. The special token '$none' can be used to specify that a value column is to be used for one but not the other. For example, 'pha;$none' will use the pha column for the source but use integral counts for the background, while '$none;pha' will do the converse. If the value column is of type logical, then the value used will be 1 for T and 0 for F. Value columns are used, for example, to integrate probabilities instead of integral counts. )0 P(If the )BD(-T)ES( \201rdb table\202 switch is used, the output will conform to starbase/rdb data base format: tabs will be inserted between columns rather than spaces and line-feed will be inserted between tables. )0 P(Finally, note that )BD(funcnts)ES( is an image program, even though it can be run directly on FITS binary tables. This means that image filtering is applied to the rows in order to ensure that the same results are obtained regardless of whether a table or the equivalent binned image is used. Because of this, however, the number of counts found using )BD(funcnts)ES( can differ from the number of events found using row-filter programs such as )BD(fundisp)ES( or )BD(funtable)ES( For more information about these difference, see the discussion of )0 58 1 A(Region Boundaries)58 0 TN TL()Ec /AF f D(. )0 2 9 H(funcone)WB 72 Sn()WB 6 Sn( - cone search of a binary table containing RA, Dec columns)EA()EH( )BD() 1 81 PR(funcone [columns])RP()ES( )0 P() 9 84 PR( -d deccol:[hdr] # Dec column name, units \201def: DEC:d\202 -j # join columns from list file -J # join columns from list file, output all rows -l listfile # read centers and radii from a list -L listfile # read centers and radii from a list, output list rows -n # don't use cone limits as a filter -r racol:[hdr] # RA column name, units \201def: RA:h\202 -x # append RA_CEN, DEC_CEN, RAD_CEN, CONE_KEY cols -X # append RA_CEN, DEC_CEN, RAD_CEN, CONE_KEY cols, output all rows)RP( )0 P(Funcone performs a cone search on the RA and Dec columns of a FITS binary table. The distance from the center RA, Dec position to the RA, Dec in each row in the table is calculated. Rows whose distance is less than the specified radius are output. )0 P(The first argument to the program specifies the FITS file, raw event file, or raw array file. If "stdin" is specified, data are read from the standard input. Use )0 42 1 A(Funtools Bracket Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions, and filters. The second argument is the output FITS file. If "stdout" is specified, the FITS binary table is written to the standard output. )0 P( The third and fourth required arguments are the RA and Dec center position. By default, RA is specified in hours while Dec is specified in degrees. You can change the units of either of these by appending the character "d" \201degrees\202, "h" \201hours\202 or "r" \201radians\202. Sexagesimal notation is supported, with colons or spaces separating hms and dms. \201When using spaces, please ensure that the entire string is quoted.\202 )0 P(The fifth required argument is the radius of the cone search. By default, the radius value is given in degrees. The units can be changed by appending the character "d" \201degrees\202, "r" \201radians\202, "'" \201arc minutes\202 or '"' \201arc seconds\202. )0 P(By default, all columns of the input file are copied to the output file. Selected columns can be output using an optional sixth argument in the form: ) 1 31 PR( "column1 column1 ... columnN")RP( A seventh argument allows you to output selected columns from the list file when )BD(-j)ES( switch is used. Note that the RA and Dec columns used in the cone calculation must not be de-selected. )0 P(Also by default, the RA and Dec column names are named "RA" and "Dec", and are given in units of hours and degrees respectively. You can change both the name and the units using the -r [RA] and/or -d [Dec] switches. Once again, one of "h", "d", or "r" is appended to the column name to specify units but in this case, there must be a colon ":" between the name and the unit specification. )0 P(If the )BD(-l [listfile])ES( switch is used, then one or more of the center RA, center Dec, and radius can be taken from a list file \201which can be a FITS table or an ASCII column text file\202. In this case, the third \201center RA\202, fourth \201center Dec\202, and fifth \201radius\202 command line arguments can either be a column name in the list file \201if that parameter varies\202 or else a numeric value \201if that parameter is static\202. When a column name is specified for the RA, Dec, or radius, you can append a colon followed by "h", "d", or "r" to specify units \201also ' and " for radius\202. The cone search algorithm is run once for each row in the list, taking RA, Dec, and radius values from the specified columns or from static numeric values specified on the command line. )0 P(When using a list, all valid rows from each iteration are written to a single output file. Use the )BD(-x)ES( switch to help delineate which line of the list file was used to produce the given output row\201s\202. This switch causes the values for the center RA, Dec, radius, and row number to be appended to the output file, in columns called RA_CEN, DEC_CEN, RAD_CEN and CONE_KEY, respectively. Alternatively, the )BD(-j)ES( \201join\202 switch will append all columns from the list row to the output row \201essentially a join of the list row and input row\202, along with the CONE_KEY row number. These two switches are mutually exclusive. )0 P(The )BD(-X)ES( and )BD(-J)ES( switches write out the same data as their lower case counterparts for each row satisfying a cone search. In addition, these switches also write out rows from the event file that do not satisfy any cone search. In such cases, that CONE_KEY column will be given a value of -1 and the center and list position information will be set to zero for the given row. Thus, all rows of the input event file are guaranteed to be output, with rows satisfying at least one cone search having additional search information. )0 P(The )BD(-L)ES( switch acts similarly to the )BD(-l)ES( switch in that it takes centers from a list file. However, it also implicitly sets the -j switch, so that output rows are the join of the input event row and the center position row. In addition, this switch also writes out all center position rows for which no event satisfies the cone search criteria of that row. The CONE_KEY column will be given a value of -2 for center rows that were not close to any data row and the event columns will be zeroed out for such rows. In this way, all centers rows are guaranteed to be output at least once. )0 P(If any of "all row" switches \201)BD(-X)ES(, )BD(-J)ES(, or )BD(-L)ES(\202 are specified, then a new column named JSTAT is added to the output table. The positive values in this column indicate the center position row number \201starting from 1\202 in the list file that this data row successful matched in a cone search. A value of -1 means that the data row did not match any center position. A value of -2 means that the center position was not matched by any data row. )0 P(Given a center position and radius, the cone search algorithm calculates limit parameters for a box enclosing the specified cone, and only tests rows whose positions values lie within those limits. For small files, the overhead associated with this cone limit filtering can cause the program to run more slowly than if all events were tested. You can turn off cone limit filtering using the )BD(-n)ES( switch to see if this speeds up the processing \201especially useful when processing a large list of positions\202. )0 P(For example, the default cone search uses columns "RA" and "Dec" in hours and degrees \201respectively\202 and RA position in hours, Dec and radius in degrees: ) 1 42 PR( funone in.fits out.fits 23.45 34.56 0.01)RP( To specify the RA position in degrees: ) 1 44 PR( funcone in.fits out.fits 23.45d 34.56 0.01)RP( To get RA and Dec from a list but use a static value for radius \201and also write identifying info for each row in the list\202: ) 1 57 PR( funcone -x -l list.txt in.fits out.fits MYRA MYDec 0.01)RP( User specified columns in degrees, RA position in hours \201sexagesimal notation\202, Dec position in degrees \201sexagesimal notation\202 and radius in arc minutes: ) 1 66 PR( funcone -r myRa:d -d myDec in.fits out.fits 12:30:15.5 30:12 15')RP( )0 2 10 H(fundisp)WB 73 Sn()WB 7 Sn( - display data in a Funtools data file)EA()EH( )BD() 1 62 PR(fundisp [-f format] [-l] [-n] [-T] [columns|bitpix=n])RP()ES( )0 P() 5 68 PR( -f # format string for display -l # display image as a list containing the columns X, Y, VAL -n # don't output header -F [c] # use specified character as column separator \201def: space\202 -T # output in rdb/starbase format \201tab separators\202)RP( )0 P()BD(fundisp)ES( displays the data in the specified )0 42 1 A(FITS Extension)42 0 TN TL()Ec /AF f D( and/or )0 49 1 A(Image Section)49 0 TN TL()Ec /AF f D( of a FITS file, or in a )0 49 1 A(Section)49 0 TN TL()Ec /AF f D( of a non-FITS array or raw event file. )0 P(The first argument to the program specifies the FITS input image, array, or raw event file to display. If "stdin" is specified, data are read from the standard input. Use )0 42 1 A(Funtools Bracket Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions, image sections, and filters. )0 P(If the data being displayed are columns \201either in a FITS binary table or a raw event file\202, the individual rows are listed. Filters can be added using bracket notation. Thus: ) 13 75 PR( [sh] fundisp "test.ev[time-\201int\202time>.15]" X Y PHA PI TIME DX DY ------- ------- ------- --------- ---------------- ---------- ---------- 10 8 10 8 17.1600 8.50 10.50 9 9 9 9 17.1600 9.50 9.50 10 9 10 9 18.1600 9.50 10.50 10 9 10 9 18.1700 9.50 10.50 8 10 8 10 17.1600 10.50 8.50 9 10 9 10 18.1600 10.50 9.50 9 10 9 10 18.1700 10.50 9.50 10 10 10 10 19.1600 10.50 10.50 10 10 10 10 19.1700 10.50 10.50 10 10 10 10 19.1800 10.50 10.50)RP( [NB: The FITS binary table test file test.ev, as well as the FITS image test.fits, are contained in the funtools funtest directory.] )0 P(When a table is being displayed using )BD(fundisp)ES(, a second optional argument can be used to specify the columns to display. For example: ) 12 56 PR( [sh] fundisp "test.ev[time-\201int\202time>=.99]" "x y time" X Y TIME -------- -------- --------------------- 5 -6 40.99000000 4 -5 59.99000000 -1 0 154.99000000 -2 1 168.99000000 -3 2 183.99000000 -4 3 199.99000000 -5 4 216.99000000 -6 5 234.99000000 -7 6 253.99000000)RP( )0 P(The special column )BD($REGION)ES( can be specified to display the region id of each row: ) 12 89 PR( [sh $] fundisp "test.ev[time-\201int\202time>=.99&&annulus\2010 0 0 10 n=3\202]" 'x y time $REGION' X Y TIME REGION -------- -------- --------------------- ---------- 5 -6 40.99000000 3 4 -5 59.99000000 2 -1 0 154.99000000 1 -2 1 168.99000000 1 -3 2 183.99000000 2 -4 3 199.99000000 2 -5 4 216.99000000 2 -6 5 234.99000000 3 -7 6 253.99000000 3)RP( )0 P(Here only rows with the proper fractional time and whose position also is within one of the three annuli are displayed. )0 P(Columns can be excluded from display using a minus sign before the column: ) 12 64 PR( [sh $] fundisp "test.ev[time-\201int\202time>=.99]" "-time" X Y PHA PI DX DY -------- -------- -------- ---------- ----------- ----------- 5 -6 5 -6 5.50 -6.50 4 -5 4 -5 4.50 -5.50 -1 0 -1 0 -1.50 0.50 -2 1 -2 1 -2.50 1.50 -3 2 -3 2 -3.50 2.50 -4 3 -4 3 -4.50 3.50 -5 4 -5 4 -5.50 4.50 -6 5 -6 5 -6.50 5.50 -7 6 -7 6 -7.50 6.50)RP( All columns except the time column are displayed. )0 P(The special column )BD($N)ES( can be specified to display the ordinal value of each row. Thus, continuing the previous example: ) 12 74 PR( fundisp "test.ev[time-\201int\202time>=.99]" '-time $n' X Y PHA PI DX DY N ------- -------- -------- ---------- ----------- ----------- ---------- 5 -6 5 -6 5.50 -6.50 337 4 -5 4 -5 4.50 -5.50 356 -1 0 -1 0 -1.50 0.50 451 -2 1 -2 1 -2.50 1.50 465 -3 2 -3 2 -3.50 2.50 480 -4 3 -4 3 -4.50 3.50 496 -5 4 -5 4 -5.50 4.50 513 -6 5 -6 5 -6.50 5.50 531 -7 6 -7 6 -7.50 6.50 550)RP( Note that the column specification is enclosed in single quotes to protect '$n' from begin expanded by the shell. )0 P(In general, the rules for activating and de-activating columns are: )UL()-1 LI( If only exclude columns are specified, then all columns but the exclude columns will be activated. )-1 LI( If only include columns are specified, then only the specified columns are activated. )-1 LI( If a mixture of include and exclude columns are specified, then all but the exclude columns will be active; this last case is ambiguous and the rule is arbitrary.)LU( In addition to specifying columns names explicitly, the special symbols )BD(+)ES( and )BD(-)ES( can be used to activate and de-activate )BD(all)ES( columns. This is useful if you want to activate the $REGION column along with all other columns. According to the rules, the syntax "$REGION" only activates the region column and de-activates the rest. Use "+ $REGION" to activate all columns as well as the region column. )0 P(If the data being displayed are image data \201either in a FITS primary image, a FITS image extension, or an array file\202, an mxn pixel display is produced, where m and n are the dimensions of the image. By default, pixel values are displayed using the same data type as in the file. However, for integer data where the BSCALE and BZERO header parameters are present, the data is displayed as floats. In either case, the display data type can be overridden using an optional second argument of the form: ) 1 10 PR( bitpix=n)RP( where n is 8,16,32,-32,-64, for unsigned char, short, int, float and double, respectively. )0 P(Of course, running )BD(fundisp)ES( on anything but the smallest image usually results in a display whose size makes it unreadable. Therefore, one can uses bracket notation \201see below\202 to apply section and/or blocking to the image before generating a display. For example: ) 9 66 PR( [sh] fundisp "test.fits[2:6,2:7]" bitpix=-32 2 3 4 5 6 ---------- ---------- ---------- ---------- ---------- 2: 3.00 4.00 5.00 6.00 7.00 3: 4.00 5.00 6.00 7.00 8.00 4: 5.00 6.00 7.00 8.00 9.00 5: 6.00 7.00 8.00 9.00 10.00 6: 7.00 8.00 9.00 10.00 11.00 7: 8.00 9.00 10.00 11.00 12.00)RP( )0 P(Note that is is possible to display a FITS binary table as an image simply by passing the table through )BD(funimage)ES( first: ) 9 68 PR( [sh] ./funimage test.ev stdout | fundisp "stdin[2:6,2:7]" bitpix=8 2 3 4 5 6 ------- ------- ------- ------- ------- 2: 3 4 5 6 7 3: 4 5 6 7 8 4: 5 6 7 8 9 5: 6 7 8 9 10 6: 7 8 9 10 11 7: 8 9 10 11 12)RP( If the )BD(-l)ES( \201list\202 switch is used, then an image is displayed as a list containing the columns: X, Y, VAL. For example: ) 33 45 PR( fundisp -l "test1.fits[2:6,2:7]" bitpix=-32 X Y VAL ---------- ---------- ----------- 2 2 6.00 3 2 1.00 4 2 1.00 5 2 1.00 6 2 1.00 2 3 1.00 3 3 5.00 4 3 1.00 5 3 1.00 6 3 1.00 2 4 1.00 3 4 1.00 4 4 4.00 5 4 1.00 6 4 1.00 2 5 1.00 3 5 1.00 4 5 1.00 5 5 3.00 6 5 1.00 2 6 1.00 3 6 1.00 4 6 1.00 5 6 1.00 6 6 2.00 2 7 1.00 3 7 1.00 4 7 1.00)WR( 5 7 1.00 6 7 1.00)RP( )0 P(If the )BD(-n)ES( \201nohead\202 switch is used, then no header is output for tables. This is useful, for example, when fundisp output is being directed into gnuplot. )0 P(The )BD(fundisp)ES( program uses a default set of display formats: ) 10 33 PR( datatype TFORM format -------- ----- -------- double D "%21.8f" float E "%11.2f" int J "%10d" short I "%8d" byte B "%6d" string A "%12.12s" bits X "%8x" logical L "%1x")RP( Thus, the default display of 1 double and 2 shorts gives: ) 7 42 PR( [sh] fundisp snr.ev "time x y" TIME X Y --------------------- -------- -------- 79494546.56818075 546 201 79488769.94469175 548 201 ...)RP( You can change the display format for individual columns or for all columns of a given data types by means of the -f switch. The format string that accompanies -f is a space-delimited list of keyword=format values. The keyword values can either be column names \201in which case the associated format pertains only to that column\202 or FITS table TFORM specifiers \201in which case the format pertains to all columns having that data type\202. For example, you can change the double and short formats for all columns like this: ) 7 53 PR( [sh] fundisp -f "D=%22.11f I=%3d" snr.ev "time x y" TIME X Y ---------------------- --- --- 79494546.56818075478 546 201 79488769.94469174743 548 201 ...)RP( )0 P(Alternatively, you can change the format of the time and x columns like this: ) 7 56 PR( [sh] fundisp -f "time=%22.11f x=%3d" snr.ev "time x y" TIME X Y ---------------------- --- -------- 79494546.56818075478 546 201 79488769.94469174743 548 201 ...)RP( Note that there is a potential conflict if a column has the same name as one of the TFORM specifiers. In the examples above, the the "X" column in the table has the same name as the X \201bit\202 datatype. To resolve this conflict, the format string is processed such that TFORM datatype specifiers are checked for first, using a case-sensitive comparison. If the specified format value is not an upper case TFORM value, then a case-insensitive check is made on the column name. This means that, in the examples above, "X=%3d" will refer to the X \201bit\202 datatype, while "x=%3d" will refer to the X column: ) 15 38 PR( [sh] fundisp -f "X=%3d" snr.ev "x y" X Y -------- -------- 546 201 548 201 ... [sh] fundisp -f "x=%3d" snr.ev "x y" X Y --- -------- 546 201 548 201 ...)RP( As a rule, therefore, it is best always to specify the column name in lower case and TFORM data types in upper case. )0 P(The )BD(-f [format])ES( will change the format for a single execution of fundisp. You also can use the )BD(FUN_FORMAT)ES( envronment variable to change the format for all invocations of fundisp. The format of this environment variable's value is identical to that used with the )BD(-f)ES( switch. This global value can be overridden in individual cases by use of the )BD(-f [format])ES( switch. )0 P(Caveats: Please also note that it is the user's responsibility to match the format specifier to the column data type correctly. Also note that, in order to maintain visual alignment between names and columns, the column name will be truncated \201on the left\202 if the format width is less than the length of the name. However, truncation is not performed if the output is in RDB format \201using the -T switch\202. )0 P([An older-style format string is supported but deprecated. It consists of space-delimited C format statements for all data types, specified in the following order: ) 1 40 PR( double float int short byte string bit.)RP( This order of the list is based on the assumption that people generally will want to change the float formats. )0 P(If "-" is entered instead of a format statement for a given data type, the default format is used. Also, the format string can be terminated without specifying all formats, and defaults will be used for the rest of the list. Note that you must supply a minimum field width, i.e., "%6d" and "%-6d" are legal, "%d" is not legal. By using -f [format], you can change the double and short formats like this: ) 7 51 PR( [sh] fundisp -f "22.11f - - 3d" snr.ev "time x y" TIME X Y ---------------------- --- --- 79494546.56818075478 546 201 79488769.94469174743 548 201 ...)RP( NB: This format is deprecated and will be removed in a future release.] )0 P(The )BD(-F[c])ES( switch can be used to specify a \201single-character\202 column separator \201where the default is a space\202. Note that column formatting will almost certainly also add spaces to pad individual columns to the required width. These can be removed with a program such as sed, at the cost of generating unaligned columns. For example: ) 26 117 PR(fundisp -F',' snr.ev'[cir 512 512 .1]' X, Y, PHA, PI, TIME, DX, DY --------,--------,--------,--------,---------------------,--------,-------- 512, 512, 6, 7, 79493997.45854475, 578, 574 512, 512, 8, 9, 79494575.58943175, 579, 573 512, 512, 5, 6, 79493631.03866175, 578, 575 512, 512, 5, 5, 79493290.86521725, 578, 575 512, 512, 8, 9, 79493432.00990875, 579, 573 fundisp -F',' snr.ev'[cir 512 512 .1]' | sed 's/ *, */,/g' X,Y,PHA,PI,TIME,DX,DY --------,--------,--------,--------,---------------------,--------,-------- 512,512,6,7,79493997.45854475,578,574 512,512,8,9,79494575.58943175,579,573 512,512,5,6,79493631.03866175,578,575 512,512,5,5,79493290.86521725,578,575 512,512,8,9,79493432.00990875,579,573 fundisp -f "x=%3d y=%3d pi=%1d pha=%1d time=%20.11f dx=%3d dy=%3d" -F',' snr.ev'[cir 512 512 .1]' | sed 's/ *, */,/g' X,Y,A,I,TIME,DX,DY ---,---,-,-,--------------------,---,--- 512,512,6,7,79493997.45854474604,578,574 512,512,8,9,79494575.58943174779,579,573 512,512,5,6,79493631.03866174817,578,575 512,512,5,5,79493290.86521725357,578,575 512,512,8,9,79493432.00990875065,579,573)RP( )0 P(If the )BD(-T)ES( \201rdb table\202 switch is used, the output will conform to starbase/rdb data base format: tabs will be inserted between columns rather than spaces. This format is not available when displaying image pixels \201except in conjunction with the )BD(-l)ES( switch\202. )0 P(Finally, note that )BD(fundisp)ES( can be used to create column filters from the auxiliary tables in a FITS file. For example, the following shell code will generate a good-time interval \201GTI\202 filter for X-ray data files that contain a standard GTI extension: ) 3 68 PR( #!/bin/sh sed '1,/---- .*/d /^$/,$d' | awk 'tot>0{printf "||"};{printf "time="$1":"$2; tot++}')RP( If this script is placed in a file called "mkgti", it can be used in a command such as: ) 1 46 PR( fundisp foo.fits"[GTI]" | mkgti > gti.filter)RP( The resulting filter file can then be used in various funtools programs: ) 1 37 PR( funcnts foo.fits"[@gti.filter]" ...)RP( to process only the events in the good-time intervals. )0 2 11 H(funhead)WB 74 Sn()WB 8 Sn( - display a header in a Funtools file)EA()EH( )BD() 1 50 PR(funhead [-a] [-s] [-t] [-L] [oname ename])RP()ES( )0 P() 4 60 PR( -a # display all extension headers -s # display 79 chars instead of 80 before the new-line -t # prepend data type char to each line of output -L # output in rdb/starbase list format)RP( )0 P()BD(funhead)ES( displays the FITS header parameters in the specified )0 42 1 A(FITS Extension)42 0 TN TL()Ec /AF f D(. )0 P(The first argument to the program specifies the Funtools input file to display. If "stdin" is specified, data are read from the standard input. )0 42 1 A(Funtools Bracket Notation)42 0 TN TL()Ec /AF f D( is used to specify particular FITS extension to process. Normally, the full 80 characters of each header card is output, followed by a new-line. )0 P(If the )BD(-a)ES( switch is specified, the header from each FITS extensions in the file is displayed. Note, however, that the )BD(-a)ES( switch does not work with FITS files input via stdin. We hope to remove this restriction in a future release. )0 P(If the )BD(-s)ES( switch is specified, only 79 characters are output before the new-line. This helps the display on 80 character terminals. )0 P(If the )BD(-t)ES( switch is specified, the data type of the parameter is output as a one character prefix, followed by 77 characters of the param. The parameter data types are defined as: FUN_PAR_UNKNOWN \201'u'\202, FUN_PAR_COMMENT \201'c'\202, FUN_PAR_LOGICAL \201'l'\202, FUN_PAR_INTEGER \201'i'\202, FUN_PAR_STRING \201's'\202, FUN_PAR_REAL \201'r'\202, FUN_PAR_COMPLEX \201'x'\202. )0 P(If the )BD(-L)ES( \201rdb table\202 switch is used, the output will conform to starbase/rdb data base list format. )0 P(For example to display the EVENTS extension \201binary table\202: ) 17 65 PR( [sh] funhead "foo.fits[EVENTS]" XTENSION= 'BINTABLE' / FITS 3D BINARY TABLE BITPIX = 8 / Binary data NAXIS = 2 / Table is a matrix NAXIS1 = 20 / Width of table in bytes NAXIS2 = 30760 / Number of entries in table PCOUNT = 0 / Random parameter count GCOUNT = 1 / Group count TFIELDS = 7 / Number of fields in each row EXTNAME = 'EVENTS ' / Table name EXTVER = 1 / Version number of table TFORM1 = '1I ' / Data type for field TTYPE1 = 'X ' / Label for field TUNIT1 = ' ' / Physical units for field TFORM2 = '1I ' / Data type for field etc. ... END)RP( )0 P(To display the third header: ) 14 65 PR( [sh] funhead "foo.fits[3]" XTENSION= 'BINTABLE' / FITS 3D BINARY TABLE BITPIX = 8 / Binary data NAXIS = 2 / Table is a matrix NAXIS1 = 32 / Width of table in bytes NAXIS2 = 40 / Number of entries in table PCOUNT = 0 / Random parameter count GCOUNT = 1 / Group count TFIELDS = 7 / Number of fields in each row EXTNAME = 'TGR ' / Table name EXTVER = 1 / Version number of table TFORM1 = '1D ' / Data type for field etc. ... END)RP( )0 P(To display the primary header \201i.e., extension 0\202: ) 8 59 PR( sh> funhead "coma.fits[0]" SIMPLE = T /STANDARD FITS FORMAT BITPIX = 16 /2-BYTE TWOS-COMPL INTEGER NAXIS = 2 /NUMBER OF AXES NAXIS1 = 800 / NAXIS2 = 800 / DATATYPE= 'INTEGER*2' /SHORT INTEGER END)RP( )0 P(The funhead program also can edit \201i.e. add, delete, or modify\202 or display individual headers parameters. Edit mode is signalled by the presence of two additional command-line arguments: output file and edit command file, in that order. Edit mode acts as a filter: the output file will contain the entire input FITS file, including other extensions. The edit command file can be "stdin", in which case edit command are read from the standard input. )0 P(The edit command file contains parameter comments \201having '#' in the first column\202 and delete and assignment\201modify or add\202 operations. A delete operation is specified by preceding the parameter name with a minus sign "-". A display operation \201very useful in interactive sessions, i.e., where the edit commands are taken from stdin\202 is specified by preceding the parameter name with a question mark "?". In either case, a parameter value need not be specified. An assignment operation is specified in the same two ways that a parameter is specified in a text header \201but without the comment character that precedes header params\202, i.e.: )UL()-1 LI( FITS-style comments have an equal sign "=" between the keyword and value and an optional slash "/" to signify a comment. The strict FITS rules on column positions are not enforced. )-1 LI( Free-form comments can have an optional colon separator between the keyword and value. In the absence of quote, all tokens after the keyword are part of the value, i.e. no comment is allowed.)LU( )0 P(For example, the following interactive session checks for the existence of parameters, adds new parameters, modifies them, and modifies and deletes existing parameters: ) 20 55 PR( sh$ ./funhead snr.ev foo.fits - # look for FOO1 ? FOO1 WARNING: FOO1 not found # add new foo1 FOO1 = 100 # add foo2 FOO2 = 200 # reset foo1 to a different value FOO1 -1 # delete foo2 -FOO2 # change existing value EXTVER 2 ? XS-SORT XS-SORT = 'EOF ' / type of event sort # delete existing value -XS-SORT # exit ^D)RP( )0 P(See )0 47 1 A(Column-based Text Files)47 0 TN TL()Ec /AF f D( for more information about header parameter format. )0 P( )0 P( )0 2 12 H(funhist)WB 75 Sn()WB 9 Sn( - create a 1D histogram of a column \201from a FITS binary table or raw event file\202 or an image)EA()EH( )BD() 1 51 PR(funhist [-n|-w|-T] [column] [[lo:hi:]bins])RP()ES( )0 P() 3 61 PR( -n # normalize bin value by the width of each bin -w # specify bin width instead of number of bins in arg3 -T # output in rdb/starbase format \201tab separators\202)RP( )0 P()BD(funhist)ES( creates a one-dimensional histogram from the specified columns of a )0 42 1 A(FITS Extension)42 0 TN TL()Ec /AF f D( binary table of a FITS file \201or from a non-FITS raw event file\202, or from a FITS image or array, and writes that histogram as an ASCII table. Alternatively, the program can perform a 1D projection of one of the image axes. )0 P(The first argument to the program is required, and specifies the Funtools file: FITS table or image, raw event file, or array. If "stdin" is specified, data are read from the standard input. Use )0 42 1 A(Funtools Bracket Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions, and filters. )0 P(For a table, the second argument also is required. It specifies the column to use in generating the histogram. If the data file is of type image \201or array\202, the column is optional: if "x" \201or "X"\202, "y" \201or "Y"\202 is specified, then a projection is performed over the x \201dim1\202 or y \201dim2\202 axes, respectively. \201That is, this projection will give the same results as a histogram performed on a table containing the equivalent x,y event rows.\202 If no column name is specified or "xy" \201or "XY"\202 is specified for the image, then a histogram is performed on the values contained in the image pixels. )0 P(The argument that follows is optional and specifies the number of bins to use in creating the histogram and, if desired, the range of bin values. For image and table histograms, the range should specify the min and max data values. For image histograms on the x and y axes, the range should specify the min and max image bin values. If this argument is omitted, the number of output bins for a table is calculated either from the TLMIN/TLMAX headers values \201if these exist in the table FITS header for the specified column\202 or by going through the data to calculate the min and max value. For an image, the number of output bins is calculated either from the DATAMIN/DATAMAX header values, or by going through the data to calculate min and max value. \201Note that this latter calculation might fail if the image cannot be fit in memory.\202 If the data are floating point \201table or image\202 and the number of bins is not specified, an arbitrary default of 128 is used. )0 P(For binary table processing, the )BD(-w)ES( \201bin width\202 switch can be used to specify the width of each bin rather than the number of bins. Thus: ) 1 29 PR( funhist test.ev pha 1:100:5)RP( means that 5 bins of width 20 are used in the histogram, while: ) 1 32 PR( funhist -w test.ev pha 1:100:5)RP( means that 20 bins of width 5 are used in the histogram. )0 P(The data are divvied up into the specified number of bins and the resulting 1D histogram \201or projection\202 is output in ASCII table format. For a table, the output displays the low_edge \201inclusive\202 and hi_edge \201exclusive\202 values for the data. For example, a 15-row table containing a "pha" column whose values range from -7.5 to 7.5 can be processed thus: ) 47 62 PR( [sh] funhist test.ev pha # data file: /home/eric/data/test.ev # column: pha # min,max,bins: -7.5 7.5 15 bin value lo_edge hi_edge ------ --------- --------------------- --------------------- 1 22 -7.50000000 -6.50000000 2 21 -6.50000000 -5.50000000 3 20 -5.50000000 -4.50000000 4 19 -4.50000000 -3.50000000 5 18 -3.50000000 -2.50000000 6 17 -2.50000000 -1.50000000 7 16 -1.50000000 -0.50000000 8 30 -0.50000000 0.50000000 9 16 0.50000000 1.50000000 10 17 1.50000000 2.50000000 11 18 2.50000000 3.50000000 12 19 3.50000000 4.50000000 13 20 4.50000000 5.50000000 14 21 5.50000000 6.50000000 15 22 6.50000000 7.50000000 [sh] funhist test.ev pha 1:6 # data file: /home/eric/data/test.ev # column: pha # min,max,bins: 0.5 6.5 6 bin value lo_edge hi_edge ------ --------- --------------------- --------------------- 1 16 0.50000000 1.50000000)WR( 2 17 1.50000000 2.50000000 3 18 2.50000000 3.50000000 4 19 3.50000000 4.50000000 5 20 4.50000000 5.50000000 6 21 5.50000000 6.50000000 [sh] funhist test.ev pha 1:6:3 # data file: /home/eric/data/test.ev # column: pha # min,max,bins: 0.5 6.5 3 bin value lo_edge hi_edge ------ --------- --------------------- --------------------- 1 33 0.50000000 2.50000000 2 37 2.50000000 4.50000000 3 41 4.50000000 6.50000000)RP( )0 P(For a table histogram, the )BD(-n)ES(\201normalize\202 switch can be used to normalize the bin value by the width of the bin \201i.e., hi_edge-lo_edge\202: ) 11 74 PR( [sh] funhist -n test.ev pha 1:6:3 # data file: test.ev # column: pha # min,max,bins: 0.5 6.5 3 # width normalization \201val/\201hi_edge-lo_edge\202\202 is applied bin value lo_edge hi_edge ------ --------------------- --------------------- --------------------- 1 16.50000000 0.50000000 2.50000000 2 6.16666667 2.50000000 4.50000000 3 4.10000000 4.50000000 6.50000000)RP( This could used, for example, to produce a light curve with values having units of counts/second instead of counts. )0 P(For an image histogram, the output displays the low and high image values \201both inclusive\202 used to generate the histogram. For example, in the following example, 184 pixels had a value of 1, 31 had a value of 2, while only 2 had a value of 3,4,5,6, or 7: ) 13 74 PR( [sh] funhist test.fits # data file: /home/eric/data/test.fits # min,max,bins: 1 7 7 bin value lo_val hi_val ------ --------------------- --------------------- --------------------- 1 184.00000000 1.00000000 1.00000000 2 31.00000000 2.00000000 2.00000000 3 2.00000000 3.00000000 3.00000000 4 2.00000000 4.00000000 4.00000000 5 2.00000000 5.00000000 5.00000000 6 2.00000000 6.00000000 6.00000000 7 2.00000000 7.00000000 7.00000000)RP( )0 P(For the axis projection of an image, the output displays the low and high image bins \201both inclusive\202 used to generate the projection. For example, in the following example, 21 counts had their X bin value of 2, etc.: ) 23 74 PR( [sh] funhist test.fits x 2:7 # data file: /home/eric/data/test.fits # column: X # min,max,bins: 2 7 6 bin value lo_bin hi_bin ------ --------------------- --------------------- --------------------- 1 21.00000000 2.00000000 2.00000000 2 20.00000000 3.00000000 3.00000000 3 19.00000000 4.00000000 4.00000000 4 18.00000000 5.00000000 5.00000000 5 17.00000000 6.00000000 6.00000000 6 16.00000000 7.00000000 7.00000000 [sh] funhist test.fits x 2:7:2 # data file: /home/eric/data/test.fits # column: X # min,max,bins: 2 7 2 bin value lo_bin hi_bin ------ --------------------- --------------------- --------------------- 1 60.00000000 2.00000000 4.00000000 2 51.00000000 5.00000000 7.00000000)RP( )0 P(You can use gnuplot or other plotting programs to graph the results, using a script such as: ) 7 119 PR( #!/bin/sh sed -e '1,/---- .*/d /^$/,$d' | \200 awk '\200 BEGIN{print "set nokey; set title \200"funhist\200"; set xlabel \200"bin\200"; set ylabel \200"counts\200"; plot \200"-\200" with boxes"} \200 {print $3, $2, $4-$3}' | \200 gnuplot -persist - 1>/dev/null 2>&1)RP( Similar plot commands are supplied in the script )BD(funhist.plot)ES(: ) 1 49 PR( funhist test.ev pha ... | funhist.plot gnuplot)RP( )0 2 13 H(funimage)WB 76 Sn()WB 10 Sn( - create a FITS image from a Funtools data file)EA()EH( )BD() 3 73 PR(funimage [-a] [bitpix=n] funimage [-l] [bitpix=n] funimage [-p x|y] [bitpix=n])RP()ES( )0 P() 3 65 PR( -a # append to existing output file as an image extension -l # input is a list file containing xcol, ycol, value -p [x|y] # project along x or y axis to create a 1D image)RP( )0 P()BD(funimage)ES( creates a primary FITS image from the specified )0 42 1 A(FITS Extension)42 0 TN TL()Ec /AF f D( and/or )0 49 1 A(Image Section)49 0 TN TL()Ec /AF f D( of a FITS file, or from an )0 49 1 A(Image Section)49 0 TN TL()Ec /AF f D( of a non-FITS array, or from a raw event file. )0 P(The first argument to the program specifies the FITS input image, array, or raw event file to process. If "stdin" is specified, data are read from the standard input. Use )0 42 1 A(Funtools Bracket Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions, image sections, and filters. The second argument is the output FITS file. If "stdout" is specified, the FITS image is written to the standard output. By default, the output pixel values are of the same data type as those of the input file \201or type "int" when binning a table\202, but this can be overridden using an optional third argument of the form: ) 1 10 PR( bitpix=n)RP( where n is 8,16,32,-32,-64, for unsigned char, short, int, float and double, respectively. )0 P(If the input data are of type image, the appropriate section is extracted and blocked \201based on how the )0 49 1 A(Image Section)49 0 TN TL()Ec /AF f D( is specified\202, and the result is written to the FITS primary image. When an integer image containing the BSCALE and BZERO keywords is converted to float, the pixel values are scaled and the scaling keywords are deleted from the output header. When converting integer scaled data to integer \201possibly of a different size\202, the pixels are not scaled and the scaling keywords are retained. )0 P(If the input data is a binary table or raw event file, these are binned into an image, from which a section is extracted and blocked, and written to a primary FITS image. In this case, it is necessary to specify the two columns that will be used in the 2D binning. This can be done on the command line using the )BD(bincols=\201x,y\202)ES( keyword: ) 1 46 PR( funcnts "foo.ev[EVENTS,bincols=\201detx,dety\202]")RP( The full form of the )BD(bincols=)ES( specifier is: ) 1 77 PR( bincols=\201[xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]]]\202)RP( where the tlmin, tlmax, and binsiz specifiers determine the image binning dimensions: ) 2 56 PR( dim = \201tlmax - tlmin\202/binsiz \201floating point data\202 dim = \201tlmax - tlmin\202/binsiz + 1 \201integer data\202)RP( Using this syntax, it is possible to bin any two columns of a binary table at any bin size. Note that the tlmin, tlmax, and binsiz specifiers can be omitted if TLMIN, TLMAX, and TDBIN header parameters \201respectively\202 are present in the FITS binary table header for the column in question. Note also that if only one parameter is specified, it is assumed to be tlmax, and tlmin defaults to 1. If two parameters are specified, they are assumed to be tlmin and tlmax. See )0 50 1 A(Binning FITS Binary Tables and Non-FITS Event Files)50 0 TN TL()Ec /AF f D( for more information about binning parameters. )0 P(By default, a new 2D FITS image file is created and the image is written to the primary HDU. If the )BD(-a)ES( \201append\202 switch is specified, the image is appended to an existing FITS file as an IMAGE extension. \201If the output file does not exist, the switch is effectively ignored and the image is written to the primary HDU.\202 This can be useful in a shell programming environment when processing multiple FITS images that you want to combine into a single final FITS file. )0 P()BD(funimage)ES( also can take input from a table containing columns of x, y, and value \201e.g., the output from )BD(fundisp -l)ES( which displays each image x and y and the number of counts at that position.\202 When the )BD(-l)ES( \201list\202 switch is used, the input file is taken to be a FITS or ASCII table containing \201at least\202 three columns that specify the x and y image coordinates and the value of that image pixel. In this case, )BD(funimage)ES( requires four extra arguments: xcolumn:xdims, ycolumn:ydims, vcolumn and bitpix=n. The x and y col:dim information takes the form: ) 3 55 PR( name:dim # values range from 1 to dim name:min:max # values range from min to max name:min:max:binsiz # dimensions scaled by binsize)RP( In particular, the min value should be used whenever the minimum coordinate value is something other than one. For example: ) 2 69 PR( funimage -l foo.lst foo.fits xcol:0:512 ycol:0:512 value bitpix=-32)RP( )0 P(The list feature also can be used to read unnamed columns from standard input: simply replace the column name with a null string. Note that the dimension information is still required: ) 5 60 PR( funimage -l stdin foo.fits "":0:512 "":0:512 "" bitpix=-32 240 250 1 255 256 2 ... ^D)RP( )0 P(The list feature provides a simple way to generate a blank image. If you pass a )0 47 1 A(Column-based Text File)47 0 TN TL()Ec /AF f D( to funimage in which the text header contains the required image information, then funimage will correctly make a blank image. For example, consider the following text file \201called foo.txt\202: ) 3 20 PR( x:I:1:10 y:I:1:10 ------ ------ 0 0)RP( This text file defines two columns, x and y, each of data type 32-bit int and image dimension 10. The command: ) 1 36 PR( funimage foo.txt foo.fits bitpix=8)RP( will create an empty FITS image called foo.fits containing a 10x10 image of unsigned char: ) 13 75 PR( fundisp foo.fits 1 2 3 4 5 6 7 8 9 10 ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ 10: 0 0 0 0 0 0 0 0 0 0 9: 0 0 0 0 0 0 0 0 0 0 8: 0 0 0 0 0 0 0 0 0 0 7: 0 0 0 0 0 0 0 0 0 0 6: 0 0 0 0 0 0 0 0 0 0 5: 0 0 0 0 0 0 0 0 0 0 4: 0 0 0 0 0 0 0 0 0 0 3: 0 0 0 0 0 0 0 0 0 0 2: 0 0 0 0 0 0 0 0 0 0 1: 1 0 0 0 0 0 0 0 0 0)RP( Note that the text file must contain at least one row of data. However, in the present example, event position 0,0 is outside the limits of the image and will be ignored. \201You can, of course, use real x,y values to seed the image with data.\202 )0 P(Furthermore, you can use the TEXT filter specification to obviate the need for an input text file altogether. The following command will create the same 10x10 char image without an actual input file: ) 3 69 PR( funimage stdin'[TEXT\201x:I:10,y:I:10\202]' foo.fits bitpix=8 < /dev/null or funimage /dev/null'[TEXT\201x:I:10,y:I:10\202]' foo.fits bitpix=8)RP( )0 P(You also can use either of these methods to generate a region mask simply by appending a region inside the filter brackets and specfying )BD(mask=all)ES( along with the bitpix. For example, the following command will generate a 10x10 char mask using 3 regions: ) 2 76 PR( funimage stdin'[TEXT\201x:I:10,y:I:10\202,cir\2015,5,4\202,point\20110,1\202,-cir\2015,5,2\202]' \200 foo.fits bitpix=8,mask=all < /dev/null)RP( The resulting mask looks like this: ) 13 75 PR( fundisp foo.fits 1 2 3 4 5 6 7 8 9 10 ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ 10: 0 0 0 0 0 0 0 0 0 0 9: 0 0 0 0 0 0 0 0 0 0 8: 0 0 1 1 1 1 1 0 0 0 7: 0 1 1 1 1 1 1 1 0 0 6: 0 1 1 0 0 0 1 1 0 0 5: 0 1 1 0 0 0 1 1 0 0 4: 0 1 1 0 0 0 1 1 0 0 3: 0 1 1 1 1 1 1 1 0 0 2: 0 0 1 1 1 1 1 0 0 0 1: 0 0 0 0 0 0 0 0 0 2)RP( )0 P(You can use )BD(funimage)ES( to create 1D image projections along the x or y axis using the )BD(-p [x|y])ES( switch. This capability works for both images and tables. For example consider a FITS table named ev.fits containing the following rows: ) 17 19 PR( X Y -------- -------- 1 1 1 2 1 3 1 4 1 5 2 2 2 3 2 4 2 5 3 3 3 4 3 5 4 4 4 5 5 5)RP( A corresponding 5x5 image, called dim2.fits, would therefore contain: ) 7 59 PR( 1 2 3 4 5 ---------- ---------- ---------- ---------- ---------- 5: 1 1 1 1 1 4: 1 1 1 1 0 3: 1 1 1 0 0 2: 1 1 0 0 0 1: 1 0 0 0 0)RP( A projection along the y axis can be performed on either the table or the image: ) 9 59 PR( funimage -p y ev.fits stdout | fundisp stdin 1 2 3 4 5 ---------- ---------- ---------- ---------- ---------- 1: 1 2 3 4 5 funimage -p y dim2.fits stdout | fundisp stdin 1 2 3 4 5 ---------- ---------- ---------- ---------- ---------- 1: 1 2 3 4 5)RP( )0 P(Furthermore, you can create a 1D image projection along any column of a table by using the )BD(bincols=[column])ES( filter specification and specifying a single column. For example, the following command projects the same 1D image along the y axis of a table as use of the )BD(-p y)ES( switch: ) 4 59 PR( funimage ev.fits'[bincols=y]' stdout | fundisp stdin 1 2 3 4 5 ---------- ---------- ---------- ---------- ---------- 1: 1 2 3 4 5)RP( )0 P(Examples: )0 P(Create a FITS image from a FITS binary table: ) 1 33 PR( [sh] funimage test.ev test.fits)RP( )0 P(Display the FITS image generated from a blocked section of FITS binary table: ) 5 60 PR( [sh] funimage "test.ev[2:8,3:7,2]" stdout | fundisp stdin 1 2 3 --------- --------- --------- 1: 20 28 36 2: 28 36 44)RP( )0 2 14 H(funindex)WB 77 Sn()WB 11 Sn( - create an index for a column of a FITS binary table)EA()EH( )BD() 1 42 PR(funindex [oname])RP()ES( )0 P() 7 71 PR( NB: these options are not compatible with Funtools processing. Please use the defaults instead. -c # compress output using gzip" -a # ASCII output, ignore -c \201default: FITS table\202" -f # FITS table output \201default: FITS table\202" -l # long output, i.e. with key value\201s\202 \201default: long\202" -s # short output, i.e. no key value\201s\202 \201default: long\202")RP( )0 P(The funindex script creates an index for the specified column \201key\202 by running funtable -s \201sort\202 and then saving the column value and the record number for each sorted row. This index will be used automatically by funtools filtering of that column, provided the index file's modification date is later than that of the data file. )0 P( The first required argument is the name of the FITS binary table to index. Please note that text files cannot be indexed at this time. The second required argument is the column \201key\202 name to index. While multiple keys can be specified in principle, the funtools index processing assume a single key and will not recognize files containing multiple keys. )0 P(By default, the output index file name is [root]_[key].idx, where [root] is the root of the input file. Funtools looks for this specific file name when deciding whether to use an index for faster filtering. Therefore, the optional third argument \201output file name\202 should not be used for funtools processing. )0 P(For example, to create an index on column Y for a given FITS file, use: ) 1 21 PR( funindex foo.fits Y)RP( This will generate an index named foo_y.idx, which will be used by funtools for filters involving the Y column. )0 2 15 H(funjoin)WB 78 Sn()WB 12 Sn( - join two or more FITS binary tables on specified columns)EA()EH( )BD() 1 57 PR(funjoin [switches] ... )RP()ES( )0 P() 11 74 PR( -a cols # columns to activate in all files -a1 cols ... an cols # columns to activate in each file -b 'c1:bvl,c2:bv2' # blank values for common columns in all files -bn 'c1:bv1,c2:bv2' # blank values for columns in specific files -j col # column to join in all files -j1 col ... jn col # column to join in each file -m min # min matches to output a row -M max # max matches to output a row -s # add 'jfiles' status column -S col # add col as status column -t tol # tolerance for joining numeric cols [2 files only])RP( )BD(funjoin)ES( joins rows from two or more \201up to 32\202 )0 42 1 A(FITS Binary Table files)42 0 TN TL()Ec /AF f D(, based on the values of specified join columns in each file. NB: the join columns must have an index file associated with it. These files are generated using the )BD(funindex)ES( program. )0 P(The first argument to the program specifies the first input FITS table or raw event file. If "stdin" is specified, data are read from the standard input. Subsequent arguments specify additional event files and tables to join. The last argument is the output FITS file. )0 P(NB: Do )BD(not)ES( use )0 42 1 A(Funtools Bracket Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions and row filters when running funjoin or you will get wrong results. Rows are accessed and joined using the index files directly, and this bypasses all filtering. )0 P(The join columns are specified using the )BD(-j col)ES( switch \201which specifies a column name to use for all files\202 or with )BD(-j1 col1)ES(, )BD(-j2 col2)ES(, ... )BD(-jn coln)ES( switches \201which specify a column name to use for each file\202. A join column must be specified for each file. If both )BD(-j col)ES( and )BD(-jn coln)ES( are specified for a given file, then the latter is used. Join columns must either be of type string or type numeric; it is illegal to mix numeric and string columns in a given join. For example, to join three files using the same key column for each file, use: ) 1 52 PR( funjoin -j key in1.fits in2.fits in3.fits out.fits)RP( A different key can be specified for the third file in this way: ) 1 65 PR( funjoin -j key -j3 otherkey in1.fits in2.fits in3.fits out.fits)RP( )0 P(The )BD(-a "cols")ES( switch \201and )BD(-a1 "col1")ES(, )BD(-a2 "cols2")ES( counterparts\202 can be used to specify columns to activate \201i.e. write to the output file\202 for each input file. By default, all columns are output. )0 P(If two or more columns from separate files have the same name, the second \201and subsequent\202 columns are renamed to have an underscore and a numeric value appended. )0 P(The )BD(-m min)ES( and )BD(-M max)ES( switches specify the minimum and maximum number of joins required to write out a row. The default minimum is 0 joins \201i.e. all rows are written out\202 and the default maximum is 63 \201the maximum number of possible joins with a limit of 32 input files\202. For example, to write out only those rows in which exactly two files have columns that match \201i.e. one join\202: ) 1 66 PR( funjoin -j key -m 1 -M 1 in1.fits in2.fits in3.fits ... out.fits)RP( )0 P(A given row can have the requisite number of joins without all of the files being joined \201e.g. three files are being joined but only two have a given join key value\202. In this case, all of the columns of the non-joined file are written out, by default, using blanks \201zeros or NULLs\202. The )BD(-b c1:bv1,c2:bv2)ES( and )BD(-b1 'c1:bv1,c2:bv2' -b2 'c1:bv1,c2:bv2' ...)ES( switches can be used to set the blank value for columns common to all files and/or columns in a specified file, respectively. Each blank value string contains a comma-separated list of column:blank_val specifiers. For floating point values \201single or double\202, a case-insensitive string value of "nan" means that the IEEE NaN \201not-a-number\202 should be used. Thus, for example: ) 1 62 PR( funjoin -b "AKEY:???" -b1 "A:-1" -b3 "G:NaN,E:-1,F:-100" ...)RP( means that a non-joined AKEY column in any file will contain the string "???", the non-joined A column of file 1 will contain a value of -1, the non-joined G column of file 3 will contain IEEE NaNs, while the non-joined E and F columns of the same file will contain values -1 and -100, respectively. Of course, where common and specific blank values are specified for the same column, the specific blank value is used. )0 P(To distinguish which files are non-blank components of a given row, the )BD(-s)ES( \201status\202 switch can be used to add a bitmask column named "JFILES" to the output file. In this column, a bit is set for each non-blank file composing the given row, with bit 0 corresponds to the first file, bit 1 to the second file, and so on. The file names themselves are stored in the FITS header as parameters named JFILE1, JFILE2, etc. The )BD(-S col)ES( switch allows you to change the name of the status column from the default "JFILES". )0 P(A join between rows is the Cartesian product of all rows in one file having a given join column value with all rows in a second file having the same value for its join column and so on. Thus, if file1 has 2 rows with join column value 100, file2 has 3 rows with the same value, and file3 has 4 rows, then the join results in 2*3*4=24 rows being output. )0 P(The join algorithm directly processes the index file associated with the join column of each file. The smallest value of all the current columns is selected as a base, and this value is used to join equal-valued columns in the other files. In this way, the index files are traversed exactly once. )0 P(The )BD(-t tol)ES( switch specifies a tolerance value for numeric columns. At present, a tolerance value can join only two files at a time. \201A completely different algorithm is required to join more than two files using a tolerance, somethng we might consider implementing in the future.\202 )0 P(The following example shows many of the features of funjoin. The input files t1.fits, t2.fits, and t3.fits contain the following columns: ) 28 49 PR( [sh] fundisp t1.fits AKEY KEY A B ----------- ------ ------ ------ aaa 0 0 1 bbb 1 3 4 ccc 2 6 7 ddd 3 9 10 eee 4 12 13 fff 5 15 16 ggg 6 18 19 hhh 7 21 22 fundisp t2.fits AKEY KEY C D ----------- ------ ------ ------ iii 8 24 25 ggg 6 18 19 eee 4 12 13 ccc 2 6 7 aaa 0 0 1 fundisp t3.fits AKEY KEY E F G ------------ ------ -------- -------- ----------- ggg 6 18 19 100.10 jjj 9 27 28 200.20 aaa 0 0 1 300.30 ddd 3 9 10 400.40)RP( )0 P(Given these input files, the following funjoin command: ) 3 59 PR( funjoin -s -a1 "-B" -a2 "-D" -a3 "-E" -b \200 "AKEY:???" -b1 "AKEY:XXX,A:255" -b3 "G:NaN,E:-1,F:-100" \200 -j key t1.fits t2.fits t3.fits foo.fits)RP( will join the files on the KEY column, outputting all columns except B \201in t1.fits\202, D \201in t2.fits\202 and E \201in t3.fits\202, and setting blank values for AKEY \201globally, but overridden for t1.fits\202 and A \201in file 1\202 and G, E, and F \201in file 3\202. A JFILES column will be output to flag which files were used in each row: ) 12 105 PR( AKEY KEY A AKEY_2 KEY_2 C AKEY_3 KEY_3 F G JFILES ------------ ------ ------ ------------ ------ ------ ------------ ------ -------- ----------- -------- aaa 0 0 aaa 0 0 aaa 0 1 300.30 7 bbb 1 3 ??? 0 0 ??? 0 -100 nan 1 ccc 2 6 ccc 2 6 ??? 0 -100 nan 3 ddd 3 9 ??? 0 0 ddd 3 10 400.40 5 eee 4 12 eee 4 12 ??? 0 -100 nan 3 fff 5 15 ??? 0 0 ??? 0 -100 nan 1 ggg 6 18 ggg 6 18 ggg 6 19 100.10 7 hhh 7 21 ??? 0 0 ??? 0 -100 nan 1 XXX 0 255 iii 8 24 ??? 0 -100 nan 2 XXX 0 255 ??? 0 0 jjj 9 28 200.20 4)RP( )0 2 16 H(funmerge)WB 79 Sn()WB 13 Sn( - merge one or more Funtools table files)EA()EH( )BD() 1 61 PR(funmerge [-w|-x] -f [colname] ... )RP()ES( )0 P() 3 68 PR( -f # output a column specifying file from which this event came -w # adjust position values using WCS info -x # adjust position values using WCS info and save old values)RP( )0 P()BD(funmerge)ES( merges FITS data from one or more )0 42 1 A(FITS Binary Table files)42 0 TN TL()Ec /AF f D( or raw event files. )0 P(The first argument to the program specifies the first input FITS table or raw event file. If "stdin" is specified, data are read from the standard input. Use )0 42 1 A(Funtools Bracket Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions and row filters. Subsequent arguments specify additional event files and tables to merge. \201NB: Stdin cannot not be used for any of these additional input file arguments.\202 The last argument is the output FITS file. The columns in each input table must be identical. )0 P(If an input file begins with the '@' character, it is processed as an include file, i.e., as a text file containing event file names \201as well as blank lines and/or comment lines starting with the '#' sign\202. If standard input is specified as an include file \201'@stdin'\202, then file names are read from the standard input until EOF \201^D\202. Event files and include files can be mixed on a command line. )0 P(Rows from each table are written sequentially to the output file. If the switch )BD(-f [colname])ES( is specified on the command line, an additional column is added to each row containing the number of the file from which that row was taken \201starting from one\202. In this case, the corresponding file names are stored in the header parameters having the prefix )BD(FUNFIL)ES(, i.e., FUNFIL01, FUNFIL02, etc. )0 P(Using the )BD(-w)ES( switch \201or )BD(-x)ES( switch as described below\202, )BD(funmerge)ES( also can adjust the position column values using the WCS information in each file. \201By position columns, we mean the columns that the table is binned on, i.e., those columns defined by the )BD(bincols=)ES( switch, or \201X,Y\202 by default.\202 To perform WCS alignment, the WCS of the first file is taken as the base WCS. Each position in subsequent files is adjusted by first converting it to the sky coordinate in its own WCS coordinate system, then by converting this sky position to the sky position of the base WCS, and finally converting back to a pixel position in the base system. Note that in order to perform WCS alignment, the appropriate WCS and TLMIN/TLMAX keywords must already exist in each FITS file. )0 P(When performing WCS alignment, you can save the original positions in the output file by using the )BD(-x)ES( \201for "xtra"\202 switch instead of the )BD(-w)ES( switch \201i.e., using this switch also implies using )BD(-w)ES(\202 The old positions are saved in columns having the same name as the original positional columns, with the added prefix "OLD_". )0 P(Examples: )0 P(Merge two tables, and preserve the originating file number for each row in the column called "FILE" \201along with the corresponding file name in the header\202: ) 1 51 PR( [sh] funmerge -f "FILE" test.ev test2.ev merge.ev)RP( )0 P(Merge two tables with WCS alignment, saving the old position values in 2 additional columns: ) 1 44 PR( [sh] funmerge -x test.ev test2.ev merge.ev)RP( )0 P(This program only works on raw event files and binary tables. We have not yet implemented image and array merging. )0 2 17 H(funsky)WB 80 Sn()WB 14 Sn( - convert between image and sky coordinates)EA()EH( )BD() 4 72 PR( funsky iname[ext] # RA,Dec \201deg\202 or image pix from stdin funsky iname[ext] [lname] # RA, Dec \201deg\202 or image pix from list funsky iname[ext] [col1] [col2] # named cols:units from stdin funsky iname[ext] [lname] [col1] [col2] # named cols:units from list)RP()ES( )0 P() 5 73 PR( -d # always use integer tlmin conversion \201as ds9 does\202 -r # convert x,y to RA,Dec \201default: convert RA,Dec to x,y\202 -o # include offset from the nominal target position \201in arcsec\202 -v # display input values also \201default: display output only\202 -T # output display in rdb format \201w/header,tab delimiters\202)RP( )0 P(Funsky converts input sky coordinates \201RA, Dec\202 to image coordinates \201or vice versa\202 using the WCS information contained in the specified FITS file. Several calling sequences are supported in order to make it easy to specify coordinate positions in different ways. )0 P(The first required argument is always the input FITS file \201or extension\202 containing the WCS information in an extension header. Note that the data from this file is not used. By default, the program converts input RA and Dec values to X and Y using this WCS information. If the WCS is associated with a FITS image, then the X,Y values are image values. If the WCS is associated with a binary table, then the X, Y values are physical values. To convert X,Y to RA and Dec, use the )BD(-r)ES( \201reverse\202 switch. )0 P(If no other command arguments are supplied, then the input positions are read from the standard input. Each line is assumed to contain a single coordinate position consisting of an RA in degrees \201or X in pixels\202 followed by a Dec in degrees \201or Y in pixels\202. The usual delimiters are supported \201spaces, commas, tabs\202. For example: ) 9 52 PR( # read from stdin, default column names and units [sh] funsky snr.ev 22.982695 58.606523 # input RA \201hrs\202, Dec\201deg\202 510.00 510.00 22.982127 58.607634 # input 512.00 510.50 22.981700 58.614301 # input 513.50 513.50 ^D # end of input)RP( )0 P(If a second argument is supplied, this argument is assumed to be a file containing RA \201X\202 and Dec \201Y\202 positions. The file can either be an ASCII table or a FITS binary table. The order of columns is unimportant, if the table has a column header. In this case, the names of the columns must be one of "RA", "DEC", or "X", "Y" for sky to image and image to sky conversions, respectively. If the table has no header, then once again, RA \201X\202 is assumed to first, followed by DEC \201Y\202. For example: ) 12 50 PR( # read from file, default column names and units [sh] cat hd.in RA DEC --------- --------- 22.982695 58.606523 22.982127 58.607634 22.981700 58.614301 [sh] funsky snr.ev hd.in 510.00 510.00 512.00 510.50 513.50 513.50)RP( )0 P(If three arguments are supplied, then the input positions again are read from the standard input. Each line is assumed to contain a single coordinate position consisting of an RA \201or X in pixels\202 followed by a Dec \201or Y in pixels\202, with the usual delimiters supported. However, the second and third arguments now specify the column names and/or sky units using a colon-delimited syntax: ) 1 19 PR( [colname]:[h|d|r])RP( If the colname is omitted, the names default to "RA", "DEC", "X", "Y", "COL1", or "COL2" as above. If the units are omitted, the default is degrees for both RA and Dec. When the -r switch is used \201convert from image to sky\202 the units are applied to the output instead of the input. The following examples will serve to illustrate the options: ) 36 66 PR( # read from stdin, specifying column names \201def. units: degrees\202 [sh] cat hd.in MYRA MYDEC --------- --------- 22.982695 58.606523 22.982127 58.607634 22.981700 58.614301 [sh] funsky snr.ev MYRA MYDEC < hd.in 510.00 510.00 512.00 510.50 513.50 513.50 # read from stdin, specifying column names and units [sh] cat dd.in MYRA MYDEC --------- --------- 344.740432 58.606523 344.731900 58.607634 344.725500 58.614301 [sh] funsky snr.ev MYRA:d MYDEC:d < dd.in 510.00 510.00 512.00 510.50 513.50 513.50 # read stdin, convert image to sky, specifying output sky units [sh] cat im.in 510.00 510.00 512.00 510.50 513.50 513.50)WR( [sh] cat im.in | funsky -r snr.ev :d :d 344.740432 58.606523 344.731900 58.607634 344.725500 58.614301)RP( )0 P(Finally, four command arguments specify both and input file and column names and/or units: ) 22 64 PR( [sh] cat dd.in MYRA MYDEC --------- --------- 344.740432 58.606523 344.731900 58.607634 344.725500 58.614301 [sh] funsky snr.ev dd.in MYRA:d MYDEC:d 510.00 510.00 512.00 510.50 513.50 513.50 # read file, convert image to sky, specifying output sky units [sh] cat im.in 510.00 510.00 512.00 510.50 513.50 513.50 [sh] funsky -r snr.ev im.in :d :d 344.740432 58.606523 344.731900 58.607634 344.725500 58.614301)RP( )0 P(By default, the output of funsky consists only of the converted coordinate position\201s\202, one per output line. This makes parsing in shell scripts easy. Use the )BD(-v)ES( \201verbose\202 switch to specify that the input coordinates should be pre-pended to each line. For example: ) 16 53 PR( [sh] cat dd.in MYRA MYDEC --------- --------- 344.740432 58.606523 344.731900 58.607634 344.725500 58.614301 [sh] funsky snr.ev dd.in MYRA:d MYDEC:d 510.00 510.00 512.00 510.50 513.50 513.50 [sh] funsky -v snr.ev dd.in MYRA:d MYDEC:d 344.740432 58.606523 510.00 510.00 344.731900 58.607634 512.00 510.50 344.725500 58.614301 513.50 513.50)RP( )0 P(In addition, a full starbase table can be output using the )BD(-T)ES( \201table\202 switch. This switch can be used with or without the -v switch. If the -T and -v are both specified, then a descriptive header parameters are output before the table \201mainly to remind you of the sky units\202: ) 23 62 PR( # output table in non-verbose mode [sh] funsky -T snr.ev dd.in MYRA:d MYDEC:d X Y ------------ ------------ 510.00 510.00 512.00 510.50 513.50 513.50 # output table in verbose mode [sh] funsky -T -v snr.ev dd.in MYRA:d MYDEC:d # IFILE = /Users/eric/data/snr.ev # ICOL1 = MYRA # ICOL2 = MYDEC # IUNITS1 = d # IUNITS2 = d # OCOL1 = X # OCOL2 = Y MYRA MYDEC X Y ------------ ------------ ------------ ------------ 344.740432 58.606523 510.00 510.00 344.731900 58.607634 512.00 510.50 344.725500 58.614301 513.50 513.50)RP( )0 P(Finally, the )BD(-d)ES( \201ds9\202 switch mimicks ds9's use of integer TLMIN and TLMAX values for all coordinate transformations. FITS conventions seem to call for use of floating point TLMIN and TLMAX when the data are floats. This convention is followed by funsky but results in a small discrepancy with ds9's converted values for floating point data. We will remedy this conflict in the future, maybe. )0 2 18 H(funtable)WB 81 Sn()WB 15 Sn( - copy selected rows from a Funtools file to a FITS binary table)EA()EH( )BD() 1 62 PR(funtable [-a] [-i|-z] [-m] [-s cols] [columns])RP()ES( )0 P() 5 61 PR( -a # append to existing output file as a table extension -i # for image data, only generate X and Y columns -m # for tables, write a separate file for each region -s "col1 ..." # columns on which to sort -z # for image data, output zero-valued pixels)RP( )0 P()BD(funtable)ES( selects rows from the specified )0 42 1 A(FITS Extension)42 0 TN TL()Ec /AF f D( \201binary table only\202 of a FITS file, or from a non-FITS raw event file, and writes those rows to a FITS binary table file. It also will create a FITS binary table from an image or a raw array file. )0 P(The first argument to the program specifies the FITS file, raw event file, or raw array file. If "stdin" is specified, data are read from the standard input. Use )0 42 1 A(Funtools Bracket Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions, and filters. The second argument is the output FITS file. If "stdout" is specified, the FITS binary table is written to the standard output. By default, all columns of the input file are copied to the output file. Selected columns can be output using an optional third argument in the form: ) 1 31 PR( "column1 column1 ... columnN")RP( )0 P(The )BD(funtable)ES( program generally is used to select rows from a FITS binary table using )0 52 1 A(Table Filters)52 0 TN TL()Ec /AF f D( and/or )0 54 1 A(Spatial Region Filters)54 0 TN TL()Ec /AF f D(. For example, you can copy only selected rows \201and output only selected columns\202 by executing in a command such as: ) 13 75 PR( [sh] funtable "test.ev[pha==1&)SY(\160)ES(==10]" stdout "x y pi pha" | fundisp stdin X Y PHA PI ------- ------- ------- --------- 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10 1 10)RP( )0 P(The special column )BD($REGION)ES( can be specified to write the region id of each row: ) 12 113 PR( [sh $] funtable "test.ev[time-\201int\202time>=.99&&annulus\2010 0 0 10 n=3\202]" stdout 'x y time $REGION' | fundisp stdin X Y TIME REGION -------- -------- --------------------- ---------- 5 -6 40.99000000 3 4 -5 59.99000000 2 -1 0 154.99000000 1 -2 1 168.99000000 1 -3 2 183.99000000 2 -4 3 199.99000000 2 -5 4 216.99000000 2 -6 5 234.99000000 3 -7 6 253.99000000 3)RP( )0 P(Here only rows with the proper fractional time and whose position also is within one of the three annuli are written. )0 P(Columns can be excluded from display using a minus sign before the column: ) 12 79 PR( [sh $] funtable "test.ev[time-\201int\202time>=.99]" stdout "-time" | fundisp stdin X Y PHA PI DX DY -------- -------- -------- ---------- ----------- ----------- 5 -6 5 -6 5.50 -6.50 4 -5 4 -5 4.50 -5.50 -1 0 -1 0 -1.50 0.50 -2 1 -2 1 -2.50 1.50 -3 2 -3 2 -3.50 2.50 -4 3 -4 3 -4.50 3.50 -5 4 -5 4 -5.50 4.50 -6 5 -6 5 -6.50 5.50 -7 6 -7 6 -7.50 6.50)RP( All columns except the time column are written. )0 P(In general, the rules for activating and de-activating columns are: )UL()-1 LI( If only exclude columns are specified, then all columns but the exclude columns will be activated. )-1 LI( If only include columns are specified, then only the specified columns are activated. )-1 LI( If a mixture of include and exclude columns are specified, then all but the exclude columns will be active; this last case is ambiguous and the rule is arbitrary.)LU( In addition to specifying columns names explicitly, the special symbols )EM(+)ES( and )EM(-)ES( can be used to activate and de-activate )EM(all)ES( columns. This is useful if you want to activate the $REGION column along with all other columns. According to the rules, the syntax "$REGION" only activates the region column and de-activates the rest. Use "+ $REGION" to activate all columns as well as the region column. )0 P(Ordinarily, only the selected table is copied to the output file. In a FITS binary table, it sometimes is desirable to copy all of the other FITS extensions to the output file as well. This can be done by appending a '+' sign to the name of the extension in the input file name. For example, the first command below copies only the EVENT table, while the second command copies other extensions as well: ) 2 64 PR( [sh] funtable "/proj/rd/data/snr.ev[EVENTS]" events.ev [sh] funtable "/proj/rd/data/snr.ev[EVENTS+]" eventsandmore.ev)RP( )0 P(If the input file is an image or a raw array file, then )BD(funtable)ES( will generate a FITS binary table from the pixel values in the image. Note that it is not possible to specify the columns to output \201using command-line argument 3\202. Instead, there are two ways to create such a binary table from an image. By default, a 3-column table is generated, where the columns are "X", "Y", and "VALUE". For each pixel in the image, a single row \201event\202 is generated with the "X" and "Y" columns assigned the dim1 and dim2 values of the image pixel, respectively and the "VALUE" column assigned the value of the pixel. With sort of table, running )BD(funhist)ES( on the "VALUE" column will give the same results as running )BD(funhist)ES( on the original image. )0 P(If the )BD(-i)ES( \201"individual" rows\202 switch is specified, then only the "X" and "Y" columns are generated. In this case, each positive pixel value in the image generates n rows \201events\202, where n is equal to the integerized value of that pixel \201plus 0.5, for floating point data\202. In effect, )BD(-i)ES( approximately recreates the rows of a table that would have been binned into the input image. \201Of course, this is only approximately correct, since the resulting x,y positions are integerized.\202 )0 P(If the )BD(-s [col1 col2 ... coln])ES( \201"sort"\202 switch is specified, the output rows of a binary table will be sorted using the specified columns as sort keys. The sort keys must be scalar columns and also must be part of the output file \201i.e. you cannot sort on a column but not include it in the output\202. This facility uses the )BD(_sort)ES( program \201included with funtools\202, which must be accessible via your path. )0 P(For binary tables, the )BD(-m)ES( \201"multiple files"\202 switch will generate a separate file for each region in the filter specification i.e. each file contains only the rows from that region. Rows which pass the filter but are not in any region also are put in a separate file. )0 P(The separate output file names generated by the )BD(-m)ES( switch are produced automatically from the root output file to contain the region id of the associated region. \201Note that region ids start at 1, so that the file name associated with id 0 contains rows that pass the filter but are not in any given region.\202 Output file names are generated as follows: )UL()-1 LI( A $n specification can be used anywhere in the root file name \201suitably quoted to protect it from the shell\202 and will be expanded to be the id number of the associated region. For example: ) 1 78 PR( funtable -m input.fits'[cir\201512,512,1\202;cir\201520,520,1\202...]' 'foo.goo_$n.fits')RP( will generate files named foo.goo_0.fits \201for rows not in any region but still passing the filter\202, foo.goo_1.fits \201rows in region id #1, the first region\202, foo.goo_2.fits \201rows in region id #2\202, etc. Note that single quotes in the output root are required to protect the '$' from the shell. )-1 LI( If $n is not specified, then the region id will be placed before the first dot \201.\202 in the filename. Thus: ) 1 73 PR( funtable -m input.fits'[cir\201512,512,1\202;cir\201520,520,1\202...]' foo.evt.fits)RP( will generate files named foo0.evt.fits \201for rows not in any region but still passing the filter\202, foo1.evt.fits \201rows in region id #1\202, foo2.evt.fits \201rows in region id #2\202, etc. )-1 LI( If no dot is specified in the root output file name, then the region id will be appended to the filename. Thus: ) 1 70 PR( funtable -m input.fits'[cir\201512,512,1\202;cir\201520,520,1\202...]' 'foo_evt')RP( will generate files named foo_evt0 \201for rows not in any region but still passing the filter\202, foo_evt1 \201rows in region id #1\202, foo_evt2 \201rows in region id #2\202, etc.)LU( The multiple file mechanism provide a simple way to generate individual source data files with a single pass through the data. )0 P(By default, a new FITS file is created and the binary table is written to the first extension. If the )BD(-a)ES( \201append\202 switch is specified, the table is appended to an existing FITS file as a BINTABLE extension. Note that the output FITS file must already exist. )0 P(If the )BD(-z)ES( \201"zero" pixel values\202 switch is specified and )BD(-i)ES( is not specified, then pixels having a zero value will be output with their "VALUE" column set to zero. Obviously, this switch does not make sense when individual events are output. )0 2 19 H(funtbl)WB 82 Sn()WB 16 Sn( - extract a table from Funtools ASCII output)EA()EH( )BD() 1 61 PR(funtable [-c cols] [-h] [-n table] [-p prog] [-s sep] )RP()ES( )0 P([NB: This program has been deprecated in favor of the ASCII text processing support in funtools. You can now perform fundisp on funtools ASCII output files \201specifying the table using bracket notation\202 to extract tables and columns.] The )BD(funtbl)ES( script extracts a specified table \201without the header and comments\202 from a funtools ASCII output file and writes the result to the standard output. The first non-switch argument is the ASCII input file name \201i.e. the saved output from funcnts, fundisp, funhist, etc.\202. If no filename is specified, stdin is read. The -n switch specifies which table \201starting from 1\202 to extract. The default is to extract the first table. The -c switch is a space-delimited list of column numbers to output, e.g. -c "1 3 5" will extract the first three odd-numbered columns. The default is to extract all columns. The -s switch specifies the separator string to put between columns. The default is a single space. The -h switch specifies that column names should be added in a header line before the data is output. Without the switch, no header is prepended. The -p program switch allows you to specify an awk-like program to run instead of the default \201which is host-specific and is determined at build time\202. The -T switch will output the data in rdb format \201i.e., with a 2-row header of column names and dashes, and with data columns separated by tabs\202. The -help switch will print out a message describing program usage. )0 P(For example, consider the output from the following funcnts command: ) 37 82 PR( [sh] funcnts -sr snr.ev "ann 512 512 0 9 n=3" # source # data file: /proj/rd/data/snr.ev # arcsec/pixel: 8 # background # constant value: 0.000000 # column units # area: arcsec**2 # surf_bri: cnts/arcsec**2 # surf_err: cnts/arcsec**2 # summed background-subtracted results upto net_counts error background berror area surf_bri surf_err ---- ------------ --------- ------------ --------- --------- --------- --------- 1 147.000 12.124 0.000 0.000 1600.00 0.092 0.008 2 625.000 25.000 0.000 0.000 6976.00 0.090 0.004 3 1442.000 37.974 0.000 0.000 15936.00 0.090 0.002 # background-subtracted results reg net_counts error background berror area surf_bri surf_err ---- ------------ --------- ------------ --------- --------- --------- --------- 1 147.000 12.124 0.000 0.000 1600.00 0.092 0.008 2 478.000 21.863 0.000 0.000 5376.00 0.089 0.004 3 817.000 28.583 0.000 0.000 8960.00 0.091 0.003 # the following source and background components were used: source_region\201s\202 ---------------- ann 512 512 0 9 n=3)WR( reg counts pixels sumcnts sumpix ---- ------------ --------- ------------ --------- 1 147.000 25 147.000 25 2 478.000 84 625.000 109 3 817.000 140 1442.000 249)RP( )0 P(There are four tables in this output. To extract the last one, you can execute: ) 4 60 PR( [sh] funcnts -s snr.ev "ann 512 512 0 9 n=3" | funtbl -n 4 1 147.000 25 147.000 25 2 478.000 84 625.000 109 3 817.000 140 1442.000 249)RP( Note that the output has been re-formatted so that only a single space separates each column, with no extraneous header or comment information. )0 P(To extract only columns 1,2, and 4 from the last example \201but with a header prepended and tabs between columns\202, you can execute: ) 5 82 PR( [sh] funcnts -s snr.ev "ann 512 512 0 9 n=3" | funtbl -c "1 2 4" -h -n 4 -s "\200t" #reg counts sumcnts 1 147.000 147.000 2 478.000 625.000 3 817.000 1442.000)RP( )0 P(Of course, if the output has previously been saved in a file named foo.out, the same result can be obtained by executing: ) 5 48 PR( [sh] funtbl -c "1 2 4" -h -n 4 -s "\200t" foo.out #reg counts sumcnts 1 147.000 147.000 2 478.000 625.000 3 817.000 1442.000)RP( )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 20 H(Last)WB 83 Sn( updated: April 1, 2007)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (ds9.html) D /Ti (Funtools and DS9 Image Display) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 17 Sn( )0 2 21 H(FunDS9:)WB 85 Sn()WB 84 Sn( Funtools and DS9 Image Display)EA()EH( )0 2 22 H(Summary)WB 86 Sn()EH( Describes how funtools can be integrated into the ds9 Analysis menu. )0 2 23 H(Description)WB 87 Sn()EH( )0 P()R1 2 A(SAOImage/DS9)EA( is an astronomical imaging and data visualization application used by astronomers around the world. DS9 can display standard astronomical FITS images and binary tables, but also has support for displaying raw array files, shared memory files, and data files automatically retrieved via FTP and HTTP. Standard functional capabilities include multiple frame buffers, colormap and region manipulation, and many data scaling algorithms. DS9's advanced features include TrueColor visuals, deep frame buffers, true PostScript printing, and display of image mosaics. The program's support of image tiling, "blinking", arbitrary zoom, rotation, and pan is unparalleled in astronomy. It also has innovative support for automatic retrieval and display of standard image data such as the Digital Sky Survey \201using servers at SAO, StScI, or ESO\202. )0 P(DS9 can communicate with external programs such as Funtools using the )R2 2 A(XPA)EA( messaging system. In addition, programs can be integrated directly into the DS9 GUI by means of a configurable Analysis menu. By default, the DS9 Analysis menu contains algorithms deemed essential to the core functions of DS9, e.g., display cross-cuts of data, iso-intensity contours, and WCS grids. However, new programs can be added to DS9 by creating a set-up file which can be loaded into DS9 to reconfigure the Analysis menu. ) 7 48 PR(The basic format of the analysis set-up file is: )0 P( # # Analysis command descriptions: # menu label/description # file templates for this command # "menu" \201add to menu\202 |"bind" \201bind to key\202 # analysis command line)RP( For example, the funcnts program can be specified in this way: ) 4 69 PR( Funcnts \201counts in source/bkgd regions; options: none\202 * menu funcnts $filename $regions\201source,,\202 $regions\201background,,\202 | $text)RP( As shown above, DS9 supports a macro facility to provide information as well as task support to command lines. For example, the $regions macro is expanded by DS9 to provide the current source and/or background region to the analysis command. The $text macro is expanded to generate a text window display. It also is possible to query for parameters using a $param macro, plot data using a $plot macro, etc. See the DS9 documentation for further details. )0 P(A set-up file called )0 2 A(funtools.ds9)EA( will load some useful Funtools applications \201counts in regions, radial profile, X-ray light curve and energy spectrum, 1D histogram\202 into the DS9 Analysis menu \201version 2.1 and above\202. The file resides in the bin directory where Funtools programs are installed. It can be manually loaded into DS9 from the )BD(Load Analysis Commands ...)ES( option of the )BD(Analysis)ES( menu. Alternatively, you can tell DS9 to load this file automatically at start-up time by adding the pathname to the )BD(Edit)ES(->)BD(Preferences)ES(->)BD(Analysis Menu)ES(->)BD(Analysis File)ES( menu option. \201NB: make sure you select )BD(Edit)ES(->)BD(Preferences)ES(->)BD(Save Preferences)ES( after setting the pathname.\202 )0 P(The tasks in this setup file generally process the original disk-based FITS file. Funcnts-based results \201radial profile, counts in regions\202 are presented in WCS units, if present in the FITS header. For situations where a disk file is not available \201e.g., image data generated and sent to DS9's 'fits' XPA access point\202, versions of the radial profile and counts in regions tasks also are also offered utilizing DS9's internal image data. Results are presented in pixels. Aside from the units, the results should be identical to the file-based results. )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 24 H(Last)WB 88 Sn( updated: November 16, 2005)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (library.html) D /Ti (Funtools Programming) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 18 Sn( )0 2 25 H(FunLib:)WB 91 Sn()WB 89 Sn( the Funtools Programming Interface)EA()EH( )0 2 26 H(Summary)WB 92 Sn()EH( A description of the Funtools library. )0 2 27 H(Introduction)WB 93 Sn()WB 90 Sn( to the Funtools Programming Interface)EH()EA( )0 P(To create a Funtools application, you need to include the funtools.h definitions file in your code: ) 1 23 PR( #include )RP( You then call Funtools subroutines and functions to access Funtools data. The most important routines are: )UL( )0 P()-1 LI( )0 25 1 A(FunOpen)25 0 TN TL()Ec /AF f D(: open a Funtools file )-1 LI()0 35 1 A(FunInfoGet)35 0 TN TL()Ec /AF f D(: get info about an image or table )-1 LI()0 26 1 A(FunImageGet)26 0 TN TL()Ec /AF f D(: retrieve image data )-1 LI()0 28 1 A(FunImageRowGet)28 0 TN TL()Ec /AF f D(: retrieve image data by row )-1 LI()0 27 1 A(FunImagePut)27 0 TN TL()Ec /AF f D(: output image data )-1 LI()0 29 1 A(FunImageRowPut)29 0 TN TL()Ec /AF f D(: output image data by row )-1 LI()0 32 1 A(FunColumnSelect)32 0 TN TL()Ec /AF f D(: select columns in a table for access )-1 LI()0 30 1 A(FunTableRowGet)30 0 TN TL()Ec /AF f D(: retrieve rows from a table )-1 LI()0 31 1 A(FunTableRowPut)31 0 TN TL()Ec /AF f D(: output rows to a table )-1 LI( )0 40 1 A(FunClose)40 0 TN TL()Ec /AF f D(: close a Funtools file)LU( Your program must be linked against the libfuntools.a library, along with the math library. The following libraries also might be required on your system: )UL()-1 LI( -lsocket -lnsl for socket support )-1 LI( -ldl for dynamic loading)LU( )0 P(For example, on a Solaris system using gcc, use the following link line: ) 1 53 PR( gcc -o foo foo.c -lfuntools -lsocket -lnsl -ldl -lm)RP( On a Solaris system using Solaris cc, use the following link line: ) 1 48 PR( gcc -o foo foo.c -lfuntools -lsocket -lnsl -lm)RP( On a Linux system using gcc, use the following link line: ) 1 38 PR( gcc -o foo foo.c -lfuntools -ldl -lm)RP( Once configure has built a Makefile on your platform, the required "extra" libraries \201aside from -lm, which always is required\202 are specified in that file's EXTRA_LIBS variable. For example, under Linux you will find: ) 3 26 PR( grep EXTRA_LIBS Makefile EXTRA_LIBS = -ldl ...)RP( )0 P(The Funtools library contains both the zlib library \201http://www.gzip.org/zlib/\202 and Doug Mink's WCS library \201http://tdc-www.harvard.edu/software/wcstools/\202. It is not necessary to put these libraries on a Funtools link line. Include files necessary for using these libraries are installed in the Funtools include directory. )0 2 28 H(Funtools)WB 94 Sn()WB 20 Sn( Programming Tutorial)EA()EH( The )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( function is used to open a FITS file, an array, or a raw event file: ) 4 79 PR( /* open the input FITS file for reading */ ifun = FunOpen\201iname, "r", NULL\202; /* open the output FITS file for writing, and connect it to the input file */ ofun = FunOpen\201iname, "w", ifun\202;)RP( A new output file can inherit header parameters automatically from existing input file by passing the input Funtools handle as the last argument to the new file's )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( call as shown above. )0 P(For image data, you then can call )0 26 1 A(FunImageGet\201\202)26 0 TN TL()Ec /AF f D( to read an image into memory. ) 3 61 PR( float buf=NULL; /* extract and bin the data section into an image buffer */ buf = FunImageGet\201fun, NULL, "bitpix=-32"\202;)RP( If the \201second\202 buf argument to this call is NULL, buffer space is allocated automatically. The \201third\202 plist argument can be used to specify the return data type of the array. If NULL is specified, the data type of the input file is used. )0 P(To process an image buffer, you would generally make a call to )0 35 1 A(FunInfoGet\201\202)35 0 TN TL()Ec /AF f D( to determine the dimensions of the image \201which may have been changed from the original file dimensions due to )0 49 1 A(Funtools image sectioning)49 0 TN TL()Ec /AF f D( on the command line\202. In a FITS image, the index along the dim1 axis varies most rapidly, followed by the dim2 axis, etc. Thus, to access each pixel in an 2D image, use a double loop such as:)RP( buf = FunImageGet\201fun, NULL, "bitpix=-32"\202; FunInfoGet\201fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0\202; for\201i=1; i<=dim2; i++\202{ for\201j=1; j<=dim1; j++\202{ ... process buf[\201\201i-1\202*dim1\202+\201j-1\202] ... } })RP( or: ) 5 65 PR( buf = FunImageGet\201fun, NULL, "bitpix=-32"\202; FunInfoGet\201fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0\202; for\201i=0; i<\201dim1*dim2\202; i++\202{ ... process buf[i] ... })RP( Finally, you can write the resulting image to disk using )0 27 1 A(FunImagePut\201\202)27 0 TN TL()Ec /AF f D(: ) 1 48 PR( FunImagePut\201fun2, buf, dim1, dim2, -32, NULL\202;)RP( Note that Funtools automatically takes care of book-keeping tasks such as reading and writing FITS headers \201although you can, of course, write your own header or add your own parameters to a header\202. )0 P(For binary tables and raw event files, a call to )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( will be followed by a call to the )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( routine to select columns to be read from the input file and/or written to the output file: ) 8 69 PR( typedef struct evstruct{ double time; int time2; } *Ev, EvRec; FunColumnSelect\201fun, sizeof\201EvRec\202, NULL, "time", "D", "rw", FUN_OFFSET\201Ev, time\202, "time2", "J", "w", FUN_OFFSET\201Ev, time2\202, NULL\202;)RP( Columns whose \201third\202 mode argument contains an "r" are "readable", i.e., columns will be read from the input file and converted into the data type specified in the call's second argument. These columns values then are stored in the specified offset of the user record structure. Columns whose mode argument contains a "w" are "writable", i.e., these values will be written to the output file. The )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( routine also offers the option of automatically merging user columns with the original input columns when writing the output rows. )0 P(Once a set of columns has been specified, you can retrieve rows using )0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D(, and write the rows using )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D(: ) 17 70 PR( Ev ebuf, ev; /* get rows -- let routine allocate the array */ while\201 \201ebuf = \201Ev\202FunTableRowGet\201fun, NULL, MAXROW, NULL, &got\202\202 \202{ /* process all rows */ for\201i=0; itime2 = \201int\202\201ev->time+.5\202; /* change the input time as well */ ev->time = -\201ev->time/10.0\202; } /* write out this batch of rows with the new column */ FunTableRowPut\201fun2, \201char *\202ebuf, got, 0, NULL\202; /* free row data */ if\201 ebuf \202 free\201ebuf\202; })RP( The input rows are retrieved into an array of user structs, which can be accessed serially as shown above. Once again, Funtools automatically takes care of book-keeping tasks such as reading and writing FITS headers \201although you can, of course, write your own header or add your own parameters to a header\202. )0 P(When all processing is done, you can call )0 40 1 A(FunClose\201\202)40 0 TN TL()Ec /AF f D( to close the file\201s\202: ) 2 17 PR( FunClose\201fun2\202; FunClose\201fun\202;)RP( )0 P(These are the basics of processing FITS files \201and arrays or raw event data\202 using Funtools. The routines in these examples are described in more detail below, along with a few other routines that support parameter access, data flushing, etc. )0 2 29 H(Compiling)WB 95 Sn()WB 22 Sn( and Linking)EA()EH( )0 P(To create a Funtools application, a software developer will include the funtools.h definitions file in Funtools code: ) 1 23 PR( #include )RP( The program is linked against the libfuntools.a library, along with the math library \201and the dynamic load library, if the latter is available on your system\202: ) 1 38 PR( gcc -o foo foo.c -lfuntools -ldl -lm)RP( )0 P(If gcc is used, Funtools filtering can be performed using dynamically loaded shared objects that are built at run-time. Otherwise, filtering is performed using a slave process. )0 P(Funtools has been built on the following systems: )UL()-1 LI( Sun/Solaris 5.X )-1 LI( Linux/RedHat Linux 5.X,6.X,7.X )-1 LI( Dec Alpha/OSF1 V4.X )-1 LI( WindowsNT/Cygwin 1.0 )-1 LI( SGI/IRIX64 6.5)LU( )0 2 30 H(A)WB 96 Sn()WB 21 Sn( Short Digression on Subroutine Order)EA()EH( )0 P(There is a natural order for all I/O access libraries. You would not think of reading a file without first opening it, or writing a file after closing it. A large part of the experiment in funtools is to use the idea of "natural order" as a means of making programming easier. We do this by maintaining the state of processing for a given funtools file, so that we can do things like write headers and flush extension padding at the right time, without you having to do it. )0 P(For example, if you open a new funtools file for writing using )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(, then generate an array of image data and call )0 27 1 A(FunImagePut\201\202)27 0 TN TL()Ec /AF f D(, funtools knows to write the image header automatically. There is no need to think about writing a standard header. Of course, you can add parameters to the file first by calling one of the )0 38 1 A(FunParamPut\201\202)38 0 TN TL()Ec /AF f D( routines, and these parameters will automatically be added to the header when it is written out. There still is no need to write the header explicitly. )0 P(Maintaining state in this way means that there are certain rules of order which should be maintained in any funtools program. In particular, we strongly recommend the following ordering rules be adhered to: )UL()-1 LI( When specifying that input extensions be copied to an output file via a reference handle, open the output file )BD(before)ES( reading the input file. \201Otherwise the initial copy will not occur\202. )-1 LI( Always write parameters to an output file using one of the )0 38 1 A(FunParamPut\201\202)38 0 TN TL()Ec /AF f D( calls )BD(before)ES( writing any data. \201This is a good idea for all FITS libraries, to avoid having to recopy data is the FITS header needs to be extended by adding a single parameter.\202 )-1 LI( If you retrieve an image, and need to know the data type, use the FUN_SECT_BITPIX option of )0 35 1 A(FunInfoGet\201\202)35 0 TN TL()Ec /AF f D(, )BD(after)ES( calling )0 26 1 A(FunImageGet\201\202)26 0 TN TL()Ec /AF f D(, since it is possible to change the value of BITPIX from the latter. )-1 LI( When specifying that input extensions be copied to an output file via a reference handle, close the output file )BD(before)ES( closing input file, or else use )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( explicitly on the output file )BD(before)ES( closing the input file. \201Otherwise the final copy will not occur\202.)LU( )0 P(We believe that these are the natural rules that are implied in most FITS programming tasks. However, we recognize that making explicit use of "natural order" to decide what automatic action to take on behalf of the programmer is experimental. Therefore, if you find that your needs are not compatible with our preferred order, please let us know -- it will be most illuminating for us as we evaluate this experiment. )0 2 31 H(Funtools)WB 97 Sn()WB 41 Sn( Programming Examples)EA()EH( )0 P(The following complete coding examples are provided to illustrate the simplicity of Funtools applications. They can be found in the funtest subdirectory of the Funtools distribution. In many cases, you should be able to modify one of these programs to generate your own Funtools program: )UL()-1 LI()0 2 A(evread.c)EA(: read and write binary tables )-1 LI()0 2 A(evcols.c)EA(: add column and rows to binary tables )-1 LI()0 2 A(evmerge.c)EA(: merge new columns with existing columns )-1 LI()0 2 A(evnext.c)EA(: manipulate raw data pointers )-1 LI()0 2 A(imblank.c)EA(: blank out image values below a threshold )-1 LI()0 2 A(asc2fits.c)EA(: convert a specific ASCII table to FITS binary table)LU( )0 2 32 H(The)WB 98 Sn()WB 24 Sn( Funtools Programming Reference Manual)EA()EH( )0 P() 45 116 PR(#include Fun )0 25 1 A(FunOpen\201char *name, char *mode, Fun ref\202)25 0 TN TL()Ec /AF f D( void *)0 26 1 A(FunImageGet\201Fun fun, void *buf, char *plist\202)26 0 TN TL()Ec /AF f D( int )0 27 1 A(FunImagePut\201Fun fun, void *buf, int dim1, int dim2, int bitpix, char *plist\202)27 0 TN TL()Ec /AF f D( void * )0 28 1 A(FunImageRowGet\201Fun fun, void *buf, int rstart, int rstop, char *plist\202)28 0 TN TL()Ec /AF f D( void * )0 29 1 A(FunImageRowPut\201Fun fun, void *buf, int rstart, int rstop, int dim1, int dim2, int bitpix, char *plist\202)29 0 TN TL()Ec /AF f D( int )0 32 1 A(FunColumnSelect\201Fun fun, int size, char *plist, ...\202)32 0 TN TL()Ec /AF f D( void )0 33 1 A(FunColumnActivate\201Fun fun, char *s, char *plist\202)33 0 TN TL()Ec /AF f D( int )0 34 1 A(FunColumnLookup\201Fun fun, char *s, int which, char **name, int *type, int *mode, int *offset, int *n, int *width\202)34 0 TN TL()Ec /AF f D( void *)0 30 1 A(FunTableRowGet\201Fun fun, void *rows, int maxrow, char *plist, int *nrow\202)30 0 TN TL()Ec /AF f D( int )0 31 1 A(FunTableRowPut\201Fun fun, void *rows, int nev, int idx, char *plist\202)31 0 TN TL()Ec /AF f D( int )0 37 1 A(FunParamGetb\201Fun fun, char *name, int n, int defval, int *got\202)37 0 TN TL()Ec /AF f D( int )0 37 1 A(FunParamGeti\201Fun fun, char *name, int n, int defval, int *got\202)37 0 TN TL()Ec /AF f D( double )0 37 1 A(FunParamGetd\201Fun fun, char *name, int n, double defval, int *got\202)37 0 TN TL()Ec /AF f D( char *)0 37 1 A(FunParamGets\201Fun fun, char *name, int n, char *defval, int *got\202)37 0 TN TL()Ec /AF f D( int )0 38 1 A(FunParamPutb\201Fun fun, char *name, int n, int value, char *comm, int append\202)38 0 TN TL()Ec /AF f D()WR( int )0 38 1 A(FunParamPuti\201Fun fun, char *name, int n, int value, char *comm, int append\202)38 0 TN TL()Ec /AF f D( int )0 38 1 A(FunParamPutd\201Fun fun, char *name, int n, double value, int prec, char *comm, int append\202)38 0 TN TL()Ec /AF f D( int )0 38 1 A(FunParamPuts\201Fun fun, char *name, int n, char *value, char *comm, int append\202)38 0 TN TL()Ec /AF f D( int )0 35 1 A(FunInfoGet\201Fun fun, int type, ...\202)35 0 TN TL()Ec /AF f D( int )0 36 1 A(FunInfoPut\201Fun fun, int type, ...\202)36 0 TN TL()Ec /AF f D( void )0 39 1 A(FunFlush\201Fun fun, char *plist\202)39 0 TN TL()Ec /AF f D( void )0 40 1 A(FunClose\201Fun fun\202)40 0 TN TL()Ec /AF f D()RP( )0 2 33 H(FunOpen)WB 99 Sn()WB 25 Sn( - open a Funtools data file)EA()EH( )BD() 3 47 PR( #include Fun FunOpen\201char *name, char *mode, Fun ref\202;)RP()ES( )0 P(The )BD(FunOpen\201\202)ES( routine opens a Funtools data file for reading or appending, or creates a new FITS file for writing. The )BD(name)ES( argument specifies the name of the Funtools data file to open. You can use IRAF-style bracket notation to specify )0 42 1 A(Funtools Files, Extensions, and Filters)42 0 TN TL()Ec /AF f D(. A separate call should be made each time a different FITS extension is accessed: ) 7 65 PR( Fun fun; char *iname; ... if\201 !\201fun = FunOpen\201iname, "r", NULL\202\202 \202{ fprintf\201stderr, "could not FunOpen input file: %s\200n", iname\202; exit\2011\202; })RP( )0 P(If )BD(mode)ES( is "r", the file is opened for reading, and processing is set up to begin at the specified extension. For reading, )BD(name)ES( can be )BD(stdin)ES(, in which case the standard input is read. )0 P(If )BD(mode)ES( is "w", the file is created if it does not exist, or opened and truncated for writing if it does exist. Processing starts at the beginning of the file. The )BD(name)ES( can be )BD(stdout)ES(, in which case the standard output is readied for processing. )0 P(If )BD(mode)ES( is "a", the file is created if it does not exist, or opened if it does exist. Processing starts at the end of the file. The )BD(name)ES( can be )BD(stdout)ES(, in which case the standard output is readied for processing. )0 P(When a Funtools file is opened for writing or appending, a previously opened )0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( can be specified as the third argument. This handle typically is associated with the input Funtools file that will be used to generate the data for the output data. When a reference file is specified in this way, the output file will inherit the \201extension\202 header parameters from the input file: ) 8 67 PR( Fun fun, fun2; ... /* open input file */ if\201 !\201fun = FunOpen\201argv[1], "r", NULL\202\202 \202 gerror\201stderr, "could not FunOpen input file: %s\200n", argv[1]\202; /* open the output FITS image, inheriting params from input */ if\201 !\201fun2 = FunOpen\201argv[2], "w", fun\202\202 \202 gerror\201stderr, "could not FunOpen output file: %s\200n", argv[2]\202;)RP( Thus, in the above example, the output FITS binary table file will inherit all of the parameters associated with the input binary table extension. )0 P(A file opened for writing with a )0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( also inherits the selected columns \201i.e. those columns chosen for processing using the )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( routine\202 from the reference file as its default columns. This makes it easy to open an output file in such a way that the columns written to the output file are the same as the columns read in the input file. Of course, column selection can easily be tailored using the )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( routine. In particular, it is easy to merge user-defined columns with the input columns to generate a new file. See the )0 2 A(evmerge)EA( for a complete example. )0 P(In addition, when a )0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( is supplied in a )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( call, it is possible also to specify that all other extensions from the reference file \201other than the input extension being processed\202 should be copied from the reference file to the output file. This is useful, for example, in a case where you are processing a FITS binary table or image and you want to copy all of the other extensions to the output file as well. Copy of other extensions is controlled by adding a "C" or "c" to the mode string of the )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( call )BD(of the input reference file)ES(. If "C" is specified, then other extensions are )BD(always)ES( copied \201i.e., copy is forced by the application\202. If "c" is used, then other extensions are copied if the user requests copying by adding a plus sign "+" to the extension name in the bracket specification. For example, the )BD(funtable)ES( program utilizes "c" mode, giving users the option of copying all other extensions: ) 6 67 PR( /* open input file -- allow user copy of other extensions */ if\201 !\201fun = FunOpen\201argv[1], "rc", NULL\202\202 \202 gerror\201stderr, "could not FunOpen input file: %s\200n", argv[1]\202; /* open the output FITS image, inheriting params from input */ if\201 !\201fun2 = FunOpen\201argv[2], "w", fun\202\202 \202 gerror\201stderr, "could not FunOpen output file: %s\200n", argv[2]\202;)RP( Thus, )BD(funtable)ES( supports either of these command lines: ) 4 60 PR( # copy only the EVENTS extension csh> funtable "test.ev[EVENTS,circle\201512,512,10\202]" foo.ev # copy ALL extensions csh> funtable "test.ev[EVENTS+,circle\201512,512,10\202]" foo.ev)RP( )0 P(Use of a )0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( implies that the input file is opened before the output file. However, it is important to note that if copy mode \201"c" or "C"\202 is specified for the input file, the actual input file open is delayed until just after the output file is opened, since the copy of prior extensions to the output file takes place while Funtools is seeking to the specified input extension. This implies that the output file should be opened before any I/O is done on the input file or else the copy will fail. Note also that the copy of subsequent extension will be handled automatically by )0 40 1 A(FunClose\201\202)40 0 TN TL()Ec /AF f D( if the output file is closed before the input file. Alternatively, it can be done explicitly by )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D(, but again, this assumes that the input file still is open. )0 P(Upon success )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( returns a Fun handle that is used in subsequent Funtools calls. On error, NULL is returned. )0 2 34 H(FunImageGet)WB 100 Sn()WB 26 Sn( - get an image or image section)EA()EH( )BD() 3 52 PR( #include void *FunImageGet\201Fun fun, void *buf, char *plist\202)RP()ES( )0 P(The )BD(FunImageGet\201\202)ES( routine returns an binned image array of the specified section of a Funtools data file. If the input data are already of type image, the array is generated by extracting the specified image section and then binning it according to the specified bin factor. If the input data are contained in a binary table or raw event file, the rows are binned on the columns specified by the )BD(bincols=)ES( keyword \201using appropriate default columns as necessary\202, after which the image section and bin factors are applied. In both cases, the data is automatically converted from FITS to native format, if necessary. )0 P(The first argument is the Funtools handle returned by )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(. The second )BD(buf)ES( argument is a pointer to a data buffer to fill. If NULL is specified, FunImageGet will allocate a buffer of the appropriate size. Generally speaking, you always want Funtools to allocate the buffer because the image dimensions will be determined by )0 49 1 A(Funtools image sectioning)49 0 TN TL()Ec /AF f D( on the command line. )0 P(The third )BD(plist)ES( \201i.e., parameter list\202 argument is a string containing one or more comma-delimited )BD(keyword=value)ES( parameters. It can be used to specify the return data type using the )BD(bitpix=)ES( keyword. If no such keyword is specified in the plist string, the data type of the returned image is the same as the data type of the original input file, or is of type int for FITS binary tables. )0 P(If the )BD(bitpix=)ES( keyword is supplied in the plist string, the data type of the returned image will be one of the supported FITS image data types: )UL()-1 LI( 8 unsigned char )-1 LI( 16 short )-1 LI( 32 int )-1 LI( -32 float )-1 LI( -64 double)LU( For example: ) 4 57 PR( void *buf; /* extract data section into an image buffer */ if\201 !\201buf = FunImageGet\201fun, NULL, NULL\202\202 \202 gerror\201stderr, "could not FunImageGet: %s\200n", iname\202;)RP( will allocate buf and retrieve the image in the file data format. In this case, you will have to determine the data type \201using the FUN_SECT_BITPIX value in the )0 35 1 A(FunInfoGet\201\202)35 0 TN TL()Ec /AF f D( routine\202 and then use a switch statement to process each data type: ) 17 65 PR( int bitpix; void *buf; unsigned char *cbuf; short *sbuf; int *ibuf; ... buf = FunImageGet\201fun, NULL, NULL\202; FunInfoGet\201fun, FUN_SECT_BITPIX, &bitpix, 0\202; /* set appropriate data type buffer to point to image buffer */ switch\201bitpix\202{ case 8: cbuf = \201unsigned char *\202buf; break; case 16: sbuf = \201short *\202buf; break; case 32: ibuf = \201int *\202buf; break; ...)RP( See the )0 2 A(imblank example code)EA( for more details on how to process an image when the data type is not specified beforehand. )0 P(It often is easier to specify the data type directly: ) 4 57 PR( double *buf; /* extract data section into a double image buffer */ if\201 !\201buf = FunImageGet\201fun, NULL, "bitpix=-64"\202\202 \202 gerror\201stderr, "could not FunImageGet: %s\200n", iname\202;)RP( will extract the image while converting to type double. )0 P(On success, a pointer to the image buffer is returned. \201This will be the same as the second argument, if NULL is not passed to the latter.\202 On error, NULL is returned. )0 P(In summary, to retrieve image or row data into a binned image, you simply call FunOpen\201\202 followed by )0 26 1 A(FunImageGet\201\202)26 0 TN TL()Ec /AF f D(. Generally, you then will want to call )0 35 1 A(FunInfoGet\201\202)35 0 TN TL()Ec /AF f D( to retrieve the axis dimensions \201and data type\202 of the section you are processing \201so as to take account of sectioning and blocking of the original data\202: ) 20 73 PR( double *buf; int i, j; int dim1, dim2; ... other declarations, etc. /* open the input FITS file */ if\201 !\201fun = FunOpen\201argv[1], "rc", NULL\202\202 \202 gerror\201stderr, "could not FunOpen input file: %s\200n", argv[1]\202; /* extract and bin the data section into a double float image buffer */ if\201 !\201buf = FunImageGet\201fun, NULL, "bitpix=-64"\202\202 \202 gerror\201stderr, "could not FunImageGet: %s\200n", argv[1]\202; /* get dimension information from funtools structure */ FunInfoGet\201fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0\202; /* loop through pixels and reset values below limit to value */ for\201i=0; i int FunImagePut\201Fun fun, void *buf, int dim1, int dim2, int bitpix, char *plist\202)RP()ES( The )BD(FunImagePut\201\202)ES( routine outputs an image array to a FITS file. The image is written either as a primary header/data unit or as an image extension, depending on whether other data have already been written to the file. That is, if the current file position is at the beginning of the file, a primary HDU is written. Otherwise, an image extension is written. )0 P(The first argument is the Funtools handle returned by )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(. The second )BD(buf)ES( argument is a pointer to a data buffer to write. The )BD(dim1)ES(and )BD(dim2)ES( arguments that follow specify the dimensions of the image, where dim1 corresponds to naxis1 and dim2 corresponds to naxis2. The )BD(bitpix)ES( argument specifies the data type of the image and can have the following FITS-standard values: )UL()-1 LI( 8 unsigned char )-1 LI( 16 short )-1 LI( 32 int )-1 LI( -32 float )-1 LI( -64 double)LU( )0 P(When )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D( is first called for a given image, Funtools checks to see if the primary header has already been written \201by having previously written an image or a binary table.\202 If not, this image is written to the primary HDU. Otherwise, it is written to an image extension. )0 P(Thus, a simple program to generate a FITS image might look like this: ) 16 67 PR( int i; int dim1=512, dim2=512; double *dbuf; Fun fun; dbuf = malloc\201dim1*dim2*sizeof\201double\202\202; /* open the output FITS image, preparing to copy input params */ if\201 !\201fun = FunOpen\201argv[1], "w", NULL\202\202 \202 gerror\201stderr, "could not FunOpen output file: %s\200n", argv[1]\202; for\201i=0; i<\201dim1*dim2\202; i++\202{ ... fill dbuf ... } /* put the image \201header will be generated automatically */ if\201 !FunImagePut\201fun, buf, dim1, dim2, -64, NULL\202 \202 gerror\201stderr, "could not FunImagePut: %s\200n", argv[1]\202; FunClose\201fun\202; free\201dbuf\202;)RP( )0 P(In addition, if a )0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( was specified when this table was opened, the parameters from this )0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( are merged into the new image header. Furthermore, if a reference image was specified during )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(, the values of )BD(dim1)ES(, )BD(dim2)ES(, and )BD(bitpix)ES( in the calling sequence can all be set to 0. In this case, default values are taken from the reference image section. This is useful if you are reading an image section in its native data format, processing it, and then writing that section to a new FITS file. See the )0 2 A(imblank example code)EA(. )0 P(The data are assumed to be in the native machine format and will automatically be swapped to FITS big-endian format if necessary. This behavior can be over-ridden with the )BD(convert=[true|false])ES( keyword in the )BD(plist)ES( param list string. )0 P(When you are finished writing the image, you should call )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( to write out the FITS image padding. However, this is not necessary if you subsequently call FunClose\201\202 without doing any other I/O to the FITS file. )0 2 36 H(FunImageRowGet)WB 102 Sn()WB 28 Sn( - get row\201s\202 of an image)EA()EH( )BD() 4 65 PR( #include void *FunImageRowGet\201Fun fun, void *buf, int rstart, int rstop, char *plist\202)RP()ES( )0 P(The )BD(FunImageRowGet\201\202)ES( routine returns one or more image rows from the specified section of a Funtools data file. If the input data are of type image, the array is generated by extracting the specified image rows and then binning them according to the specified bin factor. If the input data are contained in a binary table or raw event file, the rows are binned on the columns specified by the )BD(bincols=)ES( keyword \201using appropriate default columns as needed\202, after which the image section and bin factors are applied. )0 P(The first argument is the Funtools handle returned by )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(. The second )BD(buf)ES( argument is a pointer to a data buffer to fill. If NULL is specified, FunImageGet\201\202 will allocate a buffer of the appropriate size. )0 P(The third and fourth arguments specify the first and last row to retrieve. Rows are counted starting from 1, up to the value of FUN_YMAX\201fun\202. The final )BD(plist)ES( \201i.e., parameter list\202 argument is a string containing one or more comma-delimited )BD(keyword=value)ES( parameters. It can be used to specify the return data type using the )BD(bitpix=)ES( keyword. If no such keyword is specified in the plist string, the data type of the image is the same as the data type of the original input file, or is of type int for FITS binary tables. )0 P(If the )BD(bitpix=)ES(value is supplied in the plist string, the data type of the returned image will be one of the supported FITS image data types: )UL()-1 LI( 8 unsigned char )-1 LI( 16 short )-1 LI( 32 int )-1 LI( -32 float )-1 LI( -64 double)LU( )0 P(For example: ) 17 65 PR( double *drow; Fun fun; ... open files ... /* get section dimensions */ FunInfoGet\201fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0\202; /* allocate one line's worth */ drow = malloc\201dim1*sizeof\201double\202\202; /* retrieve and process each input row \201starting at 1\202 */ for\201i=1; i <= dim2; i++\202{ if\201 !FunImageRowGet\201fun, drow, i, i, "bitpix=-64"\202 \202 gerror\201stderr, "can't FunImageRowGet: %d %s\200n", i, iname\202; /* reverse the line */ for\201j=1; j<=dim1; j++\202{ ... process drow[j-1] ... } } ...)RP( )0 P(On success, a pointer to the image buffer is returned. \201This will be the same as the second argument, if NULL is not passed to the latter.\202 On error, NULL is returned. Note that the considerations described above for specifying binning columns in )0 26 1 A(FunImageGet\201\202)26 0 TN TL()Ec /AF f D( also apply to )BD(FunImageRowGet\201\202)ES(. )0 2 37 H(FunImageRowPut)WB 103 Sn()WB 29 Sn( - put row\201s\202 of an image)EA()EH( )BD() 4 67 PR( #include void *FunImageRowPut\201Fun fun, void *buf, int rstart, int rstop, int dim1, int dim2, int bitpix, char *plist\202)RP()ES( )0 P(The )BD(FunImageRowPut\201\202)ES( routine writes one or more image rows to the specified FITS image file. The first argument is the Funtools handle returned by )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(. The second )BD(buf)ES( argument is a pointer to the row data buffer, while the third and fourth arguments specify the starting and ending rows to write. Valid rows values range from 1 to dim2, i.e., row is one-valued. )0 P(The )BD(dim1)ES(and )BD(dim2)ES( arguments that follow specify the dimensions, where dim1 corresponds to naxis1 and dim2 corresponds to naxis2. The )BD(bitpix)ES( argument data type of the image and can have the following FITS-standard values: )UL()-1 LI( 8 unsigned char )-1 LI( 16 short )-1 LI( 32 int )-1 LI( -32 float )-1 LI( -64 double)LU( For example: ) 16 65 PR( double *drow; Fun fun, fun2; ... open files ... /* get section dimensions */ FunInfoGet\201fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0\202; /* allocate one line's worth */ drow = malloc\201dim1*sizeof\201double\202\202; /* retrieve and process each input row \201starting at 1\202 */ for\201i=1; i <= dim2; i++\202{ if\201 !FunImageRowGet\201fun, drow, i, i, "bitpix=-64"\202 \202 gerror\201stderr, "can't FunImageRowGet: %d %s\200n", i, iname\202; ... process drow ... if\201 !FunImageRowPut\201fun2, drow, i, i, 64, NULL\202 \202 gerror\201stderr, "can't FunImageRowPut: %d %s\200n", i, oname\202; } ...)RP( )0 P(The data are assumed to be in the native machine format and will automatically be swapped to big-endian FITS format if necessary. This behavior can be over-ridden with the )BD(convert=[true|false])ES( keyword in the )BD(plist)ES( param list string. )0 P(When you are finished writing the image, you should call )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( to write out the FITS image padding. However, this is not necessary if you subsequently call FunClose\201\202 without doing any other I/O to the FITS file. )0 2 38 H(FunColumnSelect)WB 104 Sn()WB 32 Sn( - select Funtools columns)EA()EH( )BD() 11 73 PR( #include int FunColumnSelect\201Fun fun, int size, char *plist, char *name1, char *type1, char *mode1, int offset1, char *name2, char *type2, char *mode2, int offset2, ..., NULL\202 int FunColumnSelectArr\201Fun fun, int size, char *plist, char **names, char **types, char **modes, int *offsets, int nargs\202;)RP()ES( The )BD(FunColumnSelect\201\202)ES( routine is used to select the columns from a Funtools binary table extension or raw event file for processing. This routine allows you to specify how columns in a file are to be read into a user record structure or written from a user record structure to an output FITS file. )0 P(The first argument is the Fun handle associated with this set of columns. The second argument specifies the size of the user record structure into which columns will be read. Typically, the sizeof\201\202 macro is used to specify the size of a record structure. The third argument allows you to specify keyword directives for the selection and is described in more detail below. )0 P(Following the first three required arguments is a variable length list of column specifications. Each column specification will consist of four arguments: )UL()-1 LI( )BD(name)ES(: the name of the column )-1 LI( )BD(type)ES(: the data type of the column as it will be stored in the user record struct \201not the data type of the input file\202. The following basic data types are recognized: )UL()-1 LI(A: ASCII characters )-1 LI(B: unsigned 8-bit char )-1 LI(I: signed 16-bit int )-1 LI(U: unsigned 16-bit int \201not standard FITS\202 )-1 LI(J: signed 32-bit int )-1 LI(V: unsigned 32-bit int \201not standard FITS\202 )-1 LI(E: 32-bit float )-1 LI(D: 64-bit float)LU( The syntax used is similar to that which defines the TFORM parameter in FITS binary tables. That is, a numeric repeat value can precede the type character, so that "10I" means a vector of 10 short ints, "E" means a single precision float, etc. Note that the column value from the input file will be converted to the specified data type as the data is read by )0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D(. )0 P([ A short digression regarding bit-fields: Special attention is required when reading or writing the FITS bit-field type \201"X"\202. Bit-fields almost always have a numeric repeat character preceding the 'X' specification. Usually this value is a multiple of 8 so that bit-fields fit into an integral number of bytes. For all cases, the byte size of the bit-field B is \201N+7\202/8, where N is the numeric repeat character. )0 P(A bit-field is most easily declared in the user struct as an array of type char of size B as defined above. In this case, bytes are simply moved from the file to the user space. If, instead, a short or int scalar or array is used, then the algorithm for reading the bit-field into the user space depends on the size of the data type used along with the value of the repeat character. That is, if the user data size is equal to the byte size of the bit-field, then the data is simply moved \201possibly with endian-based byte-swapping\202 from one to the other. If, on the other hand, the data storage is larger than the bit-field size, then a data type cast conversion is performed to move parts of the bit-field into elements of the array. Examples will help make this clear: )UL()-1 LI( If the file contains a 16X bit-field and user space specifies a 2B char array[2], then the bit-field is moved directly into the char array. )-1 LI( If the file contains a 16X bit-field and user space specifies a 1I scalar short int, then the bit-field is moved directly into the short int. )-1 LI( If the file contains a 16X bit-field and user space specifies a 1J scalar int, then the bit-field is type-cast to unsigned int before being moved \201use of unsigned avoids possible sign extension\202. )-1 LI( If the file contains a 16X bit-field and user space specifies a 2J int array[2], then the bit-field is handled as 2 chars, each of which are type-cast to unsigned int before being moved \201use of unsigned avoids possible sign extension\202. )-1 LI( If the file contains a 16X bit-field and user space specifies a 1B char, then the bit-field is treated as a char, i.e., truncation will occur. )-1 LI( If the file contains a 16X bit-field and user space specifies a 4J int array[4], then the results are undetermined. )LU( For all user data types larger than char, the bit-field is byte-swapped as necessary to convert to native format, so that bits in the resulting data in user space can be tested, masked, etc. in the same way regardless of platform.] )0 P(In addition to setting data type and size, the )BD(type)ES( specification allows a few ancillary parameters to be set, using the full syntax for )BD(type)ES(: ) 1 53 PR( [@][n][[['B']poff]][:[tlmin[:tlmax[:binsiz]]]])RP( )0 P(The special character "@" can be prepended to this specification to indicated that the data element is a pointer in the user record, rather than an array stored within the record. )0 P(The [n] value is an integer that specifies the number of elements that are in this column \201default is 1\202. TLMIN, TLMAX, and BINSIZ values also can be specified for this column after the type, separated by colons. If only one such number is specified, it is assumed to be TLMAX, and TLMIN and BINSIZ are set to 1. )0 P(The [poff] value can be used to specify the offset into an array. By default, this offset value is set to zero and the data specified starts at the beginning of the array. The offset usually is specified in terms of the data type of the column. Thus an offset specification of [5] means a 20-byte offset if the data type is a 32-bit integer, and a 40-byte offset for a double. If you want to specify a byte offset instead of an offset tied to the column data type, precede the offset value with 'B', e.g. [B6] means a 6-bye offset, regardless of the column data type. The [poff] is especially useful in conjunction with the pointer @ specification, since it allows the data element to anywhere stored anywhere in the allocated array. For example, a specification such as "@I[2]" specifies the third \201i.e., starting from 0\202 element in the array pointed to by the pointer value. A value of "@2I[4]" specifies the fifth and sixth values in the array. For example, consider the following specification: ) 12 67 PR( typedef struct EvStruct{ short x[4], *atp; } *Event, EventRec; /* set up the \201hardwired\202 columns */ FunColumnSelect\201 fun, sizeof\201EventRec\202, NULL, "2i", "2I ", "w", FUN_OFFSET\201Event, x\202, "2i2", "2I[2]", "w", FUN_OFFSET\201Event, x\202, "at2p", "@2I", "w", FUN_OFFSET\201Event, atp\202, "at2p4", "@2I[4]", "w", FUN_OFFSET\201Event, atp\202, "atp9", "@I[9]", "w", FUN_OFFSET\201Event, atp\202, "atb20", "@I[B20]", "w", FUN_OFFSET\201Event, atb\202, NULL\202;)RP( Here we have specified the following columns: )UL()-1 LI( 2i: two short ints in an array which is stored as part the record )-1 LI( 2i2: the 3rd and 4th elements of an array which is stored as part of the record )-1 LI( an array of at least 10 elements, not stored in the record but allocated elsewhere, and used by three different columns: )UL()-1 LI( at2p: 2 short ints which are the first 2 elements of the allocated array )-1 LI( at2p4: 2 short ints which are the 5th and 6th elements of the allocated array )-1 LI( atp9: a short int which is the 10th element of the allocated array)LU( )-1 LI( atb20: a short int which is at byte offset 20 of another allocated array)LU( In this way, several columns can be specified, all of which are in a single array. )BD(NB)ES(: it is the programmer's responsibility to ensure that specification of a positive value for poff does not point past the end of valid data. )-1 LI( )BD(read/write mode)ES(: "r" means that the column is read from an input file into user space by )0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D(, "w" means that the column is written to an output file. Both can specified at the same time. )-1 LI( )BD(offset)ES(: the offset into the user data to store this column. Typically, the macro FUN_OFFSET\201recname, colname\202 is used to define the offset into a record structure.)LU( )0 P(When all column arguments have been specified, a final NULL argument must added to signal the column selection list. )0 P(As an alternative to the varargs )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( routine, a non-varargs routine called )0 32 1 A(FunColumnSelectArr\201\202)32 0 TN TL()Ec /AF f D( also is available. The first three arguments \201fun, size, plist\202 of this routine are the same as in )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D(. Instead of a variable argument list, however, )0 32 1 A(FunColumnSelectArr\201\202)32 0 TN TL()Ec /AF f D( takes 5 additional arguments. The first 4 arrays arguments contain the names, types, modes, and offsets, respectively, of the columns being selected. The final argument is the number of columns that are contained in these arrays. It is the user's responsibility to free string space allocated in these arrays. )0 P(Consider the following example: ) 12 54 PR( typedef struct evstruct{ int status; float pi, pha, *phas; double energy; } *Ev, EvRec; FunColumnSelect\201fun, sizeof\201EvRec\202, NULL, "status", "J", "r", FUN_OFFSET\201Ev, status\202, "pi", "E", "r", FUN_OFFSET\201Ev, pi\202, "pha", "E", "r", FUN_OFFSET\201Ev, pha\202, "phas", "@9E", "r", FUN_OFFSET\201Ev, phas\202, NULL\202;)RP( )0 P(Each time a row is read into the Ev struct, the "status" column is converted to an int data type \201regardless of its data type in the file\202 and stored in the status value of the struct. Similarly, "pi" and "pha", and the phas vector are all stored as floats. Note that the "@" sign indicates that the "phas" vector is a pointer to a 9 element array, rather than an array allocated in the struct itself. The row record can then be processed as required: ) 9 70 PR( /* get rows -- let routine allocate the row array */ while\201 \201ebuf = \201Ev\202FunTableRowGet\201fun, NULL, MAXROW, NULL, &got\202\202 \202{ /* process all rows */ for\201i=0; ipi = \201ev->pi+.5\202; ev->pha = \201ev->pi-.5\202; })RP( )0 P()0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( can also be called to define "writable" columns in order to generate a FITS Binary Table, without reference to any input columns. For example, the following will generate a 4-column FITS binary table when )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D( is used to write Ev records: ) 12 56 PR( typedef struct evstruct{ int status; float pi, pha double energy; } *Ev, EvRec; FunColumnSelect\201fun, sizeof\201EvRec\202, NULL, "status", "J", "w", FUN_OFFSET\201Ev, status\202, "pi", "E", "w", FUN_OFFSET\201Ev, pi\202, "pha", "E", "w", FUN_OFFSET\201Ev, pha\202, "energy", "D", "w", FUN_OFFSET\201Ev, energy\202, NULL\202;)RP( All columns are declared to be write-only, so presumably the column data is being generated or read from some other source. )0 P(In addition, )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( can be called to define )BD(both)ES( "readable" and "writable" columns. In this case, the "read" columns are associated with an input file, while the "write" columns are associated with the output file. Of course, columns can be specified as both "readable" and "writable", in which case they are read from input and \201possibly modified data values are\202 written to the output. The )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( call itself is made by passing the input Funtools handle, and it is assumed that the output file has been opened using this input handle as its )0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D(. )0 P(Consider the following example: ) 13 54 PR( typedef struct evstruct{ int status; float pi, pha, *phas; double energy; } *Ev, EvRec; FunColumnSelect\201fun, sizeof\201EvRec\202, NULL, "status", "J", "r", FUN_OFFSET\201Ev, status\202, "pi", "E", "rw", FUN_OFFSET\201Ev, pi\202, "pha", "E", "rw", FUN_OFFSET\201Ev, pha\202, "phas", "@9E", "rw", FUN_OFFSET\201Ev, phas\202, "energy", "D", "w", FUN_OFFSET\201Ev, energy\202, NULL\202;)RP( As in the "read" example above, each time an row is read into the Ev struct, the "status" column is converted to an int data type \201regardless of its data type in the file\202 and stored in the status value of the struct. Similarly, "pi" and "pha", and the phas vector are all stored as floats. Since the "pi", "pha", and "phas" variables are declared as "writable" as well as "readable", they also will be written to the output file. Note, however, that the "status" variable is declared as "readable" only, and hence it will not be written to an output file. Finally, the "energy" column is declared as "writable" only, meaning it will not be read from the input file. In this case, it can be assumed that "energy" will be calculated in the program before being output along with the other values. )0 P(In these simple cases, only the columns specified as "writable" will be output using )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D(. However, it often is the case that you want to merge the user columns back in with the input columns, even in cases where not all of the input column names are explicitly read or even known. For this important case, the )BD(merge=[type])ES( keyword is provided in the plist string. )0 P(The )BD(merge=[type])ES( keyword tells Funtools to merge the columns from the input file with user columns on output. It is normally used when an input and output file are opened and the input file provides the )0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( for the output file. In this case, each time )0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D( is called, the raw input rows are saved in a special buffer. If )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D( then is called \201before another call to )0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D(\202, the contents of the raw input rows are merged with the user rows according to the value of )BD(type)ES( as follows: )UL()-1 LI( )BD(update)ES(: add new user columns, and update value of existing ones \201maintaining the input data type\202 )-1 LI( )BD(replace)ES(: add new user columns, and replace the data type and value of existing ones. \201Note that if tlmin/tlmax values are not specified in the replacing column, but are specified in the original column being replaced, then the original tlmin/tlmax values are used in the replacing column.\202 )-1 LI( )BD(append)ES(: only add new columns, do not "replace" or "update" existing ones)LU( )0 P(Consider the example above. If )BD(merge=update)ES( is specified in the plist string, then "energy" will be added to the input columns, and the values of "pi", "pha", and "phas" will be taken from the user space \201i.e., the values will be updated from the original values, if they were changed by the program\202. The data type for "pi", "pha", and "phas" will be the same as in the original file. If )BD(merge=replace)ES( is specified, both the data type and value of these three input columns will be changed to the data type and value in the user structure. If )BD(merge=append)ES( is specified, none of these three columns will be updated, and only the "energy" column will be added. Note that in all cases, "status" will be written from the input data, not from the user record, since it was specified as read-only. )0 P(Standard applications will call )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( to define user columns. However, if this routine is not called, the default behavior is to transfer all input columns into user space. For this purpose a default record structure is defined such that each data element is properly aligned on a valid data type boundary. This mechanism is used by programs such as fundisp and funtable to process columns without needing to know the specific names of those columns. It is not anticipated that users will need such capabilities \201contact us if you do!\202 )0 P(By default, )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( reads/writes rows to/from an "array of structs", where each struct contains the column values for a single row of the table. This means that the returned values for a given column are not contiguous. You can set up the IO to return a "struct of arrays" so that each of the returned columns are contiguous by specifying )BD(org=structofarrays)ES( \201abbreviation: )BD(org=soa)ES(\202 in the plist. \201The default case is )BD(org=arrayofstructs)ES( or )BD(org=aos)ES(.\202 )0 P(For example, the default setup to retrieve rows from a table would be to define a record structure for a single event and then call )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( as follows: ) 14 73 PR( typedef struct evstruct{ short region; double x, y; int pi, pha; double time; } *Ev, EvRec; got = FunColumnSelect\201fun, sizeof\201EvRec\202, NULL, "x", "D:10:10", mode, FUN_OFFSET\201Ev, x\202, "y", "D:10:10", mode, FUN_OFFSET\201Ev, y\202, "pi", "J", mode, FUN_OFFSET\201Ev, pi\202, "pha", "J", mode, FUN_OFFSET\201Ev, pha\202, "time", "1D", mode, FUN_OFFSET\201Ev, time\202, NULL\202;)RP( Subsequently, each call to FunTableRowGet\201\202)EA( will return an array of structs, one for each returned row. If instead you wanted to read columns into contiguous arrays, you specify )BD(org=soa)ES(: ) 14 72 PR( typedef struct aevstruct{ short region[MAXROW]; double x[MAXROW], y[MAXROW]; int pi[MAXROW], pha[MAXROW]; double time[MAXROW]; } *AEv, AEvRec; got = FunColumnSelect\201fun, sizeof\201AEvRec\202, "org=soa", "x", "D:10:10", mode, FUN_OFFSET\201AEv, x\202, "y", "D:10:10", mode, FUN_OFFSET\201AEv, y\202, "pi", "J", mode, FUN_OFFSET\201AEv, pi\202, "pha", "J", mode, FUN_OFFSET\201AEv, pha\202, "time", "1D", mode, FUN_OFFSET\201AEv, time\202, NULL\202;)RP( Note that the only modification to the call is in the plist string. )0 P(Of course, instead of using staticly allocated arrays, you also can specify dynamically allocated pointers: ) 16 75 PR( /* pointers to arrays of columns \201used in struct of arrays\202 */ typedef struct pevstruct{ short *region; double *x, *y; int *pi, *pha; double *time; } *PEv, PEvRec; got = FunColumnSelect\201fun, sizeof\201PEvRec\202, "org=structofarrays", "$region", "@I", mode, FUN_OFFSET\201PEv, region\202, "x", "@D:10:10", mode, FUN_OFFSET\201PEv, x\202, "y", "@D:10:10", mode, FUN_OFFSET\201PEv, y\202, "pi", "@J", mode, FUN_OFFSET\201PEv, pi\202, "pha", "@J", mode, FUN_OFFSET\201PEv, pha\202, "time", "@1D", mode, FUN_OFFSET\201PEv, time\202, NULL\202;)RP( Here, the actual storage space is either allocated by the user or by the )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( call\202. )0 P(In all of the above cases, the same call is made to retrieve rows, e.g.: ) 1 64 PR( buf = \201void *\202FunTableRowGet\201fun, NULL, MAXROW, NULL, &got\202;)RP( However, the individual data elements are accessed differently. For the default case of an "array of structs", the individual row records are accessed using: ) 5 69 PR( for\201i=0; ix, ev->y, ev->pi, ev->pha, ev->dx, ev->dy, ev->time\202; })RP( For a struct of arrays or a struct of array pointers, we have a single struct through which we access individual columns and rows using: ) 6 63 PR( aev = \201AEv\202buf; for\201i=0; ix[i], aev->y[i], aev->pi[i], aev->pha[i], aev->dx[i], aev->dy[i], aev->time[i]\202; })RP( Support for struct of arrays in the )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D( call is handled analogously. )0 P(See the )0 2 A(evread example code)EA( and )0 2 A(evmerge example code)EA( for working examples of how )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( is used. )0 2 39 H(FunColumnActivate)WB 105 Sn()WB 33 Sn( - activate Funtools columns)EA()EH( )BD() 3 55 PR( #include void FunColumnActivate\201Fun fun, char *s, char *plist\202)RP()ES( )0 P(The )BD(FunColumnActivate\201\202)ES( routine determines which columns \201set up by )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D(\202 ultimately will be read and/or written. By default, all columns that are selected using )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( are activated. The )0 33 1 A(FunColumnActivate\201\202)33 0 TN TL()Ec /AF f D( routine can be used to turn off/off activation of specific columns. )0 P(The first argument is the Fun handle associated with this set of columns. The second argument is a space-delimited list of columns to activate or de-activate. Columns preceded by "+" are activated and columns preceded by a "-" are de-activated. If a column is named without "+" or "-", it is activated. The reserved strings "$region" and '$n' are used to activate a special columns containing the filter region value and row value, respectively, associated with this row. For example, if a filter containing two circular regions is specified as part of the Funtools file name, this column will contain a value of 1 or 2, depending on which region that row was in. The reserved strings "$x" and "$y" are used to activate the current binning columns. Thus, if the columns DX and DY are specified as binning columns: ) 1 42 PR( [sh $] fundisp foo.fits[bincols=\201DX,DY\202])RP( then "$x" and "$y" will refer to these columns in a call to )0 33 1 A(FunColumnActivate\201\202)33 0 TN TL()Ec /AF f D(. )0 P(In addition, if the activation string contains only columns to be activated, then the routine will de-activate all other columns. Similarly, if the activation string contains only columns to de-activate, then the routine will activate all other columns before activating the list. This makes it simple to change the activation state of all columns without having to know all of the column names. For example: )UL()-1 LI( )BD("pi pha time")ES( # only these three columns will be active )-1 LI( )BD("-pi -pha -time")ES( # all but these columns will be active )-1 LI( )BD("pi -pha")ES( # only pi is active, pha is not, others are not )-1 LI( )BD("+pi -pha")ES( # same as above )-1 LI( )BD("pi -pha -time")ES( # only pi is active, all others are not )-1 LI( )BD("pi pha")ES( # pha and pi are active, all others are not )-1 LI( )BD("pi pha -x -y")ES( # pha and pi are active, all others are not)LU( )0 P(You can use the column activation list to reorder columns, since columns are output in the order specified. For example: ) 19 77 PR( # default output order fundisp snr.ev'[cir 512 512 .1]' X Y PHA PI TIME DX DY -------- -------- -------- -------- --------------------- -------- -------- 512 512 6 7 79493997.45854475 578 574 512 512 8 9 79494575.58943175 579 573 512 512 5 6 79493631.03866175 578 575 512 512 5 5 79493290.86521725 578 575 512 512 8 9 79493432.00990875 579 573 # re-order the output by specifying explicit order fundisp snr.ev'[cir 512 512 .1]' "time x y dy dx pi pha" TIME X Y DY DX PI PHA --------------------- -------- -------- -------- -------- -------- -------- 79493997.45854475 512 512 574 578 7 6 79494575.58943175 512 512 573 579 9 8 79493631.03866175 512 512 575 578 6 5 79493290.86521725 512 512 575 578 5 5 79493432.00990875 512 512 573 579 9 8)RP( )0 P(A "+" sign by itself means to activate all columns, so that you can reorder just a few columns without specifying all of them: ) 9 77 PR( # reorder 3 columns and then output the rest fundisp snr.ev'[cir 512 512 .1]' "time pi pha +" TIME PI PHA Y X DX DY --------------------- -------- -------- -------- -------- -------- -------- 79493997.45854475 7 6 512 512 578 574 79494575.58943175 9 8 512 512 579 573 79493631.03866175 6 5 512 512 578 575 79493290.86521725 5 5 512 512 578 575 79493432.00990875 9 8 512 512 579 573)RP( The column activation/deactivation is performed in the order of the specified column arguments. This means you can mix "+", "-" \201which de-activates all columns\202 and specific column names to reorder and select columns in one command. For example, consider the following: ) 9 59 PR( # reorder and de-activate fundisp snr.ev'[cir 512 512 .1]' "time pi pha + -x -y" TIME PI PHA DX DY --------------------- -------- -------- -------- -------- 79493997.45854475 7 6 578 574 79494575.58943175 9 8 579 573 79493631.03866175 6 5 578 575 79493290.86521725 5 5 578 575 79493432.00990875 9 8 579 573)RP( We first activate "time", "pi", and "pha" so that they are output first. We then activate all of the other columns, and then de-activate "x" and "y". Note that this is different from: ) 9 77 PR( # probably not what you want ... fundisp snr.ev'[cir 512 512 .1]' "time pi pha -x -y +" TIME PI PHA Y X DX DY --------------------- -------- -------- -------- -------- -------- -------- 79493997.45854475 7 6 512 512 578 574 79494575.58943175 9 8 512 512 579 573 79493631.03866175 6 5 512 512 578 575 79493290.86521725 5 5 512 512 578 575 79493432.00990875 9 8 512 512 579 573)RP( Here, "x" and "y" are de-activated, but then all columns including "x" and "y" are again re-activated. )0 P(Typically, )0 33 1 A(FunColumnActivate\201\202)33 0 TN TL()Ec /AF f D( uses a list of columns that are passed into the program from the command line. For example, the code for funtable contains the following: ) 9 66 PR( char *cols=NULL; /* open the input FITS file */ if\201 !\201fun = FunOpen\201argv[1], "rc", NULL\202\202 \202 gerror\201stderr, "could not FunOpen input file: %s\200n", argv[1]\202; /* set active flag for specified columns */ if\201 argc >= 4 \202 cols = argv[3]; FunColumnActivate\201fun, cols, NULL\202;)RP( The )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( call sets the default columns to be all columns in the input file. The )0 33 1 A(FunColumnActivate\201\202)33 0 TN TL()Ec /AF f D( call then allows the user to control which columns ultimately will be activated \201i.e., in this case, written to the new file\202. For example: ) 1 39 PR( funtable test.ev foo.ev "pi pha time")RP( will process only the three columns mentioned, while: ) 1 33 PR( funtable test.ev foo.ev "-time")RP( will process all columns except "time". )0 P(If )0 33 1 A(FunColumnActivate\201\202)33 0 TN TL()Ec /AF f D( is called with a null string, then the environment variable )BD(FUN_COLUMNS)ES( will be used to provide a global value, if present. This is the reason why we call the routine even if no columns are specified on the command line \201see example above\202, instead of calling it this way: ) 4 45 PR( /* set active flag for specified columns */ if\201 argc >= 4 \202{ FunColumnActivate\201fun, argv[3], NULL\202; })RP( )0 2 40 H(FunColumnLookup)WB 106 Sn()WB 34 Sn( - lookup a Funtools column)EA()EH( )BD() 5 56 PR( #include int FunColumnLookup\201Fun fun, char *s, int which, char **name, int *type, int *mode, int *offset, int *n, int *width\202)RP()ES( )0 P(The )BD(FunColumnLookup\201\202)ES( routine returns information about a named \201or indexed\202 column. The first argument is the Fun handle associated with this set of columns. The second argument is the name of the column to look up. If the name argument is NULL, the argument that follows is the zero-based index into the column array of the column for which information should be returned. The next argument is a pointer to a char *, which will contain the name of the column. The arguments that follow are the addresses of int values into which the following information will be returned: )UL()-1 LI( )BD(type)ES(: data type of column: )UL()-1 LI(A: ASCII characters )-1 LI(B: unsigned 8-bit char )-1 LI(I: signed 16-bit int )-1 LI(U: unsigned 16-bit int \201not standard FITS\202 )-1 LI(J: signed 32-bit int )-1 LI(V: unsigned 32-bit int \201not standard FITS\202 )-1 LI(E: 32-bit float )-1 LI(D: 64-bit float)LU( )-1 LI( )BD(mode)ES(: bit flag status of column, including: )UL()-1 LI( COL_ACTIVE 1 is column activated? )-1 LI( COL_IBUF 2 is column in the raw input data? )-1 LI( COL_PTR 4 is column a pointer to an array? )-1 LI( COL_READ 010 is read mode selected? )-1 LI( COL_WRITE 020 is write mode selected? )-1 LI( COL_REPLACEME 040 is this column being replaced by user data?)LU( )-1 LI( )BD(offset)ES(: byte offset in struct )-1 LI( )BD(n)ES(: number of elements \201i.e. size of vector\202 in this column )-1 LI( )BD(width)ES(: size in bytes of this column)LU( If the named column exists, the routine returns a positive integer, otherwise zero is returned. \201The positive integer is the index+1 into the column array where this column was located.\202 If NULL is passed as the return address of one \201or more\202 of these values, no data is passed back for that information. For example: ) 2 76 PR( if\201 !FunColumnLookup\201fun, "phas", 0, NULL NULL, NULL, NULL, &npha, NULL\202 \202 gerror\201stderr, "can't find phas column\200n"\202;)RP( only returns information about the size of the phas vector. )0 2 41 H(FunTableRowGet)WB 107 Sn()WB 30 Sn( - get Funtools rows)EA()EH( )BD() 4 68 PR( #include void *FunTableRowGet\201Fun fun, void *rows, int maxrow, char *plist, int *nrow\202)RP()ES( )0 P(The )BD(FunTableRowGet\201\202)ES( routine retrieves rows from a Funtools binary table or raw event file, and places the values of columns selected by )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( into an array of user structs. Selected column values are automatically converted to the specified user data type \201and to native data format\202 as necessary. )0 P(The first argument is the Fun handle associated with this row data. The second )BD(rows)ES( argument is the array of user structs into which the selected columns will be stored. If NULL is passed, the routine will automatically allocate space for this array. \201This includes proper allocation of pointers within each struct, if the "@" pointer type is used in the selection of columns. Note that if you pass NULL in the second argument, you should free this space using the standard free\201\202 system call when you are finished with the array of rows.\202 The third )BD(maxrow)ES( argument specifies the maximum number of rows to be returned. Thus, if )BD(rows)ES( is allocated by the user, it should be at least of size maxrow*sizeof\201evstruct\202. )0 P(The fourth )BD(plist)ES( argument is a param list string. Currently, the keyword/value pair "mask=transparent" is supported in the plist argument. If this string is passed in the call's plist argument, then all rows are passed back to the user \201instead of just rows passing the filter\202. This is only useful when )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( also is used to specify "$region" as a column to return for each row. In such a case, rows found within a region have a returned region value greater than 0 \201corresponding to the region id of the region in which they are located\202, rows passing the filter but not in a region have region value of -1, and rows not passing any filter have region value of 0. Thus, using "mask=transparent" and the returned region value, a program can process all rows and decide on an action based on whether a given row passed the filter or not. )0 P(The final argument is a pointer to an int variable that will return the actual number of rows returned. The routine returns a pointer to the array of stored rows, or NULL if there was an error. \201This pointer will be the same as the second argument, if the latter is non-NULL\202. ) 16 69 PR( /* get rows -- let routine allocate the row array */ while\201 \201buf = \201Ev\202FunTableRowGet\201fun, NULL, MAXROW, NULL, &got\202\202 \202{ /* process all rows */ for\201i=0; ienergy = \201ev->pi+ev->pha\202/2.0; ev->pha = -ev->pha; ev->pi = -ev->pi; } /* write out this batch of rows */ FunTableRowPut\201fun2, buf, got, 0, NULL\202; /* free row data */ if\201 buf \202 free\201buf\202; })RP( As shown above, successive calls to )0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D( will return the next set of rows from the input file until all rows have been read, i.e., the routine behaves like sequential Unix I/O calls such as fread\201\202. See )0 2 A(evmerge example code)EA( for a more complete example. )0 P(Note that FunTableRowGet\201\202 also can be called as FunEventsGet\201\202, for backward compatibility. )0 2 42 H(FunTableRowPut)WB 108 Sn()WB 31 Sn( - put Funtools rows)EA()EH( ) 1 70 PR()BD(int FunTableRowPut\201Fun fun, void *rows, int nev, int idx, char *plist\202)ES()RP( The )BD(FunTableRowPut\201\202)ES( routine writes rows to a FITS binary table, taking its input from an array of user structs that contain column values selected by a previous call to )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D(. Selected column values are automatically converted from native data format to FITS data format as necessary. )0 P(The first argument is the Fun handle associated with this row data. The second )BD(rows)ES( argument is the array of user structs to output. The third )BD(nrow)ES( argument specifies the number number of rows to write. The routine will write )BD(nrow)ES( records, starting from the location specified by )BD(rows)ES(. )0 P(The fourth )BD(idx)ES( argument is the index of the first raw input row to write, in the case where rows from the user buffer are being merged with their raw input row counterparts \201see below\202. Note that this )BD(idx)ES( value is has nothing to do with the row buffer specified in argument 1. It merely matches the row being written with its corresponding \201hidden\202 raw row. Thus, if you read a number of rows, process them, and then write them out all at once starting from the first user row, the value of )BD(idx)ES( should be 0: ) 14 70 PR( Ev ebuf, ev; /* get rows -- let routine allocate the row array */ while\201 \201ebuf = \201Ev\202FunTableRowGet\201fun, NULL, MAXROW, NULL, &got\202\202 \202{ /* process all rows */ for\201i=0; i int FunParamGetb\201Fun fun, char *name, int n, int defval, int *got\202 int FunParamGeti\201Fun fun, char *name, int n, int defval, int *got\202 double FunParamGetd\201Fun fun, char *name, int n, double defval, int *got\202 char *FunParamGets\201Fun fun, char *name, int n, char *defval, int *got\202)RP()ES( )0 P(The four routines )BD(FunParamGetb\201\202)ES(, )BD(FunParamGeti\201\202)ES(, )BD(FunParamGetd\201\202)ES(, and )BD(FunParamGets\201\202)ES(, return the value of a FITS header parameter as a boolean, int, double, and string, respectively. The string returned by )BD(FunParamGets\201\202)ES( is a malloc'ed copy of the header value and should be freed when no longer needed. )0 P(The first argument is the Fun handle associated with the FITS header being accessed. Normally, the header is associated with the FITS extension that you opened with )BD(FunOpen\201\202)ES(. However, you can use FunInfoPut\201\202 to specify access of the primary header. In particular, if you set the FUN_PRIMARYHEADER parameter to 1, then the primary header is used for all parameter access until the value is reset to 0. For example: ) 9 75 PR( int val; FunParamGeti\201fun, "NAXIS", 1, 0, &got\202; # current header val=1; FunInfoPut\201fun, FUN_PRIMARYHEADER, &val, 0\202; # switch to ... FunParamGeti\201fun, "NAXIS", 1, 0, &got\202; # ... primary header FunParamGeti\201fun, "NAXIS", 2, 0, &got\202; # ... primary header val=0; FunInfoPut\201fun, FUN_PRIMARYHEADER, &val, 0\202; # switch back to ... FunParamGeti\201fun, "NAXIS", 2, 0, &got\202; # current header)RP( )0 P(Alternatively, you can use the FUN_PRIMARY macro to access parameters from the primary header on a per-parameter basis: ) 2 72 PR( FunParamGeti\201fun, "NAXIS1", 0, 0, &got\202; # current header FunParamGeti\201FUN_PRIMARY\201fun\202, "NAXIS1", 0, 0, &got\202; # primary header)RP( )BD(NB: FUN_PRIMARY is deprecated.)ES( It makes use of a global parameter and therefore will not not appropriate for threaded applications, when we make funtools thread-safe. We recommend use of FunInfoPut\201\202 to switch between the extension header and the primary header. )0 P(For output data, access to the primary header is only possible until the header is written out, which usually takes place when the first data are written. )0 P(The second argument is the name of the parameter to access. The third )BD(n)ES( argument, if non-zero, is an integer that will be added as a suffix to the parameter name. This makes it easy to use a simple loop to process parameters having the same root name. For example, to gather up all values of TLMIN and TLMAX for each column in a binary table, you can use: ) 4 74 PR( for\201i=0, got=1; got; i++\202{ fun->cols[i]->tlmin = \201int\202FunParamGeti\201fun, "TLMIN", i+1, 0.0, &got\202; fun->cols[i]->tlmax = \201int\202FunParamGeti\201fun, "TLMAX", i+1, 0.0, &got\202; })RP( )0 P(The fourth )BD(defval)ES( argument is the default value to return if the parameter does not exist. Note that the data type of this parameter is different for each specific FunParamGet\201\202 call. The final )BD(got)ES( argument will be 0 if no param was found. Otherwise the data type of the parameter is returned as follows: FUN_PAR_UNKNOWN \201'u'\202, FUN_PAR_COMMENT \201'c'\202, FUN_PAR_LOGICAL \201'l'\202, FUN_PAR_INTEGER \201'i'\202, FUN_PAR_STRING \201's'\202, FUN_PAR_REAL \201'r'\202, FUN_PAR_COMPLEX \201'x'\202. )0 P(These routines return the value of the header parameter, or the specified default value if the header parameter does not exist. The returned value is a malloc'ed string and should be freed when no longer needed. )0 P(By default, )BD(FunParamGets\201\202)ES( returns the string value of the named parameter. However, you can use FunInfoPut\201\202 to retrieve the raw 80-character FITS card instead. In particular, if you set the FUN_RAWPARAM parameter to 1, then card images will be returned by FunParamGets\201\202 until the value is reset to 0. )0 P(Alternatively, if the FUN_RAW macro is applied to the name, then the 80-character raw FITS card is returned instead. )BD(NB: FUN_RAW is deprecated.)ES( It makes use of a global parameter and therefore will not not appropriate for threaded applications, when we make funtools thread-safe. We recommend use of FunInfoPut\201\202 to switch between the extension header and the primary header. )0 P(Note that in addition to the behaviors described above, the routine )BD(FunParamGets\201\202)ES( will return the 80 raw characters of the )BD(nth)ES( FITS card \201including the comment\202 if )BD(name)ES( is specified as NULL and )BD(n)ES( is positive. For example, to loop through all FITS header cards in a given extension and print out the raw card, use: ) 9 55 PR( for\201i=1; ;i++\202{ if\201 \201s = FunParamGets\201fun, NULL, i, NULL, &got\202\202 \202{ fprintf\201stdout, "%.80s\200n", s\202; free\201s\202; } else{ break; } })RP( )0 2 43 H(FunParamPut)WB 109 Sn()WB 38 Sn( - put a Funtools param value)EA()EH( )BD() 13 71 PR( #include int FunParamPutb\201Fun fun, char *name, int n, int value, char *comm, int append\202 int FunParamPuti\201Fun fun, char *name, int n, int value, char *comm, int append\202 int FunParamPutd\201Fun fun, char *name, int n, double value, int prec, char *comm, int append\202 int FunParamPuts\201Fun fun, char *name, int n, char *value, char *comm, int append\202)RP()ES( )0 P(The four routines )BD(FunParamPutb\201\202)ES(, )BD(FunParamPuti\201\202)ES(, )BD(FunParamPutd\201\202)ES(, and )BD(FunParamPuts\201\202)ES(, will set the value of a FITS header parameter as a boolean, int, double, and string, respectively. )0 P(The first argument is the Fun handle associated with the FITS header being accessed. Normally, the header is associated with the FITS extension that you opened with )BD(FunOpen\201\202)ES(. However, you can use FunInfoPut\201\202 to specify that use of the primary header. In particular, if you set the FUN_PRIMARYHEADER parameter to 1, then the primary header is used for all parameter access until the value is reset to 0. For example: ) 5 69 PR( int val; FunParamPuti\201fun, "NAXIS1", 0, 10, NULL, 1\202; # current header val=1; FunInfoPut\201fun, FUN_PRIMARYHEADER, &val, 0\202; # switch to ... FunParamPuti\201fun, "NAXIS1", 0, 10, NULL, 1\202; # primary header)RP( \201You also can use the deprecated FUN_PRIMARY macro, to access parameters from the primary header.\202 )0 P(The second argument is the )BD(name)ES( of the parameter. \201 In accordance with FITS standards, the special names )BD(COMMENT)ES( and )BD(HISTORY)ES(, as well as blank names, are output without the "= " value indicator in columns 9 and 10. )0 P(The third )BD(n)ES( argument, if non-zero, is an integer that will be added as a suffix to the parameter name. This makes it easy to use a simple loop to process parameters having the same root name. For example, to set the values of TLMIN and TLMAX for each column in a binary table, you can use: ) 4 70 PR( for\201i=0; i int FunInfoGet\201Fun fun, int type, char *addr, ...\202)RP()ES( )0 P(The )BD(FunInfoGet\201\202)ES( routine returns information culled from the Funtools structure. The first argument is the Fun handle from which information is to be retrieved. This first required argument is followed by a variable length list of pairs of arguments. Each pair consists of an integer representing the type of information to retrieve and the address where the information is to be stored. The list is terminated by a 0. The routine returns the number of get actions performed. )0 P(The full list of available information is described below. Please note that only a few of these will be useful to most application developers. For imaging applications, the most important types are: ) 3 47 PR( FUN_SECT_DIM1 int /* dim1 for section */ FUN_SECT_DIM2 int /* dim2 for section */ FUN_SECT_BITPIX int /* bitpix for section */)RP( These would be used to determine the dimensions and data type of image data retrieved using the )0 26 1 A(FunImageGet\201\202)26 0 TN TL()Ec /AF f D( routine. For example: ) 17 68 PR( /* extract and bin the data section into an image buffer */ buf = FunImageGet\201fun, NULL, NULL\202; /* get required information from funtools structure. this should come after the FunImageGet\201\202 call, in case the call changed sect_bitpix */ FunInfoGet\201fun, FUN_SECT_BITPIX, &bitpix, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0\202; /* loop through pixels and reset values below limit to value */ for\201i=0; i void pix2wcs \201wcs,xpix,ypix,xpos,ypos\202 struct WorldCoor *wcs; /* World coordinate system structure */ double xpix,ypix; /* x and y coordinates in pixels */ double *xpos,*ypos; /* RA and Dec in degrees \201returned\202 */)RP( which converts pixel coordinates to sky coordinates, and: ) 5 67 PR( void wcs2pix \201wcs, xpos, ypos, xpix, ypix, offscl\202 struct WorldCoor *wcs; /* World coordinate system structure */ double xpos,ypos; /* World coordinates in degrees */ double *xpix,*ypix; /* coordinates in pixels */ int *offscl; /* 0 if within bounds, else off scale */)RP( which converts sky coordinates to pixel coordinates. Again, please note that the wcs structure returned by FUN_WCS assumes that image coordinates are passed to the pix2wcs routine, while FUN_WCS0 assumes that physical coordinates are passed. )0 P(Note that funtools.h file automatically includes wcs.h. An example program that utilizes these WCS structure to call WCS Library routines is )0 2 A(twcs.c)EA(. )0 P(The following is the complete list of information that can be returned: ) 52 79 PR( name type comment --------- -------- --------------------------------------------- FUN_FNAME char * /* file name */ FUN_GIO GIO /* gio handle */ FUN_HEADER FITSHead /* fitsy header struct */ FUN_TYPE int /* TY_TABLE,TY_IMAGE,TY_EVENTS,TY_ARRAY */ FUN_BITPIX int /* bits/pixel in file */ FUN_MIN1 int /* tlmin of axis1 -- tables */ FUN_MAX1 int /* tlmax of axis1 -- tables */ FUN_MIN2 int /* tlmin of axis2 -- tables */ FUN_MAX2 int /* tlmax of axis2 -- tables */ FUN_DIM1 int /* dimension of axis1 */ FUN_DIM2 int /* dimension of axis2 */ FUN_ENDIAN int /* 0=little, 1=big endian */ FUN_FILTER char * /* supplied filter */ FUN_IFUN FITSHead /* pointer to reference header */ FUN_IFUN0 FITSHead /* same as above, but no reset performed */ /* image information */ FUN_DTYPE int /* data type for images */ FUN_DLEN int /* length of image in bytes */ FUN_DPAD int /* padding to end of extension */ FUN_DOBLANK int /* was blank keyword defined? */ FUN_BLANK int /* value for blank */ FUN_SCALED int /* was bscale/bzero defined? */ FUN_BSCALE double /* bscale value */ FUN_BZERO double /* bzero value */ /* table information */ FUN_NROWS int /* number of rows in file \201naxis2\202 */ FUN_ROWSIZE int /* size of user row struct */ FUN_BINCOLS char * /* specified binning columns */ FUN_OVERFLOW int /* overflow detected during binning? */)WR( /* array information */ FUN_SKIP int /* bytes to skip in array header */ /* section information */ FUN_SECT_X0 int /* low dim1 value of section */ FUN_SECT_X1 int /* hi dim1 value of section */ FUN_SECT_Y0 int /* low dim2 value of section */ FUN_SECT_Y1 int /* hi dim2 value of section */ FUN_SECT_BLOCK int /* section block factor */ FUN_SECT_BTYPE int /* 's' \201sum\202, 'a' \201average\202 for binning */ FUN_SECT_DIM1 int /* dim1 for section */ FUN_SECT_DIM2 int /* dim2 for section */ FUN_SECT_BITPIX int /* bitpix for section */ FUN_SECT_DTYPE int /* data type for section */ FUN_RAWBUF char * /* pointer to raw row buffer */ FUN_RAWSIZE int /* byte size of raw row records */ /* column information */ FUN_NCOL int /* number of row columns defined */ FUN_COLS FunCol /* array of row columns */ /* WCS information */ FUN_WCS struct WorldCoor * /* wcs structure, converted for images*/ FUN_WCS0 struct WorldCoor * /* wcs structure, not converted */)RP( )0 P(Row applications would not normally need any of this information. An example of how these values can be used in more complex programs is the )0 2 A(evnext example code)EA(. In this program, the time value for each row is changed to be the value of the succeeding row. The program thus reads the time values for a batch of rows, changes the time values to be the value for the succeeding row, and then merges these changed time values back with the other columns to the output file. It then reads the next batch, etc. )0 P(This does not work for the last row read in each batch, since there is no succeeding row until the next batch is read. Therefore, the program saves that last row until it has read the next batch, then processes the former before starting on the new batch. In order to merge the last row successfully, the code uses FUN_RAWBUF to save and restore the raw input data associated with each batch of rows. Clearly, this requires some information about how funtools works internally. We are happy to help you write such programs as the need arises. )0 2 45 H(FunInfoPut)WB 111 Sn()WB 36 Sn( - put information into a Funtools struct)EA()EH( )BD() 3 52 PR( #include int FunInfoPut\201Fun fun, int type, char *addr, ...\202)RP()ES( )0 P(The )BD(FunInfoPut\201\202)ES( routine puts information into a Funtools structure. The first argument is the Fun handle from which information is to be retrieved. After this first required argument comes a variable length list of pairs of arguments. Each pair consists of an integer representing the type of information to store and the address of the new information to store in the struct. The variable list is terminated by a 0. The routine returns the number of put actions performed. )0 P(The full list of available information is described above with the )0 36 1 A(FunInfoPut\201\202)36 0 TN TL()Ec /AF f D( routine. Although use of this routine is expected to be uncommon, there is one important situation in which it plays an essential part: writing multiple extensions to a single output file. )0 P(For input, multiple extensions are handled by calling )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( for each extension to be processed. When opening multiple inputs, it sometimes is the case that you will want to process them and then write them \201including their header parameters\202 to a single output file. To accomplish this, you open successive input extensions using )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( and then call )BD(FunInfoPut\201\202)ES( to set the )0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( of the output file to that of the newly opened input extension: ) 4 71 PR( /* open a new input extension */ ifun=FunOpen\201tbuf, "r", NULL\202\202 \202 /* make the new extension the reference handle for the output file */ FunInfoPut\201ofun, FUN_IFUN, &ifun, 0\202;)RP( Resetting FUN_IFUN has same effect as when a funtools handle is passed as the final argument to )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(. The state of the output file is reset so that a new extension is ready to be written. Thus, the next I/O call on the output extension will output the header, as expected. )0 P(For example, in a binary table, after resetting FUN_IFUN you can then call )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( to select the columns for output. When you then call )0 27 1 A(FunImagePut\201\202)27 0 TN TL()Ec /AF f D( or )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D(, a new extension will be written that contains the header parameters from the reference extension. Remember to call )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( to complete output of a given extension. )0 P(A complete example of this capability is given in the )0 2 A(evcol example code)EA(. The central algorithm is: )UL()-1 LI( open the output file without a reference handle )-1 LI( loop: open each input extension in turn )UL()-1 LI( set the reference handle for output to the newly opened input extension )-1 LI( read the input rows or image and perform processing )-1 LI( write new rows or image to the output file )-1 LI( flush the output )-1 LI( close input extension)LU( )-1 LI( close output file)LU( Note that )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( is called after processing each input extension in order to ensure that the proper padding is written to the output file. A call to )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( also ensures that the extension header is written to the output file in the case where there are no rows to output. )0 P(If you wish to output a new extension without using a )0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D(, you can call FunInfoPut\201\202 to reset the FUN_OPS value directly. For a binary table, you would then call FunColumnSelect\201\202 to set up the columns for this new extension. ) 6 59 PR( /* reset the operations performed on this handle */ int ops=0; FunInfoPut\201ofun, FUN_OPS, &ops, 0\202; FunColumnSelect\201fun, sizeof\201EvRec\202, NULL, "MYCOL", "J", "w", FUN_OFFSET\201Ev, mycol\202, NULL\202;)RP( Once the FUN_OPS variable has been reset, the next I/O call on the output extension will output the header, as expected. )0 2 46 H(FunFlush)WB 112 Sn()WB 39 Sn( - flush data to output file)EA()EH( )BD() 3 37 PR( #include void FunFlush\201Fun fun, char *plist\202)RP()ES( )0 P(The )BD(FunFlush)ES( routine will flush data to a FITS output file. In particular, it can be called after all rows have been written \201using the )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D( routine\202 in order to add the null padding that is required to complete a FITS block. It also should be called after completely writing an image using )0 27 1 A(FunImagePut\201\202)27 0 TN TL()Ec /AF f D( or after writing the final row of an image using )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D(. )0 P(The )BD(plist)ES( \201i.e., parameter list\202 argument is a string containing one or more comma-delimited )BD(keyword=value)ES( parameters. If the plist string contains the parameter "copy=remainder" and the file was opened with a reference file, which, in turn, was opened for extension copying \201i.e. the input )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( mode also was "c" or "C"\202, then FunFlush also will copy the remainder of the FITS extensions from the input reference file to the output file. This normally would be done only at the end of processing. )0 P(Note that )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( is called with "copy=remainder" in the mode string by FunClose\201\202. This means that if you close the output file before the reference input file, it is not necessary to call )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( explicitly, unless you are writing more than one extension. See the )0 2 A(evmerge example code)EA(. However, it is safe to call )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( more than once without fear of re-writing either the padding or the copied extensions. )0 P(In addition, if )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( is called on an output file with the plist set to "copy=reference" and if the file was opened with a reference file, the reference extension is written to the output file. This mechanism provides a simple way to copy input extensions to an output file without processing the former. For example, in the code fragment below, an input extension is set to be the reference file for a newly opened output extension. If that reference extension is not a binary table, it is written to the output file: ) 22 73 PR( /* process each input extension in turn */ for\201ext=0; ;ext++\202{ /* get new extension name */ sprintf\201tbuf, "%s[%d]", argv[1], ext\202; /* open input extension -- if we cannot open it, we are done */ if\201 !\201ifun=FunOpen\201tbuf, "r", NULL\202\202 \202 break; /* make the new extension the reference handle for the output file */ FunInfoPut\201ofun, FUN_IFUN, &ifun, 0\202; /* if its not a binary table, just write it out */ if\201 !\201s=FunParamGets\201ifun, "XTENSION", 0, NULL, &got\202\202 || strcmp\201s, "BINTABLE"\202\202{ if\201 s \202 free\201s\202; FunFlush\201ofun, "copy=reference"\202; FunClose\201ifun\202; continue; } else{ /* process binary table */ .... } })RP( )0 2 47 H(FunClose)WB 113 Sn()WB 40 Sn( - close a Funtools data file)EA()EH( )BD() 3 24 PR( #include void FunClose\201Fun fun\202)RP()ES( )0 P(The )BD(FunClose\201\202)ES( routine closes a previously-opened Funtools data file, freeing control structures. If a )0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( was passed to the )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( call for this file, and if copy mode also was specified for that file, then )0 40 1 A(FunClose\201\202)40 0 TN TL()Ec /AF f D( also will copy the remaining extensions from the input file to the output file \201if the input file still is open\202. Thus, we recommend always closing the output Funtools file )BD(before)ES( the input file. \201Alternatively, you can call )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( explicitly\202. )0 2 48 H(FunRef:)WB 114 Sn()WB 23 Sn( the Funtools Reference Handle)EA()EH( )0 2 49 H(Summary)WB 115 Sn()EH( A description of how to use a Funtools reference handle to connect a Funtools input file to an output file. )0 2 50 H(Description)WB 116 Sn()EH( )0 P(The Funtools reference handle connects a Funtools input file to a Funtools output file so that parameters \201or even whole extensions\202 can be copied from the one to the other. To make the connection, the Funtools handle of the input file is passed to the final argument of the )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( call for the output file: ) 4 67 PR( if\201 !\201ifun = FunOpen\201argv[1], "r", NULL\202\202 \202 gerror\201stderr, "could not FunOpen input file: %s\200n", argv[1]\202; if\201 !\201ofun = FunOpen\201argv[2], "w", ifun\202\202 \202 gerror\201stderr, "could not FunOpen output file: %s\200n", argv[2]\202;)RP( It does not matter what type of input or output file \201or extension\202 is opened, or whether they are the same type. When the output image or binary table is written using )0 27 1 A(FunImagePut\201\202)27 0 TN TL()Ec /AF f D( or )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D( an appropriate header will be written first, with parameters copied from the input extension. Of course, invalid parameters will be removed first, e.g., if the input is a binary table and the output is an image, then binary table parameters such as TFORM, TUNIT, etc. parameters will not be copied to the output. )0 P(Use of a reference handle also allows default values to be passed to )0 27 1 A(FunImagePut\201\202)27 0 TN TL()Ec /AF f D( in order to write out an output image with the same dimensions and data type as the input image. To use the defaults from the input, a value of 0 is entered for dim1, dim2, and bitpix. For example: ) 5 40 PR( fun = FunOpen\201argv[1], "r", NULL\202; fun2 = FunOpen\201argv[2], "w", fun\202; buf = FunImageGet\201fun, NULL, NULL\202; ... process image data ... FunImagePut\201fun2, buf, 0, 0, 0, NULL\202;)RP( Of course, you often want to get information about the data type and dimensions of the image for processing. The above code is equivalent to the following: ) 7 61 PR( fun = FunOpen\201argv[1], "r", NULL\202; fun2 = FunOpen\201argv[2], "w", fun\202; buf = FunImageGet\201fun, NULL, NULL\202; FunInfoGet\201fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, FUN_SECT_BITPIX, &bitpix, 0\202; ... process image data ... FunImagePut\201fun2, buf, dim1, dim2, bitpix, NULL\202;)RP( )0 P(It is possible to change the reference handle for a given output Funtools handle using the )0 36 1 A(FunInfoPut\201\202)36 0 TN TL()Ec /AF f D( routine: ) 2 71 PR( /* make the new extension the reference handle for the output file */ FunInfoPut\201fun2, FUN_IFUN, &fun, 0\202;)RP( When this is done, Funtools specially resets the output file to start a new output extension, which is connected to the new input reference handle. You can use this mechanism to process multiple input extensions into a single output file, by successively opening the former and setting the reference handle for the latter. For example: ) 18 73 PR( /* open a new output FITS file */ if\201 !\201fun2 = FunOpen\201argv[2], "w", NULL\202\202 \202 gerror\201stderr, "could not FunOpen output file: %s\200n", argv[2]\202; /* process each input extension in turn */ for\201ext=0; ;ext++\202{ /* get new extension name */ sprintf\201tbuf, "%s[%d]", argv[1], ext\202; /* open it -- if we cannot open it, we are done */ if\201 !\201fun=FunOpen\201tbuf, "r", NULL\202\202 \202 break; /* make the new extension the reference handle for the output file */ FunInfoPut\201fun2, FUN_IFUN, &fun, 0\202; ... process ... /* flush output extension \201write padding, etc.\202 */ FunFlush\201fun2, NULL\202; /* close the input extension */ FunClose\201fun\202; })RP( In this example, the output file is opened first. Then each successive input extension is opened, and the output reference handle is set to the newly opened input handle. After data processing is performed, the output extension is flushed and the input extension is closed, in preparation for the next input extension. )0 P(Finally, a reference handle can be used to copy other extensions from the input file to the output file. Copy of other extensions is controlled by adding a "C" or "c" to the mode string of the )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( call )BD(of the input reference file)ES(. If "C" is specified, then other extensions are )BD(always)ES( copied \201i.e., copy is forced by the application\202. If "c" is used, then other extensions are copied if the user requests copying by adding a plus sign "+" to the extension name in the bracket specification. For example, the )BD(funtable)ES( program utilizes user-specified "c" mode so that the second example below will copy all extensions: ) 4 60 PR( # copy only the EVENTS extension csh> funtable "test.ev[EVENTS,circle\201512,512,10\202]" foo.ev # copy ALL extensions csh> funtable "test.ev[EVENTS+,circle\201512,512,10\202]" foo.ev)RP( When extension copy is specified in the input file, the call to )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( on the input file delays the actual file open until the output file also is opened \201or until I/O is performed on the input file, which ever happens first\202. Then, when the output file is opened, the input file is also opened and input extensions are copied to the output file, up to the specific extension being opened. Processing of input and output extensions then proceed. )0 P(When extension processing is complete, the remaining extensions need to be copied from input to output. This can be done explicitly, using the )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( call with the "copy=remaining" plist: ) 1 34 PR( FunFlush\201fun, "copy=remaining"\202;)RP( Alternatively, this will happen automatically, if the output file is closed )BD(before)ES( the input file: ) 5 77 PR( /* we could explicitly flush remaining extensions that need copying */ /* FunFlush\201fun2, "copy=remaining"\202; */ /* but if we close output before input, end flush is done automatically */ FunClose\201fun2\202; FunClose\201fun\202;)RP( )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 51 H(Last)WB 117 Sn( updated: December 1, 2005)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (files.html) D /Ti (Funtools Data Files) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 42 Sn( )0 2 52 H(FunFiles:)WB 120 Sn()WB 118 Sn( Funtools Data Files)EA()EH( )0 2 53 H(Summary)WB 121 Sn()EH( This document describes the data file formats \201FITS, array, raw events\202 as well as the file types \201gzip, socket, etc.\202 supported by Funtools. )0 2 54 H(Description)WB 122 Sn()EH( )0 P(Funtools supports FITS images and binary tables, and binary files containing array \201homogeneous\202 data or event \201heterogeneous\202 data. IRAF-style brackets are appended to the filename to specify various kinds of information needed to characterize these data: ) 3 49 PR( file[ext|ind|ARRAY\201\202|EVENTS\201\202,section][filters] or file[ext|ind|ARRAY\201\202|EVENTS\201\202,section,filters])RP( where: )UL()-1 LI( )BD(file)ES( is the Funtools file name )-1 LI( )BD(ext)ES( is the FITS extension name )-1 LI( )BD(ind)ES( is the FITS extension number )-1 LI( )BD(ARRAY\201\202)ES( is an array specification )-1 LI( )BD(EVENTS\201\202)ES( is an event specification )-1 LI( )BD(section)ES( is the image section specification )-1 LI( )BD(filters)ES( are spatial region and table \201row\202 filters)LU( )0 2 55 H(Supported)WB 123 Sn()WB 43 Sn( Data Formats)EA()EH( )0 P(Funtools programs \201and the underlying libraries\202 support the following data file formats: )UL()-1 LI( FITS images \201and image extensions\202 )-1 LI( FITS binary tables )-1 LI( binary files containing an array of homogeneous data )-1 LI( binary files containing events, i.e. records of heterogeneous data )-1 LI( column-based text files, which are documented )0 47 1 A(here)47 0 TN TL()Ec /AF f D( )-1 LI( non-disk files and lists of files)LU( Information needed to identify and characterize the event or image data can be specified on the command line using IRAF-style bracket notation appended to the filename: ) 5 69 PR( foo.fits # open FITS default extension image.fits[3] # open FITS extension #3 events.fits[EVENTS] # open EVENTS extension array.file[ARRAY\201s1024\202] # open 1024x1024 short array events.file[EVENTS\201x:1024,y:1024...\202] # open non-FITS event list)RP( Note that in many Unix shells \201e.g., csh and tcsh\202, filenames must be enclosed in quotes to protect the brackets from shell processing. )0 2 56 H(FITS)WB 124 Sn()WB 44 Sn( Images and Binary Tables)EA()EH( )0 P(When )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( opens a FITS file without a bracket specifier, the default behavior is to look for a valid image in the primary HDU. In the absence of a primary image, Funtools will try to open an extension named either )BD(EVENTS)ES( or )BD(STDEVT)ES(, if one of these exists. This default behavior supports both FITS image processing and standard X-ray event list processing \201which, after all, is what we at SAO/HEAD do\202. )0 P(In order to open a FITS binary table or image extension explicitly, it is necessary to specify either the extension name or the extension number in brackets: ) 3 71 PR( foo.fits[1] # open extension #1: the primary HDU foo.fits[3] # open extension #3 of a FITS file foo.fits[GTI] # open GTI extension of a FITS file)RP( The ext argument specifies the name of the FITS extension \201i.e. the value of the EXTENSION header parameter in a FITS extension\202, while the index specifies the value of the FITS EXTVER header parameter. Following FITS conventions, extension numbers start at 1. )0 P(When a FITS data file is opened for reading using )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(, the specified extension is automatically located and is used to initialize the Funtools internal data structures. )0 2 57 H(Non-FITS)WB 125 Sn()WB 45 Sn( Raw Event Files)EA()EH( In addition to FITS tables, Funtools programs and libraries can operate on non-FITS files containing heterogeneous event records. To specify such an event file, use: )UL()-1 LI( file[EVENTS\201event-spec\202] )-1 LI( file[EVENTS\201\202])LU( where )BD(event-spec)ES( is a string that specified the names, data types, and optional image dimensions for each element of the event record: )UL()-1 LI( [name]:[n][type]:[\201lodim:\202hidim])LU( )0 P(Data types follow standard conventions for FITS binary tables, but include two extra unsigned types \201'U' and 'V'\202: )UL()-1 LI( )BD(B)ES( -- unsigned 8-bit char )-1 LI( )BD(I)ES( -- signed 16-bit int )-1 LI( )BD(J)ES( -- signed 32-bit int )-1 LI( )BD(K)ES( -- signed 64-bit int )-1 LI( )BD(E)ES( -- 32-bit float )-1 LI( )BD(D)ES( -- 64-bit float )-1 LI( )BD(U)ES( -- unsigned 16-bit int )-1 LI( )BD(V)ES( -- unsigned 32-bit int)LU( An optional integer value )BD(n)ES( can be prefixed to the type to indicate that the element is an array of n values. For example: ) 1 37 PR( foo.fits[EVENTS\201x:I,y:I,status:4J\202])RP( defines x and y as 16-bit ints and status as an array of 4 32-bit ints. )0 P(Furthermore, image dimensions can be attached to the event specification in order to tell Funtools how to bin the events into an image. They follow the conventions for the FITS TLMIN/TLMAX keywords. If the low image dimension is not specified, it defaults to 1. Thus: )UL()-1 LI( RAWX:J:1:100 )-1 LI( RAWX:J:100)LU( both specify that the dimension of this column runs from 1 to 100. )0 P(NB: it is required that all padding be specified in the record definition. Thus, when writing out whole C structs instead of individual record elements, great care must be taken to include the compiler-added padding in the event definition. )0 P(For example, suppose a FITS binary table has the following set of column definitions: ) 22 54 PR( TTYPE1 = 'X ' / Label for field TFORM1 = '1I ' / Data type for field TLMIN1 = 1 / Min. axis value TLMAX1 = 10 / Max. axis value TTYPE2 = 'Y ' / Label for field TFORM2 = '1I ' / Data type for field TLMIN2 = 2 / Min. axis value TLMAX2 = 11 / Max. axis value TTYPE3 = 'PHA ' / Label for field TFORM3 = '1I ' / Data type for field TTYPE4 = 'PI ' / Label for field TFORM4 = '1J ' / Data type for field TTYPE5 = 'TIME ' / Label for field TFORM5 = '1D ' / Data type for field TTYPE6 = 'DX ' / Label for field TFORM6 = '1E ' / Data type for field TLMIN6 = 1 / Min. axis value TLMAX6 = 10 / Max. axis value TTYPE7 = 'DY ' / Label for field TFORM7 = '1E ' / Data type for field TLMIN7 = 3 / Min. axis value TLMAX7 = 12 / Max. axis value)RP( An raw event file containing these same data would have the event specification: ) 1 61 PR( EVENTS\201X:I:10,Y:I:2:11,PHA:I,PI:J,TIME:D,DX:E:10,DY:E:3:12\202)RP( )0 P(If no event specification string is included within the EVENTS\201\202 operator, then the event specification is taken from the )BD(EVENTS)ES( environment variable: ) 1 65 PR( setenv EVENTS "X:I:10,Y:I:10,PHA:I,PI:J,TIME:D,DX:E:10,DY:E:10")RP( )0 P(In addition to knowing the data structure, it is necessary to know the )EM(endian)ES( ordering of the data, i.e., whether or not the data is in )EM(bigendian)ES( format, so that we can convert to the native format for this platform. This issue does not arise for FITS Binary Tables because all FITS files use big-endian ordering, regardless of platform. But for non-FITS data, big-endian data produced on a Sun workstation but read on a Linux PC needs to be byte-swapped, since PCs use little-endian ordering. To specify an ordering, use the )EM(bigendian=)ES( or )EM(endian=)ES( keywords on the command-line or the EVENTS_BIGENDIAN or EVENTS_ENDIAN environment variables. The value of the )EM(bigendian)ES( variables should be "true" or "false", while the value of the )EM(endian)ES( variables should be "little" or "big". )0 P(For example, a PC can access data produced by a Sun using: ) 7 35 PR( hrc.nepr[EVENTS\201\202,bigendian=true] or hrc.nepr[EVENTS\201\202,endian=big] or setenv EVENTS_BIGENDIAN true or setenv EVENTS_ENDIAN big)RP( If none of these are specified, the data are assumed to follow the format for that platform and no byte-swapping is performed. )0 2 58 H(Non-FITS)WB 126 Sn()WB 46 Sn( Array Files)EA()EH( In addition to FITS images, Funtools programs and libraries can operate on non-FITS files containing arrays of homogeneous data. To specify an array file, use: )UL()-1 LI( file[ARRAY\201array-spec\202] )-1 LI( file[ARRAY\201\202])LU( where array-spec is of the form: )UL()-1 LI( [type][dim1][.dim2][:skip][endian])LU( and where [type] is: )UL()-1 LI( b \2018-bit unsigned char\202 )-1 LI( s \20116-bit short int\202 )-1 LI( u \20116-bit unsigned short int\202 )-1 LI( i \20132-bit int\202 )-1 LI( r,f \20132-bit float\202 )-1 LI( d \20164-bit float\202)LU( )0 P(The dim1 specification is required, but dim2 is optional and defaults to dim1. The skip specification is optional and defaults to 0. The optional endian specification can be 'l' or 'b' and defaults to the endian type for the current machine. )0 P(If no array specification is included within the ARRAY\201\202 operator, then the array specification is taken from the )BD(ARRAY)ES( environment variable. For example: ) 7 76 PR( foo.arr[ARRAY\201r512\202] # bitpix=-32 dim1=512 dim2=512 foo.arr[ARRAY\201r512.400\202] # bitpix=-32 dim1=512 dim2=400 foo.arr[ARRAY\201r512.400]\202 # bitpix=-32 dim1=512 dim2=400 foo.arr[ARRAY\201r512.400:2880\202] # bitpix=-32 dim1=512 dim2=400 skip=2880 foo.arr[ARRAY\201r512l\202] # bitpix=-32 dim1=512 dim2=512 endian=little setenv ARRAY "r512.400:2880" foo.arr[ARRAY\201\202] # bitpix=-32 dim1=512 dim2=400 skip=2880)RP( )0 2 59 H(Specifying)WB 127 Sn()WB 49 Sn( Image Sections)EA()EH( Once a data file \201and possibly, a FITS extension\202 has been specified, the next \201optional\202 part of a bracket specification can be used to select image )BD(section)ES( information, i.e., to specify the x,y limits of an image section, as well as the blocking factor to apply to that section. This information can be added to any file specification but only is used by Funtools image processing routines. )0 P(The format of the image section specification is one of the following: )UL()-1 LI( file[xy0:xy1,block] )-1 LI( file[x0:x1,y0:y1,block] )-1 LI( file[x0:x1,*,block] )-1 LI( file[*,y0:y1,block] )-1 LI( file[*,block])LU( where the limit values can be ints or "*" for default. A single "*" can be used instead of val:val, as shown. Note that blocking is applied to the section after it is extracted. )0 P(In addition to image sections specified by the lo and hi x,y limits, image sections using center positions can be specified: )UL()-1 LI( file[dim1@xcen,dim2@ycen] )-1 LI( file[xdim2@xcen@ycen] )-1 LI( file[dim1@xcen,dim2@ycen,block] )-1 LI( file[dim@xcen@ycen,block])LU( Note that the \201float\202 values for dim, dim1, dim2, xcen, ycen must be specified or else the expression does not make sense! )0 P(In all cases, block is optional and defaults to 1. An 's' or 'a' can be appended to signify "sum" or "average" blocking \201default is "sum"\202. Section specifications are given in image coordinates by default. If you wish to specify physical coordinates, add a 'p' as the last character of the section specification, before the closing bracket. For example: ) 2 21 PR()UL()-1 LI( file[-8:-7,-8:-7p] )-1 LI( file[-8:-7,-8:-7,2p])LU()RP( A section can be specified in any Funtools file name. If the operation to be applied to that file is an imaging operation, then the specification will be utilized. If the operation is purely a table operation, then the section specification is ignored. )0 P(Do not be confused by: ) 2 15 PR( foo.fits[2] foo.fits[*,2])RP( The former specifies opening the second extension of the FITS file. The latter specifies application of block 2 to the image section. )0 P(Note that the section specification must come after any of FITS )BD(ext)ES( name or )BD(ind)ES( number, but all sensible defaults are supported: )UL()-1 LI( file[ext] )-1 LI( file[ext,index] )-1 LI( file[index] )-1 LI( file[ext,section] )-1 LI( file[ext,index,section] )-1 LI( file[index,section] )-1 LI( file[section])LU( )0 2 60 H(Binning)WB 128 Sn()WB 50 Sn( FITS Binary Tables and Non-FITS Event Files)EH( If a FITS binary table or a non-FITS raw event file is to be binned into a 2D image \201e.g., using the )0 10 1 A(funimage)10 0 TN TL()Ec /AF f D( program\202, it is necessary to specify the two columns to be used for the binning, as well as the dimensions of the image. Funtools first looks for a specifier of the form: ) 1 74 PR( bincols=\201[xnam[:tlmin[:tlmax:[binsiz]]]],[ynam[:tlmin[:tlmax[:binsiz]]]]\202)RP( in bracket syntax, and uses the column names thus specified. The tlmin, tlmax, and binsiz specifiers determine the image binning dimensions using: ) 2 56 PR( dim = \201tlmax - tlmin\202/binsiz \201floating point data\202 dim = \201tlmax - tlmin\202/binsiz + 1 \201integer data\202)RP( These tlmin, tlmax, and binsiz specifiers can be omitted if TLMIN, TLMAX, and TDBIN header parameters are present in the FITS binary table header, respectively. If only one parameter is specified, it is assumed to be tlmax, and tlmin defaults to 1. If two parameters are specified, they are assumed to be tlmin and tlmax. For example, to bin an HRC event list columns "VPOS" and "UPOS", use: ) 1 31 PR( hrc.nepr[bincols=\201VPOS,UPOS\202])RP( or ) 1 42 PR( hrc.nepr[bincols=\201VPOS:49152,UPOS:4096\202])RP( Note that you can optionally specify the dimensions of these columns to cover cases where neither TLMAX keywords are defined in the header. If either dimension is specified, then both must be specified. )0 P(You can set the FITS_BINCOLS or EVENTS_BINCOLS environment variable as an alternative to adding the "bincols=" specifier to each file name for FITS binary tables and raw event files, respectively. If no binning keywords or environment variables are specified, or if the specified columns are not in the binary table, the Chandra parameters CPREF \201or PREFX\202 are searched for in the FITS binary table header. Failing this, columns named "X" and "Y" are sought. If these are not found, the code looks for columns containing the characters "X" and "Y". Thus, you can bin on "DETX" and "DETX" columns without specifying them, if these are the only column names containing the "X" and "Y" characters. )0 P(Ordinarily, each event or row contributes one count to an image pixel during the 2D binning process. Thus, if five events all have the same \201x,y\202 position, the image pixel value for that position will have a value of five. It is possible to specify a variable contribution for each event by using the vcol=[colname] filter spec: ) 1 15 PR( vcol=[colname])RP( The vcol colname is a column containing a numeric value in each event row that will be used as the contribution of the given event to its image pixel. For example, consider an event file that has the following content: ) 10 24 PR( x:e:4 y:e:4 v:e ------ ------ ---- 1 1 1.0 2 2 2.0 3 3 3.0 4 4 0.0 1 1 1.0 2 2 2.0 3 3 3.0 4 4 4.0)RP( There are two events with x,y value of \2011,1\202 so ordinarily a 2D image will have a value of 2 in the \2011,1\202 pixel. If the v column is specified as the value column: ) 1 20 PR( foo.fits'[vcol=v]')RP( then each pixel will contain the additive sum of the associated \201x,y\202 column values from the v column. For example, image pixel \2011,1\202 will contain 1. + 1. = 2, image pixel \2012,2\202 will contain \2012 + 2\202 = 4, etc. )0 P(An important variation on the use of a value column to specify the contribution an event makes to an image pixel is when the value column contains the reciprocal of the event contribution. For this case, the column name should be prefixed with a / \201divide sign\202 thus: ) 1 21 PR( foo.fits'[vcol=/v]')RP( Each image pixel value will then be the sum of the reciprocals of the value column. A zero in the value column results in NaN \201not a number\202. Thus, in the above example, image pixel \2011.1\202 will contain 1/1 + 1/1 = 2, image pixel \2012,2\202 will contain \2011/2 + 1/2\202 = 1, etc. Image pixel \2014,4\202 will contain \2011/0 + 1/4\202 = NaN. )0 P(You can set the FITS_VCOL or EVENTS_VCOL environment variable as an alternative to adding the "vcol=" specifier to each file name for FITS binary tables and raw event files, respectively. )0 P(Finally, when binning events, the data type of the resulting 2D image must be specified. This can be done with the "bitpix=[n]" keyword in the bracket specification. For example: ) 1 45 PR( events.fits[bincols=\201VPOS,UPOS\202,bitpix=-32])RP( will create a floating point image binned on columns VPOS and UPOS. If no bitpix keyword is specified, bitpix=32 is assumed. As with bincols values, you also can use the FITS_BITPIX and EVENTS_BITPIX environment variables to set this value for FITS binary tables and raw event files, respectively. )0 P(The )BD(funimage)ES( program also allows you to create a 1D image projection along any column of a table by using the )BD(bincols=[column])ES( filter specification and specifying a single column. For example, the following command projects a 1D image along the chipx column of a table: ) 1 43 PR( funimage ev.fits'[bincols=chipx]' im.fits)RP( See )0 10 1 A(funimage)10 0 TN TL()Ec /AF f D( for more information about creating 1D and 2D images. )0 P(Finally, please note that Funtools supports most FITS standards. We will add missing support as required by the community. In general, however, we do not support non-standard extensions. For example, we sense the presence of the binary table 'variable length array' proposed extension and we pass it along when copying and filtering files, but we do not process it. We will add support for new standards as they become official. )0 2 61 H(Table)WB 129 Sn()WB 119 Sn( and Spatial Region Filters)EH( )0 P(Note that, in addition extensions and image sections, Funtools bracket notation can be used to specify table and spatial region filters. These filters are always placed after the image section information. They can be specified in the same bracket or in a separate bracket immediately following: )UL()-1 LI( file[ext|ind|ARRAY\201\202|EVENTS\201\202,section][filters] )-1 LI( file[ext|ind|ARRAY\201\202|EVENTS\201\202,section,filters])LU( where: )UL()-1 LI( )BD(file)ES( is the Funtools file name )-1 LI( )BD(ARRAY\201\202)ES( is an array specification )-1 LI( )BD(EVENTS\201\202)ES( is an event list specification )-1 LI( )BD(ext)ES( is the FITS extension name )-1 LI( )BD(ind)ES( is the FITS extension number )-1 LI( )BD(section)ES( is the image section to extract )-1 LI( )BD(filters)ES( are spatial region and table \201row\202 filters to apply)LU( The topics of table and region filtering are covered in detail in: )UL()-1 LI()0 52 1 A(Table Filtering)52 0 TN TL()Ec /AF f D( )-1 LI()0 54 1 A(Spatial Region Filtering)54 0 TN TL()Ec /AF f D()LU( )0 2 62 H(Disk)WB 130 Sn()WB 51 Sn( Files and Other Supported File Types)EA()EH( )0 P(The specified )BD(file)ES( usually is an ordinary disk file. In addition, gzip'ed files are supported in Funtools: gzip'ed input files are automatically uncompressed as they are read, and gzip'ed output files are compressed as they are written. NB: if a FITS binary table is written in gzip format, the number of rows in the table will be set to -1. Such a file will work with Funtools programs but will not work with other FITS programs such as ds9. )0 P(The special keywords "stdin" and "stdout" designate Unix standard input and standard output, respectively. The string "-" \201hyphen\202 will be taken to mean "stdin" if the file is opened for reading and "stdout" if the file is opened for writing. )0 P(A file also can be an INET socket on the same or another machine using the syntax: ) 1 14 PR( machine:port)RP( Thus, for example: ) 1 14 PR( karapet:1428)RP( specifies that I/O should be performed to/from port 1428 on the machine karapet. If no machine name is specified, the default is to use the current machine: ) 1 7 PR( :1428)RP( This means to open port 1428 on the current machine. Socket support allows you to generate a distributed pipe: ) 2 48 PR( on karapet: funtask1 in.fits bynars:1428 on bynars: funtask2 :1428 out.fits)RP( The socket mechanism thus supports simple parallel processing using )BD(process decomposition)ES(. Note that parallel processing using )BD(data decomposition)ES( is supported via the )BD(section)ES( specifier \201see below\202, and the )BD(row#)ES( specifier, which is part of )0 52 1 A(Table Filtering)52 0 TN TL()Ec /AF f D(. )0 P(A file also can be a pointer to shared memory using the syntax: ) 1 22 PR( shm:[id|@key][:size])RP( A shared memory segment is specified with a )BD(shm:)ES( prefix, followed by either the shared memory id or the shared memory key \201where the latter is prefixed by the '@' character\202. The size \201in bytes\202 of the shared memory segment can then be appended \201preceded by the ':' character\202. If the size specification is absent, the code will attempt to determine the length automatically. If the open mode contains the string "w+", then the memory segment will be created if it does not exist. \201It also will be released and deleted when the file is closed.\202 In the case where a memory segment is being created, the length of the segment is required. )0 P(A file also can be Unix piped command \201i.e. a program to run\202 using the syntax: ) 1 31 PR( "pipe: command arg1 ... argn")RP( The output from the command must be a valid FITS file. It is important to use quotes to protect spaces so that command arguments are passed correctly. A silly example is: ) 1 60 PR( fundisp "pipe: funtable 'foo.fits[cir 512 512 .1]' stdout")RP( This seemed like a good idea at the time ... )0 2 63 H(Lists)WB 131 Sn()WB 51 Sn( of Files)EA()EH( )0 P(Funtools also will process a list of files as a single file using the syntax: ) 1 31 PR( "list: file1 file2 ... filen")RP( The files in the list are separated by whitespace. Any of the above file types can be used. For example, if two files, foo1.fits and foo2.fits, are part of the same observation, they can be processed as a single file \201using their own filters\202: ) 17 77 PR( fundisp "list: foo1.fits[cir\201512,512,10\202] foo2.fits[cir\201511,511,10\202]" X Y PHA PI TIME DX DY -------- -------- -------- -------- --------------------- -------- -------- 512 512 6 7 79493997.45854475 578 574 512 512 8 9 79494575.58943175 579 573 512 512 5 6 79493631.03866175 578 575 512 512 5 5 79493290.86521725 578 575 512 512 8 9 79493432.00990875 579 573 511 511 5 5 79488631.09462625 580 575 511 511 10 11 79488780.60006675 580 573 511 511 4 4 79494562.35474326 580 575 511 511 6 6 79488203.01561825 580 575 511 511 6 6 79488017.99730176 580 575 511 511 4 4 79494332.45355175 580 575 511 511 9 10 79492685.94014275 581 574 511 511 5 5 79487708.71298325 580 575 511 511 8 9 79493719.00160225 581 573)RP( Again, note that it is important to avoid spaces in the filters because the list separator also is whitespace. To protect whitespace in a filter, enclose the file specification in quotes: ) 1 72 PR( fundisp "list: 'foo1.fits[cir 512 512 .1]' foo2.fits[cir\201511,511,.1\202]")RP( )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 64 H(Last)WB 132 Sn( updated: February 15, 2006)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (text.html) D /Ti (Column-based Text Files) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 47 Sn( )0 2 65 H(Funtext:)WB 134 Sn()WB 133 Sn( Support for Column-based Text Files)EA()EH( )0 2 66 H(Summary)WB 135 Sn()EH( )0 P(This document contains a summary of the options for processing column-based text files. )0 2 67 H(Description)WB 136 Sn()EH( )0 P(Funtools will automatically sense and process "standard" column-based text files as if they were FITS binary tables without any change in Funtools syntax. In particular, you can filter text files using the same syntax as FITS binary tables: ) 3 54 PR( fundisp foo.txt'[cir 512 512 .1]' fundisp -T foo.txt > foo.rdb funtable foo.txt'[pha=1:10,cir 512 512 10]' foo.fits)RP( )0 P(The first example displays a filtered selection of a text file. The second example converts a text file to an RDB file. The third example converts a filtered selection of a text file to a FITS binary table. )0 P(Text files can also be used in Funtools image programs. In this case, you must provide binning parameters \201as with raw event files\202, using the bincols keyword specifier: ) 1 75 PR( bincols=\201[xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]])RP( For example: ) 1 64 PR( funcnts foo'[bincols=\201x:1024,y:1024\202]' "ann 512 512 0 10 n=10")RP( )0 2 68 H(Standard)WB 137 Sn( Text Files)EH( )0 P(Standard text files have the following characteristics: )UL()-1 LI( Optional comment lines start with # )-1 LI( Optional blank lines are considered comments )-1 LI( An optional table header consists of the following \201in order\202: )UL( )-1 LI( a single line of alpha-numeric column names )-1 LI( an optional line of unit strings containing the same number of cols )-1 LI( an optional line of dashes containing the same number of cols)LU( )-1 LI( Data lines follow the optional header and \201for the present\202 consist of the same number of columns as the header. )-1 LI( Standard delimiters such as space, tab, comma, semi-colon, and bar.)LU( )0 P(Examples: ) 26 46 PR( # rdb file foo1 foo2 foo3 foos ---- ---- ---- ---- 1 2.2 3 xxxx 10 20.2 30 yyyy # multiple consecutive whitespace and dashes foo1 foo2 foo3 foos --- ---- ---- ---- 1 2.2 3 xxxx 10 20.2 30 yyyy # comma delims and blank lines foo1,foo2,foo3,foos 1,2.2,3,xxxx 10,20.2,30,yyyy # bar delims with null values foo1|foo2|foo3|foos 1||3|xxxx 10|20.2||yyyy # header-less data 1 2.2 3 xxxx 10 20.2 30 yyyy)RP( )0 P(The default set of token delimiters consists of spaces, tabs, commas, semi-colons, and vertical bars. Several parsers are used simultaneously to analyze a line of text in different ways. One way of analyzing a line is to allow a combination of spaces, tabs, and commas to be squashed into a single delimiter \201no null values between consecutive delimiters\202. Another way is to allow tab, semi-colon, and vertical bar delimiters to support null values, i.e. two consecutive delimiters implies a null value \201e.g. RDB file\202. A successful parser is one which returns a consistent number of columns for all rows, with each column having a consistent data type. More than one parser can be successful. For now, it is assumed that successful parsers all return the same tokens for a given line. \201Theoretically, there are pathological cases, which will be taken care of as needed\202. Bad parsers are discarded on the fly. )0 P(If the header does not exist, then names "col1", "col2", etc. are assigned to the columns to allow filtering. Furthermore, data types for each column are determined by the data types found in the columns of the first data line, and can be one of the following: string, int, and double. Thus, all of the above examples return the following display: ) 4 58 PR( fundisp foo'[foo1>5]' FOO1 FOO2 FOO3 FOOS ---------- --------------------- ---------- ------------ 10 20.20000000 30 yyyy)RP( )0 2 69 H(Comments)WB 138 Sn( Convert to Header Params)EH( )0 P(Comments which precede data rows are converted into header parameters and will be written out as such using funimage or funhead. Two styles of comments are recognized: )0 P(1. FITS-style comments have an equal sign "=" between the keyword and value and an optional slash "/" to signify a comment. The strict FITS rules on column positions are not enforced. In addition, strings only need to be quoted if they contain whitespace. For example, the following are valid FITS-style comments: ) 5 55 PR( # fits0 = 100 # fits1 = /usr/local/bin # fits2 = "/usr/local/bin /opt/local/bin" # fits3c = /usr/local/bin /opt/local/bin /usr/bin # fits4c = "/usr/local/bin /opt/local/bin" / path dir)RP( Note that the fits3c comment is not quoted and therefore its value is the single token "/usr/local/bin" and the comment is "opt/local/bin /usr/bin". This is different from the quoted comment in fits4c. )0 P(2. Free-form comments can have an optional colon separator between the keyword and value. In the absence of quote, all tokens after the keyword are part of the value, i.e. no comment is allowed. If a string is quoted, then slash "/" after the string will signify a comment. For example: ) 9 54 PR( # com1 /usr/local/bin # com2 "/usr/local/bin /opt/local/bin" # com3 /usr/local/bin /opt/local/bin /usr/bin # com4c "/usr/local/bin /opt/local/bin" / path dir # com11: /usr/local/bin # com12: "/usr/local/bin /opt/local/bin" # com13: /usr/local/bin /opt/local/bin /usr/bin # com14c: "/usr/local/bin /opt/local/bin" / path dir)RP( )0 P(Note that com3 and com13 are not quoted, so the whole string is part of the value, while comz4c and com14c are quoted and have comments following the values. )0 P(Some text files have column name and data type information in the header. You can specify the format of column information contained in the header using the "hcolfmt=" specification. See below for a detailed description. )0 2 70 H(Multiple)WB 139 Sn( Tables in a Single File)EH( )0 P( Multiple tables are supported in a single file. If an RDB-style file is sensed, then a ^L \201vertical tab\202 will signify end of table. Otherwise, an end of table is sensed when a new header \201i.e., all alphanumeric columns\202 is found. \201Note that this heuristic does not work for single column tables where the column type is ASCII and the table that follows also has only one column.\202 You also can specify characters that signal an end of table condition using the )BD(eot=)ES( keyword. See below for details. )0 P(You can access the nth table \201starting from 1\202 in a multi-table file by enclosing the table number in brackets, as with a FITS extension: ) 1 18 PR( fundisp foo'[2]')RP( The above example will display the second table in the file. \201Index values start at 1 in oder to maintain logical compatibility with FITS files, where extension numbers also start at 1\202. )0 2 71 H(TEXT\201\202)WB 140 Sn( Specifier)EH( )0 P(As with ARRAY\201\202 and EVENTS\201\202 specifiers for raw image arrays and raw event lists respectively, you can use TEXT\201\202 on text files to pass key=value options to the parsers. An empty set of keywords is equivalent to not having TEXT\201\202 at all, that is: ) 2 23 PR( fundisp foo fundisp foo'[TEXT\201\202]')RP( are equivalent. A multi-table index number is placed before the TEXT\201\202 specifier as the first token, when indexing into a multi-table: fundisp foo'[2,TEXT\201...\202]' )0 P(The filter specification is placed after the TEXT\201\202 specifier, separated by a comma, or in an entirely separate bracket: ) 2 47 PR( fundisp foo'[TEXT\201...\202,circle 512 512 .1]' fundisp foo'[2,TEXT\201...\202][circle 512 512 .1]')RP( )0 2 72 H(Text\201\202)WB 141 Sn( Keyword Options)EH( )0 P( The following is a list of keywords that can be used within the TEXT\201\202 specifier \201the first three are the most important\202: )0 DL( )0 P()0 DT( delims="[delims]" )DD(Specify token delimiters for this file. Only a single parser having these delimiters will be used to process the file. ) 2 40 PR( fundisp foo.fits'[TEXT\201delims="!"\202]' fundisp foo.fits'[TEXT\201delims="\200t%"\202]')RP( )0 P()0 DT( comchars="[comchars]" )DD( Specify comment characters. You must include "\200n" to allow blank lines. These comment characters will be used for all standard parsers \201unless delims are also specified\202. ) 1 42 PR( fundisp foo.fits'[TEXT\201comchars="!\200n"\202]')RP( )0 P()0 DT( cols="[name1:type1 ...]" )DD( Specify names and data type of columns. This overrides header names and/or data types in the first data row or default names and data types for header-less tables. ) 1 70 PR( fundisp foo.fits'[TEXT\201cols="x:I,y:I,pha:I,pi:I,time:D,dx:E,dy:e"\202]')RP( )0 P(If the column specifier is the only keyword, then the cols= is not required \201in analogy with EVENTS\201\202\202: ) 1 63 PR( fundisp foo.fits'[TEXT\201x:I,y:I,pha:I,pi:I,time:D,dx:E,dy:e\202]')RP( Of course, an index is allowed in this case: ) 1 65 PR( fundisp foo.fits'[2,TEXT\201x:I,y:I,pha:I,pi:I,time:D,dx:E,dy:e\202]')RP( )0 P()0 DT( eot="[eot delim]" )DD( Specify end of table string specifier for multi-table files. RDB files support ^L. The end of table specifier is a string and the whole string must be found alone on a line to signify EOT. For example: ) 1 37 PR( fundisp foo.fits'[TEXT\201eot="END"\202]')RP( will end the table when a line contains "END" is found. Multiple lines are supported, so that: ) 1 43 PR( fundisp foo.fits'[TEXT\201eot="END\200nGAME"\202]')RP( will end the table when a line contains "END" followed by a line containing "GAME". )0 P(In the absence of an EOT delimiter, a new table will be sensed when a new header \201all alphanumeric columns\202 is found. )0 P()0 DT( null1="[datatype]" )DD( Specify data type of a single null value in row 1. Since column data types are determined by the first row, a null value in that row will result in an error and a request to specify names and data types using cols=. If you only have a one null in row 1, you don't need to specify all names and columns. Instead, use null1="type" to specify its data type. )0 P()0 DT( alen=[n] )DD(Specify size in bytes for ASCII type columns. FITS binary tables only support fixed length ASCII columns, so a size value must be specified. The default is 16 bytes. )0 P()0 DT( nullvalues=["true"|"false"] )DD(Specify whether to expect null values. Give the parsers a hint as to whether null values should be allowed. The default is to try to determine this from the data. )0 P()0 DT( whitespace=["true"|"false"] )DD( Specify whether surrounding white space should be kept as part of string tokens. By default surrounding white space is removed from tokens. )0 P()0 DT( header=["true"|"false"] )DD(Specify whether to require a header. This is needed by tables containing all string columns \201and with no row containing dashes\202, in order to be able to tell whether the first row is a header or part of the data. The default is false, meaning that the first row will be data. If a row dashes are present, the previous row is considered the column name row. )0 P()0 DT( units=["true"|"false"] )DD(Specify whether to require a units line. Give the parsers a hint as to whether a row specifying units should be allowed. The default is to try to determine this from the data. )0 P()0 DT( i2f=["true"|"false"] )DD(Specify whether to allow int to float conversions. If a column in row 1 contains an integer value, the data type for that column will be set to int. If a subsequent row contains a float in that same column, an error will be signaled. This flag specifies that, instead of an error, the float should be silently truncated to int. Usually, you will want an error to be signaled, so that you can specify the data type using cols= \201or by changing the value of the column in row 1\202. )0 P()0 DT( comeot=["true"|"false"|0|1|2] )DD(Specify whether comment signifies end of table. If comeot is 0 or false, then comments do not signify end of table and can be interspersed with data rows. If the value is true or 1 \201the default for standard parsers\202, then non-blank lines \201e.g. lines beginning with '#'\202 signify end of table but blanks are allowed between rows. If the value is 2, then all comments, including blank lines, signify end of table. )0 P()0 DT( lazyeot=["true"|"false"] )DD(Specify whether "lazy" end of table should be permitted \201default is true for standard formats, except rdb format where explicit ^L is required between tables\202. A lazy EOT can occur when a new table starts directly after an old one, with no special EOT delimiter. A check for this EOT condition is begun when a given row contains all string tokens. If, in addition, there is a mismatch between the number of tokens in the previous row and this row, or a mismatch between the number of string tokens in the prev row and this row, a new table is assumed to have been started. For example: ) 9 20 PR( ival1 sval3 ----- ----- 1 two 3 four jval1 jval2 tval3 ----- ----- ------ 10 20 thirty 40 50 sixty)RP( Here the line "jval1 ..." contains all string tokens. In addition, the number of tokens in this line \2013\202 differs from the number of tokens in the previous line \2012\202. Therefore a new table is assumed to have started. Similarly: ) 9 20 PR( ival1 ival2 sval3 ----- ----- ----- 1 2 three 4 5 six jval1 jval2 tval3 ----- ----- ------ 10 20 thirty 40 50 sixty)RP( Again, the line "jval1 ..." contains all string tokens. The number of string tokens in the previous row \2011\202 differs from the number of tokens in the current row\2013\202. We therefore assume a new table as been started. This lazy EOT test is not performed if lazyeot is explicitly set to false. )0 P()0 DT( hcolfmt=[header column format] )DD( Some text files have column name and data type information in the header. For example, VizieR catalogs have headers containing both column names and data types: ) 3 95 PR( #Column e_Kmag \201F6.3\202 ?\201k_msigcom\202 K total magnitude uncertainty \2014\202 [ucd=ERROR] #Column Rflg \201A3\202 \201rd_flg\202 Source of JHK default mag \2016\202 [ucd=REFER_CODE] #Column Xflg \201I1\202 [0,2] \201gal_contam\202 Extended source contamination \20110\202 [ucd=CODE_MISC])RP( while Sextractor files have headers containing column names alone: ) 4 79 PR( # 1 X_IMAGE Object position along x [pixel] # 2 Y_IMAGE Object position along y [pixel] # 3 ALPHA_J2000 Right ascension of barycenter \201J2000\202 [deg] # 4 DELTA_J2000 Declination of barycenter \201J2000\202 [deg])RP( The hcolfmt specification allows you to describe which header lines contain column name and data type information. It consists of a string defining the format of the column line, using "$col" \201or "$name"\202 to specify placement of the column name, "$fmt" to specify placement of the data format, and "$skip" to specify tokens to ignore. You also can specify tokens explicitly \201or, for those users familiar with how sscanf works, you can specify scanf skip specifiers using "%*"\202. For example, the VizieR hcolfmt above might be specified in several ways: ) 3 67 PR( Column $col \201$fmt\202 # explicit specification of "Column" string $skip $col \201$fmt\202 # skip one token %*s $col \201$fmt\202 # skip one string \201using scanf format\202)RP( while the Sextractor format might be specified using: ) 2 59 PR( $skip $col # skip one token %*d $col # skip one int \201using scanf format\202)RP( You must ensure that the hcolfmt statement only senses actual column definitions, with no false positives or negatives. For example, the first Sextractor specification, "$skip $col", will consider any header line containing two tokens to be a column name specifier, while the second one, "%*d $col", requires an integer to be the first token. In general, it is preferable to specify formats as explicitly as possible. )0 P(Note that the VizieR-style header info is sensed automatically by the funtools standard VizieR-like parser, using the hcolfmt "Column $col \201$fmt\202". There is no need for explicit use of hcolfmt in this case. )0 P()0 DT( debug=["true"|"false"] )DD(Display debugging information during parsing. )LD( )0 2 73 H(Environment)WB 142 Sn( Variables)EH( )0 P( Environment variables are defined to allow many of these TEXT\201\202 values to be set without having to include them in TEXT\201\202 every time a file is processed: ) 10 36 PR( keyword environment variable ------- -------------------- delims TEXT_DELIMS comchars TEXT_COMCHARS cols TEXT_COLUMNS eot TEXT_EOT null1 TEXT_NULL1 alen TEXT_ALEN bincols TEXT_BINCOLS hcolfmt TEXT_HCOLFMT)RP( )0 2 74 H(Restrictions)WB 143 Sn( and Problems)EH( )0 P( As with raw event files, the '+' \201copy extensions\202 specifier is not supported for programs such as funtable. )0 P(String to int and int to string data conversions are allowed by the text parsers. This is done more by force of circumstance than by conviction: these transitions often happens with VizieR catalogs, which we want to support fully. One consequence of allowing these transitions is that the text parsers can get confused by columns which contain a valid integer in the first row and then switch to a string. Consider the following table: ) 4 20 PR( xxx yyy zzz ---- ---- ---- 111 aaa bbb ccc 222 ddd)RP( The xxx column has an integer value in row one a string in row two, while the yyy column has the reverse. The parser will erroneously treat the first column as having data type int: ) 5 38 PR( fundisp foo.tab XXX YYY ZZZ ---------- ------------ ------------ 111 'aaa' 'bbb' 1667457792 '222' 'ddd')RP( while the second column is processed correctly. This situation can be avoided in any number of ways, all of which force the data type of the first column to be a string. For example, you can edit the file and explicitly quote the first row of the column: ) 10 40 PR( xxx yyy zzz ---- ---- ---- "111" aaa bbb ccc 222 ddd [sh] fundisp foo.tab XXX YYY ZZZ ------------ ------------ ------------ '111' 'aaa' 'bbb' 'ccc' '222' 'ddd')RP( You can edit the file and explicitly set the data type of the first column: ) 10 40 PR( xxx:3A yyy zzz ------ ---- ---- 111 aaa bbb ccc 222 ddd [sh] fundisp foo.tab XXX YYY ZZZ ------------ ------------ ------------ '111' 'aaa' 'bbb' 'ccc' '222' 'ddd')RP( You also can explicitly set the column names and data types of all columns, without editing the file: ) 5 52 PR( [sh] fundisp foo.tab'[TEXT\201xxx:3A,yyy:3A,zzz:3a\202]' XXX YYY ZZZ ------------ ------------ ------------ '111' 'aaa' 'bbb' 'ccc' '222' 'ddd')RP( The issue of data type transitions \201which to allow and which to disallow\202 is still under discussion. )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 75 H(Last)WB 144 Sn( updated: August 3, 2007)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (view.html) D /Ti (Database View Support for Tables) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 48 Sn( )0 2 76 H(Funview:)WB 146 Sn()WB 145 Sn( Database View Support for Tables)EA()EH( )0 2 77 H(Summary)WB 147 Sn()EH( )0 P(This document contains a summary of the options for utilizing database-inspired Views of tables. )0 2 78 H(Description)WB 148 Sn()EH( )0 2 79 H(Database)WB 149 Sn( Views)EH( )0 P(In database parlance, a )BD(View)ES( defines a "virtual table", i.e., a description of row and/or column selection filters \201but with no permanent storage space allocated\202. When used in place of a table, a View selects the specified rows and/or columns from one or more real tables. Views enable you to see complicated data tables in a more convenient format. They also can be used as a security mechanism, by restricting user access to specific columns and/or rows. [See: ) 1 72 PR(http://www.cs.unibo.it/~ciaccia/COURSES/RESOURCES/SQLTutorial/sqlch5.htm)RP( for a good discussion of SQL Views.] )0 P(Funtools supports an expanded notion of Views for all tabular data \201FITS tables, raw binary tables, and ASCII column files\202. Funtools Views allow you to pre-set values for the filter specification, the columns to activate, and display format \201though the latter is for fundisp only\202. Setting the filter and column activation values provides functionality equivalent to that of a classical database View, while the ability to set the format is similar to classical report writing capabilities. )0 2 80 H(Funtools)WB 150 Sn( View Attributes)EH( )0 P(A Funtools View is a text file containing one or more of the following columns: ) 7 46 PR( column description ------ ----------------------------- view name of view file data file name or template filter filter specification columns columns to activate format fundisp format specification)RP( All of the attribute columns are optional, including the )BD(view)ES( name itself. This means that a View can be named or unnamed. Unnamed Views can refer to a specific file or a template of files \201obviously if neither the view or the file column is specified, the input View specification will never be used\202. You can specify any combination of filter, column, and format parameters. \201It also is possible to apply file-specific View to other files; see the discussion on )BD(View Lists)ES( below\202. Each column has a size limit of 1024 characters. )0 P(For example, consider the following View file: ) 13 70 PR( view file format columns filter ---- ---------------------- ------ ------------ ------- x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1 x2 ${HOME}/data/snr.ev x y pi pha cir 512 512 .1 x1 ${HOME}/data/snr.ev cir 512 512 .1 x1a ${HOME}/data/snr.ev x y pi pha x0 ${HOME}/data/snr.ev xf I=%4d xc x y pi pha xr cir 512 512 .1 *.ev x y pi pha *.fit x y dx dy cir 400 400 3 *.fits I=%3d x y dx dy cir 400 400 3)RP( This database example is in rdb format, i.e. using tab delimiters and permitting null values. Any valid ASCII table format is acceptable, but if you use a format that does not permit null values, it will be necessary to quote the null strings. )0 P(The first five entries \201x3, x2, x1, x1a, x0\202 are named entries defining default values specifically for the snr.ev data file. Typically, you would use these Views by specifying View name, and the corresponding file, filter, column, and format values would be used. Note that the x0 View is essentially an alias for the pathname of this file. )0 P(The next three entries define defaults that can be applied to any file. You typically would use these View names in conjunction with a specific file name \201see )BD(View Lists)ES( below\202 so that the associated parameter\201s\202 were applied to that file. )0 P(The last three entry in the database define unnamed Views that pertains to all files ending with the specified templates. In these cases, any View that specifies a file name matching the file template would be processed with the associated parameter attributes. )0 2 81 H(Invoking)WB 151 Sn( a Funtools View \201in Place of an Input File\202)EH( )0 P(To use a Funtools View, you simply pre-pend the "v:" prefix to a View name or a file name where an input file name usually is specified. For example: ) 1 14 PR( fundisp v:x3)RP( specifies that the View named x3 \201with its file name and associated parameters\202 is processed as the input file to fundisp. Using the example database, above, this is equivalent to: ) 1 73 PR( fundisp -f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha")RP( That is, the format is used with fundisp's -f \201format\202 switch, while the filename and extension are composed of the x3 View's filename and region filter. )0 P(Similarly, executing a command such as: ) 1 19 PR( fundisp v:foo.fit)RP( will match the unnamed View associated with the template "*.fit". This is equivalent to executing: ) 1 46 PR( fundisp foo.fit'[cir 400 400 3]' "x y dx dy")RP( Of course, if you omit the "v:" prefix, then no View processing takes place: ) 2 66 PR( fundisp foo.fit # process foo.fit without any View parameters fundisp x3 # error \201assuming there is no file named x3\202)RP( )0 2 82 H(Basic)WB 152 Sn( View Matching Rules)EH( )0 P(When a "v:" prefix is recognized, Funtools searches for a View database file in the following order: ) 5 59 PR( location description ------------ ------------------------------------ FUN_VIEWFILE environment variable \201any file name\202 ./.funtools.vu hidden file, default name $HOME/.funtools.vu hidden file, default name)RP( The first View database file located is used to construct a new filename, as well as an activation column specification and a format specification. The following rules are used: )0 P(1. An attempt is made to match the input name \201i.e., the part of the input View after the "v:" prefix\202 against the )BD(view)ES( column value \201if present\202 of each row in the database. If a match is found, the values of all non-blank columns are saved for later use. Also note that the first match terminates the search: i.e., )BD(the order of the database rows matters)ES(. )0 P(2. If no )BD(view)ES( match is made, an attempt is made to match the input name against the )BD(file)ES( column value \201if present\202. Matching is performed on the full pathname of both the input name and the database file name, and on the non-directory \201root\202 part of these files. This means that the root specification: ) 1 18 PR( fundisp v:snr.ev)RP( will match a row in the database that has a full pathname in the file, allowing you to use a )BD(file)ES(-matched View without having to specify the full pathname. In this example, the "v:snr.ev" View specification will match the first row \201v:x3\202 in the database: ) 1 67 PR( x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1)RP( even though the row contains a fully qualified pathname as the file value. Once again, values of all non-blank columns are saved, and the first match terminates the search. )0 P(3. If neither a )BD(view)ES( or a )BD(view)ES( match has been found, then a simple template match is attempted against the )BD(view)ES( values. Template matching supports a simplified version of file globbing \201not a regular expression\202, with support for a single "*" \201all characters\202, "?" \201single character\202, or "[...]" \201range\202 specification. )0 P(4. If no template match was found on the )BD(view)ES( column, then a simple template match is attempted against the )BD(file)ES( columns. )0 P(5. If no match is found, then the filename \201minus the "v:" prefix\202 is returned. )0 2 83 H(More)WB 153 Sn( on View Matching Rules: Single vs. Multiple Matches )EH( The matching rules described above stop after the first match, regardless of whether that match provides values for all three parameters \201filter, columns, and format\202. In cases where a )BD(view)ES( or )BD(file)ES( match does not provide all three values, it is possible that a template match might do so. With regard to the example View database above, the x1 View provides only a filter, while omitting both the format and columns values. But note that the final rows in the database could provide the values via a template match on the filename. This sort of multiple matching is especially valuable in order to provide "global" values to several Views. )0 P(Obviously, multiple matching might not be wanted in every case. Therefore, we support both multiple matching and single matching according to the value of the FUN_VIEWMATCH environment variable. If the FUN_VIEWMATCH environment variable exists and if its value begins with "s", then a single match is used and missing parameters are not filled in with subsequent template matches on the file name. That is, matching rules above are followed exactly as explained above. If the value of this environment variable begins with "m" \201or does not exist\202, then multiple matches are used to try to fill in missing parameters. In this case, template matching always takes place and missing values are taken from these template matches. )0 P(Thus, in the example above, the View specification: ) 1 14 PR( fundisp v:x1)RP( will take the file name and filter value from the x1 View: ) 1 70 PR( x1 ${HOME}/data/snr.ev cir 512 512 .1)RP( The column value then will be taken from the "*.ev" file template match against the x1 file name: ) 1 52 PR( *.ev x y pi pha)RP( Note once again that order is important: missing values are taken in the order in which the template matches are processed. )0 2 84 H(View)WB 154 Sn( Lists: Applying a View to Any File)EH( )0 P(It is possible to apply a named View, or even several Views, to any data file by appending a )BD(viewlist)ES( immediately after the standard "v:" prefix. A viewlist takes the form: ) 1 15 PR( :v1,v2,...vn:)RP( where v1, v2, etc. are named Views. The two ":" colon characters surrounding the list are required. Thus, the syntax for applying a viewlist to a file is: ) 1 34 PR( v::view1,view2,...viewn:filename)RP( Note that the name after the last ":" is assumed to be a file; it is not permissible \201or sensible\202 to use a View name. )0 P(For example, the View specification: ) 1 19 PR( fundisp v::x2:foo)RP( applies the x2 View to the file foo \201even if there is a View named foo\202 and \201in using our example database\202 is equivalent to: ) 1 45 PR( ./fundisp foo'[cir 512 512 .1] "x y pi pha")RP( The same command can be effected using a list of Views: ) 1 23 PR( fundisp v::x1,x1a:foo)RP( )0 P(What happens if a viewlist is used and the file also matches a template? Consider, for example, this View specification: ) 1 23 PR( fundisp v::x2:foo.fit)RP( Here, the x2 View will supply filter and column values, while the template *.fit can also supply \201different\202 filter and column values. In this case, the explicitly specified Views of the viewlist trump the matched view values. )0 P(On the other hand, if a file template match can supply a View value that is not supplied by the viewlist, then that value will be taken from the file template match. For example: ) 1 24 PR( fundisp v::x2:foo.fits)RP( does not explicitly supply a format value, but the file match on *.fits can and does. You can avoid supplying missing values using file template matching by replacing the first ":" with a "-" in a viewlist specification: ) 1 24 PR( fundisp v:-x2:foo.fits)RP( The use of ":+" to explicitly allow file template matching is also supported, but is the same as the default case. Note that the nuances of viewlist support are subject to change as our experience and understanding grow. )0 2 85 H(Overriding)WB 155 Sn( Values Associated with a View)EH( )0 P(To override values associated with a View, simply supply the override values in the correct place on the command line. Thus, given the example database described above, the command: ) 1 14 PR( fundisp v:x3)RP( specifies that the View named x3, along with its file name and associated parameters, be processed as the input file to fundisp in this way: ) 1 73 PR( fundisp -f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha")RP( To override one or more of these values, simply specify a new value for the format, filter, or columns. For example, if your input View file contains a filter, then the View will use that filter as an override of the View filter: ) 1 31 PR( fundisp v:x3'[cir 400 400 3]')RP( will use the columns and format of the x3 View but not the x3 filter. Further examples are: ) 2 67 PR( fundisp v:x3 "x y dx dy" # activate a different set of columns fundisp -f "I=%3d" v:x3 # use a different format statement)RP( )0 P(Note that extension names, extension index values, and other non-filter specifications )BD(do not)ES( override the View filter. Thus: ) 1 22 PR( fundisp v:foo.fit[3])RP( will still use the filter associated with the .fit template \201see above\202, since the "3" is an extension index, not a filter. )0 2 86 H(Environment)WB 156 Sn( Variables)EH( The following environment variables are used by Funtools Views: )0 DL()0 DT()BD(FUN_VIEWNAME)ES( )DD( The )BD(FUN_VIEWNAME)ES( environment variable specifies the name and location of the View database file. If not present, the files ./.funtools.vu and $HOME/.funtools.vu are searched for, in that order. )0 DT()BD(FUN_VIEWMATCH)ES( )DD( The )BD(FUN_VIEWMATCH)ES( environment variable specifies whether a single match or multiple match algorithm is used to locate parameter values. If the value of this environment variable begins with "s", then a single match is used and missing parameters are not filled in with subsequent template matches on the file name. If the value begins with "m", then multiple matches are used to try to fill in missing parameters. The default is to use multiple matches.)LD( )0 2 87 H(Restrictions)WB 157 Sn( and Problems)EH( Support for overriding a filter \201while not overriding extension names, extension indexes, etc.\202 requires that we can sense the presence of a filter in a bracket specification. It is unclear yet whether our algorithm is perfect. )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 88 H(Last)WB 158 Sn( updated: August 3, 2007)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (filters.html) D /Ti (Table Filtering) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 52 Sn( )0 2 89 H(Funfilters:)WB 165 Sn()WB 159 Sn( Filtering Rows in a Table)EA()EH( )0 2 90 H(Summary)WB 166 Sn()EH( )0 P(This document contains a summary of the user interface for filtering rows in binary tables. )0 2 91 H(Description)WB 167 Sn()EH( )0 P(Table filtering allows a program to select rows from an table \201e.g., X-ray event list\202 by checking each row against one or more expressions involving the columns in the table. When a table is filtered, only valid rows satisfying these expressions are passed through for processing. )0 P(A filter expression is specified using bracket notation appended to the filename of the data being processed: ) 1 23 PR( foo.fits[pha==1&)SY(\160)ES(==2])RP( It is also possible to put region specification inside a file and then pass the filename in bracket notation: ) 1 19 PR( foo.fits[@my.reg])RP( Filters must be placed after the extension and image section information, when such information is present. The correct order is: )UL()-1 LI( file[fileinfo,sectioninfo][filters] )-1 LI( file[fileinfo,sectioninfo,filters])LU( where: )UL()-1 LI( )BD(file)ES( is the Funtools file name )-1 LI( )BD(fileinfo)ES( is an ARRAY, EVENT, FITS extension, or FITS index )-1 LI( )BD(sectioninfo)ES( is the image section to extract )-1 LI( )BD(filters)ES( are spatial region and table \201row\202 filters to apply)LU( See )0 42 1 A(Funtools Files)42 0 TN TL()Ec /AF f D( for more information on file and image section specifications. )0 2 92 H(Filter)WB 168 Sn( Expressions)EH( )0 P(Table filtering can be performed on columns of data in a FITS binary table or a raw event file. Table filtering is accomplished by means of )BD(table filter specifications)ES(. An table filter specification consists of one or more )BD(filter expressions)ES( Filter specifications also can contain comments and local/global processing directives. )0 P(More specifically, a filter specification consist of one or more lines containing: ) 13 75 PR( # comment until end of line # include the following file in the table descriptor @file # each row expression can contain filters separated by operators [filter_expression] BOOLOP [filter_expression2], ... # each row expression can contain filters separated by the comma operator [filter_expression1], [filter_expression2], ... # the special row# keyword allows a range of rows to be processed row#=m:n # or a single row row#=m # regions are supported -- but are described elsewhere [spatial_region_expression])RP( )0 P(A single filter expression consists of an arithmetic, logical, or other operations involving one or more column values from a table. Columns can be compared to other columns, to header values, or to numeric constants. Standard math functions can be applied to columns. Separate filter expressions can be combined using boolean operators. Standard C semantics can be used when constructing expressions, with the usual precedence and associativity rules holding sway: ) 15 55 PR( Operator Associativity -------- ------------- \201\202 left to right !! \201logical not\202 right to left ! \201bitwise not\202 - \201unary minus\202 right to left * / left to right + - left to right < <= > >= left to right == != left to right & \201bitwise and\202 left to right ^ \201bitwise exclusive or\202 left to right | \201bitwise inclusive or\202 left to right && \201logical and\202 left to right || \201logical or\202 left to right = right to left)RP( For example, if energy and pha are columns in a table, then the following are valid expressions: ) 4 24 PR( pha>1 energy == pha \201pha>1\202 && \201energy<=2\202 max\201pha,energy\202>=2.5)RP( )0 P(Comparison values can be integers or floats. Integer comparison values can be specified in decimal, octal \201using '0' as prefix\202, hex \201using '0x' as prefix\202 or binary \201using '0b' as prefix\202. Thus, the following all specify the same comparison test of a status mask: ) 4 40 PR( \201status & 15\202 == 8 # decimal \201status & 017\202 == 010 # octal \201status & 0xf\202 == 0x8 # hex \201status & 0b1111\202 == 0b1000 # binary)RP( )0 P(The special keyword row# allows you to process a range of rows. When row# is specified, the filter code skips to the designated row and only processes the specified number of rows. The "*" character can be utilized as the high limit value to denote processing of the remaining rows. Thus: ) 1 14 PR( row#=100:109)RP( processes 10 rows, starting with row 100 \201counting from 1\202, while: ) 1 12 PR( row#=100:*)RP( specifies that all but the first 99 rows are to be processed. )0 P(Spatial region filtering allows a program to select regions of an image or rows of a table \201e.g., X-ray events\202 using simple geometric shapes and boolean combinations of shapes. For a complete description of regions, see )0 54 1 A(Spatial Region Filtering)54 0 TN TL()Ec /AF f D(. )0 2 93 H(Separators)WB 169 Sn()WB 160 Sn( Also Are Operators)EA()EH( )0 P(As mentioned previously, multiple filter expressions can be specified in a filter descriptor, separated by commas or new-lines. When such a comma or new-line separator is used, the boolean AND operator is automatically generated in its place. Thus and expression such as: ) 1 15 PR( pha==1,pi=2:4)RP( is equivalent to: ) 1 26 PR( \201pha==1\202 && \201pi>=2&)SY(\160)ES(<=4\202)RP( )0 P([Note that the behavior of separators is different for filter expressions and spatial region expressions. The former uses AND as the operator, while the latter user OR. See )0 60 1 A(Combining Region and Table Filters)60 0 TN TL()Ec /AF f D( for more information about these conventions and how they are treated when combined.] )0 2 94 H(Range)WB 170 Sn()WB 161 Sn( Lists)EA()EH()0 P( )0 P(Aside from the standard C syntax, filter expressions can make use of IRAF-style )BD(range lists)ES( which specify a range of values. The syntax requires that the column name be followed by an '=' sign, which is followed by one or more comma-delimited range expressions of the form: ) 4 52 PR( col = vv # col == vv in range col = :vv # col <= vv in range col = vv: # col >= vv in range col = vv1:vv2 # vv1 <= col <= vv2 in range)RP( The vv's above must be numeric constants; the right hand side of a range list cannot contain a column name or header value. )0 P(Note that, unlike an ordinary comma separator, the comma separator used between two or more range expressions denotes OR. Thus, when two or more range expressions are combined with a comma separator, the resulting expression is a shortcut for more complicated boolean logic. For example: ) 1 18 PR( col = :3,6:8,10:)RP( is equivalent to: ) 1 47 PR( \201col<=3\202 || \201col>=6 && col <=8\202 || \201col >=10\202)RP( Note also that the single-valued rangelist: ) 1 11 PR( col = val)RP( is equivalent to the C-based filter expression: ) 1 12 PR( col == val)RP( assuming, of course, that val is a numeric constant. )0 2 95 H(Math)WB 171 Sn()WB 162 Sn( Operations and Functions)EA()EH()0 P( )0 P(It is permissible to specify C math functions as part of the filter syntax. When the filter parser recognizes a function call, it automatically includes the math.h and links in the C math library. Thus, it is possible to filter rows by expressions such as these: )UL()-1 LI(\201pi+pha\202>\2012+log\201pi\202-pha\202 )-1 LI( min\201pi,pha\202*14>x )-1 LI( max\201pi,pha\202==\201pi+1\202 )-1 LI( feq\201pi,pha\202 )-1 LI( div\201pi,pha\202>0)LU( The function feq\201a,b\202 returns true \2011\202 if the difference between a and b \201taken as double precision values\202 is less than approximately 10E-15. The function div\201a,b\202 divides a by b, but returns NaN \201not a number\202 if b is 0. It is a safe way to avoid floating point errors when dividing one column by another. )0 2 96 H(Include)WB 172 Sn()WB 163 Sn( Files)EA()EH()0 P( )0 P(The special )BD(@filename)ES( directive specifies an include file containing filter expressions. This file is processed as part of the overall filter descriptor: ) 1 23 PR( foo.fits[pha==1,@foo])RP( )0 2 97 H(Header)WB 173 Sn()WB 164 Sn( Parameters)EA()EH()0 P( )0 P(The filter syntax supports comparison between a column value and a header parameter value of a FITS binary tables \201raw event files have no such header\202. The header parameters can be taken from the binary table header or the primary header. For example, assuming there is a header value MEAN_PHA in one of these headers, you can select photons having exactly this value using: )UL()-1 LI( pha==MEAN_PHA)LU( )0 2 98 H(Examples)WB 174 Sn()EH( )0 P(Table filtering is more easily described by means of examples. Consider data containing the following table structure: )UL()-1 LI( double TIME )-1 LI( int X )-1 LI( int Y )-1 LI( short PI )-1 LI( short PHA )-1 LI( int DX )-1 LI( int DY)LU( )0 P(Tables can be filtered on these columns using IRAF/QPOE range syntax or any valid C syntax. The following examples illustrate the possibilities: )0 DL( )0 P()0 DT( pha=10 )0 DT( pha==10 )DD( select rows whose pha value is exactly 10 )0 P()0 DT( pha=10:50 )DD( select rows whose pha value is in the range of 10 to 50 )0 P()0 DT( pha=10:50,100 )DD( select rows whose pha value is in the range of 10 to 50 or is equal to 100 )0 P()0 DT( pha>=10 && pha<=50 )DD( select rows whose pha value is in the range of 10 to 50 )0 P()0 DT( pi=1,2&&pha>3 )DD( select rows whose pha value is 1 or 2 and whose pi value is 3 )0 P()0 DT( pi=1,2 || pha>3 )DD( select rows whose pha value is 1 or 2 or whose pi value is 3 )0 P()0 DT( pha==pi+1 )DD( select rows whose pha value is 1 less than the pi value )0 P()0 DT( \201pha==pi+1\202 && \201time>50000.0\202 )DD( select rows whose pha value is 1 less than the pi value and whose time value is greater than 50000 )0 P()0 DT(\201pi+pha\202>20 )DD( select rows in which the sum of the pi and pha values is greater than 20 )0 P()0 DT( pi%2==1 )DD( select rows in which the pi value is odd)LD( )0 P(Currently, integer range list limits cannot be specified in binary notation \201use decimal, hex, or octal instead\202. Please contact us if this is a problem. )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 99 H(Last)WB 175 Sn( updated: November 17, 2005)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (idx.html) D /Ti (Table Filtering with Indexes) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 53 Sn( )0 2 100 H(Funidx:)WB 177 Sn()WB 176 Sn( Using Indexes to Filter Rows in a Table)EA()EH( )0 2 101 H(Summary)WB 178 Sn()EH( )0 P(This document contains a summary of the user interface for filtering rows in binary tables with indexes. )0 2 102 H(Description)WB 179 Sn()EH( )0 P(Funtools )0 52 1 A(Table Filtering)52 0 TN TL()Ec /AF f D( allows rows in a table to be selected based on the values of one or more columns in the row. Because the actual filter code is compiled on the fly, it is very efficient. However, for very large files \201hundreds of Mb or larger\202, evaluating the filter expression on each row can take a long time. Therefore, funtools supports index files for columns, which are used automatically during filtering to reduce dramatically the number of row evaluations performed. The speed increase for indexed filtering can be an order of magnitude or more, depending on the size of the file. )0 P(The )0 11 1 A(funindex)11 0 TN TL()Ec /AF f D( program creates an index on one or more columns in a binary table. For example, to create an index for the column pi in the file huge.fits, use: ) 1 23 PR( funindex huge.fits pi)RP( This will create an index named huge_pi.idx. )0 P(When a filter expression is initialized for row evaluation, funtools looks for an index file for each column in the filter expression. If found, and if the file modification date of the index file is later than that of the data file, then the index will be used to reduce the number of rows that are evaluated in the filter. When )0 54 1 A(Spatial Region Filtering)54 0 TN TL()Ec /AF f D( is part of the expression, the columns associated with the region are checked for index files. )0 P(If an index file is not available for a given column, then in general, all rows must be checked when that column is part of a filter expression. This is not true, however, when a non-indexed column is part of an AND expression. In this case, only the rows that pass the other part of the AND expression need to be checked. Thus, in some cases, filtering speed can increase significantly even if all columns are not indexed. )0 P(Also note that certain types of filter expression syntax cannot make use of indices. For example, calling functions with column names as arguments implies that all rows must be checked against the function value. Once again, however, if this function is part of an AND expression, then a significant improvement in speed still is possible if the other part of the AND expression is indexed. )0 P(For example, note below the dramatic speedup in searching a 1 Gb file using an AND filter, even when one of the columns \201pha\202 has no index: ) 49 69 PR( time fundisp \200 huge.fits'[idx_activate=0,idx_debug=1,pha=2348&&cir 4000 4000 1]' \200 "x y pha" x y pha ---------- ----------- ---------- 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 42.36u 13.07s 6:42.89 13.7% time fundisp \200 huge.fits'[idx_activate=1,idx_debug=1,pha=2348&&cir 4000 4000 1]' \200 "x y pha" x y pha ---------- ----------- ---------- idxeq: [INDEF] idxand sort: x[ROW 8037025:8070128] y[ROW 5757665:5792352] idxand\2011\202: INDEF [IDX_OR_SORT] )WR( idxall\2011\202: [IDX_OR_SORT] 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 3999.48 4000.47 2348 1.55u 0.37s 1:19.80 2.4%)RP( When all columns are indexed, the increase in speed can be even more dramatic: ) 50 67 PR( time fundisp \200 huge.fits'[idx_activate=0,idx_debug=1,pi=770&&cir 4000 4000 1]' \200 "x y pi" x y pi ---------- ----------- ---------- 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 42.60u 12.63s 7:28.63 12.3% time fundisp \200 huge.fits'[idx_activate=1,idx_debug=1,pi=770&&cir 4000 4000 1]' \200 "x y pi" x y pi ---------- ----------- ---------- idxeq: pi start=9473025,stop=9492240 => pi[ROW 9473025:9492240] idxand sort: x[ROW 8037025:8070128] y[ROW 5757665:5792352] idxor sort/merge: pi[ROW 9473025:9492240] [IDX_OR_SORT] )WR( idxmerge\2015\202: [IDX_OR_SORT] pi[ROW] idxall\2011\202: [IDX_OR_SORT] 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 3999.48 4000.47 770 1.67u 0.30s 0:24.76 7.9%)RP( )0 P(The miracle of indexed filtering \201and indeed, of any indexing\202 is the speed of the binary search on the index, which is of order log2\201n\202 instead of n. \201The funtools binary search method is taken from http://www.tbray.org/ongoing/When/200x/2003/03/22/Binary, to whom grateful acknowledgement is made.\202 This means that the larger the file, the better the performance. Conversely, it also means that for small files, using an index \201and the overhead involved\202 can slow filtering down somewhat. Our tests indicate that on a file containing a few tens of thousands of rows, indexed filtering can be 10 to 20 percent slower than non-indexed filtering. Of course, your mileage will vary with conditions \201disk access speed, amount of available memory, process load, etc.\202 )0 P(Any problem encountered during index processing will result in indexing being turned off, and replaced by filtering all rows. You can turn filtering off manually by setting the idx_activate variable to 0 \201in a filter expression\202 or the FILTER_IDX_ACTIVATE environment variable to 0 \201in the global environment\202. Debugging output showing how the indexes are being processed can be displayed to stderr by setting the idx_debug variable to 1 \201in a filter expression\202 or the FILTER_IDX_DEBUG environment variable to 1 \201in the global environment\202. )0 P(Currently, indexed filtering only works with FITS binary tables and raw event files. It does not work with text files. This restriction might be removed in a future release. )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 103 H(Last)WB 180 Sn( updated: August 3, 2007)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (regions.html) D /Ti (Spatial Region Filtering) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 54 Sn( )0 2 104 H(Regions:)WB 182 Sn()WB 181 Sn( Spatial Region Filtering)EA()EH( )0 2 105 H(Summary)WB 183 Sn()EH( )0 P(This document contains a summary of the user interface for spatial region filtering images and tables. )0 2 106 H(Description)WB 184 Sn()EH( )0 P(Spatial region filtering allows a program to select regions of an image or rows of a table \201e.g., X-ray events\202 to process using simple geometric shapes and boolean combinations of shapes. When an image is filtered, only pixels found within these shapes are processed. When a table is filtered, only rows found within these shapes are processed. )0 P(Spatial region filtering for images and tables is accomplished by means of )BD(region specifications)ES(. A region specification consists of one or more )BD(region expressions)ES(, which are geometric shapes,combined according to the rules of boolean algebra. Region specifications also can contain comments and local/global processing directives. )0 P(Typically, region specifications are specified using bracket notation appended to the filename of the data being processed: ) 1 31 PR( foo.fits[circle\201512,512,100\202])RP( It is also possible to put region specification inside a file and then pass the filename in bracket notation: ) 1 19 PR( foo.fits[@my.reg])RP( )0 P(When region filters are passed in bracket notation in this manner, the filtering is set up automatically when the file is opened and all processing occurs through the filter. Programs also can use the filter library API to open filters explicitly. )0 2 107 H(Region)WB 185 Sn( Expressions)EH( More specifically, region specifications consist of one or more lines containing: ) 9 68 PR( # comment until end of line global keyword=value keyword=value ... # set global value\201s\202 # include the following file in the region descriptor @file # use the FITS image as a mask \201cannot be used with other regions\202 @fitsimage # each region expression contains shapes separated by operators [region_expression1], [region_expression2], ... [region_expression], [region_expression], ...)RP( )0 P(A single region expression consists of: ) 8 72 PR( # parens and commas are optional, as is the + sign [+-]shape\201num , num , ...\202 OP1 shape num num num OP2 shape ... e.g.: \201[+-]shape\201num , num , ...\202 && shape num num || shape\201num, num\202 # a comment can come after a region -- reserved for local properties [+-]shape\201num , num , ...\202 # local properties go here, e.g. color=red)RP( )0 P(Thus, a region descriptor consists of one or more )BD(region expressions)ES( or )BD(regions)ES(, separated by comas, new-lines, or semi-colons. Each )BD(region)ES( consists of one or more )BD(geometric shapes)ES( combined using standard boolean operation. Several types of shapes are supported, including: ) 11 57 PR( shape: arguments: ----- ---------------------------------------- ANNULUS xcenter ycenter inner_radius outer_radius BOX xcenter ycenter xwidth yheight \201angle\202 CIRCLE xcenter ycenter radius ELLIPSE xcenter ycenter xwidth yheight \201angle\202 FIELD none LINE x1 y1 x2 y2 PIE xcenter ycenter angle1 angle2 POINT x1 y1 POLYGON x1 y1 x2 y2 ... xn yn)RP( )0 P(In addition, the following regions accept )BD(accelerator)ES( syntax: ) 13 73 PR( shape arguments ----- ------------------------------------------ ANNULUS xcenter ycenter radius1 radius2 ... radiusn ANNULUS xcenter ycenter inner_radius outer_radius n=[number] BOX xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn \201angle\202 BOX xcenter ycenter xwlo yhlo xwhi yhhi n=[number] \201angle\202 CIRCLE xcenter ycenter r1 r2 ... rn # same as annulus CIRCLE xcenter ycenter rinner router n=[number] # same as annulus ELLIPSE xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn \201angle\202 ELLIPSE xcenter ycenter xwlo yhlo xwhi yhhi n=[number] \201angle\202 PIE xcenter ycenter angle1 angle2 \201angle3\202 \201angle4\202 \201angle5\202 ... PIE xcenter ycenter angle1 angle2 \201n=[number]\202 POINT x1 y1 x2 y2 ... xn yn)RP( Note that the circle accelerators are simply aliases for the annulus accelerators. See )0 55 1 A(region geometry)55 0 TN TL()Ec /AF f D( for more information about accelerators. )0 P(Finally, the following are combinations of pie with different shapes \201called "panda" for "Pie AND Annulus"\202 allow for easy specification of radial sections: ) 6 75 PR( shape: arguments: ----- --------- PANDA xcen ycen ang1 ang2 nang irad orad nrad # circular CPANDA xcen ycen ang1 ang2 nang irad orad nrad # circular BPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad \201ang\202 # box EPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad \201ang\202 # ellipse)RP( The panda and cpanda specify combinations of annulus and circle with pie, respectively and give identical results. The bpanda combines box and pie, while epanda combines ellipse and pie. See )0 55 1 A(region geometry)55 0 TN TL()Ec /AF f D( for more information about pandas. )0 P(The following "shapes" are ignored by funtools \201generated by ds9\202: ) 8 62 PR( shape: arguments: ----- --------- PROJECTION x1 y1 x2 y2 width # NB: ignored by funtools RULER x1 y1 x2 y2 # NB: ignored by funtools TEXT x y # NB: ignored by funtools GRID # NB: ignored by funtools TILE # NB: ignored by funtools COMPASS # NB: ignored by funtools)RP( )0 P(All arguments to regions are real values; integer values are automatically converted to real where necessary. All angles are in degrees and run from the positive image x-axis to the positive image y-axis. If a rotation angle is part of the associated WCS header, that angle is added implicitly as well. )0 P(Note that 3-letter abbreviations are supported for all shapes, so that you can specify "circle" or "cir". )0 P()0 2 108 H(Columns)WB 186 Sn( Used in Region Filtering)EH( )0 P(By default, the x,y values in a region expression refer to the two "image binning" columns, i.e. the columns that would be used to bin the data into an image. For images, these are just the 2 dimensions of the image. For tables, these usually default to x and y but can be changed as required. For example, in Funtools, new binning columns are specified using a bincols=\201col1,col2\202 statement within the bracket string on the command line. )0 P(Alternate columns for region filtering can be specified by the syntax: ) 1 25 PR( \201col1,col2\202=region\201...\202)RP( e.g.: ) 3 34 PR( \201X,Y\202=annulus\201x,y,ri,ro\202 \201PHA,PI\202=circle\201x,y,r\202 \201DX,DY\202=ellipse\201x,y,a,b[,angle]\202)RP( )0 P()0 2 109 H(Region)WB 187 Sn( Algebra)EH( \201See also )0 56 1 A(Region Algebra)56 0 TN TL()Ec /AF f D( for more complete information.\202 )0 P(Region shapes can be combined together using Boolean operators: ) 6 72 PR( Symbol Operation Use -------- --------- ----------------------------------- ! not Exclude this shape from this region & or && and Include only the overlap of these shapes | or || inclusive or Include all of both shapes ^ exclusive or Include both shapes except their overlap)RP( Note that the !region syntax must be combined with another region in order that we be able to assign a region id properly. That is, ) 1 21 PR( !circle\201512,512,10\202)RP( is not a legal region because there is no valid region id to work with. To get the full field without a circle, combine the above with field\201\202, as in: ) 1 32 PR( field\201\202 && !circle\201512,512,10\202)RP( )0 2 110 H()WB 188 Sn( Region Separators Also Are Operators)EH( )0 P(As mentioned previously, multiple region expressions can be specified in a region descriptor, separated by commas, new-lines, or semi-colons. When such a separator is used, the boolean OR operator is automatically generated in its place but, unlike explicit use of the OR operator, the region ID is incremented \201starting from 1\202. )0 P(For example, the two shapes specified in this example are given the same region value: ) 1 50 PR( foo.fits[circle\201512,512,10\202||circle\201400,400,20\202])RP( On the other hand, the two shapes defined in the following example are given different region values: ) 1 49 PR( foo.fits[circle\201512,512,10\202,circle\201400,400,20\202])RP( )0 P(Of course these two examples will both mask the same table rows or pixels. However, in programs that distinguish region id's \201such as )0 5 1 A(funcnts)5 0 TN TL()Ec /AF f D( \202, they will act differently. The explicit OR operator will result in one region expression consisting of two shapes having the same region id and funcnts will report a single region. The comma operator will cause funcnts to report two region expressions, each with one shape, in its output. )0 P(In general, commas are used to separate region expressions entered in bracket notation on the command line: ) 2 57 PR( # regions are added to the filename in bracket notation foo.fits[circle\201512,512,100\202,circle\201400,400,20\202])RP( New-lines are used to separate region expressions in a file: ) 4 58 PR( # regions usually are separated by new-lines in a file # use @filename to include this file on the command line circle\201512,512,100\202 circle\201400,400,20\202)RP( Semi-colons are provided for backward compatibility with the original IRAF/PROS implementation and can be used in either case. )0 P(If a pixel is covered by two different regions expressions, it is given the mask value of the )BD(first)ES( region that contains that pixel. That is, successive regions )BD(do not)ES( overwrite previous regions in the mask, as was the case with the original PROS regions. In this way, an individual pixel is covered by one and only one region. This means that one must sometimes be careful about the order in which regions are defined. If region N is fully contained within region M, then N should be defined )BD(before)ES( M, or else it will be "covered up" by the latter. )0 2 111 H(Region)WB 189 Sn( Exclusion)EH( )0 P(Shapes also can be globally excluded from all the region specifiers in a region descriptor by using a minus sign before a region: ) 4 73 PR( operator arguments: -------- ----------- - Globally exclude the region expression following '-' sign from ALL regions specified in this file)RP( The global exclude region can be used by itself; in such a case, field\201\202 is implied. )0 P(A global exclude differs from the local exclude \201i.e. a shape prefixed by the logical not "!" symbol\202 in that global excludes are logically performed last, so that no region will contain pixels from a globally excluded shape. A local exclude is used in a boolean expression with an include shape, and only excludes pixels from that include shape. Global excludes cannot be used in boolean expressions. )0 2 112 H(Include)WB 190 Sn( Files)EH( )0 P(The )BD(@filename)ES( directive specifies an include file containing region expressions. This file is processed as part of the overall region descriptor: ) 1 35 PR( foo.fits[circle\201512,512,10\202,@foo])RP( A filter include file simply includes text without changing the state of the filter. It therefore can be used in expression. That is, if the file foo1 contains "pi==1" and foo2 contains "pha==2" then the following expressions are equivalent: ) 3 57 PR( "[@foo1&&@foo2]" is equivalent to "[pi==1&&pha==2]" "[pha==1||@foo2]" is equivalent to "[pi==1||pha==2]" "[@foo1,@foo2]" is equivalent to "[pi==1,pha==2]")RP( Be careful that you specify evaluation order properly using parenthesis, especially if the include file contains multiple filter statements. For example, consider a file containing two regions such as: ) 2 19 PR( circle 512 512 10 circle 520 520 10)RP( If you want to include only events \201or pixels\202 that are in these regions and have a pi value of 4, then the correct syntax is: ) 1 17 PR( pi==4&&\201@foo\202)RP( since this is equivalent to: ) 1 53 PR( pi==4 && \201circle 512 512 10 || circle 520 520 10\202)RP( If you leave out the parenthesis, you are filtering this statement: ) 1 52 PR( pi==4 && circle 512 512 10 || circle 520 520 10\202)RP( which is equivalent to: ) 1 54 PR( \201pi==4 && circle 512 512 10\202 || circle 520 520 10\202)RP( The latter syntax only applies the pi test to the first region. )0 P(For image-style filtering, the )BD(@filename)ES( can specify an 8-bit or 16-bit FITS image. In this case, the pixel values in the mask image are used as the region mask. The valid pixels in the mask must have positive values. Zero values are excluded from the mask and negative values are not allowed. Moreover, the region id value is taken as the image pixel value and the total number of regions is taken to be the highest pixel value. The dimensions of the image mask must be less than or equal to the image dimensions of the data. The mask will be replicated as needed to match the size of the image. \201Thus, best results are obtained when the data dimensions are an even multiple of the mask dimensions.\202 )0 P(An image mask can be used in any image filtering operation, regardless of whether the data is of type image or table. For example, the )0 5 1 A(funcnts)5 0 TN TL()Ec /AF f D( \202 program performs image filtering on images or tables, and so FITS image masks are valid input for either type of data in this program.. An image mask cannot be used in a program such as )0 7 1 A(fundisp)7 0 TN TL()Ec /AF f D( \202 when the input data is a table, because fundisp displays rows of a table and processes these rows using event-style filtering. )0 2 113 H(Global)WB 191 Sn( and Local Properties of Regions)EH( )0 P(The ds9 image display program describes a host of properties such as color, font, fix/free state, etc. Such properties can be specified globally \201for all regions\202 or locally \201for an individual region\202. The )BD(global)ES( keyword specifies properties and qualifiers for all regions, while local properties are specified in comments on the same line as the region: ) 4 30 PR( global color=red circle\20110,10,2\202 circle\20120,20,3\202 # color=blue circle\20130,30,4\202)RP( The first and third circles will be red, which the second circle will be blue. Note that funtools currently ignores region properties, as they are used in display only. )0 2 114 H()WB 192 Sn( Coordinate Systems)EH( For each region, it is important to specify the coordinate system used to interpret the region, i.e., to set the context in which position and size values are interpreted. For this purpose, the following keywords are recognized: ) 12 68 PR( name description ---- ------------------------------------------ PHYSICAL pixel coords of original file using LTM/LTV IMAGE pixel coords of current file FK4, B1950 sky coordinate systems FK5, J2000 sky coordinate systems GALACTIC sky coordinate systems ECLIPTIC sky coordinate systems ICRS currently same as J2000 LINEAR linear wcs as defined in file AMPLIFIER mosaic coords of original file using ATM/ATV DETECTOR mosaic coords of original file using DTM/DTV)RP( )0 P()0 2 115 H(Specifying)WB 193 Sn( Positions, Sizes, and Angles)EH( The arguments to region shapes can be floats or integers describing positions and sizes. They can be specified as pure numbers or using explicit formatting directives: ) 21 57 PR( position arguments description ------------------ ------------------------------ [num] context-dependent \201see below\202 [num]d degrees [num]r radians [num]p physical pixels [num]i image pixels [num]:[num]:[num] hms for 'odd' position arguments [num]:[num]:[num] dms for 'even' position arguments [num]h[num]m[num]s explicit hms [num]d[num]m[num]s explicit dms size arguments description -------------- ----------- [num] context-dependent \201see below\202 [num]" arc seconds [num]' arc minutes [num]d degrees [num]r radians [num]p physical pixels [num]i image pixels)RP( When a "pure number" \201i.e. one without a format directive such as 'd' for 'degrees'\202 is specified, its interpretation depends on the context defined by the 'coordsys' keyword. In general, the rule is: )0 P()BD(All pure numbers have implied units corresponding to the current coordinate system.)ES( )0 P(If no such system is explicitly specified, the default system is implicitly assumed to be PHYSICAL. )0 P(In practice this means that for IMAGE and PHYSICAL systems, pure numbers are pixels. Otherwise, for all systems other than linear, pure numbers are degrees. For LINEAR systems, pure numbers are in the units of the linear system. This rule covers both positions and sizes. )0 P(The input values to each shape can be specified in several coordinate systems including: ) 12 68 PR( name description ---- ---------------------------- IMAGE pixel coords of current file LINEAR linear wcs as defined in file FK4, B1950 various sky coordinate systems FK5, J2000 GALACTIC ECLIPTIC ICRS PHYSICAL pixel coords of original file using LTM/LTV AMPLIFIER mosaic coords of original file using ATM/ATV DETECTOR mosaic coords of original file using DTM/DTV)RP( )0 P(If no coordinate system is specified, PHYSICAL is assumed. PHYSICAL or a World Coordinate System such as J2000 is preferred and most general. The coordinate system specifier should appear at the beginning of the region description, on a separate line \201in a file\202, or followed by a new-line or semicolon; e.g., ) 2 26 PR( global coordsys physical circle 6500 9320 200)RP( The use of celestial input units automatically implies WORLD coordinates of the reference image. Thus, if the world coordinate system of the reference image is J2000, then ) 1 27 PR( circle 10:10:0 20:22:0 3')RP( is equivalent to: ) 1 35 PR( circle 10:10:0 20:22:0 3' # j2000)RP()RP( Note that by using units as described above, you may mix coordinate systems within a region specifier; e.g., ) 1 32 PR( circle 6500 9320 3' # physical)RP( )0 P(Note that, for regions which accept a rotation angle: ) 2 29 PR(ellipse \201x, y, r1, r2, angle\202 box\201x, y, w, h, angle\202)RP( the angle is relative to the specified coordinate system. In particular, if the region is specified in WCS coordinates, the angle is related to the WCS system, not x/y image coordinate axis. For WCS systems with no rotation, this obviously is not an issue. However, some images do define an implicit rotation \201e.g., by using a non-zero CROTA value in the WCS parameters\202 and for these images, the angle will be relative to the WCS axes. In such case, a region specification such as: ) 1 54 PR(fk4;ellipse\20122:59:43.985, +58:45:26.92,320", 160", 30\202)RP( will not, in general, be the same region specified as: ) 1 38 PR(physical;ellipse\201465, 578, 40, 20, 30\202)RP( even when positions and sizes match. The angle is relative to WCS axes in the first case, and relative to physical x,y axes in the second. )0 P(More detailed descriptions are available for: )0 55 1 A(Region Geometry)55 0 TN TL()Ec /AF f D(, )0 56 1 A(Region Algebra)56 0 TN TL()Ec /AF f D(, )0 57 1 A(Region Coordinates)57 0 TN TL()Ec /AF f D(, and )0 58 1 A(Region Boundaries)58 0 TN TL()Ec /AF f D(. )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 116 H(Last)WB 194 Sn( updated: November 17, 2005)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (reggeometry.html) D /Ti (Region Geometry) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 55 Sn( )0 2 117 H(RegGeometry:)WB 196 Sn()WB 195 Sn( Geometric Shapes in Spatial Region Filtering)EA()EH( )0 2 118 H(Summary)WB 197 Sn()EH( )0 P(This document describes the geometry of regions available for spatial filtering in IRAF/PROS analysis. )0 2 119 H(Geometric)WB 198 Sn( shapes)EH( )0 P(Several geometric shapes are used to describe regions. The valid shapes are: ) 11 57 PR( shape: arguments: ----- ---------------------------------------- ANNULUS xcenter ycenter inner_radius outer_radius BOX xcenter ycenter xwidth yheight \201angle\202 CIRCLE xcenter ycenter radius ELLIPSE xcenter ycenter xwidth yheight \201angle\202 FIELD none LINE x1 y1 x2 y2 PIE xcenter ycenter angle1 angle2 POINT x1 y1 POLYGON x1 y1 x2 y2 ... xn yn)RP( All arguments are real values; integer values are automatically converted to real where necessary. All angles are in degrees and specify angles that run counter-clockwise from the positive y-axis. )0 P(Shapes can be specified using "command" syntax: ) 1 23 PR( [shape] arg1 arg2 ...)RP( or using "routine" syntax: ) 1 26 PR( [shape]\201arg1, arg2, ...\202)RP( or by any combination of the these. \201Of course, the parentheses must balance and there cannot be more commas than necessary.\202 The shape keywords are case-insensitive. Furthermore, any shape can be specified by a three-character unique abbreviation. For example, one can specify three circular regions as: ) 1 64 PR( "foo.fits[CIRCLE 512 512 50;CIR\201128 128, 10\202;cir\201650,650,20\202]")RP( \201Quotes generally are required to protect the region descriptor from being processed by the Unix shell.\202 )2 1 1 HR( )0 P(The )BD(annulus)ES( shape specifies annuli, centered at xcenter, ycenter, with inner and outer radii \201r1, r2\202. For example, ) 1 20 PR( ANNULUS 25 25 5 10)RP( specifies an annulus centered at 25.0 25.0 with an inner radius of 5.0 and an outer radius of 10. Assuming \201as will be done for all examples in this document, unless otherwise noted\202 this shape is used in a mask of size 40x40, it will look like this: ) 42 51 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:........................................ 39:........................................ 38:........................................ 37:........................................ 36:........................................ 35:........................................ 34:....................111111111........... 33:...................11111111111.......... 32:.................111111111111111........ 31:.................111111111111111........ 30:................11111111111111111....... 29:...............1111111.....1111111...... 28:...............111111.......111111...... 27:...............11111.........11111...... 26:...............11111.........11111...... 25:...............11111.........11111...... 24:...............11111.........11111...... 23:...............11111.........11111...... 22:...............111111.......111111...... 21:...............1111111.....1111111...... 20:................11111111111111111....... 19:.................111111111111111........ 18:.................111111111111111........ 17:...................11111111111.......... 16:....................111111111........... 15:........................................ 14:........................................ 13:........................................ 12:........................................)WR( 11:........................................ 10:........................................ 9:........................................ 8:........................................ 7:........................................ 6:........................................ 5:........................................ 4:........................................ 3:........................................ 2:........................................ 1:........................................)RP( )2 1 1 HR( )0 P(The )BD(box)ES( shape specifies an orthogonally oriented box, centered at xcenter, ycenter, of size xwidth, yheight. It requires four arguments and accepts an optional fifth argument to specify a rotation angle. When the rotation angle is specified \201in degrees\202, the box is rotated by an angle that runs counter-clockwise from the positive y-axis. )0 P(The )BD(box)ES( shape specifies a rotated box, centered at xcenter, ycenter, of size xwidth, yheight. The box is rotated by an angle specified in degrees that runs counter-clockwise from the positive y-axis. If the angle argument is omitted, it defaults to 0. )2 1 1 HR( )0 P(The )BD(circle)ES( shape specifies a circle, centered at xcenter, ycenter, of radius r. It requires three arguments. )2 1 1 HR( )0 P(The )BD(ellipse)ES( shape specifies an ellipse, centered at xcenter, ycenter, with y-axis width a and the y-axis length b defined such that: ) 1 27 PR( x**2/a**2 + y**2/b**2 = 1)RP( Note that a can be less than, equal to, or greater than b. The ellipse is rotated the specified number of degrees. The rotation is done according to astronomical convention, counter-clockwise from the positive y-axis. An ellipse defined by: ) 1 23 PR( ELLIPSE 20 20 5 10 45)RP( will look like this: ) 42 49 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:........................................ 39:........................................ 38:........................................ 37:........................................ 36:........................................ 35:........................................ 34:........................................ 33:........................................ 32:........................................ 31:........................................ 30:........................................ 29:........................................ 28:........................................ 27:............111111...................... 26:............11111111.................... 25:............111111111................... 24:............11111111111................. 23:............111111111111................ 22:............111111111111................ 21:.............111111111111............... 20:.............1111111111111.............. 19:..............111111111111.............. 18:...............111111111111............. 17:...............111111111111............. 16:................11111111111............. 15:..................111111111............. 14:...................11111111............. 13:.....................111111............. 12:........................................)WR( 11:........................................ 10:........................................ 9:........................................ 8:........................................ 7:........................................ 6:........................................ 5:........................................ 4:........................................ 3:........................................ 2:........................................ 1:........................................)RP( )2 1 1 HR( )0 P(The )BD(field)ES( shape specifies the entire field as a region. It is not usually specified explicitly, but is used implicitly in the case where no regions are specified, that is, in cases where either a null string or some abbreviation of the string "none" is input. )BD(Field)ES( takes no arguments. )2 1 1 HR( )0 P(The )BD(pie)ES( shape specifies an angular wedge of the entire field, centered at xcenter, ycenter. The wedge runs between the two specified angles. The angles are given in degrees, running counter-clockwise from the positive x-axis. For example, ) 1 18 PR( PIE 20 20 90 180)RP( defines a region from 90 degrees to 180 degrees, i.e., quadrant 2 of the Cartesian plane. The display of such a region looks like this: ) 42 51 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:11111111111111111111.................... 39:11111111111111111111.................... 38:11111111111111111111.................... 37:11111111111111111111.................... 36:11111111111111111111.................... 35:11111111111111111111.................... 34:11111111111111111111.................... 33:11111111111111111111.................... 32:11111111111111111111.................... 31:11111111111111111111.................... 30:11111111111111111111.................... 29:11111111111111111111.................... 28:11111111111111111111.................... 27:11111111111111111111.................... 26:11111111111111111111.................... 25:11111111111111111111.................... 24:11111111111111111111.................... 23:11111111111111111111.................... 22:11111111111111111111.................... 21:11111111111111111111.................... 20:........................................ 19:........................................ 18:........................................ 17:........................................ 16:........................................ 15:........................................ 14:........................................ 13:........................................ 12:........................................)WR( 11:........................................ 10:........................................ 9:........................................ 8:........................................ 7:........................................ 6:........................................ 5:........................................ 4:........................................ 3:........................................ 2:........................................ 1:........................................)RP( The pie slice specified is always a counter-clockwise sweep between the angles, starting at the first angle and ending at the second. Thus: ) 1 17 PR( PIE 10 15 30 60)RP( describes a 30 degree sweep from 2 o'clock to 1 o'clock, while: ) 1 17 PR( PIE 10 15 60 30)RP( describes a 330 degree counter-clockwise sweep from 1 o'clock to 2 o'clock passing through 12 o'clock \2010 degrees\202. Note in both of these examples that the center of the slice can be anywhere on the plane. The second mask looks like this: ) 42 51 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:111111111111111111111111................ 39:11111111111111111111111................. 38:11111111111111111111111................. 37:1111111111111111111111.................. 36:1111111111111111111111.................. 35:111111111111111111111................... 34:11111111111111111111.................... 33:11111111111111111111.................... 32:1111111111111111111....................1 31:1111111111111111111..................111 30:111111111111111111.................11111 29:111111111111111111................111111 28:11111111111111111...............11111111 27:1111111111111111..............1111111111 26:1111111111111111.............11111111111 25:111111111111111............1111111111111 24:111111111111111..........111111111111111 23:11111111111111.........11111111111111111 22:11111111111111........111111111111111111 21:1111111111111.......11111111111111111111 20:111111111111......1111111111111111111111 19:111111111111....111111111111111111111111 18:11111111111....1111111111111111111111111 17:11111111111..111111111111111111111111111 16:1111111111.11111111111111111111111111111 15:1111111111111111111111111111111111111111 14:1111111111111111111111111111111111111111 13:1111111111111111111111111111111111111111 12:1111111111111111111111111111111111111111)WR( 11:1111111111111111111111111111111111111111 10:1111111111111111111111111111111111111111 9:1111111111111111111111111111111111111111 8:1111111111111111111111111111111111111111 7:1111111111111111111111111111111111111111 6:1111111111111111111111111111111111111111 5:1111111111111111111111111111111111111111 4:1111111111111111111111111111111111111111 3:1111111111111111111111111111111111111111 2:1111111111111111111111111111111111111111 1:1111111111111111111111111111111111111111)RP( The pie slice goes to the edge of the field. To limit its scope, pie usually is is combined with other shapes, such as circles and annuli, using boolean operations. \201See below and in "help regalgebra"\202. )0 P(Pie Performance Notes: )0 P(Pie region processing time is proportional to the size of the image, and not the size of the region. This is because the pie shape is the only infinite length shape, and we essentially must check all y rows for inclusion \201unlike other regions, where the y limits can be calculated beforehand\202. Thus, pie can run very slowly on large images. In particular, it will run MUCH more slowly than the panda shape in image-based region operations \201such as funcnts\202. We recommend use of panda over pie where ever possible. )0 P(If you must use pie, always try to put it last in a boolean && expression. The reason for this is that the filter code is optimized to exit as soon as the result is know. Since pie is the slowest region, it is better to avoid executing it if another region can decide the result. Consider, for example, the difference in time required to process a Chandra ACIS file when a pie and circle are combined in two different orders: ) 5 74 PR( time ./funcnts nacis.fits "circle 4096 4096 100 && pie 4096 4096 10 78" 2.87u 0.38s 0:35.08 9.2% time ./funcnts nacis.fits "pie 4096 4096 10 78 && circle 4096 4096 100 " 89.73u 0.36s 1:03.50 141.8%)RP( )0 P(Black-magic performance note: )0 P(Panda region processing uses a )BD(quick test)ES( pie region instead of the normal pie region when combining its annulus and pie shapes. This )BD(qtpie)ES( shape differs from the normal pie in that it utilizes the y limits from the previous region with which it is combined. In a panda shape, which is a series of annuli combined with pies, the processing time is thus reduced to that of the annuli. )0 P(You can use the qtpie shape instead of pie in cases where you are combining pie with another shape using the && operator. This will cause the pie limits to be set using limits from the other shape, and will speed up the processing considerably. For example, the above execution of funcnts can be improved considerably using this technique: ) 2 75 PR( time ./funcnts nacis.fits "circle 4096 4096 100 && qtpie 4096 4096 10 78" 4.66u 0.33s 0:05.87 85.0%)RP( )0 P(We emphasize that this is a quasi-documented feature and might change in the future. The qtpie shape is not recognized by ds9 or other programs. )2 1 1 HR( )0 P(The )BD(line)ES( shape allows single pixels in a line between \201x1,y1\202 and \201x2,y2\202 to be included or excluded. For example: ) 44 49 PR( LINE \2015,6, 24,25\202 ) 43 49 PR(displays as: ) 42 49 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:........................................ 39:........................................ 38:........................................ 37:........................................ 36:........................................ 35:........................................ 34:........................................ 33:........................................ 32:........................................ 31:........................................ 30:........................................ 29:........................................ 28:........................................ 27:........................................ 26:........................................ 25:.......................1................ 24:......................1................. 23:.....................1.................. 22:....................1................... 21:...................1.................... 20:..................1..................... 19:.................1...................... 18:................1....................... 17:...............1........................ 16:..............1......................... 15:.............1.......................... 14:............1...........................)WR( 13:...........1............................)WR( 12:..........1.............................)WR( 11:.........1.............................. 10:........1............................... 9:.......1................................ 8:......1................................. 7:.....1.................................. 6:....1................................... 5:........................................ 4:........................................ 3:........................................ 2:........................................ 1:........................................)RP( )2 1 1 HR( )0 P(The )BD(point)ES( shape allows single pixels to be included or excluded. Although the \201x,y\202 values are real numbers, they are truncated to integer and the corresponding pixel is included or excluded, as specified. )0 P(Several points can be put in one region declaration; unlike the original IRAF implementation, each now is given a different region mask value. This makes it easier, for example, for funcnts to determine the number of photons in the individual pixels. For example, ) 1 37 PR( POINT \2015,6, 10,11, 20,20, 35,30\202)RP( will give the different region mask values to all four points, as shown below: ) 42 49 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:........................................ 39:........................................ 38:........................................ 37:........................................ 36:........................................ 35:........................................ 34:........................................ 33:........................................ 32:........................................ 31:........................................ 30:..................................4..... 29:........................................ 28:........................................ 27:........................................ 26:........................................ 25:........................................ 24:........................................ 23:........................................ 22:........................................ 21:........................................ 20:...................3.................... 19:........................................ 18:........................................ 17:........................................ 16:........................................ 15:........................................ 14:........................................ 13:........................................ 12:........................................)WR( 11:.........2.............................. 10:........................................ 9:........................................ 8:........................................ 7:........................................ 6:....1................................... 5:........................................ 4:........................................ 3:........................................ 2:........................................ 1:........................................)RP( )2 1 1 HR( )0 P(The )BD(polygon)ES( shape specifies a polygon with vertices \201x1, y1\202 ... \201xn, yn\202. The polygon is closed automatically: one should not specify the last vertex to be the same as the first. Any number of vertices are allowed. For example, the following polygon defines a right triangle as shown below: ) 1 33 PR( POLYGON \20110,10, 10,30, 30,30\202)RP( looks like this: ) 42 49 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:........................................ 39:........................................ 38:........................................ 37:........................................ 36:........................................ 35:........................................ 34:........................................ 33:........................................ 32:........................................ 31:........................................ 30:..........11111111111111111111.......... 29:..........1111111111111111111........... 28:..........111111111111111111............ 27:..........11111111111111111............. 26:..........1111111111111111.............. 25:..........111111111111111............... 24:..........11111111111111................ 23:..........1111111111111................. 22:..........111111111111.................. 21:..........11111111111................... 20:..........1111111111.................... 19:..........111111111..................... 18:..........11111111...................... 17:..........1111111....................... 16:..........111111........................ 15:..........11111......................... 14:..........1111.......................... 13:..........111........................... 12:..........11............................)WR( 11:..........1............................. 10:........................................ 9:........................................ 8:........................................ 7:........................................ 6:........................................ 5:........................................ 4:........................................ 3:........................................ 2:........................................ 1:........................................)RP( Note that polygons can get twisted upon themselves if edge lines cross. Thus: ) 1 37 PR( POL \20110,10, 20,20, 20,10, 10,20\202)RP( will produce an area which is two triangles, like butterfly wings, as shown below: ) 42 49 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:........................................ 39:........................................ 38:........................................ 37:........................................ 36:........................................ 35:........................................ 34:........................................ 33:........................................ 32:........................................ 31:........................................ 30:........................................ 29:........................................ 28:........................................ 27:........................................ 26:........................................ 25:........................................ 24:........................................ 23:........................................ 22:........................................ 21:........................................ 20:........................................ 19:..........1........1.................... 18:..........11......11.................... 17:..........111....111.................... 16:..........1111..1111.................... 15:..........1111111111.................... 14:..........1111..1111.................... 13:..........111....111.................... 12:..........11......11....................)WR( 11:..........1........1.................... 10:........................................ 9:........................................ 8:........................................ 7:........................................ 6:........................................ 5:........................................ 4:........................................ 3:........................................ 2:........................................ 1:........................................)RP( )2 1 1 HR( )0 P(The following are combinations of pie with different shapes \201called "panda" for "Pie AND Annulus"\202 allow for easy specification of radial sections: ) 6 76 PR( shape: arguments: ----- --------- PANDA xcen ycen ang1 ang2 nang irad orad nrad # circular CPANDA xcen ycen ang1 ang2 nang irad orad nrad # circular BPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad \201ang\202 # box EPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad \201ang\202 # ellipse)RP( The )BD(panda)ES( \201)BD(P)ES(ies )BD(AND)ES( )BD(A)ES(nnuli\202 shape can be used to create combinations of pie and annuli markers. It is analogous to a Cartesian product on those shapes, i.e., the result is several shapes generated by performing a boolean AND between pies and annuli. Thus, the panda and cpanda specify combinations of annulus and circle with pie, respectively and give identical results. The bpanda combines box and pie, while epanda combines ellipse and pie. )0 P(Consider the example shown below: ) 1 31 PR( PANDA\20120,20, 0,360,3, 0,15,4\202)RP( Here, 3 pie slices centered at 20, 20 are combined with 4 annuli, also centered at 20, 20. The result is a mask with 12 regions \201displayed in base 16 to save characters\202: ) 42 51 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:........................................ 39:........................................ 38:........................................ 37:........................................ 36:........................................ 35:........................................ 34:..............44444444444............... 33:............444444444444444............. 32:...........88444444444444444............ 31:.........888844443333344444444.......... 30:........88888833333333333444444......... 29:........88888733333333333344444......... 28:.......8888877733333333333344444........ 27:......888887777332222233333344444....... 26:......888877777622222222333334444....... 25:.....88887777766622222222333334444...... 24:.....88887777666622222222233334444...... 23:.....88887777666651111222233334444...... 22:.....88877776666551111122223333444...... 21:.....88877776666555111122223333444...... 20:.....888777766665559999aaaabbbbccc...... 19:.....888777766665559999aaaabbbbccc...... 18:.....888777766665599999aaaabbbbccc...... 17:.....88887777666659999aaaabbbbcccc...... 16:.....888877776666aaaaaaaaabbbbcccc...... 15:.....888877777666aaaaaaaabbbbbcccc...... 14:......8888777776aaaaaaaabbbbbcccc....... 13:......888887777bbaaaaabbbbbbccccc....... 12:.......88888777bbbbbbbbbbbbccccc........)WR( 11:........888887bbbbbbbbbbbbccccc......... 10:........888888bbbbbbbbbbbcccccc......... 9:.........8888ccccbbbbbcccccccc.......... 8:...........88ccccccccccccccc............ 7:............ccccccccccccccc............. 6:..............ccccccccccc............... 5:........................................ 4:........................................ 3:........................................ 2:........................................ 1:........................................)RP( )2 1 1 HR( )0 P(Several regions with different mask values can be combined in the same mask. This supports comparing data from the different regions. \201For information on how to combine different shapes into a single region, see "help regalgebra".\202 For example, consider the following set of regions: ) 3 24 PR( ANNULUS 25 25 5 10 ELLIPSE 20 20 5 10 315 BOX 15 15 5 10)RP( The resulting mask will look as follows: ) 42 49 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:........................................ 39:........................................ 38:........................................ 37:........................................ 36:........................................ 35:........................................ 34:....................111111111........... 33:...................11111111111.......... 32:.................111111111111111........ 31:.................111111111111111........ 30:................11111111111111111....... 29:...............1111111.....1111111...... 28:...............111111.......111111...... 27:...............11111.222222..11111...... 26:...............111112222222..11111...... 25:...............111112222222..11111...... 24:...............111112222222..11111...... 23:...............111112222222..11111...... 22:...............111111222222.111111...... 21:..............211111112222.1111111...... 20:............322211111111111111111....... 19:............32222111111111111111........ 18:............22222111111111111111........ 17:............222222211111111111.......... 16:............22222222111111111........... 15:............222222222................... 14:............22222222.................... 13:............222222...................... 12:............33333.......................)WR( 11:............33333....................... 10:........................................ 9:........................................ 8:........................................ 7:........................................ 6:........................................ 5:........................................ 4:........................................ 3:........................................ 2:........................................ 1:........................................)RP( Note that when a pixel is in 2 or more regions, it is arbitrarily assigned to a one of the regions in question \201often based on how a give C compiler optimizes boolean expressions\202. )0 P()0 2 120 H(Region)WB 199 Sn( accelerators)EH( )0 P(Two types of \200fBaccelerators)ES(, to simplify region specification, are provided as natural extensions to the ways shapes are described. These are: extended lists of parameters, specifying multiple regions, valid for annulus, box, circle, ellipse, pie, and points; and )BD(n=)ES(, valid for annulus, box, circle, ellipse, and pie \201not point\202. In both cases, one specification is used to define several different regions, that is, to define shapes with different mask values in the region mask. )0 P(The following regions accept )BD(accelerator)ES( syntax: ) 13 73 PR( shape arguments ----- ------------------------------------------ ANNULUS xcenter ycenter radius1 radius2 ... radiusn ANNULUS xcenter ycenter inner_radius outer_radius n=[number] BOX xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn \201angle\202 BOX xcenter ycenter xwlo yhlo xwhi yhhi n=[number] \201angle\202 CIRCLE xcenter ycenter r1 r2 ... rn # same as annulus CIRCLE xcenter ycenter rinner router n=[number] # same as annulus ELLIPSE xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn \201angle\202 ELLIPSE xcenter ycenter xwlo yhlo xwhi yhhi n=[number] \201angle\202 PIE xcenter ycenter angle1 angle2 \201angle3\202 \201angle4\202 \201angle5\202 ... PIE xcenter ycenter angle1 angle2 \201n=[number]\202 POINT x1 y1 x2 y2 ... xn yn)RP( Note that the circle accelerators are simply aliases for the annulus accelerators. )0 P(For example, several annuli at the same center can be specified in one region expression by specifying more than two radii. If )BD(N)ES( radii are specified, then )BD(N)ES(-1 annuli result, with the outer radius of each preceding annulus being the inner radius of the succeeding annulus. Each annulus is considered a separate region, and is given a separate mask value. For example, ) 1 30 PR( ANNULUS 20 20 0 2 5 10 15 20)RP( specifies five different annuli centered at 20 20, and is equivalent to: ) 5 25 PR( ANNULUS 20.0 20.0 0 2 ANNULUS 20.0 20.0 2 5 ANNULUS 20.0 20.0 5 10 ANNULUS 20.0 20.0 10 15 ANNULUS 20.0 20.0 15 20)RP( The mask is shown below: ) 42 49 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:........................................ 39:.............5555555555555.............. 38:...........55555555555555555............ 37:.........555555555555555555555.......... 36:........55555555555555555555555......... 35:......555555555555555555555555555....... 34:.....55555555544444444444555555555...... 33:....5555555544444444444444455555555..... 32:....5555555444444444444444445555555..... 31:...555555444444444444444444444555555.... 30:..55555544444444444444444444444555555... 29:..55555544444443333333334444444555555... 28:.5555554444444333333333334444444555555.. 27:.5555544444433333333333333344444455555.. 26:555555444444333333333333333444444555555. 25:555554444443333333333333333344444455555. 24:555554444433333332222233333334444455555. 23:555554444433333322222223333334444455555. 22:555554444433333222222222333334444455555. 21:555554444433333222111222333334444455555. 20:555554444433333222111222333334444455555. 19:555554444433333222111222333334444455555. 18:555554444433333222222222333334444455555. 17:555554444433333322222223333334444455555. 16:555554444433333332222233333334444455555. 15:555554444443333333333333333344444455555. 14:555555444444333333333333333444444555555. 13:.5555544444433333333333333344444455555.. 12:.5555554444444333333333334444444555555..)WR( 11:..55555544444443333333334444444555555... 10:..55555544444444444444444444444555555... 9:...555555444444444444444444444555555.... 8:....5555555444444444444444445555555..... 7:....5555555544444444444444455555555..... 6:.....55555555544444444444555555555...... 5:......555555555555555555555555555....... 4:........55555555555555555555555......... 3:.........555555555555555555555.......... 2:...........55555555555555555............ 1:.............5555555555555..............)RP( )0 P(For boxes and ellipses, if an odd number of arguments is specified, then the last argument is assumed to be an angle. Otherwise, the angle is assumed to be zero. For example: ) 1 38 PR( ellipse 20 20 3 5 6 10 9 15 12 20 45)RP( specifies an 3 ellipses at a 45 degree angle: ) 42 51 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:........................................ 39:........................................ 38:........................................ 37:........................................ 36:........33333333........................ 35:......333333333333...................... 34:.....3333333333333333................... 33:....333333333333333333.................. 32:....33333332222233333333................ 31:...3333332222222222333333............... 30:...33333222222222222233333.............. 29:...333332222222222222223333............. 28:...3333222222211112222223333............ 27:...33332222211111111222223333........... 26:...333322222111111111122223333.......... 25:...3333222211111111111122223333......... 24:....3332222111111..1111122223333........ 23:....333322211111.....11112222333........ 22:....33332222111.......11112223333....... 21:.....33322221111.......11122223333...... 20:.....33332221111.......11112223333...... 19:.....33332222111.......11112222333...... 18:......33332221111.......11122223333..... 17:.......33322221111.....111112223333..... 16:.......3333222211111..1111112222333..... 15:........3333222211111111111122223333.... 14:.........333322221111111111222223333.... 13:..........33332222211111111222223333.... 12:...........3333222222111122222223333....)WR( 11:............333322222222222222233333.... 10:.............33333222222222222233333.... 9:..............3333332222222222333333.... 8:...............33333333222223333333..... 7:.................333333333333333333..... 6:..................3333333333333333...... 5:.....................333333333333....... 4:.......................33333333......... 3:........................................ 2:........................................ 1:........................................)RP( Note in the above example that the lower limit is not part of the region for boxes, circles, and ellipses. This makes circles and annuli equivalent, i.e.: ) 2 26 PR( circle 20 20 5 10 15 20 annulus 20 20 5 10 15 20)RP( both give the following region mask: ) 42 51 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:........................................ 39:.............3333333333333.............. 38:...........33333333333333333............ 37:.........333333333333333333333.......... 36:........33333333333333333333333......... 35:......333333333333333333333333333....... 34:.....33333333322222222222333333333...... 33:....3333333322222222222222233333333..... 32:....3333333222222222222222223333333..... 31:...333333222222222222222222222333333.... 30:..33333322222222222222222222222333333... 29:..33333322222221111111112222222333333... 28:.3333332222222111111111112222222333333.. 27:.3333322222211111111111111122222233333.. 26:333333222222111111111111111222222333333. 25:333332222221111111111111111122222233333. 24:33333222221111111.....11111112222233333. 23:3333322222111111.......1111112222233333. 22:333332222211111.........111112222233333. 21:333332222211111.........111112222233333. 20:333332222211111.........111112222233333. 19:333332222211111.........111112222233333. 18:333332222211111.........111112222233333. 17:3333322222111111.......1111112222233333. 16:33333222221111111.....11111112222233333. 15:333332222221111111111111111122222233333. 14:333333222222111111111111111222222333333. 13:.3333322222211111111111111122222233333.. 12:.3333332222222111111111112222222333333..)WR( 11:..33333322222221111111112222222333333... 10:..33333322222222222222222222222333333... 9:...333333222222222222222222222333333.... 8:....3333333222222222222222223333333..... 7:....3333333322222222222222233333333..... 6:.....33333333322222222222333333333...... 5:......333333333333333333333333333....... 4:........33333333333333333333333......... 3:.........333333333333333333333.......... 2:...........33333333333333333............ 1:.............3333333333333..............)RP( )0 P(As a final example, specifying several angles in one pie slice expression is equivalent to specifying several separate slices with the same center. As with the annulus, if )BD(N)ES( angles are specified, then )BD(N)ES(-1 slices result, with the ending angle of each preceding slice being the starting angle of the succeeding slice. Each slice is considered a separate region, and is given a separate mask value. For example, ) 1 26 PR( PIE 12 12 315 45 115 270)RP( specifies three regions as shown below: ) 42 51 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:2222222222222222222222222222222222222222 39:2222222222222222222222222222222222222221 38:2222222222222222222222222222222222222211 37:2222222222222222222222222222222222222111 36:2222222222222222222222222222222222221111 35:3222222222222222222222222222222222211111 34:3222222222222222222222222222222222111111 33:3322222222222222222222222222222221111111 32:3322222222222222222222222222222211111111 31:3332222222222222222222222222222111111111 30:3332222222222222222222222222221111111111 29:3333222222222222222222222222211111111111 28:3333222222222222222222222222111111111111 27:3333322222222222222222222221111111111111 26:3333322222222222222222222211111111111111 25:3333322222222222222222222111111111111111 24:3333332222222222222222221111111111111111 23:3333332222222222222222211111111111111111 22:3333333222222222222222111111111111111111 21:3333333222222222222221111111111111111111 20:3333333322222222222211111111111111111111 19:3333333322222222222111111111111111111111 18:3333333332222222221111111111111111111111 17:3333333332222222211111111111111111111111 16:3333333333222222111111111111111111111111 15:3333333333222221111111111111111111111111 14:3333333333322211111111111111111111111111 13:3333333333322111111111111111111111111111 12:33333333333.1111111111111111111111111111)WR( 11:3333333333331111111111111111111111111111 10:333333333333.111111111111111111111111111 9:333333333333..11111111111111111111111111 8:333333333333...1111111111111111111111111 7:333333333333....111111111111111111111111 6:333333333333.....11111111111111111111111 5:333333333333......1111111111111111111111 4:333333333333.......111111111111111111111 3:333333333333........11111111111111111111 2:333333333333.........1111111111111111111 1:333333333333..........111111111111111111)RP( )0 P(The annulus, box, circle, ellipse, and pie shapes also accept an )BD(n=[int])ES( syntax for specifying multiple regions. The )BD(n=[int])ES(syntax interprets the previous \201shape-dependent\202 arguments as lower and upper limits for the region and creates n shapes with evenly spaced boundaries. For example, if )BD(n=[int])ES( is specified in an annulus, the two immediately preceding radii \201)BD(rn)ES( and )BD(rm)ES(\202 are divided into )BD(int)ES( annuli, such that the inner radius of the first is )BD(rn)ES( and the outer radius of the last is )BD(rm)ES(. For example, ) 1 24 PR( ANNULUS 20 20 5 20 n=3)RP( is equivalent to: ) 1 26 PR( ANNULUS 20 20 5 10 15 20)RP( If this syntax is used with an ellipse or box, then the two preceding pairs of values are taken to be lower and upper limits for a set of ellipses or boxes. A circle uses the two preceding arguments for upper and lower radii. For pie, the two preceding angles are divided into n wedges such that the starting angle of the first is the lower bound and the ending angle of the last is the upper bound. In all cases, the )BD(n=[int])ES( syntax allows any single alphabetic character before the "=", i.e, i=3, z=3, etc. are all equivalent. )0 P(Also note that for boxes and ellipses, the optional angle argument is always specified after the )BD(n=[int])ES( syntax. For example: ) 45 57 PR( ellipse 20 20 4 6 16 24 n=3 45 ) 44 57 PR(specifies 3 elliptical regions at an angle of 45 degrees: ) 42 45 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 40:........33333333........................ 39:.....33333333333333..................... 38:....33333333333333333................... 37:...33333333333333333333................. 36:..33333333333333333333333............... 35:.3333333333222223333333333.............. 34:3333333322222222222233333333............ 33:33333332222222222222223333333........... 32:333333222222222222222222333333.......... 31:3333322222222222222222222333333......... 30:33333222222222111122222222333333........ 29:333332222222111111112222222333333....... 28:3333222222211111111111222222333333...... 27:3333222222111111111111112222233333...... 26:33332222221111111111111112222233333..... 25:33332222211111111.111111112222233333.... 24:333322222111111......111111222223333.... 23:333322222111111.......111112222233333... 22:33333222221111.........11111222223333... 21:333332222211111.........11112222233333.. 20:.33332222211111.........11111222223333.. 19:.33333222221111.........111112222233333. 18:..33332222211111.........11112222233333. 17:..333332222211111.......111111222233333. 16:...333322222111111......111111222223333. 15:...333332222211111111.111111112222233333)WR( 14:....333332222211111111111111122222233333)WR( 13:.....33333222221111111111111122222233333 12:.....33333322222211111111111222222233333)WR( 11:......3333332222222111111112222222333333 10:.......333333222222221111222222222333333 9:........33333322222222222222222222333333 8:.........333333222222222222222222333333. 7:..........33333332222222222222223333333. 6:...........3333333322222222222233333333. 5:.............3333333333222223333333333.. 4:..............33333333333333333333333... 3:................33333333333333333333.... 2:..................33333333333333333..... 1:....................33333333333333......)RP( )0 P(Both the variable argument syntax and the )BD(n=[int])ES( syntax must occur alone in a region descriptor \201aside from the optional angle for boxes and ellipses\202. They cannot be combined. Thus, it is not valid to precede or follow an )BD(n=[int])ES( accelerator with more angles or radii, as in this example: ) 3 49 PR( # INVALID -- one too many angles before a=5 ... # and no angles are allowed after a=5 PIE 12 12 10 25 50 a=5 85 135)RP( Instead, use three separate specifications, such as: ) 3 21 PR( PIE 12 12 10 25 PIE 12 12 25 50 a=5 PIE 12 12 85 135)RP( The original \201IRAF\202 implementation of region filtering permitted this looser syntax, but we found it caused more confusion than it was worth and therefore removed it. )0 P(NB: Accelerators may be combined with other shapes in a boolean expression in any order. \201This is a change starting with funtools v1.1.1. Prior to this release, the accelerator shape had to be specified last\202. The actual region mask id values returned depend on the order in which the shapes are specified, although the total number of pixels or rows that pass the filter will be consistent. For this reason, use of accelerators in boolean expressions is discouraged in programs such as funcnts, where region mask id values are used to count events or image pixels. )0 P([All region masks displayed in this document were generated using the )BD(fundisp)ES( routine and the undocumented "mask=all" argument \201with spaced removed using sed \202: ) 2 72 PR( fundisp "funtools/funtest/test40.fits[ANNULUS 25 25 5 10]" mask=all |\200 sed 's/ //g')RP( Note that you must supply an image of the appropriate size -- in this case, a FITS image of dimension 40x40 is used.] )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 121 H(Last)WB 200 Sn( updated: March 12, 2007)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (regalgebra.html) D /Ti (Region Algebra) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 56 Sn( )0 2 122 H(RegAlgebra:)WB 202 Sn()WB 201 Sn( Boolean Algebra on Spatial Regions)EA()EH( )0 2 123 H(Summary)WB 203 Sn()EH( )0 P(This document describes the boolean arithmetic defined for region expressions. )0 2 124 H(Description)WB 204 Sn()EH( )0 P(When defining a region, several shapes can be combined using boolean operations. The boolean operators are \201in order of precedence\202: ) 6 53 PR( Symbol Operator Associativity ------ -------- ------------- ! not right to left & and left to right ^ exclusive or left to right | inclusive or left to right)RP( For example, to create a mask consisting of a large circle with a smaller box removed, one can use the )BD(and)ES( and )BD(not)ES( operators: ) 1 36 PR( CIRCLE\20111,11,15\202 & !BOX\20111,11,3,6\202)RP( and the resulting mask is: ) 42 49 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 1:1111111111111111111111.................. 2:1111111111111111111111.................. 3:11111111111111111111111................. 4:111111111111111111111111................ 5:111111111111111111111111................ 6:1111111111111111111111111............... 7:1111111111111111111111111............... 8:1111111111111111111111111............... 9:111111111...1111111111111............... 10:111111111...1111111111111............... 11:111111111...1111111111111............... 12:111111111...1111111111111............... 13:111111111...1111111111111............... 14:111111111...1111111111111............... 15:1111111111111111111111111............... 16:1111111111111111111111111............... 17:111111111111111111111111................ 18:111111111111111111111111................ 19:11111111111111111111111................. 20:1111111111111111111111.................. 21:1111111111111111111111.................. 22:111111111111111111111................... 23:..11111111111111111..................... 24:...111111111111111...................... 25:.....11111111111........................ 26:........................................ 27:........................................ 28:........................................ 29:........................................)WR( 30:........................................ 31:........................................ 32:........................................ 33:........................................ 34:........................................ 35:........................................ 36:........................................ 37:........................................ 38:........................................ 39:........................................ 40:........................................)RP( A three-quarter circle can be defined as: ) 1 40 PR( CIRCLE\20120,20,10\202 & !PIE\20120,20,270,360\202)RP( and looks as follows: ) 42 49 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 1:........................................ 2:........................................ 3:........................................ 4:........................................ 5:........................................ 6:........................................ 7:........................................ 8:........................................ 9:........................................ 10:........................................ 11:...............111111111................ 12:..............11111111111............... 13:............111111111111111............. 14:............111111111111111............. 15:...........11111111111111111............ 16:..........1111111111111111111........... 17:..........1111111111111111111........... 18:..........1111111111111111111........... 19:..........1111111111111111111........... 20:..........1111111111111111111........... 21:..........1111111111.................... 22:..........1111111111.................... 23:..........1111111111.................... 24:..........1111111111.................... 25:...........111111111.................... 26:............11111111.................... 27:............11111111.................... 28:..............111111.................... 29:...............11111....................)WR( 30:........................................ 31:........................................ 32:........................................ 33:........................................ 34:........................................ 35:........................................ 36:........................................ 37:........................................ 38:........................................ 39:........................................ 40:........................................)RP( Two non-intersecting ellipses can be made into the same region: ) 1 40 PR( ELL\20120,20,10,20,90\202 | ELL\2011,1,20,10,0\202)RP( and looks as follows: ) 42 49 PR( 1234567890123456789012345678901234567890 ---------------------------------------- 1:11111111111111111111.................... 2:11111111111111111111.................... 3:11111111111111111111.................... 4:11111111111111111111.................... 5:1111111111111111111..................... 6:111111111111111111...................... 7:1111111111111111........................ 8:111111111111111......................... 9:111111111111............................ 10:111111111............................... 11:...........11111111111111111............ 12:........111111111111111111111111........ 13:.....11111111111111111111111111111...... 14:....11111111111111111111111111111111.... 15:..11111111111111111111111111111111111... 16:.1111111111111111111111111111111111111.. 17:111111111111111111111111111111111111111. 18:111111111111111111111111111111111111111. 19:111111111111111111111111111111111111111. 20:111111111111111111111111111111111111111. 21:111111111111111111111111111111111111111. 22:111111111111111111111111111111111111111. 23:111111111111111111111111111111111111111. 24:.1111111111111111111111111111111111111.. 25:..11111111111111111111111111111111111... 26:...11111111111111111111111111111111..... 27:.....11111111111111111111111111111...... 28:.......111111111111111111111111......... 29:...........11111111111111111............)WR( 30:........................................ 31:........................................ 32:........................................ 33:........................................ 34:........................................ 35:........................................ 36:........................................ 37:........................................ 38:........................................ 39:........................................ 40:........................................)RP( You can use several boolean operations in a single region expression, to create arbitrarily complex regions. With the important exception below, you can apply the operators in any order, using parentheses if necessary to override the natural precedences of the operators. )0 P(NB: Using a panda shape is always much more efficient than explicitly specifying "pie & annulus", due to the ability of panda to place a limit on the number of pixels checked in the pie shape. If you are going to specify the intersection of pie and annulus, use panda instead. )0 P(As described in "help regreometry", the )BD(PIE)ES( slice goes to the edge of the field. To limit its scope, )BD(PIE)ES( usually is is combined with other shapes, such as circles and annuli, using boolean operations. In this context, it is worth noting that that there is a difference between )BD(-PIE)ES( and )BD(&!PIE)ES(. The former is a global exclude of all pixels in the )BD(PIE)ES( slice, while the latter is a local excludes of pixels affecting only the region\201s\202 with which the )BD(PIE)ES( is combined. For example, the following region uses )BD(&!PIE)ES( as a local exclude of a single circle. Two other circles are also defined and are unaffected by the local exclude: ) 21 56 PR( CIRCLE\2011,8,1\202 CIRCLE\2018,8,7\202&!PIE\2018,8,60,120\202&!PIE\2018,8,240,300\202 CIRCLE\20115,8,2\202 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 - - - - - - - - - - - - - - - 15: . . . . . . . . . . . . . . . 14: . . . . 2 2 2 2 2 2 2 . . . . 13: . . . 2 2 2 2 2 2 2 2 2 . . . 12: . . 2 2 2 2 2 2 2 2 2 2 2 . . 11: . . 2 2 2 2 2 2 2 2 2 2 2 . . 10: . . . . 2 2 2 2 2 2 2 . . . . 9: . . . . . . 2 2 2 . . . . 3 3 8: 1 . . . . . . . . . . . . 3 3 7: . . . . . . 2 2 2 . . . . 3 3 6: . . . . 2 2 2 2 2 2 2 . . . . 5: . . 2 2 2 2 2 2 2 2 2 2 2 . . 4: . . 2 2 2 2 2 2 2 2 2 2 2 . . 3: . . . 2 2 2 2 2 2 2 2 2 . . . 2: . . . . 2 2 2 2 2 2 2 . . . . 1: . . . . . . . . . . . . . . .)RP( Note that the two other regions are not affected by the )BD(&!PIE)ES(, which only affects the circle with which it is combined. )0 P(On the other hand, a )BD(-PIE)ES( is an global exclude that does affect other regions with which it overlaps: ) 23 39 PR( CIRCLE\2011,8,1\202 CIRCLE\2018,8,7\202 -PIE\2018,8,60,120\202 -PIE\2018,8,240,300\202 CIRCLE\20115,8,2\202 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 - - - - - - - - - - - - - - - 15: . . . . . . . . . . . . . . . 14: . . . . 2 2 2 2 2 2 2 . . . . 13: . . . 2 2 2 2 2 2 2 2 2 . . . 12: . . 2 2 2 2 2 2 2 2 2 2 2 . . 11: . . 2 2 2 2 2 2 2 2 2 2 2 . . 10: . . . . 2 2 2 2 2 2 2 . . . . 9: . . . . . . 2 2 2 . . . . . . 8: . . . . . . . . . . . . . . . 7: . . . . . . 2 2 2 . . . . . . 6: . . . . 2 2 2 2 2 2 2 . . . . 5: . . 2 2 2 2 2 2 2 2 2 2 2 . . 4: . . 2 2 2 2 2 2 2 2 2 2 2 . . 3: . . . 2 2 2 2 2 2 2 2 2 . . . 2: . . . . 2 2 2 2 2 2 2 . . . . 1: . . . . . . . . . . . . . . .)RP( The two smaller circles are entirely contained within the two exclude )BD(PIE)ES( slices and therefore are excluded from the region. )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 125 H(Last)WB 205 Sn( updated: November 17, 2005)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (regcoords.html) D /Ti (Spatial Region Coordinates) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 57 Sn( )0 2 126 H(RegCoords:)WB 207 Sn()WB 206 Sn( Spatial Region Coordinates)EA()EH( )0 2 127 H(Summary)WB 208 Sn()EH( )0 P(This document describes the specification of coordinate systems, and the interpretation of coordinate values, for spatial region filtering. )0 2 128 H(Pixel)WB 209 Sn( coordinate systems)EH( )0 P(The default coordinate system for regions is PHYSICAL, which means that region position and size values are taken from the original data. \201Note that this is a change from the original IRAF/PROS implementation, in which the IMAGE coordinate system was the default.\202 PHYSICAL coordinates always refer to pixel positions on the original image \201using IRAF LTM and LTV keywords\202. With PHYSICAL coordinates, if a set of coordinates specifies the position of an object in an original FITS file, the same coordinates will specify the same object in any FITS derived from the original. Physical coordinates are invariant with blocking of FITS files or taking sections of images, even when a blocked section is written to a new file. )0 P(Thus, although a value in pixels refers, by default, to the PHYSICAL coordinate system, you may specify that position values refer to the image coordinate system using the )BD(global)ES( or )BD(local)ES( properties commands: ) 2 23 PR( global coordsys image circle 512 512 100)RP( The )BD(global)ES( command changes the coordinate system for all regions that follow, while the )BD(local)ES( command changes the coordinate system only for the region immediately following: ) 3 22 PR( local coordsys image circle 512 512 100 circle 1024 1024 200)RP( This changes the coordinate system only for the region that follows. In the above example, the second region uses the global coordinate system \201PHYSICAL by default\202. )0 P()0 2 129 H(World)WB 210 Sn( Coordinate Systems)EH( If World Coordinate System information is contained in the data file being filtered, it also is possible to define regions using a sky coordinate system. Supported systems include: ) 10 67 PR( name description ---- ----------- PHYSICAL pixel coords of original file using LTM/LTV IMAGE pixel coords of current file FK4, B1950 sky coordinate systems FK5, J2000 sky coordinate systems GALACTIC sky coordinate systems ECLIPTIC sky coordinate systems ICRS currently same as J2000 LINEAR linear wcs as defined in file)RP( In addition, two mosaic coordinate systems have been defined that utilize the \201evolving\202 IRAF mosaic keywords: ) 4 68 PR( name description ---- ----------- AMPLIFIER mosaic coords of original file using ATM/ATV DETECTOR mosaic coords of original file using DTM/DTV)RP( Again, to use one of these coordinate systems, the )BD(global)ES( or )BD(local)ES( properties commands are used: ) 1 26 PR( global coordsys galactic)RP( )0 2 130 H(WCS)WB 211 Sn( Positions and Sizes)EH( In addition to pixels, positional values in a WCS-enabled region can be specified using sexagesimal or degrees format: ) 11 57 PR( position arguments description ------------------ ----------- [num] context-dependent \201see below\202 [num]d degrees [num]r radians [num]p physical pixels [num]i image pixels [num]:[num]:[num] hms for 'odd' position arguments [num]:[num]:[num] dms for 'even' position arguments [num]h[num]m[num]s explicit hms [num]d[num]m[num]s explicit dms)RP( If ':' is used as sexagesimal separator, the value is considered to be specifying hours/minutes/seconds if it is the first argument of a positional pair, and degrees/minutes/seconds for the second argument of a pair \201except for galactic coordinates, which always use degrees\202: ) 7 78 PR( argument description ----------- ----------- 10:20:30.0 10 hours, 20 minutes, 30 seconds for 1st positional argument 10 degrees, 20 minutes, 30 seconds for 2nd positional argument 10h20m30.0 10 hours, 20 minutes, 30 seconds 10d20m30.0 10 degrees, 20 minutes, 30 seconds 10.20d 10.2 degrees)RP( Similarly, the units of size values are defined by the formating character\201s\202 attached to a number: ) 9 53 PR( size arguments description -------------- ----------- [num] context-dependent \201see below\202 [num]" arc seconds [num]' arc minutes [num]d degrees [num]r radians [num]p physical pixels [num]i image pixels)RP( For example: ) 8 34 PR( argument description ----------- ----------- 10 ten pixels 10' ten minutes of arc 10" ten seconds of arc 10d ten degrees 10p ten pixels 0.5r half of a radian)RP( )0 P(An example of using sky coordinate systems follows: ) 4 65 PR( global coordsys B1950 -box 175.54d 20.01156d 10' 10' local coordsys J2000 pie 179.57d 22.4d 0 360 n=4 && annulus 179.57d 22.4d 3' 24' n=5)RP( At the FK4 1950 coordinates 175.54d RA, 20.01156d DEC exclude a 10 minute by 10 minute box. Then at the FK5 2000 coordinates 179.57d RA 22.4d DEC draw a radial profile regions pattern with 4 quadrants and 5 annuli ranging from 3 minutes to 24 minutes in diameter. In this example, the default coordinate system is overridden by the commands in the regions spec. )0 2 131 H(NB:)WB 212 Sn( The Meaning of Pure Numbers Are Context Sensitive)EH( )0 P(When a "pure number" \201i.e. one without a format directive such as 'd' for 'degrees'\202 is specified as a position or size, its interpretation depends on the context defined by the 'coordsys' keyword. In general, the rule is: )0 P()BD(All pure numbers have implied units corresponding to the current coordinate system.)ES( )0 P(If no coordinate system is explicitly specified, the default system is implicitly assumed to be PHYSICAL. In practice this means that for IMAGE and PHYSICAL systems, pure numbers are pixels. Otherwise, for all systems other than LINEAR, pure numbers are degrees. For LINEAR systems, pure numbers are in the units of the linear system. This rule covers both positions and sizes. )0 P(As a corollary, when a sky-formatted number is used with the IMAGE or PHYSICAL coordinate system \201which includes the default case of no coordsys being specified\202, the formatted number is assumed to be in the units of the WCS contained in the current file. If no sky WCS is specified, an error results. )0 P(Examples: ) 2 43 PR( circle\201512,512,10\202 ellipse 202.44382d 47.181656d 0.01d 0.02d)RP( )0 P(In the absence of a specified coordinate system, the circle uses the default PHYSICAL units of pixels, while the ellipse explicitly uses degrees, presumably to go with the WCS in the current file. ) 5 43 PR( global coordsys=fk5 global color=green font="system 10 normal" circle 202.44382 47.181656 0.01 circle 202.44382 47.181656 10p ellipse\201512p,512p,10p,15p,20\202)RP( )0 P(Here, the circles use the FK5 units of degrees \201except for the explicit use of pixels in the second radius\202, while the ellipse explicitly specifies pixels. The ellipse angle is in degrees. )0 P(Note that Chandra data format appears to use "coordsys=physical" implicitly. Therefore, for most Chandra applications, valid regions can be generated safely by asking ds9 to save/display regions in pixels using the PHYSICAL coordsys. )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 132 H(Last)WB 213 Sn( updated: November 17, 2005)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (regbounds.html) D /Ti (Spatial Region Boundaries) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 58 Sn( )0 2 133 H(RegBounds:)WB 215 Sn()WB 214 Sn( Region Boundaries)EA()EH( )0 2 134 H(Summary)WB 216 Sn()EH( Describes how spatial region boundaries are handled. )0 2 135 H(Description)WB 217 Sn()EH( )0 P(The golden rule for spatial region filtering was first enunciated by Leon VanSpeybroeck in 1986: )0 P()BD(Each photon will be counted once, and no photon will be counted more than once)ES(. )0 P(This means that we must be careful about boundary conditions. For example, if a circle is contained in an annulus such that the inner radius of the annulus is the same as the radius of the circle, then photons on that boundary must always be assigned to one or the other region. That is, the number of photons in both regions must equal the sum of the number of photons in each region taken separately. With this in mind, the rules for determining whether a boundary image pixel or table row are assigned to a region are defined below. )0 2 136 H(Image)WB 218 Sn( boundaries : radially-symmetric shapes \201circle, annuli, ellipse\202)EH( For image filtering, pixels whose center is inside the boundary are included. This also applies non-radially-symmetric shapes. When a pixel center is exactly on the boundary, the pixel assignment rule is: )UL()-1 LI( the outer boundary of a symmetric shape does not include such pixels )-1 LI( the inner boundary of a symmetric shape \201annulus\202 includes such pixels)LU( In this way, an annulus with radius from 0 to 1, centered exactly on a pixel, includes the pixel on which it is centered, but none of its neighbors. These rules ensure that when defining concentric shapes, no pixels are omitted between concentric regions and no pixels are claimed by two regions. When applied to small symmetric shapes, the shape is less likely to be skewed, as would happen with non-radially-symmetric rules. These rules differ from the rules for box-like shapes, which are more likely to be positioned adjacent to one another. )0 2 137 H(Image)WB 219 Sn( Boundaries: non-radially symmetric shapes \201polygons, boxes\202)EH( For image filtering, pixels whose center is inside the boundary are included. This also applies radially-symmetric shapes. When a pixel center is exactly on the boundary of a non-radially symmetric region, the pixel is included in the right or upper region, but not the left or lower region. This ensures that geometrically adjoining regions touch but don't overlap. )0 2 138 H(Row)WB 220 Sn( Boundaries are Analytic)EH( When filtering table rows, the boundary rules are the same as for images, except that the calculation is not done on the center of a pixel, \201since table rows, especially X-ray events rows, often have discrete, floating point positions\202 but are calculated exactly. That is, an row is inside the boundary without regard to its integerized pixel value. For rows that are exactly on a region boundary, the above rules are applied to ensure that all rows are counted once and no row is counted more than once. )0 P(Because row boundaries are calculated differently from image boundaries, certain programs will give different results when filtering the same region file. In particular, fundisp/funtable \201which utilize analytic row filtering\202 perform differently from funcnts \201which performs image filtering, even on tables\202. )0 2 139 H(Image)WB 221 Sn( Boundaries vs. Row Boundaries: Practical Considerations)EH( )0 P(You will sometimes notice a discrepancy between running funcnts on an binary table file and running fundisp on the same file with the same filter. For example, consider the following: ) 2 49 PR( fundisp test1.fits"[box\2014219,3887,6,6,0\202]" | wc 8893 320148 3752846)RP( Since fundisp has a 2-line header, there are actually 8891 photons that pass the filter. But then run funtable and select only the rows that pass this filter, placing them in a new file: ) 1 58 PR( ./funtable test1.fits"[box\2014219,3887,6,6,0\202]" test2.fits)RP( Now run funcnts using the original filter on the derived file: ) 12 61 PR( ./funcnts test2.fits "physical; box\2014219,3887,6,6,0\202" [... lot of processed output ...] # the following source and background components were used: source region\201s\202 ---------------- physical; box\2014219,3887,6,6,0\202 reg counts pixels ---- ------------ --------- 1 7847.000 36)RP( There are 1044 rows \201events\202 that pass the row filter in fundisp \201or funtable\202 but fail to make it through funcnts. Why? )0 P(The reason can be traced to how analytic row filtering \201fundisp, funtable\202 differs from integerized pixel filtering\201funcnts, funimage\202. Consider the region: ) 1 22 PR( box\2014219,3887,6,6,0\202)RP( Analytically \201i.e., using row filtering\202, positions will pass this filter successfully if: ) 2 19 PR( 4216 <= x <= 4222 3884 <= y <= 3890)RP( For example, photons with position values of x=4216.4 or y=3884.08 will pass. )0 P(Integerized image filtering is different in that the pixels that will pass this filter have centers at: ) 2 40 PR( x = 4217, 4218, 4219, 4220, 4221, 4222 y = 3885, 3886, 3887, 3888, 3889, 3890)RP( Note that there are 6 pixels in each direction, as specified by the region. That means that positions will pass the filter successfully if: ) 2 24 PR( 4217 <= \201int\202x <= 4222 3885 <= \201int\202y <= 3890)RP( Photons with position values of x=4216.4 or y=3884.08 will NOT pass. )0 P(Note that the position values are integerized, in effect, binned into image values. This means that x=4222.4 will pass this filter, but not the analytic filter above. We do this to maintain the design goal that either all counts in a pixel are included in an integerized filter, or else none are included. )0 P([It could be argued that the correct photon limits for floating point row data really should be: ) 2 23 PR( 4216.5 <= x <= 4222.5 3884.5 <= y <= 3890.5)RP( since each pixel extends for .5 on either side of the center. We chose to the maintain integerized algorithm for all image-style filtering so that funcnts would give the exact same results regardless of whether a table or a derived non-blocked binned image is used.] )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 140 H(Last)WB 222 Sn( updated: November 16, 2005)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (regdiff.html) D /Ti (Differences Between Funtools and IRAF Regions) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 59 Sn( )0 2 141 H(RegDiff:Differences)WB 224 Sn()WB 223 Sn( Between Funtools and IRAF Regions)EA()EH( )0 2 142 H(Summary)WB 225 Sn()EH( Describes the differences between Funtools/ds9 regions and the old IRAF/PROS regions. )0 2 143 H(Description)WB 226 Sn()EH( )0 P(We have tried to make Funtools regions compatible with their predecessor, IRAF/PROS regions. For simple regions and simple boolean algebra between regions, there should be no difference between the two implementations. The following is a list of differences and incompatibilities between the two: )UL( )0 P()-1 LI(If a pixel is covered by two different regions expressions, Funtools assigns the mask value of the )BD(first)ES( region that contains that pixel. That is, successive regions )BD(do not)ES( overwrite previous regions in the mask, as was the case with the original PROS regions. This means that one must define overlapping regions in the reverse order in which they were defined in PROS. If region N is fully contained within region M, then N should be defined )BD(before)ES( M, or else it will be "covered up" by the latter. This change is necessitated by the use of optimized filter compilation, i.e., Funtools only tests individual regions until a proper match is made. )0 P()-1 LI( The )BD(PANDA)ES( region has replaced the old PROS syntax in which a )BD(PIE)ES( accelerator was combined with an )BD(ANNULUS)ES( accelerator using )BD(AND)ES(. That is, ) 1 48 PR( ANNULUS\20120,20,0,15,n=4\202 & PIE\20120,20,0,360,n=3\202)RP( has been replaced by: ) 1 29 PR( PANDA\20120,20,0,360,3,0,15,4\202)RP( The PROS syntax was inconsistent with the meaning of the )BD(AND)ES( operator. )0 P()-1 LI( The meaning of pure numbers \201i.e., without format specifiers\202 in regions has been clarified, as has the syntax for specifying coordinate systems. See the general discussion on )0 54 1 A(Spatial Region Filtering)54 0 TN TL()Ec /AF f D( for more information. )LU( )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 144 H(Last)WB 227 Sn( updated: November 16, 2005)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (combo.html) D /Ti (Combining Region and Table Filters) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 60 Sn( )0 2 145 H(FunCombine:)WB 230 Sn()WB 228 Sn( Combining Region and Table Filters)EA()EH( )0 2 146 H(Summary)WB 231 Sn()EH( )0 P(This document discusses the conventions for combining region and table filters, especially with regards to the comma operator. )0 2 147 H(Comma)WB 232 Sn()WB 229 Sn( Conventions)EA()EH( )0 P(Filter specifications consist of a series of boolean expressions, separated by commas. These expressions can be table filters, spatial region filters, or combinations thereof. Unfortunately, common usage requires that the comma operator must act differently in different situations. Therefore, while its use is intuitive in most cases, commas can be a source of confusion. )0 P(According to long-standing usage in IRAF, when a comma separates two table filters, it takes on the meaning of a boolean )BD(and)ES(. Thus: ) 1 24 PR( foo.fits[pha==1,pi==2])RP( is equivalent to: ) 1 27 PR( foo.fits[pha==1 && pi==2])RP( When a comma separates two spatial region filters, however, it has traditionally taken on the meaning of a boolean )BD(or)ES(. Thus: ) 1 46 PR( foo.fits[circle\20110,10,3\202,ellipse\20120,20,8,5\202])RP( is equivalent to: ) 1 49 PR( foo.fits[circle\20110,10,3\202 || ellipse\20120,20,8,5\202])RP( \201except that in the former case, each region is given a unique id in programs such as funcnts\202. )0 P(Region and table filters can be combined: ) 1 34 PR( foo.fits[circle\20110,10,3\202,pi=1:5])RP( or even: ) 1 61 PR( foo.fits[pha==1&&circle\20110,10,3\202,pi==2&&ellipse\20120,20,8,5\202])RP( In these cases, it is not obvious whether the command should utilize an )BD(or)ES( or )BD(and)ES( operator. We therefore arbitrarily chose to implement the following rule: )UL()-1 LI( if both expressions contain a region, the operator used is )BD(or)ES(. )-1 LI( if one \201or both\202 expression\201s\202 does not contain a region, the operator used is )BD(and)ES(.)LU( This rule handles the cases of pure regions and pure column filters properly. It unambiguously assigns the boolean )BD(and)ES( to all mixed cases. Thus: ) 1 34 PR( foo.fits[circle\20110,10,3\202,pi=1:5])RP( and ) 1 34 PR( foo.fits[pi=1:5,circle\20110,10,3\202])RP( both are equivalent to: ) 1 37 PR( foo.fits[circle\20110,10,3\202 && pi=1:5])RP( )0 P([NB: This arbitrary rule )BD(replaces the previous arbitrary rule)ES( \201pre-funtools 1.2.3\202 which stated: )UL()-1 LI( if the 2nd expression contains a region, the operator used is )BD(or)ES(. )-1 LI( if the 2nd expression does not contain a region, the operator used is )BD(and)ES(.)LU( In that scenario, the )BD(or)ES( operator was implied by: ) 1 21 PR( pha==4,circle 5 5 1)RP( while the )BD(and)ES( operator was implied by ) 1 21 PR( circle 5 5 1,pha==4)RP( Experience showed that this non-commutative treatment of the comma operator was confusing and led to unexpected results.] )0 P(The comma rule must be considered provisional: comments and complaints are welcome to help clarify the matter. Better still, we recommend that the comma operator be avoided in such cases in favor of an explicit boolean operator. )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 148 H(Last)WB 233 Sn( updated: November 16, 2005)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (env.html) D /Ti (Funtools Environment Variables) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 61 Sn( )0 2 149 H(FunEnv:)WB 235 Sn()WB 234 Sn( Funtools Environment Variables)EA()EH( )0 2 150 H(Summary)WB 236 Sn()EH( Describes the environment variables which can be used to tailor the overall Funtools environment. )0 2 151 H(Description)WB 237 Sn()EH( )0 P(The following environment variables are supported by Funtools: )0 DL()0 P()0 DT()BD(FITS_EXTNAME)ES( )DD( The )BD(FITS_EXTNAME)ES( environment variable specifies the default FITS extension name when )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( is called on a file lacking a primary image. Thus, ) 1 29 PR( setenv FITS_EXTNAME "NEWEV")RP( will allow you to call )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( on files without specifying NEWEV in the )0 42 1 A(Funtools bracket specification)42 0 TN TL()Ec /AF f D(. If no FITS_EXTNAME variable is defined and the extension name also is not passed in the bracket specification, then the default will be to look for standard X-ray event table extension names "EVENTS" or "STDEVT" \201we are, after all, and X-ray astronomy group at heart!\202. )0 P()0 DT()BD(FITS_EXTNUM)ES( )DD( The )BD(FITS_EXTNUM)ES( environment variable specifies the default FITS extension number when )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( is called on a file lacking a primary image. Thus, ) 1 22 PR( setenv FITS_EXTNUM 7)RP( will allow you to call )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( on files to open the seventh extension without specifying the number in the )0 42 1 A(Funtools bracket specification)42 0 TN TL()Ec /AF f D(. )0 P()0 DT()BD(FITS_BINCOLS)ES( and )BD(EVENTS_BINCOLS)ES( )DD( These environment variable specifies the default binning key for FITS binary tables and raw event files, respectively. They can be over-ridden using the )BD(bincols=[naxis1,naxis2])ES( keyword in a )0 42 1 A(Funtools bracket specification)42 0 TN TL()Ec /AF f D(. The value of each environment variable is a pair of comma-delimited columns, enclosed in parentheses, to use for binning. For example, if you want to bin on detx and dety by default, then use: ) 1 35 PR( setenv FITS_BINCOLS "\201detx,dety\202")RP( in preference to adding a bincols specification to each filename: ) 1 31 PR( foo.fits[bincols=\201detx,dety\202])RP( )0 P()0 DT()BD(FITS_BITPIX)ES( and )BD(EVENTS_BITPIX)ES( )DD( These environment variable specifies the default bitpix value for binning FITS binary tables and raw event files, respectively. They can be over-ridden using the )BD(bitpix=[value])ES( keyword in a )0 42 1 A(Funtools bracket specification)42 0 TN TL()Ec /AF f D(. The value of each environment variable is one of the standard FITS bitpix values \2018,16,32,-32,-64\202. For example, if you want binning routines to create a floating array, then use: ) 1 24 PR( setenv FITS_BITPIX -32)RP( in preference to adding a bitpix specification to each filename: ) 1 22 PR( foo.fits[bitpix=-32])RP( )0 P()0 DT()BD(ARRAY)ES( )DD( The )BD(ARRAY)ES( environment variable specifies the default definition of an array file for Funtools. It is used if there is no array specification passed in the )BD(ARRAY\201\202)ES( directive in a )0 46 1 A(Non-FITS Array specification)46 0 TN TL()Ec /AF f D(. The value of the environment variable is a valid array specification such as: ) 2 25 PR( setenv ARRAY "s100.150" foo.arr[ARRAY\201\202])RP( This can be defined in preference to adding the specification to each filename: ) 1 26 PR( foo.arr[ARRAY\201s100.150\202])RP( )0 P()0 DT()BD(EVENTS)ES( )DD( The )BD(EVENTS)ES( environment variable specifies the default definition of an raw event file for Funtools. It is used if there is no EVENTS specification passed in the )BD(EVENTS\201\202)ES( directive in a )0 45 1 A(Non-FITS EVENTS specification)45 0 TN TL()Ec /AF f D(. The value of the environment variable is a valid EVENTS specification such as: ) 2 73 PR( setenv EVENTS "x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024" foo.ev[EVENTS\201\202])RP( This can be defined in preference to adding the specification to each filename: ) 1 73 PR( foo.ev[EVENTS\201x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024\202])RP()LD( The following filter-related environment variables are supported by Funtools: )0 DL( )0 P()0 DT()BD(FILTER_PTYPE)ES( )DD( The )BD(FILTER_PTYPE)ES( environment variable specifies how to build a filter. There are three possible methods: )0 DL()0 DT(process or p )DD(The filter is compiled and linked against the funtools library \201which must therefore be accessible in the original install directory\202 to produce a slave program. This program is fed events or image data and returns filter results. )0 DT(dynamic or d \201gcc only\202 )DD(The filter is compiled and linked against the funtools library \201which must therefore be accessible in the original install directory\202 to produce a dynamic shared object, which is loaded into the funtools program and executed as a subroutine. \201Extensive testing has shown that, contrary to expectations, this method is no faster than using a slave process.\202 )0 DT(contained or c )DD(The filter and all supporting region code is compiled and linked without reference to the funtools library to produce a slave program \201which is fed events or image data and returns filter results\202. This method is slower than the other two, because of the time it takes to compile the region filtering code. It is used by stand-alone programs such as ds9, which do not have access to the funtools library.)LD( By default, )BD(dynamic)ES( is generally used for gcc compilers and )BD(process)ES( for other compilers. However the filter building algorithm will check for required external files and will use )BD(contained)ES( is these are missing. )0 P()0 DT()BD(FUN_MAXROW)ES( )DD( The )BD(FUN_MAXROW)ES( environment variable is used by core row-processing Funtools programs \201funtable, fundisp, funcnts, funhist, funmerge, and funcalc\202 to set the maximum number of rows read at once \201i.e. it sets the third argument to the FunTableRowGet\201\202 call\202. The default is 8192. Note that this variable is a convention only: it will not be a part of a non-core Funtools program unless code is explicitly added, since each call to FunTableRowGet\201\202 specifies its own maximum number of rows to read. NB: if you make this value very large, you probably will need to increase )BD(FUN_MAXBUFSIZE)ES( \201see below\202 as well. )0 P()0 DT()BD(FUN_MAXBUFSIZE)ES( )DD( The )BD(FUN_MAXBUFSIZE)ES( environment variable is used to limit the max buffer size that will be allocated to hold table row data. This buffer size is calculated to be the row size of the table multiplied by the maximum number of rows read at once \201see above\202. Since the row size is unlimited \201and we have examples of it being larger than 5 Mb\202, it is possible that the total buffer size will exceed the machine capabilities. We therefore set a default value of 5Mb for the max buffer size, and adjust maxrow so that the total size calculated is less than this max buffer size. \201If the row size is greater than this max buffer size, then maxrow is set to 1.\202 This environment variable will change the max buffer size allowed. )0 P()0 DT()BD(FILTER_CC)ES( )DD( The )BD(FILTER_CC)ES( environment variable specifies the compiler to use for compiling a filter specification. You also can use the )BD(CC)ES( environment variable. If neither has been set, then gcc will be used if available. Otherwise cc is used if available. )0 P()0 DT()BD(FILTER_EXTRA)ES( )DD( The )BD(FILTER_EXTRA)ES( environment variable specifies extra options to add to a filter compile command line. In principle, you can add libraries, include files, and compiler switches. This variable should be used with care. )0 P()0 DT()BD(FILTER_TMPDIR)ES( )DD( The )BD(FILTER_TMPDIR)ES( environment variable specifies the temporary directory for filter compilation intermediate files. You also can use the )BD(TMPDIR)ES( and )BD(TMP)ES( variables. By default, /tmp is used as the temporary directory. )0 P()0 DT()BD(FILTER_KEEP)ES( )DD( The )BD(FILTER_KEEP)ES( environment variable specifies whether the intermediate filter files \201i.e. C source file and compile log file\202 should be saved after a filter is built. The default is "false", so that these intermediate files are deleted. This variable is useful for debugging, but care should be taken to reset its value to false when debugging is complete. )LD( )0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( )0 5 152 H(Last)WB 238 Sn( updated: November 16, 2005)EH( )WB NL /Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc DS /Ba f D /BO 0 D Bs /UR (changelog.html) D /Ti (Funtools ChangeLog) D /Au () D /Df f D /ME [()] D 0 BO R ()1 Sl()WB 62 Sn( )0 2 153 H(Funtools)WB 239 Sn( ChangeLog)EH( )0 P(This ChangeLog covers both the Funtools library and the suite of applications. It will be updated as we continue to develop and improve Funtools. The up-to-date version can be found )R5 2 A(here)EA(. [The changelog for the initial development of Funtools, covering the beta releases, can be found )R6 2 A(here)EA(.] )0 2 154 H()WB 240 Sn( Patch Release 1.4.5 \201internal ds9 release\202)EH( )UL()0 P()-1 LI( Removed permission checking from Find\201\202 on cygwin systems. This was broken by Windows 7. )0 P()-1 LI( Removed addition of -no-cpp-precomp flag from gcc 4.2 and beyond.)LU( )0 2 155 H()WB 241 Sn( Patch Release 1.4.4 \201internal ds9 release\202)EH( )UL()0 P()-1 LI( Fixed -J funcone, which was not properly outputting all rows. )0 P()-1 LI( Filter: when an image is flipped, the rotation angle must be reversed. )0 P()-1 LI( Filter: add support for windows-based ipc communication when using tcc compiler.)LU( )0 2 156 H()WB 242 Sn( Patch Release 1.4.3 \201internal ds9 release\202)EH( )UL()0 P()-1 LI( Filter: improve checks for existence of compiler, even if CC is set. )0 P()-1 LI( Change launch.h to xlaunch.h to avoid conflict with OS X. )0 P()-1 LI( handle flipped images in filtering)LU( )0 2 157 H()WB 243 Sn( Patch Release 1.4.2 \201internal ds9 release\202)EH( )UL()0 P( )-1 LI( Port to gcc 4.2. )0 P()-1 LI( Fix 1-byte filters on intel machines \201missing SW1 no-op\202. )0 P()-1 LI( Remove ambiguity from filt.l \201and calc.l\202 using [A-z] in a case-insensitive lexer. )0 P()-1 LI( In funsky, the default unit for RA was changed from hours to degrees. )0 P()-1 LI( Fixed bug in funtable in which TCRVL header values were output as strings. )0 P()-1 LI( Added support for running funtools filters in Rosetta \201i.e. running PPC executables on an Intel Mac\202 by sensing and handling data swap requirements. Only works with FILTER_PTYPE set to 'c' \201can't link against wrong architecture libraries\202. )0 P()-1 LI( Fixed bug in FITS library to allow "-" in extension names. )0 P()-1 LI( Code and documentation now agree that the copy extension specifier \201'+'\202 comes after the extension name.)LU( )0 2 158 H()WB 244 Sn( Patch Release 1.4.1 \201internal ds9 release\202)EH( )UL()0 P()-1 LI( Modified internal Launch\201\202 routine to use posix_spawn\201\202, if necessary. This is required for OS X 10.5 \201leopard\202, which frowns upon use of fork\201\202 and exec\201\202. Also modified zprocess routines to use Launch\201\202.)LU( )0 2 159 H()WB 245 Sn( Public Release 1.4.0 \20115 August 2007\202)EH( )UL()-1 LI( Public release of production-quality code, incorporating changes and improvements from previous beta releases, including: )UL()-1 LI( Support for access to ASCII text column files. )-1 LI( Support for fast indexed access of binary tables. )-1 LI( Support for database views of tables, i.e. pre-set values for the filter specification, the columns to activate, and display format. )-1 LI( New programs include funcone \201cone search\202, funindex \201create index files\202, and funcen \201calculate centroids within regions\202.)LU( )LU( )0 2 160 H()WB 246 Sn( Release 1.3.0b[n] \201mainly internal SAO beta releases\202)EH( )UL( )0 P()-1 LI( Added -F[c] switch to change the column delimiter to the specified character. )0 P()-1 LI( Extended fundisp's format switch \201-f\202 so that it can now handle complex formats such as 'x=sometext%3d- y=othertest%3d.ext'. )0 P()-1 LI( Added support for creating and processing 1D FITS images. )0 P()-1 LI( Added vcol=colname and vcol=/colname to filter specifications to support use of a third value column when binning 2D images. )0 P()-1 LI( Added switches to funcone to write out data rows are not within any cone \201-J, -X\202 and centers which have no close data rows \201-L\202. )0 P()-1 LI( In funjoin, added ability to specify a numeric tolerance for when joining two files. )0 P()-1 LI( shared memory support in gio now can create a shared segment if w+ is specified as the open mode. )0 P()-1 LI( Changed reggeometry man page so that examples correctly show angles going counter-clockwise from the x-axis instead of from the y-axis. )0 P()-1 LI( Added checks to funmerge to ensure that all files have the same columns. )0 P()-1 LI( Fixed bug in text support that prevented header-less files from being processed properly. )0 P()-1 LI( Added support for 64-bit images \201bitpix=64\202 and table columns \201TFORM=K\202. )0 P()-1 LI( Filter code was not applying bscale/bzero to columns. )0 P( )-1 LI( Fixed funimage bug that caused a .5/block error in WCS CRPIX values generated from binary tables. )0 P()-1 LI( Added feq\201a,b\202 and div\201a,b\202 macros to funcalc. )0 P()-1 LI( Added support for single-line #define to funcalc. )0 P()-1 LI( Updated wcs library to 3.6.6 )0 P()-1 LI( Fix bug in funcen in which ra,dec was not being calculated correctly if physical and image coords did not match up. )0 P()-1 LI( The filter syntax "col1 = col2" now explicitly generates an error \201you really want to do "col1 == col2"\202. )0 P()-1 LI( Added -o switch to include offset from the nominal target position. )0 P()-1 LI( Fundisp now displays multi-dimensional vector columns properly. )0 P()-1 LI( Documented support for lists of files processed as a single file using "list: file1 ... filen" syntax. )0 P()-1 LI( Fixed bugs in support for pipe file type \201i.e. ability to pass commands as a filename using "pipe: cmd arg1 ... argn" syntax\202. )0 P()-1 LI( Fixed bug in funhist processing of image-based pixel histograms \201i.e using "xy" for columns\202 where a region was specified. All pixels outside the region were erroneously being added to the bin containing the 0 value. )0 P()-1 LI( Disabled multi-file processing in funds9, which was breaking support for pathnames containing spaces and is not used by ds9 anyway. )0 P()-1 LI( Added support for Views of tables, i.e. pre-set values for the filter specification, the columns to activate, and display format \201though the latter is for fundisp only\202. )0 P()-1 LI( Added -l switch to funimage to read x, y, val columns from a list. )0 P()-1 LI( Removed useless and meaningless section syntax foo'[*]' because it breaks pointer de-referencing on string columns \201i.e. foo'[*xxx=='a']'\202. Use foo'[*,*]' instead, as documented. )0 P()-1 LI( String variables were not always being terminated properly in the filter code because FITS 'A' data is not necessarily null-terminated. )0 P()-1 LI( Added funtools version number to all usage\201\202 displays. )0 P()-1 LI( Added explanation of switch arguments to many usage\201\202 displays. )0 P()-1 LI( The filter keyword row# now supports single row selection as well as range selection, i.e., "row#=100" along with previous "row#=100:200". )0 P()-1 LI( fundisp now outputs "0x" before hex values. )0 P()-1 LI( Fixed bug in filter parser which processed rangelists incorrectly if spaces were put into the rangelist \201i.e. "pha= 1 : 3" instead of pha=1:3\202. )0 P()-1 LI( Fixed a bug in funindex which created a wrongly named index file if more than one "." was in the input file name. )0 P()-1 LI( Added support to funcone to take ra, dec, radius from a list \201i.e. columns in a FITS file or a text file\202. )0 P()-1 LI( Fixed a bug in FunColumnActivate so that if some columns are explicitly activated while others are de-activated, only the explicitly activated columns are activated \201code was activating all columns in this case\202. )0 P()-1 LI( Fixed a bug in funindex which prevented indexing tables containing a column named N. )0 P()-1 LI( fundisp now encloses ASCII column values in single quotes \201unless -T is specified to output RDB format\202. )0 P()-1 LI( If a filter specification only involves indexed columns, then the compiled filter is not used. )0 P()-1 LI( Funmerge can now be given a list of files to merge using @list syntax. Also removed the restriction on how many files can be merged \201was limited to the max number of open files\202. )0 P()-1 LI( Added ability to edit \201add, delete, modify\202 header parameters in funhead by specifying an output file \201editing acts as a filter\202 and an edit command file \201which can be stdin\202. )0 P()-1 LI( Funtools now contains preliminary code to support \201fast\202 indexed access of binary tables. See idx.html or "man funidx" for more details. )0 P()-1 LI( Funtools now contains preliminary code supporting access to ASCII column files. See text.html or "man funtext" for more details. )0 P()-1 LI( Fixed bug in funcalc in which columns used in an expression were always being replaced by new columns, with all associated parameters \201e.g. WCS\202 were being deleted. Now this only happens if the column explicitly changes its data type. )0 P()-1 LI( Fixed bug in funcalc in which the raw data and user data became out of sync for one row after every 8192 \201FUN_MAXROW\202 rows. )0 P()-1 LI( Fixed bug in gio in which gseek returned 0 instead of the current byte offset for disk files. )0 P()-1 LI( Added funcone program to perform cone search on RA, Dec columns in a FITS binary table. )0 P()-1 LI( Fixed bug in polygon, pie and rotated box region filtering for tables \201nearby rows exactly in line between two non-vertical or non-horizontal vertices were being accepted incorrectly\202. )0 P()-1 LI( Fixed pie and panda regions so that the angles now start from positive x axis == 0 degrees and run counter-clockwise, as documented. They were going from positive y. NB: a similar change was made to ds9 release 4.0b3. You must be using ds9 4.0b3 or later in order to have the correct behavior when generating regions in ds9 and using them in funtools. )0 P()-1 LI( Added -p [prog] switch to funcalc to save the generated program. instead of executing \201and deleting\202 it. )0 P()-1 LI( Upgraded zlib to 1.2.3. )LU( )0 2 161 H()WB 247 Sn( Patch Release 1.2.4 \201internal SAO and beta release only\202)EH( )UL( )0 P()-1 LI( In funcalc, added support for user-specified arguments via the -a [argstr] switch. These arguments are accessed in the compiled program using the supplied ARGC and ARGV\201n\202 macros. )0 P()-1 LI( Added -n \201no header display\202 to fundisp to skip outputting header. )0 P()-1 LI( Added checks for various types of blank filters. )0 P( )-1 LI( Added macros NROW \201current row number\202 and WRITE_ROW \201write current row to disk\202 to funcalc. )0 P()-1 LI( funcalc no longer requires that at least one data column be specified in the compiled expression. )0 P()-1 LI( Added FUN_NROWS to FunInfoGet\201\202 to return the total number of rows in an input table \201i.e. value of NAXIS2\202. )0 P( )-1 LI( The compiled funcalc program now includes stdlib.h and unistd.h. )0 P()-1 LI( The util/NaN.h header file is now modified at configure time to contain endian status for the target architecture. References to specific platforms have been removed. )0 P()-1 LI( Added -m switch to funtable to output multiple files, one for each input region \201and a separate file for events that pass the filters but are not in any region\202. )0 P()-1 LI( Added ability to add new parameters \201FunParamPutx\202 after writing data if space is previously reserved in the form of a blank parameter whose value is the name of the param to be updated. \201Also requires the append argument of FunParamPutx be set to 2\202. )0 P( )-1 LI( Added ability to build shared libraries. With --enable-shared=yes, shared library is built but not used. With --enable-shared=link, shared library is linked against \201requires proper installation and/or use of LD_LIBRARY_PATH\202. )0 P()-1 LI( Added -v [column] support to funcnts so that counts in a table can be accumulated using values from a specified column \201instead of the default case where an integral count is accumulated for each event in a region\202. )0 P()-1 LI( Added funcen program to calculate centroids within regions \201binary tables only\202. Also added support for a funcen-based centroid tool to funtools.ds9. )0 P()-1 LI( Fixed bug which prevented successful filtering of columns containing arrays. )0 P()-1 LI( Added filter check to ensure that a column is not incorrectly used as an array. )0 P()-1 LI( Fundisp now displays column arrays indexed from 0, not 1. )0 P()-1 LI( Added -i [interval] support to funcnts so that multiple intervals can be processed in a single pass through the data. For example, specifying -i "pha=1:5;pha=6:10;pha=11:15" will generate results in each of 3 pha bands. )0 P()-1 LI( Fixed calculation of LTV quantities when binning floating point column data \201value was off by 0.5\202. )0 P()-1 LI( Added support for 'D' in floating point header values. )0 P()-1 LI( Added -a switch to funimage and funtable to append output image or table to an existing FITS file \201as an IMAGE or BINTABLE extension\202. )0 P()-1 LI( Added support for column scaling \201TSCAL and TZERO\202 on input columns. Note that the default column type is changed to accommodate scaling \201e.g. a column of type 'I' is changed to 'J', 'J' is changed to 'D'\202 so that the scaled values can be handled properly by programs such as fundisp \201which utilize default types\202. )0 P( )-1 LI( Added support to FunColumnSelect\201\202 for handling structs of arrays \201i.e. where returned columns are contiguous\202 instead of the default array of structs \201returned row are contiguous\202. This is done by specifying "org=structofarrays" in the plist and passing a single struct containing the arrays. )0 P()-1 LI( When writing an rdb/starbase file, fundisp now outputs the full column name, regardless of the width of the column \201which ordinarily is truncated to match\202. )0 P()-1 LI( Fixed support for large files by changing all file positions variables from "long" declarations to "off_t. )0 P()-1 LI( Fixed bug in funcalc incorrectly processed multiple array references \201e.g. cur->foo[0]=cur->x;cur->foo[1]=cur->y;\202 within a single line of code. )0 P()-1 LI( Added FILTER_CFLAGS environment variable for all filtering. Also added --with-filter-cc and --with-filter-cflags options on configure to allow specification of a default C compiler and associated CFLAGS for filtering. All of this is necessary in order to support 64-bit libraries under Solaris. )0 P()-1 LI( Added the funtbl script to extract a table from Funtools ASCII output. )0 P()-1 LI( Added code to funimage to update IRAF DATASEC keyword. )0 P()-1 LI( Added checks to ensure that image dimensions are positive. )0 P()-1 LI( Fixed a bug in funimage where int data was being scaled using BSCALE and BZERO but these keywords also were being retained in the output image header. Now the data are not scaled unless the output data type is float \201in which case the scaling parameters are removed\202. )0 P()-1 LI( Fixed a bug in funmerge which prevented merging of files unless one of the -f, -w, or -x switches were used. )0 P()-1 LI( Fixed a bug in funtable and fundisp which caused the special '$n' column to be output incorrectly. )0 P()-1 LI( Fixed sort option in funtable, which previously worked only if the record size was an even divisor of 8192 \201and returned garbage otherwise\202. )0 P()-1 LI( Fixed bug in filters involving FITS data type 'X' \201bitfield\202. )0 P()-1 LI( Fixed bug in funcnts in which the output angles and radii were being displayed incorrectly when multiple panda shapes were specified. )0 P()-1 LI( Fixed bug in pandas and pies using n= syntax when first angle specified was greater than second. The resulting mask was of the correct shape but contained only a single region. )0 P()-1 LI( Table row access routines will now decrease maxrows if memory cannot be allocated for maxrows*sizeof\201row\202, i.e. if the size of a row is so large that space for maxrows cannot be allocated. )0 P()-1 LI( The FUN_MAXBUFSIZE environment variable was added to limit the max buffer size that will be allocated to hold table row data. The default is 5Mb. )0 P()-1 LI( Generated PostScript and PDF versions of the help pages. )0 P()-1 LI( Moved OPTIONS section before \201often-lengthy\202 DESCRIPTION section in man pages. )0 P()-1 LI( All memory allocation now does error checking on the result \201except wcs library, which is external code\202. )0 P()-1 LI( Removed some compiler warnings that surfaced when using gcc -O2. )0 P()-1 LI( Updated wcs library to 3.5.5. )0 P()-1 LI( Upgraded zlib to 1.2.1. )LU( )0 2 162 H()WB 248 Sn( Patch Release 1.2.3 \20112 January 2004\202)EH( )UL( )0 P()-1 LI( Generated man pages from the html pages. These are installed automatically at build time. )0 P()-1 LI( Changed instances of sprintf\201\202 to snprintf\201\202 to protect against buffer overflow. )0 P()-1 LI( Fixed a number of compiler warnings in non-ANSI compilers. )0 P()-1 LI( Increased SZ_LINE parameter value from 1024 to 4096. )LU( )0 2 163 H()WB 249 Sn( Patch Release 1.2.3b1 \20119 August 2003\202)EH( )UL( )0 P()-1 LI( The rule for using comma to separate a table filter expression and a region expression has been changed. The rule now states: )UL()-1 LI( if both expressions contain a region, the operator used is )BD(or)ES(. )-1 LI( if one \201or both\202 expression\201s\202 does not contain a region, the operator used is )BD(and)ES(.)LU( This rule handles the cases of pure regions and pure column filters properly. It unambiguously assigns the boolean )BD(and)ES( to all mixed cases. Thus: ) 1 34 PR( foo.fits[circle\20110,10,3\202,pi=1:5])RP( and ) 1 34 PR( foo.fits[pi=1:5,circle\20110,10,3\202])RP( both are equivalent to: ) 1 37 PR( foo.fits[circle\20110,10,3\202 && pi=1:5])RP( )0 P()-1 LI( When include files are used in filters, they now have implied parentheses surrounding them. Thus, if a region file foo.reg contains two regions \201e.g. circle 1 2 3 and circle 4 5 6\202, the syntax: ) 1 21 PR( pha=4:5&&@foo.reg)RP( is equivalent to: ) 1 42 PR( pha=4:5 && \201circle 1 2 3 || cir 4 5 6\202)RP( instead of: ) 1 40 PR( pha=4:5 && circle 1 2 3 || cir 4 5 6)RP( and the pha filter is applied to both regions. )0 P()-1 LI( Filters and comments now can be terminated with the string literal "\200n" as well as ";" and the new-line character. This means that a region can have comments embedded in it: ) 1 72 PR( funcnts foo.fits "circle 512 512 10 # color=red\200n circle 512 512 20")RP( )0 P()-1 LI( Added capability to update the value of an existing parameter after writing the table or image \201assuming the output image is a disk file or is being redirected into a file\202. )0 P()-1 LI( Improved handling of parentheses in filter expressions. )0 P( )-1 LI( Fixed a bug in image \201not event\202 regions in which circles and annuli with radius of 1 pixel were not being processed. No counts and no area would be found in such regions. )0 P()-1 LI( Fixed a bug in funcnts in which the radii column values for out of sync if multiple annuli were specified \201instead of a single varargs or accel annulus\202. )0 P()-1 LI( By default, fundisp will display integer image data as floats if the BSCALE and BZERO header parameters are present. )0 P()-1 LI( Added -L switch to funhead to output starbase list format. )0 P()-1 LI( Changed the name of the routine _FunColumnSelect to FunColumnSelectArr, in order to emphasize that it is not a private routine. )0 P()-1 LI( Funcalc now checks to ensure that a column was specified as part of the expression. )0 P()-1 LI( Funcalc local variables in the compiled program now use a "__" prefix to avoid conflicts with user-defined variables. )0 P()-1 LI( Unofficial unsigned short \201bitpix=-16\202 image data now is scaled correctly using BSCALE and BZERO header parameters. )0 P()-1 LI( Ported to Intel icc and gcc 3.3 compilers. )0 P()-1 LI( Updated wcs library to 3.5.1. )0 P()-1 LI( Changed license from public domain to GNU GPL. )LU( )0 2 164 H()WB 250 Sn( Patch Release 1.2.2 \20118 May 2003\202)EH( )UL( )0 P( )-1 LI( Fixed funcalc so that it now actually compiles an expression and runs it, instead of getting a "filter compilation error". Oops! )0 P()-1 LI( Fixed bug in FunOpen in which the bracket specification was being removed from the filename if a disk file was opened for "w" or "a". )0 P()-1 LI( Fixed bug in FunFlush which prevented two successive calls to FunImagePut from writing the second extension header properly. )0 P()-1 LI( All filter routines now use gerror\201stderr, ...\202 call instead of fprintf\201stderr, ...\202 so that output to stderr can be turned off \201via setgerror\201level\202 or GERROR environment variable\202. )0 P()-1 LI( All standard Funtools programs check for GERROR environment variable before setting gerror flag. )0 P()-1 LI( Some error messages about invalid region arguments were not being printed. )0 P()-1 LI( FITS parameters/headers now conform more closely to FITS standard: )UL()-1 LI( Blank keywords are treated in the same way as COMMENTS and HISTORY cards )-1 LI( XTENSION keywords are now exactly 8 characters long )-1 LI( 'E' is output instead of 'e' in floating point param values )-1 LI( PCOUNT and GCOUNT are output correctly for image extensions )-1 LI( EXTEND=T is output in primary header )-1 LI( COMMENTS and HISTORY start in column 9)LU( )LU( )0 2 165 H()WB 251 Sn( Patch Release 1.2.1 \20124 April 2003\202)EH( )UL( )0 P()-1 LI( Varargs ellipse and box annular regions were being processed incorrectly when the following conditions all were met: )UL()-1 LI( the region was specified in physical or wcs coordinates )-1 LI( the data file contained LTM/LTV keywords, i.e., it was blocked with respect to the original data file )-1 LI( the program being run was an image program \201e.g. funcnts, funimage\202)LU( Varargs ellipse and boxes are regions of the form: ) 2 43 PR( ellipse x y a1 b1 a2 b2 ... an bn [angle] box x y l1 w1 l2 w2 ... ln wn [angle])RP( where at least 2 sets of axis \201length\202 values were specified to form an annulus \201i.e. simple ellipses and boxes worked properly\202. With all of the above conditions met, a region in physical coordinates saw its second length argument converted incorrectly from physical coordinates to image coordinates. In simple terms, this means that funcnts did not process elliptical or box regions in physical coords on blocked images properly. Note that blocking on the command line \201e.g. foo.fits[*,*,2]\202 did work when no LTM/LTV keywords existed in the file. )0 P()-1 LI( The fundisp -f switch now supports specification of column-specific display formats as well as a more convenient way to specify datatype-specific display formats. Both use keyword=value specifiers. For columns, use: ) 1 58 PR( fundisp -f "colname1=format1 colname2=format2 ..." ...)RP( e.g. ) 1 40 PR( fundisp -f "time=%13.2f pha=%3d" ...)RP( You also can specify display formats for individual datatypes using the FITS binary table TFORM variables as the keywords: ) 1 65 PR( fundisp -f "D=double_format E=float_format J=int_format etc.")RP( e.g. ) 1 35 PR( fundisp -f "D=%13.2f I=%3d" ...)RP( The old position-dependent syntax is deprecated. )0 P()-1 LI( Fundisp will now print out a single 16-bit \201or 32-bit\202 unsigned int for a column whose data format is 16X \201or 32X\202, instead of printing 2 \201or 4\202 unsigned chars. )0 P()-1 LI( Fixed bug in which fundisp was not able to display bitfield data for raw event lists. )0 P()-1 LI( Previously, when binning columns used implicitly in a region and explicitly in a filter could suffer from a case sensitivity problem. This has been fixed. )0 P()-1 LI( Fixed internal mask=all switch on fundisp. )0 P()-1 LI( Filter include files now simply include text without changing the state of the filter. They therefore can be used in expression. That is, if foo1 contains "pi==1" and foo2 contains "pha==2" then the following expressions are equivalent: ) 3 57 PR( "[@foo1&&@foo2]" is equivalent to "[pi==1&&pha==2]" "[pha==1||@foo2]" is equivalent to "[pi==1||pha==2]" "[@foo1,@foo2]" is equivalent to "[pi==1,pha==2]")RP( )0 P()-1 LI( Fixed bug in filter specification which caused a SEGV if a varargs-style region was enclosed in parens. )0 P()-1 LI( Updated wcs library to 3.3.2. )LU( )0 2 166 H()WB 252 Sn( Public Release 1.2.0 \20124 March 2003\202)EH( )UL( )0 P()-1 LI( BSCALE and BZERO are now always applied to int pixel data, instead of only being applied if the desired output is floating point. )LU( )0 2 167 H()WB 253 Sn( Beta Release 1.2.b3 \2014 February 2003\202)EH( )UL( )0 P()-1 LI( In FunColumnSelect, added the ability to specify an offset into an array in the type specification, using the extended syntax: ) 1 48 PR( [@][n][[poff]][:[tlmin[:tlmax[:binsiz]]]])RP( The [poff] string specifies the offset. For example, a type specification such as "@I[2]" specifies the third \201i.e., starting from 0\202 element in the array pointed to by the pointer value. A value of "@2I[4]" specifies the fifth and sixth values in the array. )0 P()-1 LI( Added a non-varargs version of FunColumnSelect called _FunColumnSelect: ) 3 76 PR(int _FunColumnSelect\201Fun fun, int size, char *plist, char **names, char **types, char **modes, int *offsets, int nargs\202;)RP( )0 P()-1 LI( Added support for sorting binary tables by column name using: funtable -s "col1 col2 ... coln" ... )0 P()-1 LI( Added the FUN_RAW macro which, when applied to the "name" parameter of FunParamGets\201\202, returns the 80-character raw FITS card instead of only the value. )0 P()-1 LI( Added support for comparing column values with binary masks of the form 0b[01]+, e.g.: ) 1 23 PR( \201status&0b111\202==0b001)RP( Previously, such masks had to be specified in decimal, octal, or hex. )0 P()-1 LI( Completed support for type 'L' \201logical\202 in fundisp and in filtering of binary tables. )0 P()-1 LI( Fixed bug in funhist that was improperly setting the number of bins when the data was of type float. )0 P()-1 LI( Fixed bug in filter/Makefile where the filter OBJPATH #define was being passed to the wrong module. )LU( )0 2 168 H()WB 254 Sn( Beta Release 1.2.b2 \2017 October 2002\202)EH( )UL( )0 P()-1 LI( Updated wcs library to 3.1.3. )0 P()-1 LI( Added support for reading gzip'ed files via stdin. )LU( )0 2 169 H()WB 255 Sn( Beta Release 1.2.b1 \20124 September 2002\202)EH( )UL( )0 P()-1 LI( Added the following accelerators to region filtering: ) 8 73 PR( shape: arguments: ----- --------- BOX xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn \201angle\202 BOX xcenter ycenter xwlo yhin xwout yhhi n=[number] \201angle\202 CIRCLE xcenter ycenter r1 r2 ... rn # same as annulus CIRCLE xcenter ycenter rinner router n=[number] # same as annulus ELLIPSE xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn \201angle\202 ELLIPSE xcenter ycenter xwlo yhin xwout yhhi n=[number] \201angle\202)RP( )0 P()-1 LI( Added the following new pandas \201Pie AND Annulus\202 to region filtering: ) 5 77 PR( shape: arguments: ----- --------- CPANDA xcen ycen ang1 ang2 nang irad orad nrad # same as panda BPANDA xcen ycen ang1 ang2 nang ixlo iylo ixhi iyhi nrad \201ang\202 # box EPANDA xcen ycen ang1 ang2 nang ixlo iylo ixhi iyhi nrad \201ang\202 # ellipse)RP( )0 P()-1 LI( Added support for filtering images using simple FITS image masks, i.e. 8-bit or 16-bit FITS images where the value of a pixel is the region id number for that pixel \201and therefore must be greater than 0\202. The image section being filtered must either be the same size as the mask dimensions or else be an even multiple of the mask. This works with image-style filtering, i.e., funcnts can utilize a mask on both images and binary tables. )0 P()-1 LI( Added '$n' to fundisp column specification to allow display of ordinal value of each row passing the filter. )0 P()-1 LI( Added code to support region filtering on image sections. )0 P()-1 LI( Fixed bugs which prevented filtering more than one ASCII region file. )0 P()-1 LI( Fixed bug occasionally causing filter slave processes to become zombies. )0 P()-1 LI( Fixed bugs in event filtering: annulus with inner radius of 0 \201i.e., a circle\202 was rejecting events with coordinates xcen, ycen. Also, pie with angles of 0 and 360 was rejecting some events. Image filtering \201e.g. funcnts\202 did not have these problems. )0 P()-1 LI( Filters now accept global exclude regions without an include region. In such a case, the field region is implied. That is, "-circle\201x,y,r\202" is equivalent to "field; -circle\201x,y,r\202", etc. )0 P()-1 LI( Fixed panda so that it can be used as a global exclude. )0 P()-1 LI( Allow empty ds9 region file \201comments and globals only\202 to be a valid filter. Totally ignore zero length region or include file. )0 P( )-1 LI( Fixed funcnts bug that was displaying 0 value as inner radius of a circle, instead of just one radius value. )LU( )0 2 170 H()WB 256 Sn( Public Release 1.1.0 \20122 April 2002\202)EH( )0 P(New features include: )UL()0 P()-1 LI( Funtools programs now accept gzip'ed files as valid input. )0 P()-1 LI( Improved security via replacement of system\201\202 function. )0 P()-1 LI( fundisp, funcnts, funhist can output starbase/rdb format \201tabs between columns, form-feeds between tables\202. )0 P()-1 LI( Improved support for Windows platform, as well as new support for Mac OSX.)LU( )0 2 171 H()WB 257 Sn( Pre-Release 1.1.0e \20110 April 2002\202)EH( )UL( )0 P()-1 LI( Added enough support to skip over variable length arrays in BINTABLES. We will add full support if this non-standard construct becomes more widely used. )0 P()-1 LI( Fixed bug in underlying fitsy _gread\201\202 routine that was returning an arbitrary bytes-read value if the input fd was invalid. )LU( )0 2 172 H()WB 258 Sn( Pre-Release 1.1.0e \20119 March 2002\202)EH( )UL( )0 P()-1 LI( Added additional check for Windows/PC to filter/Nan.h. )0 P()-1 LI( Upgraded zlib library to 1.1.4 \201fix double free security hole\202. )LU( )0 2 173 H()WB 259 Sn( Pre-Release 1.1.0e \20127 February 2002\202)EH( )UL( )0 P()-1 LI( Changed filter/process.[ch] to filter/zprocess.[ch] to avoid name collision with Cygwin include file. )0 P()-1 LI( Added -a switch to funhead to display all headers in a FITS file. )LU( )0 2 174 H()WB 260 Sn( Pre-Release 1.1.0e \20111 February 2002\202)EH( )UL( )0 P()-1 LI( Fixed filter parser so that it ignores ds9 "ruler" and "text" markers only up to the first \200n or ; \201was ignoring to last \200n\202. )0 P()-1 LI( The NBLOCK parameter in fitsy/headdata.c was too large for Mac OS X \201max size of a declared char buf seems to be about .5 Mb\202. )LU( )0 2 175 H()WB 261 Sn( Beta Release 1.0.1b5 \20131 January 2002\202)EH( )UL( )0 P()-1 LI( Fixed bug introduced in calculated IRAF LTM values in 1.0.1b3. )0 P()-1 LI( Fixed bug in filter parser giving wrong answers when two range lists were combined with and explicit boolean operator: ) 1 34 PR( $ fundisp $S"[x=512&&y=511,512]")RP( incorrectly acted like: ) 1 39 PR( fundisp $S"[\201x=512&&y=511\202||\201y=512\202]")RP( instead of: ) 1 37 PR( fundisp $S"[x=512&&\201y=511||y=512\202]")RP( In general, we recommend use of explicit parentheses. )0 P()-1 LI( Fixed filter/NaN.h to recognize Compaq Alpha again \201broken by their last change to cc\202. )0 P()-1 LI( Removed redundant varargs definitions that conflicted with Alpha compiler definitions. )0 P()-1 LI( Added blank line to inc.sed to work around Apple Mac OS X bug in which the "i" \201insert\202 command was treating final \200\200 as continuation \200 in the text. )0 P( )-1 LI( Added include of mkrtemp.h to mkrtemp.c to get conditional compilation for Mac OSX. )0 P()-1 LI( Added support for --with-zlib to fitsy so that ds9 could use its own copy of zlib \201and not build the copy in fitsy\202. )0 P()-1 LI( Removed config.cache and Makefile files from distribution tar file. )LU( )0 2 176 H()WB 262 Sn( Beta Release 1.0.1b4 \20126 January 2002\202)EH( )UL( )0 P()-1 LI( Make explicit that column filters are not permitted in an image expression \201such as the funcnts region arguments\202. )0 P()-1 LI( Fix bug in region parser in which a region \201without parens\202, followed immediately by an operator: ) 1 24 PR( circle 512 512 .5&)SY(\160)ES(==1)RP( was not processing the final argument of the region correctly. )0 P()-1 LI( Ignore new "tile" directive in filters \201used by ds9\202. )LU( )0 2 177 H()WB 263 Sn( Beta Release 1.0.1b3 \2014 January 2002\202)EH( )UL( )0 P()-1 LI( Made modifications to Makefile.in to make releases easier. )0 P()-1 LI( Added instructions Makefile.in so that funtools.h will always have correct #defines for FUN_VERSION, FUN_MAJOR_VERSION, FUN_MINOR_VERSION, and FUN_PATCH_LEVEL. )0 P()-1 LI( Allow #include statements in funcalc program files. )0 P()-1 LI( funimage now updates all 4 CDX_Y values by the block factor. )0 P()-1 LI( Minor changes to make funtools work under darwin \201Mac OS X\202. )LU( )0 2 178 H()WB 264 Sn( Beta Release 1.0.1b2 \20114 November 2001\202)EH( )UL( )0 P()-1 LI( Fixed FunOpen\201\202 bug \201introduced in b1\202 in which filenames without extensions SEGV'ed on open. Yikes! )0 P()-1 LI( Funmerge now extends the tlmin/tlmax values of the output binning columns so that merged events from widely separated files are valid in the output table. )0 P()-1 LI( In funhist, added -w switch to specify bin width \201lo:hi:width\202 instead of number of bins \201lo:hi:num\202. Added support for this new width option in funtools.ds9. )0 P()-1 LI( If a tdbin value was set using bincols=\201name:tlmin:tlmax:tdbin, ...\202, the WCS parameters were not being updated properly. )0 P()-1 LI( Cleaned up build support for zlib. )LU( )0 2 179 H()WB 265 Sn( Beta Release 1.0.1b1 \2016 November 2001\202)EH( )UL( )0 P()-1 LI( Added support for gzip'ed files to the underlying fitsy/gio library. This means that all funtools programs now accept gzip'ed files as valid input: ) 1 41 PR( funcnts foo.fits.gz "circle 504 512 10")RP( It is no longer necessary to run gunzip and pipe the results to stdin of a funtools program. )0 P()-1 LI( Funtools tasks are now placed in a sub-menu in the DS9 Analysis menu, instead of at the top level. )0 P()-1 LI( Fixed a bug in funcnts in which the bottom-most pixel of a small circle or annulus region could be missed when the region is only one pixel wide for that value of y. )0 P()-1 LI( Added -n switch to funhist so that table histograms could be normalized by the width of the bin \201val/\201hi_edge-lo_edge\202\202. )0 P()-1 LI( Added -T switch to fundisp, funcnts, funhist to output in starbase/rdb format \201uses tabs instead of spaces between columns, form-feeds between tables, etc.\202 )0 P()-1 LI( Fixed a bug in which the field\201\202 region was not being properly processed in combination with an image section. This could affect funcnts processing of image data where an image section was specified \201though it usually resulted in a funcnts error\202. )0 P()-1 LI( Fixed bug in display of binary table header for vector columns. )0 P()-1 LI( Filters now recognize hex constants \201starting with 0x\202 and long constants \201ending with L\202. )0 P()-1 LI(Filenames containing a ':' are now only treated as sockets if they actually are in the form of a valid ip:port. )0 P()-1 LI(Replaced funtools.ds9 with a new version that calls a new funds9 script, instead of calling funcnts or funhist directly. The new script supports gzip'ed files and bracket specifications on filenames at the same time, which the direct call could not. Also the new script has better error reporting. )0 P()-1 LI( Replaced system\201\202 call used to compile filter and funcalc expression with a special launch\201\202 call, which performs execvp\201\202 directly without going through sh. \201launch\201\202 works under DOS and has fewer security problems.\202 )0 P()-1 LI( Fixed image filter code in which the field\201\202 region was being ignored if it was combined with one or more exclude regions \201and no other include regions\202, resulting in no valid pixels. )0 P()-1 LI( Changed use of getdtable\201\202 to FD_SETSIZE in calls to select\201\202. )0 P()-1 LI( Added code to guard against FITS binary tables without proper TFORMx parameters. )0 P()-1 LI( Added support to FunParamGets so that it returns the raw FITS card if the specified input name is NULL and the input n value is positive. )0 P()-1 LI( Fixed bug in underlying fitsy code that set the comment in a header parameter. )LU( )0 2 180 H()WB 266 Sn( Public Release 1.0.0 \20131 July 2001\202)EH( )UL( )0 P()-1 LI( "a new day with no mistakes ... yet")LU( )2 1 1 HR()0 0 1 A(Index to the Funtools Help Pages)0 0 TN TL()Ec /AF f D( )0 5 181 H(Last)WB 267 Sn( updated: 22 April 2002)EH( )WB NL /TE t D NP TU PM 0 eq and{/Pn () D showpage}if end restore