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
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
|
<HTML>
<HEAD>
<TITLE>Funtools Programs</TITLE>
</HEAD>
<BODY>
<H2>Funtools Programs</H2>
<H2>Summary</H2>
<P>
<PRE>
<A HREF="./programs.html#funcalc">funcalc</A> [-n] [-a argstr] [-e expr] [-f file] [-l link] [-p prog] [-u] <iname> [oname [columns]]
<A HREF="./programs.html#funcen">funcen</A> [-i] [-n iter] [-t tol] [-v lev] <iname> <region>
<A HREF="./programs.html#funcnts">funcnts</A> [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_cnts]
<A HREF="./programs.html#funcone">funcone</A> [-n] [-x|-X|-j|-J] [[-l|-L] list] [-r ra_col] [-d dec_col] <iname> <oname> <ra[hdr]> <dec[hdr]> <radius[dr'"]> [columns]
<A HREF="./programs.html#fundisp">fundisp</A> [-f format] [-l] [-n] [-T] <iname> [columns|bitpix=n]
<A HREF="./programs.html#funhead">funhead</A> [-a] [-l] [-s] [-t] [-L] <iname> [oname ename]
<A HREF="./programs.html#funhist">funhist</A> [-n|-w|-T] <iname> [column] [[lo_edge:hi_edge:]bins]
<A HREF="./programs.html#funimage">funimage</A> [-a] [-l] [-p x|y] <iname> <oname> [bitpix=n]
<A HREF="./programs.html#funindex">funindex</A> <iname> <key> [oname]
<A HREF="./programs.html#funjoin">funjoin</A> [switches] <ifile1> <ifile2> ... <ifilen> <ofile>
<A HREF="./programs.html#funmerge">funmerge</A> <iname1> <iname2> ... <oname>
<A HREF="./programs.html#funsky">funsky</A> [switches] <iname1> [<lname2> <col1> <col2>]
<A HREF="./programs.html#funtable">funtable</A> [-a] [-i|-z] [-m] [-s cols] <iname> <oname> [columns]
<A HREF="./programs.html#funtbl">funtbl</A> [-c cols] [-h] [-n table] [-p prog] [-s sep] [-T] <iname>
</PRE>
<!-- =defdoc funcalc funcalc 1 -->
<!-- =section funcalc NAME -->
<H2><A NAME="funcalc">funcalc - Funtools calculator (for binary tables)</A></H2>
<!-- =section funcalc SYNOPSIS -->
<B>
<PRE>
funcalc [-n] [-a argstr] [-e expr] [-f file] [-l link] [-p prog] <iname> [oname [columns]]
</PRE>
</B>
<!-- =section funcalc OPTIONS -->
<P>
<PRE>
-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 (don't auto-declare)
</PRE>
<!-- =section funcalc DESCRIPTION -->
<P>
<B>funcalc</B> is a calculator program that allows arbitrary
expressions to be constructed, compiled, and executed on columns in a
Funtools table (FITS binary table or raw event file). It works by
integrating user-supplied expression(s) into a template C program,
then compiling and executing the program. <B>funcalc</B> expressions
are C statements, although some important simplifications (such
as automatic declaration of variables) are supported.
<P>
<B>funcalc</B> expressions can be specified in three ways: on the
command line using the <B>-e [expression]</B> switch, in a file using
the <B>-f [file]</B> switch, or from stdin (if neither <B>-e</B> nor
<B>-f</B> is specified). Of course a file containing <B>funcalc</B>
expressions can be read from stdin.
<P>
Each invocation of <B>funcalc</B> 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 (i.e., in cases where the
<B>funcalc</B> expression only prints values, no output file is
needed). If input and output file are both specified, a third optional
argument can specify the list of columns to activate (using
<A HREF="./library.html#funcolumnactivate">FunColumnActivate()</A>). Note
that <B>funcalc</B> determines whether or not to generate code for
writing an output file based on the presence or absence of an
output file argument.
<P>
A <B>funcalc</B> expression executes on each row of a table and
consists of one or more C statements that operate on the columns of
that row (possibly using temporary variables). Within an expression,
reference is made to a column of the <B>current</B> row using the C
struct syntax <B>cur->[colname]</B>, 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 <B>funcalc</B> (to be of type double). Thus, for example, a swap of
columns x and y in a table can be performed using either of the
following equivalent <B>funcalc</B> expressions:
<PRE>
double temp;
temp = cur->x;
cur->x = cur->y;
cur->y = temp;
</PRE>
or:
<PRE>
temp = cur->x;
cur->x = cur->y;
cur->y = temp;
</PRE>
When this expression is executed using a command such as:
<PRE>
funcalc -f swap.expr itest.ev otest.ev
</PRE>
the resulting file will have values of the x and y columns swapped.
<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:
<PRE>
temp = cur->x:D;
cur->x = cur->y:D;
cur->y = temp;
</PRE>
Data type specifiers follow standard FITS table syntax for defining
columns using TFORM:
<UL>
<LI>A: ASCII characters
<LI>B: unsigned 8-bit char
<LI>I: signed 16-bit int
<LI>U: unsigned 16-bit int (not standard FITS)
<LI>J: signed 32-bit int
<LI>V: unsigned 32-bit int (not standard FITS)
<LI>E: 32-bit float
<LI>D: 64-bit float
<LI>X: bits (treated as an array of chars)
</UL>
Note that only the first reference to a column should contain the
explicit data type specifier.
<P>
Of course, it is important to handle the data type of the columns
correctly. One of the most frequent cause of error in <B>funcalc</B>
programming is the implicit use of the wrong data type for a column in
expression. For example, the calculation:
<PRE>
dx = (cur->x - cur->y)/(cur->x + cur->y);
</PRE>
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:
<PRE>
dx = (cur->x:D - cur->y:D)/(cur->x + cur->y);
</PRE>
Alternatively, it can be done using C type-casting in the expression:
<PRE>
dx = ((double)cur->x - (double)cur->y)/((double)cur->x + (double)cur->y);
</PRE>
<P>
In addition to accessing columns in the current row, reference also
can be made to the <B>previous</B> row using <B>prev->[colname]</B>,
and to the <B>next</B> row using <B>next->[colname]</B>. Note that if
<B>prev->[colname]</B> is specified in the <B>funcalc</B>
expression, the very first row is not processed. If
<B>next->[colname]</B> is specified in the <B>funcalc</B>
expression, the very last row is not processed. In this way,
<B>prev</B> and <B>next</B> 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
<B>funcalc</B> expression:
<PRE>
fprintf(stdout, "%d %d\n", cur->x, prev->y);
</PRE>
<P>
New columns can be specified using the same <B>cur->[colname]</B>
syntax by appending the column type (and optional tlmin/tlmax/binsiz
specifiers), 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.
<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:
<PRE>
cur->avg:D = (cur->x + cur->y)/2.0
</PRE>
Note that the final ';' is not required for single-line expressions.
<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
<B>funcalc</B> expression, after which it can be used without
re-specifying the type. This includes reference to elements of a
column array:
<PRE>
cur->avg[0]:2D = (cur->x + cur->y)/2.0;
cur->avg[1] = (cur->x - cur->y)/2.0;
</PRE>
<P>
The 'X' (bits) data type is treated as a char array of dimension
(numeric_count/8), i.e., 16X is processed as a 2-byte char array. Each
8-bit array element is accessed separately:
<PRE>
cur->stat[0]:16X = 1;
cur->stat[1] = 2;
</PRE>
Here, a 16-bit column is created with the MSB is set to 1 and the LSB set to 2.
<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 <B>funcalc</B> 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:
<PRE>
cur->avg[0]:2D = (cur->x + cur->y)/2.0;
cur->avg[1] = (cur->x - cur->y)/2.0;
if( cur->avg[0] == cur->x )
continue;
</PRE>
<P>
If no output file argument is specified on the <B>funcalc</B> 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:
<PRE>
fpv = (cur->av3:D-cur->av1:D)/(cur->av1+cur->av2:D+cur->av3);
fbv = cur->av2/(cur->av1+cur->av2+cur->av3);
fpu = ((double)cur->au3-cur->au1)/((double)cur->au1+cur->au2+cur->au3);
fbu = cur->au2/(double)(cur->au1+cur->au2+cur->au3);
fprintf(stdout, "%f\t%f\t%f\t%f\n", fpv, fbv, fpu, fbu);
</PRE>
In the above example, we use both explicit type specification
(for "av" columns) and type casting (for "au" columns) to ensure that
all operations are performed in double precision.
<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.
<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 <B>funtable</B> for a related example.
<P>
<B>funcalc</B> works by integrating the user-specified expression
into a template C program called <A HREF="./tabcalc.c">tabcalc.c</A>.
The completed program then is compiled and executed. Variable
declarations that begin the <B>funcalc</B> 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
<A HREF="./library.html#funcolumnselect">FunColumnSelect()</A> and used
in <A HREF="./library.html#funtablerowget">FunTableRowGet()</A>. 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.
<P>
Normally, <B>funcalc</B> expression code is added to
<B>funcalc</B> 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:
<PRE>
[directive name]
... code goes here ...
end
</PRE>
The directives are:
<UL>
<LI><B>global</B> add code and declarations in global space, before the main routine.
<LI><B>local</B> add declarations (and code) just after the local declarations in
main
<LI><B>before</B> add code just before entering the main row processing loop
<LI><B>after</B> add code just after exiting the main row processing loop
</UL>
Thus, the following <B>funcalc</B> expression will declare global
variables and make subroutine calls just before and just after the
main processing loop:
<PRE>
global
double v1, v2;
double init(void);
double finish(double v);
end
before
v1 = init();
end
... process rows, with calculations using v1 ...
after
v2 = finish(v1);
if( v2 < 0.0 ){
fprintf(stderr, "processing failed %g -> %g\n", v1, v2);
exit(1);
}
end
</PRE>
Routines such as init() and finish() above are passed to the generated
program for linking using the <B>-l [link directives ...]</B>
switch. The string specified by this switch will be added to the link
line used to build the program (before the funtools library). For
example, assuming that init() and finish() are in the library
libmysubs.a in the /opt/special/lib directory, use:
<PRE>
funcalc -l "-L/opt/special/lib -lmysubs" ...
</PRE>
<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:
<PRE>
funcalc -a "1 2" ...
</PRE>
The arguments are stored in an internal array and are accessed as
strings via the ARGV(n) macro. For example, consider the following
expression:
<PRE>
local
int pmin, pmax;
end
before
pmin=atoi(ARGV(0));
pmax=atoi(ARGV(1));
end
if( (cur->pha >= pmin) && (cur->pha <= pmax) )
fprintf(stderr, "%d %d %d\n", cur->x, cur->y, cur->pha);
</PRE>
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:
<PRE>
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
</PRE>
<P>
Note that it is the user's responsibility to ensure that the correct
number of arguments are passed. The ARGV(n) 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:
<PRE>
local
long int seed=1;
double limit=0.8;
end
before
if( ARGC >= 1 ) seed = atol(ARGV(0));
if( ARGC >= 2 ) limit = atof(ARGV(1));
srand48(seed);
end
if ( drand48() > limit ) continue;
</PRE>
<P>
The macro WRITE_ROW expands to the FunTableRowPut() 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:
<PRE>
if( cur->pha:I == cur->pi:I ) continue;
a = cur->pha;
cur->pha = cur->pi;
cur->pi = a;
cur->AVG:E = (cur->pha+cur->pi)/2.0;
cur->NR:I = NROW;
if( NROW < 10 ) WRITE_ROW;
</PRE>
<p>
If the <B>-p [prog]</B> switch is specified, the expression is not
executed. Rather, the generated executable is saved with the specified
program name for later use.
<P>
If the <B>-n</B> 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. (The command can change from
platform to platform because of the use of different libraries,
compiler switches, etc.)
<P>
As mentioned previously, <B>funcalc</B> will declare a scalar
variable automatically (as a double) if that variable has been used
but not declared. This facility is implemented using a sed script
named <A HREF="./funcalc.sed">funcalc.sed</A>, 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.
<P>
In order to keep the lexical analysis of <B>funcalc</B> expressions
(reasonably) 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 (i.e., not in a
<B>local...end</B> block) will usually end up in the inner loop, not
with the local declarations:
<PRE>
/* this comment will end up in the wrong place (i.e, inner loop) */
double a; /* also in wrong place */
/* this will be in the the right place (inner loop) */
if( cur->x:D == cur->y:D ) continue; /* also in right place */
a = cur->x;
cur->x = cur->y;
cur->y = a;
cur->avg:E = (cur->x+cur->y)/2.0;
</PRE>
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.
<P>
Because <B>funcalc</B> must analyze the user expression using the data
file(s) passed on the command line, the input file(s) 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: <B>funcalc</B> cannot be used as a filter. We will
consider removing this restriction at a later time.
<P>
Along with C comments, <B>funcalc</B> expressions can have one-line
internal comments that are not passed on to the generated C
program. These internal comment start with the <B>#</B> character and
continue up to the new-line:
<PRE>
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 = (cur->x+cur->y)/2.0;
</PRE>
<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 (and therefore not
implicitly specified as a column to be read). To ensure that such a
column is read by the event loop, use the <b>explicit</b> 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:
<PRE>
explicit pi pha
</PRE>
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 <b>explicit</b>
statement can be placed anywhere.
<P>
Finally, note that <B>funcalc</B> 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.
<!-- =defdoc funcen funcen 1 -->
<!-- =section funcen NAME -->
<H2><A NAME="funcen">funcen - find centroid (for binary tables)</A></H2>
<!-- =section funcen SYNOPSIS -->
<B>
<PRE>
funcen [-i] [-n iter] [-t tol] [-v lev] <iname> <region>
</PRE>
</B>
<!-- =section funcen OPTIONS -->
<P>
<PRE>
-i # use image filtering (default: event filtering)
-n iter # max number of iterations (default: 0)
-t tol # pixel tolerance distance (default: 1.0)
-v [0,1,2,3] # output verbosity level (default: 0)
</PRE>
<!-- =section funcen DESCRIPTION -->
<P>
<B>funcen</B> iteratively calculates the centroid position within one
or more regions of a Funtools table (FITS binary table or raw event
file). 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 (and, where
available, WCS position).
<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
<A HREF="./files.html">Funtools Bracket Notation</A> to specify FITS
extensions and filters.
<P>
The second required argument is the initial region descriptor. Multiple
regions are permitted. However, compound regions (accelerators,
variable argument regions and regions connected via boolean algebra)
are not permitted. Points and polygons also are illegal. These
restrictions might be lifted in a future version, if warranted.
<p>
The <B>-n</B> (iteration number) 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(s).
Note that when iterations is 0, the data can be input via stdin.
<p>
The <B>-t</B> (tolerance) 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.
<p>
The <B>-v</B> (verbosity) 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:
<pre>
counts x y [ra dec coordsys]
</pre>
The last 3 WCS values are output if WCS information is available in the
data file header. Thus, for example:
<pre>
[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
</pre>
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.
<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(physical): 504.43 509.65
ra,dec(j2000): 345.286480 58.874587
final_region1: cir 504.43 509.65 5
</pre>
Level 2 outputs results from intermediate calculations as well.
<p>
Ordinarily, region filtering is performed using analytic (event)
filtering, i.e. that same style of filtering as is performed by
<b>fundisp</b> and <b>funtable</b>. Use the <b>-i</b> switch to specify image
filtering, i.e. the same style filtering as is performed by <b>funcnts</b>.
Thus, you can perform a quick calculation of counts in regions, using
either the analytic or image filtering method, by specifying the
<b>-n 0</b> and optional <b>-i</b> switches. These two method often
give different results because of how boundary events are processed:
<pre>
[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
</pre>
See <A HREF="./regbounds.html">Region Boundaries</A> for more information
about how boundaries are calculated using these two methods.
<!-- =defdoc funcnts funcnts 1 -->
<!-- =section funcnts NAME -->
<H2><A NAME="funcnts">funcnts - count photons in specified regions, with bkgd subtraction</A></H2>
<!-- =section funcnts SYNOPSIS -->
<B>
<PRE>
funcnts [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_value]
</PRE>
</B>
<!-- =section funcnts OPTIONS -->
<P>
<PRE>
-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
</B>
</PRE>
<!-- =section funcnts DESCRIPTION -->
<P>
<B>funcnts</B> counts photons in the specified source regions and
reports the results for each region. Regions are specified using the
<A HREF="./regions.html">Spatial Region Filtering</A> 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.
<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 <A HREF="./files.html">Funtools Bracket
Notation</A> to specify FITS extensions, image sections, and filters.
<P>
The optional second argument is the source region descriptor. If no
region is specified, the entire field is used.
<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
(i.e., no background).
<P>
In summary, the following command arguments are valid:
<PRE>
[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
</PRE>
<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 (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 field() 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.
<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:
<PRE>
[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
# 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(s)
----------------
circle(502,512,22)
reg counts pixels
---- ------------ ---------
1 4382.000 1513
background region(s)
--------------------
annulus(502,512,50,100)
reg counts pixels
---- ------------ ---------
all 8656.000 23572
</PRE>
The area units for the output columns labeled "area", "surf_bri"
(surface brightness) and "surf_err" will be given either in
arc-seconds (if appropriate WCS information is in the data file
header(s)) or in pixels. If the data file has WCS info, but you do not
want arc-second units, use the <B>-p</B> 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 <B>-z</B> switch.
<P>
Note that a simple sed command will extract the background-subtracted results
for further analysis:
<PRE>
[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
</PRE>
<P>
If separate source and background files are specified, <B>funcnts</B> 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 (e.g. degrees/pixel values in CDELT). 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.
<P>
Normally, if more than one background region is specified, <B>funcnts</B>
will combine them all into a single region and use this background
region to produce the background-subtracted results for each source
region. The <B>-m</B> (match multiple backgrounds) switch tells
<B>funcnts</B> 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:
<PRE>
[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
# 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(s)
----------------
annulus(502,512,0,22,n=2)
reg counts pixels
---- ------------ ---------
1 3238.000 373
2 1144.000 1140
background region(s)
--------------------
annulus(502,512,50,100,n=2)
reg counts pixels
---- ------------ ---------
all 8656.000 23572
</PRE>
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
<B>-m</B> 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.
<P>
Using the <B>-m</B> switch causes <B>funcnts</B> to use each of the two
background regions independently with each of the two source regions:
<PRE>
[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
# 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(s)
----------------
annulus(502,512,0,22,n=2)
reg counts pixels
---- ------------ ---------
1 3238.000 373
2 1144.000 1140
background region(s)
--------------------
ann(502,512,50,100,n=2)
reg counts pixels
---- ------------ ---------
1 3975.000 9820
2 4681.000 13752
</PRE>
<P>
Note that most floating point quantities are displayed using "f"
format. You can change this to "g" format using the <B>-g</B>
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 <B>-G</B>, which outputs
all floating values as %.14g.
<P>
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 <B>-r</B> switch will add radii
and angle columns to the output table:
<PRE>
[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
# 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(s)
----------------
annulus(502,512,0,22,n=2)
reg counts pixels
---- ------------ ---------
1 3238.000 373
2 1144.000 1140
background region(s)
--------------------
ann(502,512,50,100,n=2)
reg counts pixels
---- ------------ ---------
all 8656.000 23572
</PRE>
<P>
Radii are given in units of pixels or arc-seconds (depending on the
presence of WCS info), while the angle values (when present) are in
degrees. These columns can be used to plot radial profiles. For
example, the script <B>funcnts.plot</B> 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:
<PRE>
#!/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( $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 \"funcnts(%s)\"\n", FILES
printf "set xlabel \" radius(%s)\"\n", XLABEL
printf "set ylabel \"surf_bri(%s)\"\n", YLABEL
print "plot \"-\" 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
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\n", 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
</PRE>
Thus, to run <B>funcnts</B> and plot the results using gnuplot (version 3.7
or above), use:
<PRE>
funcnts -r snr.ev "annulus(502,512,0,50,n=5)" ... | funcnts.plot gnuplot
</PRE>
<P>
The <B>-s</B> (sum) switch causes <B>funcnts</B> to produce an
additional table of summed (integrated) background subtracted values,
along with the default table of individual values:
<PRE>
[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
# 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
# the following source and background components were used:
source region(s)
----------------
annulus(502,512,0,50,n=5)
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(s)
--------------------
annulus(502,512,50,100)
reg counts pixels
---- ------------ ---------
all 8656.000 23572
</PRE>
<P>
The <B>-t</B> and <B>-e</B> 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:
<PRE>
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= (Exposure) time for Background Data
Eb= Average exposure in Background Region, from exposure map
</PRE>
Then, Net Counts in Source region is
<PRE>
Net= C - B * (Ac*Tc*Ec)/(Ab*Tb*Eb)
</PRE>
with the standard propagation of errors for the Error on Net.
The net rate would then be
<PRE>
Net Rate = Net/(Ac*Tc*Ec)
</PRE>
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
<B>funcnts</B> will deal with the blocking automatically. Using the
<B>-e</B> switch, you can supply both source and background exposure
files (separated by ";"), 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, <B>funcnts</B> 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.
<P>
NB: The <B>-e</B> switch assumes that the exposure map overlays the
image file <B>exactly</B>, 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, <B>do not use</B> the <B>-e</B> exposure
correction. In this case, it still is possible to perform exposure
correction <B>if</B> both the image and the exposure map have valid
WCS information: use the <B>-w</B> 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 <B>-w</B> can increase the time
required to process the exposure correction considerably.
<P>
A time correction can be applied to both source and
background data using the <B>-t</B> 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:
<PRE>
[sh] funcnts -t 23.4 ... # number for source
[sh] funcnts -t "LIVETIME;23.4" ... # param for source, numeric for bkgd
</PRE>
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.
<P>
The <B>-i</B> (interval) switch is used to run <b>funcnts</b> on multiple
column-based intervals with only a single pass through the data. It is
equivalent to running <b>funcnts</b> several times with a different column
filter added to the source and background data each time. For each
interval, the full <b>funcnts</b> 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.
<P>
Two formats are supported for interval specification. The most general
format is semi-colon-delimited list of filters to be used as intervals:
<PRE>
funcnts -i "pha=1:5;pha=6:10;pha=11:15" snr.ev "circle(502,512,22)" ...
</PRE>
Conceptually, this will be equivalent to running <b>funcnts</b> three times:
<PRE>
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)"
</PRE>
However, using the <B>-i</B> switch will require only one pass through
the data.
<P>
Note that complex filters can be used to specify intervals:
<PRE>
funcnts -i "pha=1:5&&pi=4;pha=6:10&&pi=5;pha=11:15&&pi=6" snr.ev ...
</PRE>
The program simply runs the data through each filter in turn and generates
three <b>funcnts</b> outputs, separated by the line-feed character.
<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:
<PRE>
funcnts -i "pha=1:5;pi=6:10;energy=11:15" snr.ev "circle(502,512,22)" ...
</PRE>
is equivalent to running <b>funcnts</b> three times with unrelated filter
specifications.
<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:
<PRE>
funcnts -i "pha;1:5;6:10;11:15" snr.ev "circle(502,512,22)" ...
</PRE>
This is equivalent to the first example, but requires less typing. The
<b>funcnts</b> program will simply prepend "pha=" before each of the specified
intervals. (Note that this format does not contain the "=" character in
the column argument.)
<P>
Ordinarily, when <b>funcnts</b> is run on a FITS binary table (or a
raw event table), one integral count is accumulated for each row
(event) contained within a given region. The <B>-v "scol[;bcol]"</B>
(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.
<P>
If the <B>-T</B> (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.
<P>
Finally, note that <B>funcnts</B> 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 <B>funcnts</B> can differ from the number of events found
using row-filter programs such as <B>fundisp</B> or <B>funtable</B>
For more information about these difference, see the discussion of
<A HREF="./regbounds.html">Region Boundaries</A>.
<!-- =defdoc funcone funcone 1 -->
<!-- =section funcone NAME -->
<H2><A NAME="funcone">funcone - cone search of a binary table containing RA, Dec columns</A></H2>
<!-- =section funcone SYNOPSIS -->
<B>
<PRE>
funcone <switches> <iname> <oname> <ra[hdr]> <dec[hdr]> <radius[dr'"]> [columns]
</PRE>
</B>
<!-- =section funcone OPTIONS -->
<P>
<PRE>
-d deccol:[hdr] # Dec column name, units (def: DEC:d)
-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 (def: RA:h)
-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
</PRE>
<!-- =section funcone DESCRIPTION -->
<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.
<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 <A HREF="./files.html">Funtools Bracket
Notation</A> 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.
<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" (degrees), "h" (hours) or "r" (radians). Sexagesimal
notation is supported, with colons or spaces separating hms and dms.
(When using spaces, please ensure that the entire string is quoted.)
<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" (degrees), "r" (radians), "'" (arc minutes) or
'"' (arc seconds).
<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:
<PRE>
"column1 column1 ... columnN"
</PRE>
A seventh argument allows you to output selected columns from the list
file when <B>-j</B> switch is used. Note that the RA and Dec columns
used in the cone calculation must not be de-selected.
<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.
<P>
If the <B>-l [listfile]</B> switch is used, then one or more of the
center RA, center Dec, and radius can be taken from a list file (which
can be a FITS table or an ASCII column text file). In this case, the
third (center RA), fourth (center Dec), and fifth (radius) command
line arguments can either be a column name in the list file (if that
parameter varies) or else a numeric value (if that parameter is
static). 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
(also ' and " for radius). 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.
<P>
When using a list, all valid rows from each iteration are written to a
single output file. Use the <B>-x</B> switch to help delineate which
line of the list file was used to produce the given output row(s).
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
<B>-j</B> (join) switch will append all columns from the list row to
the output row (essentially a join of the list row and input row),
along with the CONE_KEY row number. These two switches are mutually
exclusive.
<P>
The <b>-X</b> and <b>-J</b> 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.
<p>
The <b>-L</b> switch acts similarly to the <b>-l</b> 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.
<p>
If any of "all row" switches (<b>-X</b>, <b>-J</b>, or <b>-L</b>) 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
(starting from 1) 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.
<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 <B>-n</B>
switch to see if this speeds up the processing (especially useful when
processing a large list of positions).
<P>
For example, the default cone search uses columns "RA" and "Dec" in hours
and degrees (respectively) and RA position in hours, Dec and radius in degrees:
<PRE>
funone in.fits out.fits 23.45 34.56 0.01
</PRE>
To specify the RA position in degrees:
<PRE>
funcone in.fits out.fits 23.45d 34.56 0.01
</PRE>
To get RA and Dec from a list but use a static value for radius (and
also write identifying info for each row in the list):
<PRE>
funcone -x -l list.txt in.fits out.fits MYRA MYDec 0.01
</PRE>
User specified columns in degrees, RA position in hours (sexagesimal
notation), Dec position in degrees (sexagesimal notation) and radius
in arc minutes:
<PRE>
funcone -r myRa:d -d myDec in.fits out.fits 12:30:15.5 30:12 15'
</PRE>
<!-- =defdoc fundisp fundisp 1 -->
<!-- =section fundisp NAME -->
<H2><A NAME="fundisp">fundisp - display data in a Funtools data file</A></H2>
<!-- =section fundisp SYNOPSIS -->
<B>
<PRE>
fundisp [-f format] [-l] [-n] [-T] <iname> [columns|bitpix=n]
</PRE>
</B>
<!-- =section fundisp OPTIONS -->
<P>
<PRE>
-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 (def: space)
-T # output in rdb/starbase format (tab separators)
</PRE>
<!-- =section fundisp DESCRIPTION -->
<P>
<B>fundisp</B> displays the data in the specified
<A HREF="./files.html">FITS Extension</A>
and/or
<A HREF="./files.html#sections">Image Section</A>
of a FITS file, or in a
<A HREF="./files.html#sections">Section</A>
of a non-FITS array or raw event file.
<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 <A HREF="./files.html">Funtools Bracket
Notation</A> to specify FITS extensions, image sections, and filters.
<P>
If the data being displayed are columns (either in a FITS binary table
or a raw event file), the individual rows are listed. Filters can be
added using bracket notation. Thus:
<PRE>
[sh] fundisp "test.ev[time-(int)time>.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
</PRE>
[NB: The FITS binary table test file test.ev, as well as the FITS
image test.fits, are contained in the funtools funtest directory.]
<P>
When a table is being displayed using <B>fundisp</B>, a second optional
argument can be used to specify the columns to display. For example:
<PRE>
[sh] fundisp "test.ev[time-(int)time>=.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
</PRE>
<P>
The special column <B>$REGION</B> can be specified to display the
region id of each row:
<PRE>
[sh $] fundisp "test.ev[time-(int)time>=.99&&annulus(0 0 0 10 n=3)]" '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
</PRE>
<P>
Here only rows with the proper fractional time and whose position also is
within one of the three annuli are displayed.
<P>
Columns can be excluded from display using a minus sign before the
column:
<PRE>
[sh $] fundisp "test.ev[time-(int)time>=.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
</PRE>
All columns except the time column are displayed.
<P>
The special column <B>$N</B> can be specified to display the
ordinal value of each row. Thus, continuing the previous example:
<PRE>
fundisp "test.ev[time-(int)time>=.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
</PRE>
Note that the column specification is enclosed in single quotes to protect
'$n' from begin expanded by the shell.
<P>
In general, the rules for activating and de-activating columns are:
<UL>
<LI> If only exclude columns are specified, then all columns but
the exclude columns will be activated.
<LI> If only include columns are specified, then only the specified columns
are activated.
<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.
</UL>
In addition to specifying columns names explicitly, the special
symbols <B>+</B> and <B>-</B> can be used to activate and
de-activate <B>all</B> 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.
<P>
If the data being displayed are image data (either in a FITS primary
image, a FITS image extension, or an array file), 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:
<PRE>
bitpix=n
</PRE>
where n is 8,16,32,-32,-64, for unsigned char, short, int, float and double,
respectively.
<P>
Of course, running <B>fundisp</B> on anything but the smallest image
usually results in a display whose size makes it unreadable.
Therefore, one can uses bracket notation (see below)
to apply section and/or blocking to the image before generating a
display. For example:
<PRE>
[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
</PRE>
<P>
Note that is is possible to display a FITS binary table as an image
simply by passing the table through <B>funimage</B> first:
<PRE>
[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
</PRE>
If the <B>-l</B> (list) switch is used, then an image is displayed as a
list containing the columns: X, Y, VAL. For example:
<PRE>
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
5 7 1.00
6 7 1.00
</PRE>
<p>
If the <B>-n</B> (nohead) switch is used, then no header is output for
tables. This is useful, for example, when fundisp output is being
directed into gnuplot.
<P>
The <B>fundisp</B> program uses a default set of display formats:
<PRE>
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"
</PRE>
Thus, the default display of 1 double and 2 shorts gives:
<PRE>
[sh] fundisp snr.ev "time x y"
TIME X Y
--------------------- -------- --------
79494546.56818075 546 201
79488769.94469175 548 201
...
</PRE>
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 (in which case
the associated format pertains only to that column) or FITS table
TFORM specifiers (in which case the format pertains to all columns
having that data type). For example, you can change the double and
short formats for all columns like this:
<PRE>
[sh] fundisp -f "D=%22.11f I=%3d" snr.ev "time x y"
TIME X Y
---------------------- --- ---
79494546.56818075478 546 201
79488769.94469174743 548 201
...
</PRE>
<p>
Alternatively, you can change the format of the time and x columns like this:
<pre>
[sh] fundisp -f "time=%22.11f x=%3d" snr.ev "time x y"
TIME X Y
---------------------- --- --------
79494546.56818075478 546 201
79488769.94469174743 548 201
...
</pre>
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 (bit) 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 (bit) datatype, while "x=%3d" will refer to the X column:
<pre>
[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
...
</pre>
As a rule, therefore, it is best always to specify the column name in
lower case and TFORM data types in upper case.
<p>
The <B>-f [format]</B> will change the format for a single execution
of fundisp. You also can use the <B>FUN_FORMAT</B> 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 <B>-f</B> switch. This global value can be overridden in
individual cases by use of the <B>-f [format]</B> switch.
<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 (on the left) if the
format width is less than the length of the name. However, truncation
is not performed if the output is in RDB format (using the -T switch).
<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:
<PRE>
double float int short byte string bit.
</PRE>
This order of the list is based on the assumption that people generally
will want to change the float formats.
<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:
<PRE>
[sh] fundisp -f "22.11f - - 3d" snr.ev "time x y"
TIME X Y
---------------------- --- ---
79494546.56818075478 546 201
79488769.94469174743 548 201
...
</PRE>
NB: This format is deprecated and will be removed in a future release.]
<P>
The <B>-F[c]</B> switch can be used to specify a (single-character)
column separator (where the default is a space). 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:
<PRE>
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
</PRE>
<P>
If the <B>-T</B> (rdb table) 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 (except in conjunction with the <B>-l</B>
switch).
<P>
Finally, note that <B>fundisp</B> 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 (GTI) filter for X-ray data files that
contain a standard GTI extension:
<PRE>
#!/bin/sh
sed '1,/---- .*/d
/^$/,$d' | awk 'tot>0{printf "||"};{printf "time="$1":"$2; tot++}'
</PRE>
If this script is placed in a file called "mkgti", it can be used in a
command such as:
<PRE>
fundisp foo.fits"[GTI]" | mkgti > gti.filter
</PRE>
The resulting filter file can then be used in various funtools programs:
<PRE>
funcnts foo.fits"[@gti.filter]" ...
</PRE>
to process only the events in the good-time intervals.
<!-- =defdoc funhead funhead 1 -->
<!-- =section funhead NAME -->
<H2><A NAME="funhead">funhead - display a header in a Funtools file</A></H2>
<!-- =section funhead SYNOPSIS -->
<B>
<PRE>
funhead [-a] [-s] [-t] [-L] <iname> [oname ename]
</PRE>
</B>
<!-- =section funhead OPTIONS -->
<P>
<PRE>
-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
</PRE>
<!-- =section funhead DESCRIPTION -->
<P>
<B>funhead</B> displays the FITS header parameters in the specified
<A HREF="./files.html">FITS Extension</A>.
<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. <A HREF="./files.html">Funtools Bracket
Notation</A> 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.
<P>
If the <B>-a</B> switch is specified, the header from each FITS
extensions in the file is displayed. Note, however, that the <B>-a</B>
switch does not work with FITS files input via stdin. We hope to
remove this restriction in a future release.
<P>
If the <B>-s</B> switch is specified, only 79 characters are output
before the new-line. This helps the display on 80 character terminals.
<P>
If the <B>-t</B> 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
('u'), FUN_PAR_COMMENT ('c'), FUN_PAR_LOGICAL ('l'), FUN_PAR_INTEGER
('i'), FUN_PAR_STRING ('s'), FUN_PAR_REAL ('r'), FUN_PAR_COMPLEX ('x').
<P>
If the <B>-L</B> (rdb table) switch is used, the output will conform
to starbase/rdb data base list format.
<P>
For example to display the EVENTS extension (binary table):
<PRE>
[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
</PRE>
<P>
To display the third header:
<PRE>
[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
</PRE>
<P>
To display the primary header (i.e., extension 0):
<PRE>
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
</PRE>
<P>
The funhead program also can edit (i.e. add, delete, or modify) 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.
<P>
The edit command file contains parameter comments (having '#' in the
first column) and delete and assignment(modify or add) operations. A
delete operation is specified by preceding the parameter name with a
minus sign "-". A display operation (very useful in interactive
sessions, i.e., where the edit commands are taken from stdin) 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 (but without the comment character that
precedes header params), i.e.:
<UL>
<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.
<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.
</UL>
<P>
For example, the following interactive session checks for the
existence of parameters, adds new parameters, modifies them, and
modifies and deletes existing parameters:
<PRE>
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
</PRE>
<P>
See <A HREF="./text.html">Column-based Text Files</A>
for more information about header parameter format.
<P>
<P>
<!-- =defdoc funhist funhist 1 -->
<!-- =section funhist NAME -->
<H2><A NAME="funhist">funhist - create a 1D histogram of a column (from a FITS binary table or raw event file) or an image</A></H2>
<!-- =section funhist SYNOPSIS -->
<B>
<PRE>
funhist [-n|-w|-T] <iname> [column] [[lo:hi:]bins]
</PRE>
</B>
<!-- =section funhist OPTIONS -->
<P>
<PRE>
-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 (tab separators)
</PRE>
<!-- =section funhist DESCRIPTION -->
<P>
<B>funhist</B> creates a one-dimensional histogram from the specified
columns of a <A HREF="./files.html">FITS Extension</A>
binary table of a FITS file (or from a non-FITS raw event file), 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.
<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
<A HREF="./files.html">Funtools Bracket Notation</A> to specify FITS
extensions, and filters.
<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 (or array), the column is optional: if "x" (or "X"), "y"
(or "Y") is specified, then a projection is performed over the x
(dim1) or y (dim2) axes, respectively. (That is, this projection will
give the same results as a histogram performed on a table containing
the equivalent x,y event rows.) If no column name is specified or
"xy" (or "XY") is specified for the image, then a histogram is
performed on the values contained in the image pixels.
<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 (if these exist
in the table FITS header for the specified column) 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.
(Note that this latter calculation might fail if the image cannot be
fit in memory.) If the data are floating point (table or image) and
the number of bins is not specified, an arbitrary default of 128 is
used.
<P>
For binary table processing, the <B>-w</B> (bin width) switch can be used
to specify the width of each bin rather than the number of bins. Thus:
<PRE>
funhist test.ev pha 1:100:5
</PRE>
means that 5 bins of width 20 are used in the histogram, while:
<PRE>
funhist -w test.ev pha 1:100:5
</PRE>
means that 20 bins of width 5 are used in the histogram.
<P>
The data are divvied up into the specified number of bins and the
resulting 1D histogram (or projection) is output in ASCII table
format. For a table, the output displays the low_edge (inclusive) and
hi_edge (exclusive) 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:
<PRE>
[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
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
</PRE>
<P>
For a table histogram, the <B>-n</B>(normalize) switch can be used to
normalize the bin value by the width of the bin (i.e., hi_edge-lo_edge):
<PRE>
[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 (val/(hi_edge-lo_edge)) 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
</PRE>
This could used, for example, to produce a light curve with values
having units of counts/second instead of counts.
<P>
For an image histogram, the output displays the low and high image
values (both inclusive) 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:
<PRE>
[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
</PRE>
<P>
For the axis projection of an image, the output displays the low and
high image bins (both inclusive) used to generate the projection. For
example, in the following example, 21 counts had their X bin value of
2, etc.:
<PRE>
[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
</PRE>
<P>
You can use gnuplot or other plotting programs to graph the
results, using a script such as:
<PRE>
#!/bin/sh
sed -e '1,/---- .*/d
/^$/,$d' | \
awk '\
BEGIN{print "set nokey; set title \"funhist\"; set xlabel \"bin\"; set ylabel \"counts\"; plot \"-\" with boxes"} \
{print $3, $2, $4-$3}' | \
gnuplot -persist - 1>/dev/null 2>&1
</PRE>
Similar plot commands are supplied in the script <B>funhist.plot</B>:
<PRE>
funhist test.ev pha ... | funhist.plot gnuplot
</PRE>
<!-- =defdoc funimage funimage 1 -->
<!-- =section funimage NAME -->
<H2><A NAME="funimage">funimage - create a FITS image from a Funtools data file</A></H2>
<!-- =section funimage SYNOPSIS -->
<B>
<PRE>
funimage [-a] <iname> <oname> [bitpix=n]
funimage [-l] <iname> <oname> <xcol:xdims> <ycol:ydims> <vcol> [bitpix=n]
funimage [-p x|y] <iname> <oname> [bitpix=n]
</PRE>
</B>
<!-- =section funimage OPTIONS -->
<P>
<PRE>
-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
</PRE>
<!-- =section funimage DESCRIPTION -->
<P>
<B>funimage</B> creates a primary FITS image from the specified
<A HREF="./files.html">FITS Extension</A>
and/or
<A HREF="./files.html#sections">Image Section</A>
of a FITS file, or from an
<A HREF="./files.html#sections">Image Section</A>
of a non-FITS array, or from a raw event file.
<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 <A HREF="./files.html">Funtools
Bracket Notation</A> 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 (or type "int" when binning a table), but this can be
overridden using an optional third argument of the form:
<PRE>
bitpix=n
</PRE>
where n is 8,16,32,-32,-64, for unsigned char, short, int, float and double,
respectively.
<P>
If the input data are of type image, the appropriate section is
extracted and blocked (based on how the
<A HREF="./files.html#sections">Image Section</A> is specified), 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
(possibly of a different size), the pixels are not scaled and the
scaling keywords are retained.
<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 <B>bincols=(x,y)</B> keyword:
<PRE>
funcnts "foo.ev[EVENTS,bincols=(detx,dety)]"
</PRE>
The full form of the <B>bincols=</B> specifier is:
<PRE>
bincols=([xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]]])
</PRE>
where the tlmin, tlmax, and binsiz specifiers determine the image binning
dimensions:
<PRE>
dim = (tlmax - tlmin)/binsiz (floating point data)
dim = (tlmax - tlmin)/binsiz + 1 (integer data)
</PRE>
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
(respectively) 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 <A HREF="./files.html#binning">Binning FITS Binary Tables and Non-FITS
Event Files</A> for more information about binning parameters.
<p>
By default, a new 2D FITS image file is created and the image is written
to the primary HDU. If the <B>-a</B> (append) switch is specified,
the image is appended to an existing FITS file as an IMAGE extension.
(If the output file does not exist, the switch is effectively ignored
and the image is written to the primary HDU.) 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.
<P>
<B>funimage</B> also can take input from a table containing columns of
x, y, and value (e.g., the output from <B>fundisp -l</B> which
displays each image x and y and the number of counts at that
position.) When the <B>-l</B> (list) switch is used, the input file is
taken to be a FITS or ASCII table containing (at least) three columns
that specify the x and y image coordinates and the value of that
image pixel. In this case, <B>funimage</B> requires four extra
arguments: xcolumn:xdims, ycolumn:ydims, vcolumn and bitpix=n. The x
and y col:dim information takes the form:
<PRE>
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
</PRE>
In particular, the min value should be used whenever the
minimum coordinate value is something other than one. For example:
<PRE>
funimage -l foo.lst foo.fits xcol:0:512 ycol:0:512 value bitpix=-32
</PRE>
<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:
<PRE>
funimage -l stdin foo.fits "":0:512 "":0:512 "" bitpix=-32
240 250 1
255 256 2
...
^D
</PRE>
<P>
The list feature provides a simple way to generate a blank image.
If you pass a <A HREF="./text.html">Column-based Text File</A>
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 (called foo.txt):
<PRE>
x:I:1:10 y:I:1:10
------ ------
0 0
</PRE>
This text file defines two columns, x and y, each of data type 32-bit int and
image dimension 10. The command:
<PRE>
funimage foo.txt foo.fits bitpix=8
</PRE>
will create an empty FITS image called foo.fits containing a 10x10
image of unsigned char:
<PRE>
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
</PRE>
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. (You can, of course,
use real x,y values to seed the image with data.)
<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:
<PRE>
funimage stdin'[TEXT(x:I:10,y:I:10)]' foo.fits bitpix=8 < /dev/null
or
funimage /dev/null'[TEXT(x:I:10,y:I:10)]' foo.fits bitpix=8
</PRE>
<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 <B>mask=all</B>
along with the bitpix. For example, the following command will generate a
10x10 char mask using 3 regions:
<PRE>
funimage stdin'[TEXT(x:I:10,y:I:10),cir(5,5,4),point(10,1),-cir(5,5,2)]' \
foo.fits bitpix=8,mask=all < /dev/null
</PRE>
The resulting mask looks like this:
<PRE>
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
</PRE>
<P>
You can use <B>funimage</B> to create 1D image projections along the x
or y axis using the <b>-p [x|y]</b> switch. This capability works for
both images and tables. For example consider a FITS table named ev.fits
containing the following rows:
<PRE>
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
</PRE>
A corresponding 5x5 image, called dim2.fits, would therefore contain:
<PRE>
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
</PRE>
A projection along the y axis can be performed on either the table or
the image:
<PRE>
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
</PRE>
<P>
Furthermore, you can create a 1D image projection along any column of
a table by using the <b>bincols=[column]</b> 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 <b>-p y</b> switch:
<PRE>
funimage ev.fits'[bincols=y]' stdout | fundisp stdin
1 2 3 4 5
---------- ---------- ---------- ---------- ----------
1: 1 2 3 4 5
</PRE>
<P>
Examples:
<P>
Create a FITS image from a FITS binary table:
<PRE>
[sh] funimage test.ev test.fits
</PRE>
<P>
Display the FITS image generated from a blocked section of FITS binary table:
<PRE>
[sh] funimage "test.ev[2:8,3:7,2]" stdout | fundisp stdin
1 2 3
--------- --------- ---------
1: 20 28 36
2: 28 36 44
</PRE>
<!-- =defdoc funindex funindex 1 -->
<!-- =section funindex NAME -->
<H2><A NAME="funindex">funindex - create an index for a column of a FITS binary table</A></H2>
<!-- =section funindex SYNOPSIS -->
<B>
<PRE>
funindex <switches> <iname> <key> [oname]
</PRE>
</B>
<!-- =section funindex OPTIONS -->
<P>
<PRE>
NB: these options are not compatible with Funtools processing. Please
use the defaults instead.
-c # compress output using gzip"
-a # ASCII output, ignore -c (default: FITS table)"
-f # FITS table output (default: FITS table)"
-l # long output, i.e. with key value(s) (default: long)"
-s # short output, i.e. no key value(s) (default: long)"
</PRE>
<!-- =section funindex DESCRIPTION -->
<P>
The funindex script creates an index for the specified column (key) by
running funtable -s (sort) 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.
<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 (key) 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.
<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 (output file name) should not be used for funtools
processing.
<P>
For example, to create an index on column Y for a given FITS file, use:
<PRE>
funindex foo.fits Y
</PRE>
This will generate an index named foo_y.idx, which will be used by funtools
for filters involving the Y column.
<!-- =defdoc funjoin funjoin 1 -->
<!-- =section funjoin NAME -->
<H2><A NAME="funjoin">funjoin - join two or more FITS binary tables on specified columns</A></H2>
<!-- =section funjoin SYNOPSIS -->
<B>
<PRE>
funjoin [switches] <ifile1> <ifile2> ... <ifilen> <ofile>
</PRE>
</B>
<!-- =section funjoin OPTIONS -->
<P>
<PRE>
-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]
</PRE>
<!-- =section funjoin DESCRIPTION -->
<B>funjoin</B> joins rows from two or more (up to 32)
<A HREF="./files.html">FITS Binary Table files</A>, 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
<B>funindex</B> program.
<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.
<P>
NB: Do <B>not</B> use <A HREF="./files.html">Funtools Bracket
Notation</A> 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.
<P>
The join columns are specified using the <B>-j col</B> switch (which
specifies a column name to use for all files) or with <B>-j1 col1</B>,
<B>-j2 col2</B>, ... <B>-jn coln</B> switches (which specify a column
name to use for each file). A join column must be specified for each file.
If both <B>-j col</B> and <B>-jn coln</B> 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:
<PRE>
funjoin -j key in1.fits in2.fits in3.fits out.fits
</PRE>
A different key can be specified for the third file in this way:
<PRE>
funjoin -j key -j3 otherkey in1.fits in2.fits in3.fits out.fits
</PRE>
<P>
The <B>-a "cols"</B> switch (and <B>-a1 "col1"</B>,
<B>-a2 "cols2"</B> counterparts) can be used to specify columns to
activate (i.e. write to the output file) for each input file. By
default, all columns are output.
<P>
If two or more columns from separate files have the same name, the
second (and subsequent) columns are renamed to have an underscore
and a numeric value appended.
<P>
The <B>-m min</B> and <B>-M max</B> switches specify the minimum
and maximum number of joins required to write out a row. The default
minimum is 0 joins (i.e. all rows are written out) and the default maximum
is 63 (the maximum number of possible joins with a limit of 32 input files).
For example, to write out only those rows in which exactly two files
have columns that match (i.e. one join):
<PRE>
funjoin -j key -m 1 -M 1 in1.fits in2.fits in3.fits ... out.fits
</PRE>
<P>
A given row can have the requisite number of joins without all of the
files being joined (e.g. three files are being joined but only two
have a given join key value). In this case, all of the columns of the
non-joined file are written out, by default, using blanks (zeros or NULLs).
The <B>-b c1:bv1,c2:bv2</B> and
<B>-b1 'c1:bv1,c2:bv2' -b2 'c1:bv1,c2:bv2' ...</B>
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 (single or double), a case-insensitive string
value of "nan" means that the IEEE NaN (not-a-number) should be
used. Thus, for example:
<PRE>
funjoin -b "AKEY:???" -b1 "A:-1" -b3 "G:NaN,E:-1,F:-100" ...
</PRE>
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.
<P>
To distinguish which files are non-blank components of a given row,
the <B>-s</B> (status) 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 <B>-S col</B> switch allows you to change the name
of the status column from the default "JFILES".
<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.
<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.
<P>
The <B>-t tol</B> switch specifies a tolerance value for numeric
columns. At present, a tolerance value can join only two files at a
time. (A completely different algorithm is required to join more than
two files using a tolerance, somethng we might consider implementing
in the future.)
<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:
<PRE>
[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
</PRE>
<P>
Given these input files, the following funjoin command:
<PRE>
funjoin -s -a1 "-B" -a2 "-D" -a3 "-E" -b \
"AKEY:???" -b1 "AKEY:XXX,A:255" -b3 "G:NaN,E:-1,F:-100" \
-j key t1.fits t2.fits t3.fits foo.fits
</PRE>
will join the files on the KEY column, outputting all columns except B
(in t1.fits), D (in t2.fits) and E (in t3.fits), and setting blank
values for AKEY (globally, but overridden for t1.fits) and A (in file
1) and G, E, and F (in file 3). A JFILES column will be output to
flag which files were used in each row:
<PRE>
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
</PRE>
<!-- =defdoc funmerge funmerge 1 -->
<!-- =section funmerge NAME -->
<H2><A NAME="funmerge">funmerge - merge one or more Funtools table files</A></H2>
<!-- =section funmerge SYNOPSIS -->
<B>
<PRE>
funmerge [-w|-x] -f [colname] <iname1> <iname2> ... <oname>
</PRE>
</B>
<!-- =section funmerge OPTIONS -->
<P>
<PRE>
-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
</PRE>
<!-- =section funmerge DESCRIPTION -->
<P>
<B>funmerge</B> merges FITS data from one or more
<A HREF="./files.html">FITS Binary Table files</A>
or raw event files.
<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 <A HREF="./files.html">Funtools Bracket
Notation</A> to specify FITS extensions and row filters. Subsequent
arguments specify additional event files and tables to merge. (NB: Stdin
cannot not be used for any of these additional input file arguments.)
The last argument is the output FITS file. The columns in each input table
must be identical.
<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 (as
well as blank lines and/or comment lines starting with the '#' sign).
If standard input is specified as an include file ('@stdin'), then
file names are read from the standard input until EOF (^D). Event
files and include files can be mixed on a command line.
<P>
Rows from each table are written sequentially to the output
file. If the switch <B>-f [colname]</B> 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 (starting from one). In
this case, the corresponding file names are stored in the header
parameters having the prefix <B>FUNFIL</B>, i.e., FUNFIL01,
FUNFIL02, etc.
<P>
Using the <B>-w</B> switch (or <B>-x</B> switch as described
below), <B>funmerge</B> also can adjust the position column values
using the WCS information in each file. (By position columns, we mean
the columns that the table is binned on, i.e., those columns defined
by the <B>bincols=</B> switch, or (X,Y) by default.) 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.
<P>
When performing WCS alignment, you can save the original positions in
the output file by using the <B>-x</B> (for "xtra") switch instead
of the <B>-w</B> switch (i.e., using this switch also implies using
<B>-w</B>) The old positions are saved in columns having the same
name as the original positional columns, with the added prefix "OLD_".
<P>
Examples:
<P>
Merge two tables, and preserve the originating file number for
each row in the column called "FILE" (along with the corresponding
file name in the header):
<PRE>
[sh] funmerge -f "FILE" test.ev test2.ev merge.ev
</PRE>
<P>
Merge two tables with WCS alignment, saving the old position values in
2 additional columns:
<PRE>
[sh] funmerge -x test.ev test2.ev merge.ev
</PRE>
<P>
This program only works on raw event files and binary tables. We have
not yet implemented image and array merging.
<!-- =defdoc funsky funsky 1 -->
<!-- =section funsky NAME -->
<H2><A NAME="funsky">funsky - convert between image and sky coordinates</A></H2>
<!-- =section funsky SYNOPSIS -->
<B>
<PRE>
funsky iname[ext] # RA,Dec (deg) or image pix from stdin
funsky iname[ext] [lname] # RA, Dec (deg) 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
</PRE>
</B>
<!-- =section funsky OPTIONS -->
<P>
<PRE>
-d # always use integer tlmin conversion (as ds9 does)
-r # convert x,y to RA,Dec (default: convert RA,Dec to x,y)
-o # include offset from the nominal target position (in arcsec)
-v # display input values also (default: display output only)
-T # output display in rdb format (w/header,tab delimiters)
</PRE>
<!-- =section funsky DESCRIPTION -->
<P>
Funsky converts input sky coordinates (RA, Dec) to image coordinates (or vice
versa) 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.
<P>
The first required argument is always the input FITS file (or
extension) 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 <B>-r</B> (reverse) switch.
<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 (or X in
pixels) followed by a Dec in degrees (or Y in pixels). The usual
delimiters are supported (spaces, commas, tabs). For example:
<PRE>
# read from stdin, default column names and units
[sh] funsky snr.ev
22.982695 58.606523 # input RA (hrs), Dec(deg)
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
</PRE>
<p>
If a second argument is supplied, this argument is assumed to be
a file containing RA (X) and Dec (Y) 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 (X) is assumed to first, followed
by DEC (Y).
For example:
<PRE>
# 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
</PRE>
<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 (or X in pixels) followed by a
Dec (or Y in pixels), 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:
<PRE>
[colname]:[h|d|r]
</PRE>
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 (convert from image
to sky) the units are applied to the output instead of the input. The following
examples will serve to illustrate the options:
<PRE>
# read from stdin, specifying column names (def. units: degrees)
[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
[sh] cat im.in | funsky -r snr.ev :d :d
344.740432 58.606523
344.731900 58.607634
344.725500 58.614301
</PRE>
<P>
Finally, four command arguments specify both and input file and column names
and/or units:
<PRE>
[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
</PRE>
<P>
By default, the output of funsky consists only of the converted coordinate
position(s), one per output line. This makes parsing in shell scripts easy.
Use the <B>-v</B> (verbose) switch to specify that the input
coordinates should be pre-pended to each line. For example:
<PRE>
[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
</PRE>
<P>
In addition, a full starbase table can be output using the <B>-T</B>
(table) 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 (mainly to remind you of the
sky units):
<PRE>
# 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
</PRE>
<P>
Finally, the <B>-d</B> (ds9) 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.
<!-- =defdoc funtable funtable 1 -->
<!-- =section funtable NAME -->
<H2><A NAME="funtable">funtable - copy selected rows from a Funtools file to a FITS binary table</A></H2>
<!-- =section funtable SYNOPSIS -->
<B>
<PRE>
funtable [-a] [-i|-z] [-m] [-s cols] <iname> <oname> [columns]
</PRE>
</B>
<!-- =section funtable OPTIONS -->
<P>
<PRE>
-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
</PRE>
<!-- =section funtable DESCRIPTION -->
<P>
<B>funtable</B> selects rows from the specified
<A HREF="./files.html">FITS Extension</A>
(binary table only) 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.
<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 <A HREF="./files.html">Funtools Bracket
Notation</A> 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:
<PRE>
"column1 column1 ... columnN"
</PRE>
<P>
The <B>funtable</B> program generally is used to select rows from a
FITS binary table using
<A HREF="./filters.html">Table Filters</A>
and/or
<A HREF="./regions.html">Spatial Region Filters</A>.
For example, you can copy only selected rows (and output only selected
columns) by executing in a command such as:
<PRE>
[sh] funtable "test.ev[pha==1&&pi==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
</PRE>
<P>
The special column <B>$REGION</B> can be specified to write the
region id of each row:
<PRE>
[sh $] funtable "test.ev[time-(int)time>=.99&&annulus(0 0 0 10 n=3)]" 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
</PRE>
<P>
Here only rows with the proper fractional time and whose position also is
within one of the three annuli are written.
<P>
Columns can be excluded from display using a minus sign before the
column:
<PRE>
[sh $] funtable "test.ev[time-(int)time>=.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
</PRE>
All columns except the time column are written.
<P>
In general, the rules for activating and de-activating columns are:
<UL>
<LI> If only exclude columns are specified, then all columns but
the exclude columns will be activated.
<LI> If only include columns are specified, then only the specified columns
are activated.
<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.
</UL>
In addition to specifying columns names explicitly, the special
symbols <EM>+</EM> and <EM>-</EM> can be used to activate and
de-activate <EM>all</EM> 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.
<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:
<PRE>
[sh] funtable "/proj/rd/data/snr.ev[EVENTS]" events.ev
[sh] funtable "/proj/rd/data/snr.ev[EVENTS+]" eventsandmore.ev
</PRE>
<P>
If the input file is an image or a raw array file, then
<B>funtable</B> 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 (using command-line argument 3). 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 (event) 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
<B>funhist</B> on the "VALUE" column will give the same results as
running <B>funhist</B> on the original image.
<P>
If the <B>-i</B> ("individual" rows) 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 (events), where n is equal
to the integerized value of that pixel (plus 0.5, for floating point
data). In effect, <B>-i</B> approximately recreates the rows of a
table that would have been binned into the input image. (Of course,
this is only approximately correct, since the resulting x,y positions
are integerized.)
<P>
If the <B>-s [col1 col2 ... coln]</B> ("sort") 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 (i.e. you cannot sort on a
column but not include it in the output). This facility uses the
<B>_sort</B> program (included with funtools), which must be accessible
via your path.
<p>
For binary tables, the <B>-m</B> ("multiple files") 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.
<P>
The separate output file names generated by the <B>-m</B> switch are
produced automatically from the root output file to contain the region id of
the associated region. (Note 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.) Output file names are generated as follows:
<UL>
<LI> A $n specification can be used anywhere in the root file name (suitably
quoted to protect it from the shell) and will be expanded to be the id
number of the associated region. For example:
<PRE>
funtable -m input.fits'[cir(512,512,1);cir(520,520,1)...]' 'foo.goo_$n.fits'
</PRE>
will generate files named foo.goo_0.fits (for rows not in any region but
still passing the filter), foo.goo_1.fits (rows in region id #1, the first
region), foo.goo_2.fits (rows in region id #2), etc. Note that single quotes
in the output root are required to protect the '$' from the shell.
<LI> If $n is not specified, then the region id will be placed before
the first dot (.) in the filename. Thus:
<PRE>
funtable -m input.fits'[cir(512,512,1);cir(520,520,1)...]' foo.evt.fits
</PRE>
will generate files named foo0.evt.fits (for rows not in any region but
still passing the filter), foo1.evt.fits (rows in region id #1),
foo2.evt.fits (rows in region id #2), etc.
<LI> If no dot is specified in the root output file name, then
the region id will be appended to the filename. Thus:
<PRE>
funtable -m input.fits'[cir(512,512,1);cir(520,520,1)...]' 'foo_evt'
</PRE>
will generate files named foo_evt0 (for rows not in any region but
still passing the filter), foo_evt1 (rows in region id #1),
foo_evt2 (rows in region id #2), etc.
</UL>
The multiple file mechanism provide a simple way to generate
individual source data files with a single pass through the data.
<p>
By default, a new FITS file is created and the binary table is written
to the first extension. If the <B>-a</B> (append) 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.
<P>
If the <B>-z</B> ("zero" pixel values) switch is specified and
<B>-i</B> 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.
<!-- =defdoc funtbl funtbl 1 -->
<!-- =section funtbl NAME -->
<H2><A NAME="funtbl">funtbl - extract a table from Funtools ASCII output</A></H2>
<!-- =section funtbl SYNOPSIS -->
<B>
<PRE>
funtable [-c cols] [-h] [-n table] [-p prog] [-s sep] <iname>
</PRE>
</B>
<!-- =section funtbl DESCRIPTION -->
<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 (specifying the table using bracket notation) to extract tables
and columns.]
The <B>funtbl</B> script extracts a specified table (without the
header and comments) 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 (i.e. the saved output from funcnts, fundisp,
funhist, etc.). If no filename is specified, stdin is read. The
-n switch specifies which table (starting from 1) 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 (which is host-specific and is determined at
build time). The -T switch will output the data in rdb format (i.e.,
with a 2-row header of column names and dashes, and with data columns
separated by tabs). The -help switch will print out a message
describing program usage.
<P>
For example, consider the output from the following funcnts command:
<PRE>
[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(s)
----------------
ann 512 512 0 9 n=3
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
</PRE>
<P>
There are four tables in this output. To extract the last one, you
can execute:
<PRE>
[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
</PRE>
Note that the output has been re-formatted so that only a single space
separates each column, with no extraneous header or comment information.
<P>
To extract only columns 1,2, and 4 from the last example (but with a header
prepended and tabs between columns), you can execute:
<PRE>
[sh] funcnts -s snr.ev "ann 512 512 0 9 n=3" | funtbl -c "1 2 4" -h -n 4 -s "\t"
#reg counts sumcnts
1 147.000 147.000
2 478.000 625.000
3 817.000 1442.000
</PRE>
<P>
Of course, if the output has previously been saved in a file named
foo.out, the same result can be obtained by executing:
<PRE>
[sh] funtbl -c "1 2 4" -h -n 4 -s "\t" foo.out
#reg counts sumcnts
1 147.000 147.000
2 478.000 625.000
3 817.000 1442.000
</PRE>
<!-- =section funcalc SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section funcen SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section funcnts SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section funcone SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section fundisp SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section funhead SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section funhist SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section funimage SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section funindex SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section funjoin SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section funmerge SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section funsky SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section funtable SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =section funtbl SEE ALSO -->
<!-- =text See funtools(n) for a list of Funtools help pages -->
<!-- =stop -->
<P>
<A HREF="./help.html">Go to Funtools Help Index</A>
<H5>Last updated: April 1, 2007</H5>
</BODY>
</HTML>
|