1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
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
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
|
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "funcnts 1"
.TH funcnts 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation"
.SH "NAME"
funcnts \- count photons in specified regions, with bkgd subtraction
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBfuncnts\fR [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_value]
.SH "OPTIONS"
.IX Header "OPTIONS"
.Vb 16
\& \-e "source_exposure[;bkgd_exposure]"
\& # source (bkgd) FITS exposure image using matching files
\& \-w "source_exposure[;bkgd_exposure]"
\& # source (bkgd) FITS exposure image using WCS transform
\& \-t "source_timecorr[;bkgd_timecorr]"
\& # source (bkgd) time correction value or header parameter name
\& \-g # output using nice g format
\& \-G # output using %.14g format (maximum precision)
\& \-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 (and angles) for annuli (and pandas)
\& \-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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBfuncnts\fR counts photons in the specified source regions and
reports the results for each region. Regions are specified using the
Spatial Region Filtering mechanism.
Photons are also counted in the specified bkgd regions applied to the
same data file or a different data file. (Alternatively, a constant
background value in counts/pixel**2 can be specified.) 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 (cnts/area**2) calculated for
each region.
.PP
The first argument to the program specifies the \s-1FITS\s0 input image, array, or
raw event file to process. If \*(L"stdin\*(R" is specified, data are read from
the standard input. Use Funtools Bracket
Notation to specify \s-1FITS\s0 extensions, image sections, and filters.
.PP
The optional second argument is the source region descriptor. If no
region is specified, the entire field is used.
.PP
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
(i.e., no background).
.PP
In summary, the following command arguments are valid:
.PP
.Vb 5
\& [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
.Ve
.PP
\&\s-1NB:\s0 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 (i.e. use it simply as a
filter) 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 \fIfield()\fR is the
default source region. This rarely is the desired behavior. On the
other hand, with \s-1FITS\s0 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.
.PP
For example, to extract the counts within a radius of 22 pixels from the
center of the \s-1FITS\s0 binary table snr.ev and subtract the background determined
from the same image within an annulus of radii 50\-100 pixels:
.PP
.Vb 10
\& [sh] funcnts snr.ev "circle(502,512,22)" "annulus(502,512,50,100)"
\& # 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
.Ve
.PP
.Vb 4
\& # 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
.Ve
.PP
.Vb 4
\& # the following source and background components were used:
\& source region(s)
\& ----------------
\& circle(502,512,22)
.Ve
.PP
.Vb 3
\& reg counts pixels
\& ---- ------------ ---------
\& 1 4382.000 1513
.Ve
.PP
.Vb 3
\& background region(s)
\& --------------------
\& annulus(502,512,50,100)
.Ve
.PP
.Vb 3
\& reg counts pixels
\& ---- ------------ ---------
\& all 8656.000 23572
.Ve
.PP
The area units for the output columns labeled \*(L"area\*(R", \*(L"surf_bri\*(R"
(surface brightness) and \*(L"surf_err\*(R" will be given either in
arc-seconds (if appropriate \s-1WCS\s0 information is in the data file
header(s)) or in pixels. If the data file has \s-1WCS\s0 info, but you do not
want arc-second units, use the \fB\-p\fR switch to force output in
pixels. Also, regions having zero area are not normally included in
the primary (background\-subtracted) 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 \fB\-z\fR switch.
.PP
Note that a simple sed command will extract the background-subtracted results
for further analysis:
.PP
.Vb 3
\& [sh] cat funcnts.sed
\& 1,/---- .*/d
\& /^$/,$d
.Ve
.PP
.Vb 2
\& [sh] sed \-f funcnts.sed funcnts.out
\& 1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001
.Ve
.PP
If separate source and background files are specified, \fBfuncnts\fR 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 \s-1WCS\s0 information is contained in
both files (e.g. degrees/pixel values in \s-1CDELT\s0). 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.
.PP
Normally, if more than one background region is specified, \fBfuncnts\fR
will combine them all into a single region and use this background
region to produce the background-subtracted results for each source
region. The \fB\-m\fR (match multiple backgrounds) switch tells
\&\fBfuncnts\fR 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:
.PP
.Vb 10
\& [sh] funcnts snr.ev "annulus(502,512,0,22,n=2)" "annulus(502,512,50,100,n=2)"
\& # 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
.Ve
.PP
.Vb 5
\& # 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
.Ve
.PP
.Vb 4
\& # the following source and background components were used:
\& source region(s)
\& ----------------
\& annulus(502,512,0,22,n=2)
.Ve
.PP
.Vb 4
\& reg counts pixels
\& ---- ------------ ---------
\& 1 3238.000 373
\& 2 1144.000 1140
.Ve
.PP
.Vb 3
\& background region(s)
\& --------------------
\& annulus(502,512,50,100,n=2)
.Ve
.PP
.Vb 3
\& reg counts pixels
\& ---- ------------ ---------
\& all 8656.000 23572
.Ve
.PP
Note that the basic region filter rule \*(L"each photon is counted once
and no photon is counted more than once\*(R" still applies when using The
\&\fB\-m\fR 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.
.PP
Using the \fB\-m\fR switch causes \fBfuncnts\fR to use each of the two
background regions independently with each of the two source regions:
.PP
.Vb 10
\& [sh] funcnts \-m snr.ev "annulus(502,512,0,22,n=2)" "ann(502,512,50,100,n=2)"
\& # 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
.Ve
.PP
.Vb 5
\& # 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
.Ve
.PP
.Vb 4
\& # the following source and background components were used:
\& source region(s)
\& ----------------
\& annulus(502,512,0,22,n=2)
.Ve
.PP
.Vb 4
\& reg counts pixels
\& ---- ------------ ---------
\& 1 3238.000 373
\& 2 1144.000 1140
.Ve
.PP
.Vb 3
\& background region(s)
\& --------------------
\& ann(502,512,50,100,n=2)
.Ve
.PP
.Vb 4
\& reg counts pixels
\& ---- ------------ ---------
\& 1 3975.000 9820
\& 2 4681.000 13752
.Ve
.PP
Note that most floating point quantities are displayed using \*(L"f\*(R"
format. You can change this to \*(L"g\*(R" format using the \fB\-g\fR
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 \fB\-G\fR, which outputs
all floating values as %.14g.
.PP
When counting photons using the annulus and panda (pie and annuli)
shapes, it often is useful to have access to the radii (and panda
angles) for each separate region. The \fB\-r\fR switch will add radii
and angle columns to the output table:
.PP
.Vb 12
\& [sh] funcnts \-r snr.ev "annulus(502,512,0,22,n=2)" "ann(502,512,50,100,n=2)"
\& # 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
.Ve
.PP
.Vb 5
\& # 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
.Ve
.PP
.Vb 4
\& # the following source and background components were used:
\& source region(s)
\& ----------------
\& annulus(502,512,0,22,n=2)
.Ve
.PP
.Vb 4
\& reg counts pixels
\& ---- ------------ ---------
\& 1 3238.000 373
\& 2 1144.000 1140
.Ve
.PP
.Vb 3
\& background region(s)
\& --------------------
\& ann(502,512,50,100,n=2)
.Ve
.PP
.Vb 3
\& reg counts pixels
\& ---- ------------ ---------
\& all 8656.000 23572
.Ve
.PP
Radii are given in units of pixels or arc-seconds (depending on the
presence of \s-1WCS\s0 info), while the angle values (when present) are in
degrees. These columns can be used to plot radial profiles. For
example, the script \fBfuncnts.plot\fR in the funtools
distribution) will plot a radial profile using gnuplot (version 3.7 or
above). A simplified version of this script is shown below:
.PP
.Vb 1
\& #!/bin/sh
.Ve
.PP
.Vb 37
\& 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( $1 == "#" && $2 == "data" && $3 == "file:" ){
\& if( FILES != "" ) FILES = FILES ","
\& FILES = FILES $4
\& }
\& else if( $1 == "#" && $2 == "radii:" ){
\& XLABEL = $3
\& }
\& else if( $1 == "#" && $2 == "surf_bri:" ){
\& YLABEL = $3
\& }
\& else if( $1 == "----" ){
\& printf "set nokey; set title \e"funcnts(%s)\e"\en", FILES
\& printf "set xlabel \e" radius(%s)\e"\en", XLABEL
\& printf "set ylabel \e"surf_bri(%s)\e"\en", YLABEL
\& print "plot \e"-\e" using 3:4:6:7:8 with boxerrorbars"
\& HEADER = 0
\& DATA = 1
\& next
\& }
\& }
\& DATA==1{
\& if( NF == 12 ){
\& print $9, $10, ($9+$10)/2, $7, $8, $7-$8, $7+$8, $10-$9
\& }
\& else{
\& exit
\& }
\& }
\& ' | gnuplot \-persist - 1>/dev/null 2>&1
.Ve
.PP
.Vb 34
\& elif [ x"$1" = xds9 ]; then
\& awk '
\& BEGIN{HEADER=1; DATA=0; XLABEL="unknown"; YLABEL="unknown"}
\& HEADER==1{
\& if( $1 == "#" && $2 == "data" && $3 == "file:" ){
\& if( FILES != "" ) FILES = FILES ","
\& FILES = FILES $4
\& }
\& else if( $1 == "#" && $2 == "radii:" ){
\& XLABEL = $3
\& }
\& else if( $1 == "#" && $2 == "surf_bri:" ){
\& YLABEL = $3
\& }
\& else if( $1 == "----" ){
\& printf "funcnts(%s) radius(%s) surf_bri(%s) 3\en", FILES, XLABEL, YLABEL
\& HEADER = 0
\& DATA = 1
\& next
\& }
\& }
\& DATA==1{
\& if( NF == 12 ){
\& print $9, $7, $8
\& }
\& else{
\& exit
\& }
\& }
\& '
\& else
\& echo "funcnts \-r ... | funcnts.plot [ds9|gnuplot]"
\& exit 1
\& fi
.Ve
.PP
Thus, to run \fBfuncnts\fR and plot the results using gnuplot (version 3.7
or above), use:
.PP
.Vb 1
\& funcnts \-r snr.ev "annulus(502,512,0,50,n=5)" ... | funcnts.plot gnuplot
.Ve
.PP
The \fB\-s\fR (sum) switch causes \fBfuncnts\fR to produce an
additional table of summed (integrated) background subtracted values,
along with the default table of individual values:
.PP
.Vb 10
\& [sh] funcnts \-s snr.ev "annulus(502,512,0,50,n=5)" "annulus(502,512,50,100)"
\& # 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
.Ve
.PP
.Vb 8
\& # 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
.Ve
.PP
.Vb 8
\& # 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
.Ve
.PP
.Vb 4
\& # the following source and background components were used:
\& source region(s)
\& ----------------
\& annulus(502,512,0,50,n=5)
.Ve
.PP
.Vb 7
\& 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
.Ve
.PP
.Vb 3
\& background region(s)
\& --------------------
\& annulus(502,512,50,100)
.Ve
.PP
.Vb 3
\& reg counts pixels
\& ---- ------------ ---------
\& all 8656.000 23572
.Ve
.PP
The \fB\-t\fR and \fB\-e\fR 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:
.PP
.Vb 4
\& 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
.Ve
.PP
.Vb 4
\& B= Raw Counts in Background Region
\& Ab= Area of Background Region
\& Tb= (Exposure) time for Background Data
\& Eb= Average exposure in Background Region, from exposure map
.Ve
.PP
Then, Net Counts in Source region is
.PP
.Vb 1
\& Net= C - B * (Ac*Tc*Ec)/(Ab*Tb*Eb)
.Ve
.PP
with the standard propagation of errors for the Error on Net.
The net rate would then be
.PP
.Vb 1
\& Net Rate = Net/(Ac*Tc*Ec)
.Ve
.PP
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 (e.g., block 4 means that each
exposure pixel contains 4x4 pixels at full resolution) and
\&\fBfuncnts\fR will deal with the blocking automatically. Using the
\&\fB\-e\fR switch, you can supply both source and background exposure
files (separated by \*(L";\*(R"), 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, \fBfuncnts\fR 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.
.PP
\&\s-1NB:\s0 The \fB\-e\fR switch assumes that the exposure map overlays the
image file \fBexactly\fR, 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, \fBdo not use\fR the \fB\-e\fR exposure
correction. In this case, it still is possible to perform exposure
correction \fBif\fR both the image and the exposure map have valid
\&\s-1WCS\s0 information: use the \fB\-w\fR switch so that the transformation
from image pixel to exposure pixel uses the \s-1WCS\s0 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 \fB\-w\fR can increase the time
required to process the exposure correction considerably.
.PP
A time correction can be applied to both source and
background data using the \fB\-t\fR switch. The value for the correction can
either be a numeric constant or the name of a header parameter in
the source (or background) file:
.PP
.Vb 2
\& [sh] funcnts \-t 23.4 ... # number for source
\& [sh] funcnts \-t "LIVETIME;23.4" ... # param for source, numeric for bkgd
.Ve
.PP
When a time correction is specified, it is applied to the net counts
as well (see algorithm above), so that the units of surface brightness
become cnts/area**2/sec.
.PP
The \fB\-i\fR (interval) switch is used to run \fBfuncnts\fR on multiple
column-based intervals with only a single pass through the data. It is
equivalent to running \fBfuncnts\fR several times with a different column
filter added to the source and background data each time. For each
interval, the full \fBfuncnts\fR output is generated, with a linefeed
character (^L) 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.
.PP
Two formats are supported for interval specification. The most general
format is semi-colon-delimited list of filters to be used as intervals:
.PP
.Vb 1
\& funcnts \-i "pha=1:5;pha=6:10;pha=11:15" snr.ev "circle(502,512,22)" ...
.Ve
.PP
Conceptually, this will be equivalent to running \fBfuncnts\fR three times:
.PP
.Vb 3
\& funcnts snr.ev'[pha=1:5]' "circle(502,512,22)"
\& funcnts snr.ev'[pha=6:10]' "circle(502,512,22)"
\& funcnts snr.ev'[pha=11:15]' "circle(502,512,22)"
.Ve
.PP
However, using the \fB\-i\fR switch will require only one pass through
the data.
.PP
Note that complex filters can be used to specify intervals:
.PP
.Vb 1
\& funcnts \-i "pha=1:5&&pi=4;pha=6:10&&pi=5;pha=11:15&&pi=6" snr.ev ...
.Ve
.PP
The program simply runs the data through each filter in turn and generates
three \fBfuncnts\fR outputs, separated by the line-feed character.
.PP
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
\&\*(L"interval\*(R" filter have to be related to another. For example:
.PP
.Vb 1
\& funcnts \-i "pha=1:5;pi=6:10;energy=11:15" snr.ev "circle(502,512,22)" ...
.Ve
.PP
is equivalent to running \fBfuncnts\fR three times with unrelated filter
specifications.
.PP
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:
.PP
.Vb 1
\& funcnts \-i "pha;1:5;6:10;11:15" snr.ev "circle(502,512,22)" ...
.Ve
.PP
This is equivalent to the first example, but requires less typing. The
\&\fBfuncnts\fR program will simply prepend \*(L"pha=\*(R" before each of the specified
intervals. (Note that this format does not contain the \*(L"=\*(R" character in
the column argument.)
.PP
Ordinarily, when \fBfuncnts\fR is run on a \s-1FITS\s0 binary table (or a
raw event table), one integral count is accumulated for each row
(event) contained within a given region. The \fB\-v \*(L"scol[;bcol]\*(R"\fR
(value column) 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.
.PP
If the \fB\-T\fR (rdb table) 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.
.PP
Finally, note that \fBfuncnts\fR is an image program, even though it
can be run directly on \s-1FITS\s0 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 \fBfuncnts\fR can differ from the number of events found
using row-filter programs such as \fBfundisp\fR or \fBfuntable\fR
For more information about these difference, see the discussion of
Region Boundaries.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See funtools(7) for a list of Funtools help pages
|