srcflux

Synopsis

Calculate the net count rates and fluxes, including uncertainties, of sources in a Chandra observation.

srcflux  infile pos outroot [bands] [regions] [srcreg] [bkgreg]
[bkgresp] [psfmethod] [psffile] [conf] [binsize] [rmffile] [arffile]
[model] [paramvals] [absmodel] [absparams] [abund] [pluginfile]
[fovfile] [asolfile] [mskfile] [bpixfile] [dtffile] [ecffile]
[marx_root] [parallel] [nproc] [tmpdir] [random_seed] [clobber]
[verbose]

Description

Calculate the net count rate, and flux, for sources in a Chandra observation given source and background regions. The count rate is calculated using the aprates tool, and so can account for the PSF contribution to both the source and background regions, for point sources. The flux is estimated in three ways:

• a model-independent estimate, using the eff2evt tool,
• a model dependent estimate, using the modelflux script to calculate the conversion factor for a given spectral model (for this stage ARFs and RMFs will be created for each source).
• and in photon units by using the fluximage tool to create exposure an corrected image.

The results are written to one or more output files, with one row per source, and one file for each energy band. With verbose>0, the results are also printed to the screen.

Specifying a source location

The simplest option is to just specify the location of the sources, with no source or background regions; that is set the pos argument but not the srcreg and bkgreg ones. By default in this case a circle is used for each source, centered on each source, and the radius is the size of a circle needed to enclose 90% of the PSF at 1.0keV.

Using source and background regions

If the srcreg and bkgreg parameters are given then they are used to calculate the source and background counts. In this mode, the pos parameter must still be specified since it is used to get the PSF fraction correction.

Estimating the PSF contribution

The PSF contribution to both the source and background regions can be estimated using one of five methods, controlled by the psfmethod argument. Extended sources should use psfmethod=ideal, which makes no correction, or psfmethod=psffile and provide an image of the surfrace brightness as the psffile parameter. The other options are discussed below in the psfmethod parameter and the "PSF Correction" section.

A fully Bayesian computation

This tool is based on the aprates tool, which performs a fully Bayesian computation, thus the result is a credible interval (confidence interval for the frequentist calculation), which is CONF parameter.

Upper limits vs. upper value for flux uncertainty

The tool does not return upper limits and that the reported values are always calculated for the lower and upper confidence bound. The upper limit calculation requires a detection threshold which does not dependent on the number of counts or the source flux. The detection threshold is not used in this tool. See Kashyap et al 2010, for full discussion of the difference between confidence bounds and upper limits.

Examples

Example 1

unix% punlearn srcflux
unix% srcflux acisf00635_repro_evt2.fits "16:27:33.115 -24:41:15.51"
rhooph

The simplest usage of srcflux is to provide an event list, a position, and an output root file name. Since the default is verbose=1, the following output is generated

srcflux
          infile = acisf00635_repro_evt2.fits
             pos = 16:27:33.115 -24:41:15.51
         outroot = rhooph
           bands = default
          srcreg =
          bkgreg =
         bkgresp = yes
       psfmethod = ideal
         psffile =
            conf = 0.9
         binsize = 1
         rmffile =
         arffile =
           model = xsphabs.abs1*xspowerlaw.pow1
       paramvals = abs1.nH=0.0;pow1.PhoIndex=2.0
        absmodel =
       absparams =
           abund = angr
         fovfile =
        asolfile =
         mskfile =
        bpixfile =
         dtffile =
         ecffile = CALDB
        parallel = yes
           nproc = INDEF
          tmpdir = /tmp
         clobber = no
         verbose = 1
            mode = ql

Extracting counts
Setting Ideal PSF : alpha=1 , beta=0
Getting net rate and confidence limits
Getting model independent fluxes
Getting model fluxes
Getting photon fluxes
Running tasks in parallel with 4 processors.
Running eff2evt for rhooph_broad_0001_src.dat
Running aprates for rhooph_broad0001_rates.par
Running eff2evt for rhooph_broad_0001_bkg.dat
Making response files for rhooph_0001
Running modeflux for region 1
Adding net rates to output
Appending flux results onto output
Appending photflux results onto output
Computing Net fluxes
Adding model fluxes to output
Scaling model flux confidence limits


Summary of source fluxes

Position                               0.5 - 7.0 keV
                                       Value        90% Conf Interval
16 27 33.11 -24 41 15.5 Rate           0.0263 c/s (0.0255,0.0272)
                        Flux           3.6E-13 erg/cm2/s (3.49E-13,3.72E-13)
                        Mod.Flux       2.73E-13 erg/cm2/s (2.65E-13,2.82E-13)

Since source and background regions are not supplied, the script by default creates a circular region that encloses 90% of the PSF at 1.0 keV.

unix% dmlist rhooph_broad.flux"[cols shape,x,y,r]" data,clean
#  SHAPE              sky(X,Y)                                 R[2]
 Circle                               3676.130      3260.330            14.35720                    0

which for this source in this observation is a circle with a 14.4 pixel radius.

The default is psfmethod=ideal, so the source region PSF fraction is assumed to be 100% and the background is assumed to have 0% of the source PSF.

unix% dmlist rhooph_broad.flux"[cols psffrac,bg_psffrac]" data,clean
#  PSFFRAC              BG_PSFFRAC
                  1.0                    0

The default energy band the Chandra Source Catalog broad band which goes from 0.5 to 7.0 keV.

The values and the 90% credible interval are also printed to the screen as shown above.

Example 2

% srcflux acisf00635_repro_evt2.fits "16:27:33.115 -24:41:15.51" rhooph
psfmethod=quick clobber=yes

Same as above but now we make use of the quick PSF method that uses the characteristic energy of the band to look up the PSF fraction. In this example the characteristic energy of the CSC broad band is 2.3keV.

...
Summary of source fluxes

Position                               0.5 - 7.0 keV
                                       Value        90% Conf Interval
16 27 33.11 -24 41 15.5 Rate           0.0302 c/s (0.0293,0.0312)
                        Flux           4.14E-13 erg/cm2/s (4.01E-13,4.28E-13)
                        Mod.Flux       3.14E-13 erg/cm2/s (3.04E-13,3.24E-13)


unix% dmlist rhooph_broad.flux"[cols psffrac,bg_psffrac]" data,clean
#  PSFFRAC              BG_PSFFRAC
     0.86991358226167                    0

Since the PSF fraction is better estimated we end up with a slightly higher RATEs.

The value of 87% should not be too surprising. Since we did not provide a region, one was created that enclosed 90% of the PSF at 1.0keV. The PSF is more broad at this higher energy, 2.3keV, so the PSF fraction is a little less.

Example 3

unix% srcflux acisf00635_repro_evt2.fits "16:27:33.115 -24:41:15.51"
rhooph psfmethod=arfcorr clob+

We repeat the above example again, now using the arfcorr tool to generate a circularly symmetric model of the PSF and compute the PSF fractions from it.

Position                               0.5 - 7.0 keV
                                       Value        90% Conf Interval
16 27 33.11 -24 41 15.5 Rate           0.0304 c/s (0.0295,0.0314)
                        Flux           4.76E-13 erg/cm2/s (4.61E-13,4.92E-13)
                        Mod.Flux       3.16E-13 erg/cm2/s (3.06E-13,3.26E-13)



unix% dmlist rhooph_broad.flux"[cols psffrac,bg_psffrac]" data,clean
#  PSFFRAC              BG_PSFFRAC
     0.86952022197560     0.11286898252867

The source PSF fraction is about the same, which is expected given that the same calibration is used to make the region size and the PSF correction. However, now the background PSF fraction is better estimated to be about 11%. Given how bright this source is the background contribution is not significant so it barely affects the value or credible interval.

Example 4

unix% srcflux acisf00635_repro_evt2.fits "16:27:33.115 -24:41:15.51"
rhooph psfmethod=psffile
psffile=CXOJ162733.1-244115/acisf00635_000N001_r0002b_psf3.fits.gz clob+

We repeat this example one last time using psfmethod=psffile and providing an image of the PSF taken from the Chandra Source Catalog for this source, CXOJ162733.1-244115.

Position                               0.5 - 7.0 keV
                                       Value        90% Conf Interval
16 27 33.11 -24 41 15.5 Rate           0.0286 c/s (0.0276,0.0295)
                        Flux           4.18E-13 erg/cm2/s (4.04E-13,4.31E-13)
                        Mod.Flux       2.97E-13 erg/cm2/s (2.87E-13,3.06E-13)

unix% dmlist rhooph_broad.flux"[cols psffrac,bg_psffrac,theta]" data,clean
#  PSFFRAC              BG_PSFFRAC           THETA
     0.92381309814224     0.06098705197973         7.6742977885

The source and background PSF fractions are now computed from the broad band PSF image that was input via the psffile parameter. The results are somewhat different than before. A visual inspection of the PSF shows it to be highly elliptical so the circular approximations made earlier were biasing the results. We can also do a quick analysis of the PSF to show that it is quite elliptical:

unix% dmellipse CXOJ162733.1-244115/acisf00635_000N001_r0002b_psf3.fits.gz psf_ellipse.fits 0.9
unix% dmlist psf_ellipse.fits"[cols shape,r,rotang]" data,clean
#  shape                            r[2]                                     rotang
 ellipse                                 16.1637725830         9.5770123050        23.2332704673

Example 5

unix% srcflux acisf00635_repro_evt2.fits "16:27:33.115 -24:41:15.51"
rhooph \
regions=optimized psfmethod=marx

        ...
Summary of source fluxes

      Position                               0.5 - 7.0 keV                           
                                             Value        90% Conf Interval          
#0001|16 27 33.11 -24 41 15.5 Rate           0.0281 c/s (0.0271,0.0291)              
                              Flux           3.83E-13 erg/cm2/s (3.7E-13,3.97E-13)   
                              Mod.Flux       3.07E-13 erg/cm2/s (2.96E-13,3.18E-13)  

        

This is the similar to the first example but now using the optimized regions option and using MARX to estimate the PSF fraction.

We can see that the source region is now a polygon (in this example with 98 sides)

unix% dmmakereg region="region(rhooph_0001_srcreg.fits)" out=- ker=ascii 
# Region file format: DS9 version 4.1
global color=blue dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
physical
Polygon(3671,3251.34,3670,3251.14,3669,3251.08,3668,3251.35,3667,
3251.74,3666.65,3252,3666,3252.84,3665.87,3253,3665,3253.52,3664.4,
3254,3664,3254.5,3663.65,3255,3663.33,3256,3663.41,3257,3663.38,
3258,3663.02,3259,3663.08,3260,3663.28,3261,3664,3261.99,3664.01,
3262,3665,3262.8,3665.24,3263,3665.07,3264,3665.5,3265,3666,3265.79,
3666.17,3266,3667,3266.82,3667.3,3267,3668,3267.32,3669,3267.01,
3669.04,3267,3670,3266.84,3670.22,3267,3670.25,3268,3670.96,3269,
3671,3269.02,3672,3269.41,3673,3269.68,3674,3269.8,3675,3269.69,
3676,3269.23,3676.86,3270,3677,3270.1,3678,3270.48,3679,3270.5,
3680,3270.47,3681,3270.21,3681.71,3270,3682,3269.94,3682.46,3270,
3683,3270.08,3684,3270.01,3684.02,3270,3685,3269.77,3686,3269,
3686,3269,3687,3268.41,3687.87,3268,3688,3267.92,3688.71,3267,
3688.82,3266,3688.89,3265,3689,3264.81,3689.67,3264,3689.87,3263,
3689.79,3262,3689.42,3261,3689,3260.31,3688.64,3260,3688.24,3259,
3688.35,3258,3688,3257.19,3687.89,3257,3687,3256.06,3686.92,3256,
3686,3255.46,3685,3255.28,3684,3255.25,3683,3255.01,3682.99,3255,
3683,3254,3682.16,3253,3682,3252.91,3681,3252.56,3680,3252.01,
3679.98,3252,3679,3251.79,3678.24,3252,3678,3252.06,3677,3252.3,
3676.69,3252,3676,3251.2,3675.66,3251,3675,3250.71,3674,3250.58,
3673,3250.52,3672,3250.73,3671.56,3251,3671,3251.34) #

And that the background region is an annulus excluding the source polygon

unix% dmmakereg region="region(/pool1/kjg/rhooph_0001_bkgreg.fits)" out=- ker=ascii
# Region file format: DS9 version 4.1
global color=blue dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
physical
Annulus(3676.13,3260.33,16.5786,18.6114) #
-Polygon(3671,3251.34,3670,3251.14,3669,3251.08,3668,3251.35,3667,
3251.74,3666.65,3252,3666,3252.84,3665.87,3253,3665,3253.52,3664.4,
3254,3664,3254.5,3663.65,3255,3663.33,3256,3663.41,3257,3663.38,
3258,3663.02,3259,3663.08,3260,3663.28,3261,3664,3261.99,3664.01,
3262,3665,3262.8,3665.24,3263,3665.07,3264,3665.5,3265,3666,3265.79,
3666.17,3266,3667,3266.82,3667.3,3267,3668,3267.32,3669,3267.01,
3669.04,3267,3670,3266.84,3670.22,3267,3670.25,3268,3670.96,3269,
3671,3269.02,3672,3269.41,3673,3269.68,3674,3269.8,3675,3269.69,
3676,3269.23,3676.86,3270,3677,3270.1,3678,3270.48,3679,3270.5,
3680,3270.47,3681,3270.21,3681.71,3270,3682,3269.94,3682.46,3270,
3683,3270.08,3684,3270.01,3684.02,3270,3685,3269.77,3686,3269,
3686,3269,3687,3268.41,3687.87,3268,3688,3267.92,3688.71,3267,
3688.82,3266,3688.89,3265,3689,3264.81,3689.67,3264,3689.87,3263,
3689.79,3262,3689.42,3261,3689,3260.31,3688.64,3260,3688.24,3259,
3688.35,3258,3688,3257.19,3687.89,3257,3687,3256.06,3686.92,3256,
3686,3255.46,3685,3255.28,3684,3255.25,3683,3255.01,3682.99,3255,
3683,3254,3682.16,3253,3682,3252.91,3681,3252.56,3680,3252.01,
3679.98,3252,3679,3251.79,3678.24,3252,3678,3252.06,3677,3252.3,
3676.69,3252,3676,3251.2,3675.66,3251,3675,3250.71,3674,3250.58,
3673,3250.52,3672,3250.73,3671.56,3251,3671,3251.34) #

and the background encloses 50 counts because we are using the same broad energy band (0.5-7.0keV).

unix% dmlist rhooph_broad.flux"[cols bg_counts,psffrac]" data,clean
#  BG_COUNTS            PSFFRAC
                 50.0     0.87110247430974

The PSF fraction is estimated from the PSF simulated at the broad band monochromatic energy, 2.3keV, which results in a value slightly less than the 90% ECF value used to generate the region at the lower 1.0keV; the PSF is larger at higher energies.

Example 6

unix% roi infile=psf_ellipse.fits outsrc=psf_region bkgradius=5 clob+
mode=h
unix% punlearn srcflux
unix% pset srcflux psfmethod=psffile clob+
unix% pset srcflux
psffile=CXOJ162733.1-244115/acisf00635_000N001_r0002b_psf3.fits.gz
unix% pset srcflux srcreg="psf_region[srcreg]"
unix% pset srcflux bkgreg="psf_region[bkgreg]"
unix% srcflux acisf00635_repro_evt2.fits "16:27:33.115 -24:41:15.51"
rhooph

In the previous example we found an ellipse that encloses 90% of the broad band PSF. We can use that as in input source region instead of the circular 90% source region at 1.0keV. However, we also need a background region so first we run the roi tool to scale the source ellipse.

Position                               0.5 - 7.0 keV
                                       Value        90% Conf Interval
16 27 33.11 -24 41 15.5 Rate           0.0285 c/s (0.0275,0.0294)
                        Flux           4.32E-13 erg/cm2/s (4.18E-13,4.46E-13)
                        Mod.Flux       2.96E-13 erg/cm2/s (2.86E-13,3.05E-13)

We see that we get consistent results with above which makes sense. As long at the PSF corrections are happening correctly, the shape and size of the region will not drastically change the results, just possibly the credible interval.

Example 7

unix% punlearn srcflux
unix% srcflux acisf00635_repro_evt2.fits '635_catalog.tsv[opt
kernel=text/tsv][significance=5:6]' rhooph bands=0.3:7.0:1.9 clob+

We can also input a file with a list of RA and Dec. values and the script will compute the NET rates and fluxes for each source. In this example we input a Tab-Separated-Value table (for example retrieved from the Chandra Source Catalog) and have filtered it include sources with a significance between 5 and 6. We have also chosen a custom energy range going from 0.3 to 7.0 keV. The screen output will now look like this:

srcflux
          infile = acisf00635_repro_evt2.fits
             pos = 635_catalog.tsv[opt kernel=text/tsv][significance=5:6]
         outroot = rhooph
           bands = 0.3:7.0:1.9
          srcreg =
          bkgreg =
         bkgresp = yes
       psfmethod = ideal
         psffile =
            conf = 0.9
         binsize = 1
         rmffile =
         arffile =
           model = xsphabs.abs1*xspowerlaw.pow1
       paramvals = abs1.nH=0.0;pow1.PhoIndex=2.0
        absmodel =
       absparams =
           abund = angr
         fovfile =
        asolfile =
         mskfile =
        bpixfile =
         dtffile =
         ecffile = CALDB
        parallel = yes
           nproc = INDEF
          tmpdir = /tmp
         clobber = yes
         verbose = 1
            mode = ql

Extracting counts
Setting Ideal PSF : alpha=1 , beta=0
Getting net rate and confidence limits
Getting model independent fluxes
Getting model fluxes
Getting photon fluxes
Running tasks in parallel with 4 processors.
Making response files for rhooph_0004
Running eff2evt for rhooph_0.3-7.0_0004_src.dat
Running eff2evt for rhooph_0.3-7.0_0005_src.dat
Making response files for rhooph_0005
Running eff2evt for rhooph_0.3-7.0_0003_src.dat
Running eff2evt for rhooph_0.3-7.0_0005_bkg.dat
Running modeflux for region 4
Running modeflux for region 5
Making response files for rhooph_0001
Running aprates for rhooph_0.3-7.00004_rates.par
Running aprates for rhooph_0.3-7.00003_rates.par
Running aprates for rhooph_0.3-7.00002_rates.par
Running aprates for rhooph_0.3-7.00001_rates.par
Running eff2evt for rhooph_0.3-7.0_0002_src.dat
Running aprates for rhooph_0.3-7.00005_rates.par
Making response files for rhooph_0003
Running eff2evt for rhooph_0.3-7.0_0001_src.dat
Running eff2evt for rhooph_0.3-7.0_0003_bkg.dat
Running modeflux for region 1
Running modeflux for region 3
Running eff2evt for rhooph_0.3-7.0_0001_bkg.dat
Making response files for rhooph_0002
Running eff2evt for rhooph_0.3-7.0_0002_bkg.dat
Running eff2evt for rhooph_0.3-7.0_0004_bkg.dat
Running modeflux for region 2
Adding net rates to output
Appending flux results onto output
Appending photflux results onto output
Computing Net fluxes
Adding model fluxes to output
Scaling model flux confidence limits


Summary of source fluxes

Position                               0.3 - 7.0 keV
                                       Value        90% Conf Interval
16 26 48.92 -24 38 23.8 Rate           0.000319 c/s (0.000219,0.000436)
                        Flux           2.65E-15 erg/cm2/s (1.82E-15,3.62E-15)
                        Mod.Flux       3.47E-15 erg/cm2/s (2.39E-15,4.75E-15)

16 26 57.34 -24 35 38.8 Rate           0.000308 c/s (0.000221,0.000413)
                        Flux           5.86E-15 erg/cm2/s (4.2E-15,7.85E-15)
                        Mod.Flux       3.07E-15 erg/cm2/s (2.2E-15,4.12E-15)

16 26 59.06 -24 35 57.3 Rate           0.000328 c/s (0.00024,0.000435)
                        Flux           2.93E-15 erg/cm2/s (2.14E-15,3.88E-15)
                        Mod.Flux       3.77E-15 erg/cm2/s (2.76E-15,5E-15)

16 27 5.22 -24 41 12.2  Rate           0.000393 c/s (0.000286,0.000517)
                        Flux           1.06E-14 erg/cm2/s (7.68E-15,1.39E-14)
                        Mod.Flux       4.28E-15 erg/cm2/s (3.12E-15,5.63E-15)

16 27 15.54 -24 33 1.8  Rate           0.000295 c/s (0.000214,0.000394)
                        Flux           5.81E-15 erg/cm2/s (4.21E-15,7.76E-15)
                        Mod.Flux       3.94E-15 erg/cm2/s (2.86E-15,5.27E-15)

Note: The processing will happen in a random order on a machine with multiple CPU cores. Since we chose a custom energy range, the output file name is now 'rhooph_0.3-7.0.flux'.

Example 8

unix% punlearn srcflux
unix% pset srcflux bands=csc conf=0.68 clob+
unix% pset srcflux model=xspowerlaw.pow1 absmodel=xsphabs.abs1
unix% pset srcflux paramvals="pow1.PhoIndex=1.0"
unix% pset srcflux absparam="abs1.nH=1.0"
unix% srcflux acisf00635_repro_evt2.fits '635_catalog.tsv[opt
kernel=text/tsv][significance=6:6.5]' rhooph

In this example we change the limits of the credible interval to be 1sigma (68%), run multiple energy bands (bands=csc will run the soft, medium, and hard bands) and setup the model to give us both observed and unabsorbed fluxes.

Summary of source fluxes

Position                               0.5 - 1.2 keV                           1.2 - 2.0 keV                           2.0 - 7.0 keV
                                       Value        68% Conf Interval          Value        68% Conf Interval          Value        68% Conf Interval
16 26 48.44 -24 28 37.1 Rate           0 c/s (NAN,2.44E-05)                    6.72E-05 c/s (4.02E-05,0.000101)        0.000467 c/s (0.000394,0.000546)
                        Flux           8.31E-17 erg/cm2/s (NAN,8.31E-17)       4.97E-16 erg/cm2/s (2.97E-16,7.45E-16)  9.12E-15 erg/cm2/s (7.69E-15,1.07E-14)
                        Mod.Flux       0 erg/cm2/s (NAN,1.12E-16)              4.38E-16 erg/cm2/s (2.62E-16,6.58E-16)  1.28E-14 erg/cm2/s (1.08E-14,1.5E-14)
                        Unabs Mod.Flux 0 erg/cm2/s (NAN,2.08E-15)              9.79E-16 erg/cm2/s (5.85E-16,1.47E-15)  1.4E-14 erg/cm2/s (1.18E-14,1.64E-14)

16 27 41.46 -24 35 37.8 Rate           0 c/s (NAN,1.13E-05)                    0.000222 c/s (0.000177,0.000273)        0.000202 c/s (0.000157,0.000253)
                        Flux           NAN erg/cm2/s (NAN,NAN)                 1.21E-15 erg/cm2/s (9.69E-16,1.49E-15)  3.39E-15 erg/cm2/s (2.64E-15,4.25E-15)
                        Mod.Flux       0 erg/cm2/s (NAN,5.02E-17)              1.45E-15 erg/cm2/s (1.16E-15,1.79E-15)  5.49E-15 erg/cm2/s (4.28E-15,6.88E-15)
                        Unabs Mod.Flux 0 erg/cm2/s (NAN,9.34E-16)              3.24E-15 erg/cm2/s (2.6E-15,3.99E-15)   6E-15 erg/cm2/s (4.68E-15,7.52E-15)

We also see an example where the lower limit for the soft band rate and fluxes is compatible with 0 and only the upper bound of the range is given.

Example 9

unix% pset srcflux absparam="abs1.nH=%GAL%"
unix% srcflux acisf00635_repro_evt2.fits '635_catalog.tsv[opt
kernel=text/tsv][significance=6:6.5]' rhooph2

This repeats the previous example, but instead of using a fixed column density for the absorbing model (i.e. the same value for all sources), it calculates individual column densities for each source, using the prop_colden tool and the NRAO catalog.

Example 10

unix% srcflux acisf00635_repro_evt2.fits "16:27:33.115 -24:41:15.51"
rhooph arffile=my.arf rmffile=my.rmf

If an ARF and RMF for the source are already available, they can be input via the arffile and rmffile, respectively. When these are specified, specextract is not run so source and background spectra are not extracted.

Important: The input ARF must not have already been corrected for the PSF fraction, OR the psfmethod should be set to "ideal". This will ensure that the PSF fraction will not be doubly applied to the model flux outputs.

Example 11

unix% srcflux
"17244/repro/acisf17244_repro_evt2.fits,18681/repro/acisf18681_repro_evt
2.fits" \
pos="9:42:32.2119,+12:20:51.349" psfmethod=quick
out=merge_17244_18681/out

This example shows how to combine the photometry for multiple observations.

srcflux
          infile = 17244/repro/acisf17244_repro_evt2.fits,18681/repro/acisf18681_repro_evt2.fits
             pos = 9:42:32.2119,+12:20:51.349
         outroot = merge_17244_18681/out
           bands = default
          srcreg =
          bkgreg =
         bkgresp = yes
       psfmethod = quick
         psffile =
            conf = 0.9
         binsize = 1
         rmffile =
         arffile =
           model = xspowerlaw.pow1
       paramvals = pow1.PhoIndex=2.0
        absmodel = xsphabs.abs1
       absparams = abs1.nH=%GAL%
           abund = angr
         fovfile =
        asolfile =
         mskfile =
        bpixfile =
         dtffile =
         ecffile = CALDB
        parallel = yes
           nproc = INDEF
          tmpdir = /tmp
     random_seed = -1
         clobber = yes
         verbose = 1
            mode = ql

Processing OBI 001
Extracting counts
Getting net rate and confidence limits
Getting model independent fluxes
Getting model fluxes
Getting photon fluxes
Running tasks in parallel with 4 processors.
Running aprates for merge_17244_18681/out_obi001_0001_broad_rates.par
Running eff2evt for merge_17244_18681/out_obi001_broad_0001_src.dat
Running eff2evt for merge_17244_18681/out_obi001_broad_0001_bkg.dat
Making response files for merge_17244_18681/out_obi001_0001
Running modeflux for region 1
Using GAL=0.032 for source 1
Adding net rates to output
Appending flux results onto output
Appending photflux results onto output
Computing Net fluxes
Adding model fluxes to output
Scaling model flux confidence limits
Processing OBI 002
Extracting counts
Getting net rate and confidence limits
Getting model independent fluxes
Getting model fluxes
Getting photon fluxes
Running tasks in parallel with 4 processors.
Running aprates for merge_17244_18681/out_obi002_0001_broad_rates.par
Running eff2evt for merge_17244_18681/out_obi002_broad_0001_src.dat
Running eff2evt for merge_17244_18681/out_obi002_broad_0001_bkg.dat
Making response files for merge_17244_18681/out_obi002_0001
Running modeflux for region 1
Using GAL=0.032 for source 1
Adding net rates to output
Appending flux results onto output
Appending photflux results onto output
Computing Net fluxes
Adding model fluxes to output
Scaling model flux confidence limits
Combining count rates
Combining spectra and running model flux for each source
Running modeflux for region 1
Using GAL=0.032 for source 1


Summary of source fluxes in OBI 001

      Position                               0.5 - 7.0 keV
                                             Value        90% Conf Interval
#0001|9 42 32.21 +12 20 51.3  Rate           0.00262 c/s (0.00204,0.00319)
                              Flux           2.85E-14 erg/cm2/s (2.22E-14,3.48E-14)
                              Mod.Flux       2.4E-14 erg/cm2/s (1.87E-14,2.93E-14)
                              Unabs Mod.Flux 2.53E-14 erg/cm2/s (1.97E-14,3.09E-14)



Summary of source fluxes in OBI 002

      Position                               0.5 - 7.0 keV
                                             Value        90% Conf Interval
#0001|9 42 32.21 +12 20 51.3  Rate           0.00247 c/s (0.00205,0.00288)
                              Flux           2.41E-14 erg/cm2/s (2.01E-14,2.82E-14)
                              Mod.Flux       2.26E-14 erg/cm2/s (1.88E-14,2.65E-14)
                              Unabs Mod.Flux 2.39E-14 erg/cm2/s (1.99E-14,2.79E-14)



Summary of merged source fluxes

      Position                               0.5 - 7.0 keV
                                             Value        90% Conf Interval
#0001|9 42 32.21 +12 20 51.3  Rate           0.00252 c/s (0.00218,0.00286)
  NumObi=2                    Mod.Flux       2.31E-14 erg/cm2/s (2E-14,2.62E-14)
                              Unabs Mod.Flux 2.44E-14 erg/cm2/s (2.11E-14,2.76E-14)

The data for each observation are extracted and calibrated separately. Then the data are combined together to compute the combined (merged) count rate, photon fluxes, and model fluxes. (Merged model independent, ie eff2evt fluxes, are not currently computed.)

The "NumObi" value reports the number of observations in which the source was imaged. The output .flux file contains a subset of the per-obsid output .flux files with the column names prefixed with "MERGED".

Example 12

unix% srcflux evt2.fits pos=wavdetect_srclist.fits \
psfmethod=marx out=out_with_plugins.fits \
pluginfile=my_plugin.py

This example shows how to specify a plugin to be run after the source properties have been computed. The Python script my_plugin.py must contain a function called "srcflux_obsid_plugin". The details of the interface and example are shown in the Plugin section (below).

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=yes)

Input Chandra event file

The input Chandra event file. The file will be filtered on energy and with the source and background regions. The file should be for a single observation (see note about merged observations below).

Multiple event files can be input. The script will iterate over each event file individually, producing the same set of properties and data products.

Parameter=pos (string required stacks=no)

RA and DEC position of the source

pos may be a single position or may be a filename that contains columns named RA and DEC. If a single position the values may be in degrees or in sexagesimal format and must contain the "+" or "-" part of the declination.

If a file name is given, then it should contain columns named RA and DEC. The values in the file must be in decimal degrees. If columns RA and DEC cannot be found then the first two columns in the file are used.

All positions must be J2000.

When srcreg and bkgreg are left unspecified, a circular source region located at the pos location(s) is use whose radius is the size of a circle needed to enclose 90% of the PSF at 1.0keV. An annular background region is also located at the pos location, that has an inner radius equal to the size of the source radius, and an outer radius 5 times the inner radius.

The pos values are also used in the PSF corrections. It is the source's pos location that is used when psfmethod=quick and psfmethod=arfcorr to estimate the PSF fractions.

Parameter=outroot (file required filetype=output stacks=no)

The output root file name including directory.

There will be one file created per energy band. The file names will be: $outroot_$band.flux. The contents of the output files is described in the "Output files" section below.

If the arffile and rmffile are left blank, then the spectrum and associated response files for each source are also saved. The files all have

Parameter=bands (string not required default=default units=keV stacks=yes)

Energy bands and characteristic energy value

A band can be given using a name (which will use the appropriate definitions from the Chandra Source Catalog) or by explicit limits.

The names for the output files are created using the minimum, maximum and effective-energy values for each band.

Band names

The following names - based on the definitions from the Chandra Source Catalog - can be used; energies are given in keV and the effective energy is the monochromatic energy used to calculate the PSF fractions:

default

The value "default" will select band="broad" for ACIS datasets and band="wide" for HRC datasets.

csc

The value "csc" can be used as a short form for the combination of "soft,medium,hard".

wide

HRC data can only use the "wide" energy band. Using the default band="default" will automatically select the wide energy band.

Explicit ranges

If you want to use different values to those of the CSC then you can use the format lo:hi:eff - where lo, hi and eff give the minimum, maximum and effective energies to use for the band (values are in keV).

Multiple bands

Multiple bands can be given either by using the name "csc" or by using a comma-separated list. The different schemes can be combined, so the following are all valid

bands="csc,broad"
bands="0.5:7:2.5,ultrasoft"
bands="0.5:7:2.5,csc"

Parameter=regions (string not required default=simple)

Algorithm used to create default source and background regions

There are three options:

'simple'

The default is 'simple'. This creates circular source regions that encloses 90% of the PSF at 1.0keV at the input source position; these regions are created by the psfsize_src script. The background region is an annulus located at the source position with an outer radius equal to 3 times the source radius and an inner radius equal to 1.7 times the source radius. Overlapping sources are excluded from each other, and sources are excluded from any overlapping background. These are created using the roi tool.

'optimized'

The second option is the 'optimized' regions; they are optimized specifically for point sources. The source region is a polygon that encloses 90% of the MARX simulated PSF generated at 1.0 keV. Overlapping source regions are shrunk until they no longer overlap (or reach a minimum of 60% of the PSF at which point they are mutually excluded from each other). These regions are created with the psf_contour tool. The background region is an annulus with an inner radius that excludes 95% of the enclosed counts fraction (ECF) of the PSF with an outer radius that encloses 50 counts; for ACIS this is 50 counts in the 0.5 to 7.0keV energy band. Source regions are excluded from the backgrounds. These regions are created with the bkg_fixed_counts tool.

With both 'simple', and 'optimized' options, the edge of the detector is taken into account in both the source and background regions by including the observation specific field-of-view (FOV) file. If 'srcreg' and 'bkgreg' are specified (not blank), then the 'simple' and 'optimized' options are ignored.

'user'

Users can provide their own custom region files by setting regions=user and supplying values for the 'srcreg' and 'bkgreg' parameters. Those regions are used exactly as provided.

Parameter=srcreg (string not required filetype=input stacks=yes)

Stack of source regions

The source region used to extra counts and the spectrum. This can either be a CIAO region syntax or can be a region file. The following are all valid examples,

ellipse(4096,4096,100,50,45)
box(3000,3000,100,50)-circle(3000,3000,10)
region(ds9.reg)
mysource.fits
region(mysource.fits)
bounds(region(my.reg))
@ciaoreg.lis

see ahelp dmregions for more information on the supported syntax.

If srcreg is specified, then bkgreg must also be specified. If multiple source positions are input, then multiple srcreg (and bkgreg) must be specified and all in the same order.

Parameter=bkgreg (string not required filetype=input stacks=yes)

Stack of background regions

The background region. It should be taken from a region near the source free of most source counts. See the description of srcreg for examples of the allowed syntax.

If srcreg is specified, then bkgreg must also be specified. If multiple source positions are input, then multiple srcreg (and bkgreg) must be specified and in the same order.

Parameter=bkgresp (boolean not required default=yes)

Create background ARF and RMF?

Should the spectral response for the background regions be created - that is ARF and RMF - as well as for the source regions. The names of these files is discussed above, in the outroot parameter.

Parameter=psfmethod (string not required default=ideal)

Method to compute PSF fraction in the source and background regions.

There are 5 different methods for computing the fraction of the PSF in the source and background regions:

• ideal : source region is assumed to contain 100% of the PSF and the background therefore contains 0% of the source flux.
• quick : the radius of the source circle is used to look up the PSF fraction in the specified energy band(s). The background is assumed to contain 0% of the source flux.
• arfcorr: the arfcorr tool is run for the source and background regions at the specified energy band(s) and the PSF fraction is estimated from the model PSF.
• psffile : allows the user to supply an image of the PSF, for example created with ChaRT or MARX. The filenames are then supplied via the psffile parameter.
• marx: allows the use to run MARX to simulate the PSF at the source location at the characteristic energy for the energy band. This runs the simulate_psf script, which requires that users have already setup to use MARX and specifically that the marx_root parameter is set to the root directory of the MARX installation.

Parameter=psffile (file not required filetype=input stacks=yes)

PSF image file(s) for use with psfmethod=psffile

An image of the PSF, for example, created by running SAOTrace, ChaRT, or MARX. If multiple source positions are input, there must be one PSF image for each source. If multiple energy bands are used, then the same PSF image is used for all energies.

The image should be large enough for both the source and background regions.

If working with an extended source, the psffile can also be an image of the model surface brightness.

Parameter=conf (real not required default=0.9 min=0 max=1)

Confidence interval

The credible interval for the errors. If the net counts are 0, then only the upper bound of the interval is reported.

Parameter=binsize (real not required default=1 min=0)

Image bin size

The image bin size used for the arfcorr PSF correction and for the fluximage images used to get the photon fluxes. The binsize should only be reduced when working with very small source regions (subpixel analysis).

Parameter=rmffile (file not required filetype=input stacks=yes)

Input ARF files

If an ARF and RMF exist for the source then the RMF can be input via the rmffile parameter. Both ARF and RMF must be available. When this parameter is used, specectract is not run so the source and background spectrum are not created. There must be 1 ARF and RMF pair for each source.

Parameter=arffile (file not required filetype=input stacks=yes)

Input ARF files

If an ARF and RMF exist for the source then the ARF can be input via the arffile parameter. Both ARF and RMF must be available. When this parameter is used, specectract is not run so the source and background spectrum are not created. There must be 1 ARF and RMF pair for each source.

The input ARF must not have had any PSF corrections or the psfmethod parameter should be set to 'ideal'. This will ensure that the PSF fraction correction is not doubly applied to the modelflux results.

If using the output from srcflux, user should use the _nopsf.arf file.

Parameter=model (string not required)

The Sherpa model expression for the source spectrum

The Sherpa model expression for the source. See ahelp modelflux

Parameter=paramvals (string not required)

Model parameters

The Sherpa model expression parameters for the source. See ahelp modelflux

The special tokens "%GAL%" (which is a short form for "%NRAO_NH%"), "%NRAO_NH%" and "%BELL_NH%" (no quotes) may be used in the model paramvals or absorption model absparams. These tokens will be replaced with the nH value retrieved by running the prop_colden tool. To use the NRAO value for nH for each source, use either the "%GAL%" or "%NRAO_NH%" tokens as in the following example:

unix% pset srcflux absmodel="xsphabs.abs1"
unix% pset absparams="abs1.nH=%GAL%"

The NRAO catalog is the default because it is an all-sky survey, whereas the Bell catalog only contains data for positions with a declination greater than -40 degrees. These tokens are case sensitive, so must be given all in upper case with both a leading and trailing % character.

Parameter=absmodel (string not required)

The absorption model component

The absorption model component can either be specified here or as part of the model expression. If it is supplied separately, then the unabsorbed fluxes will also be computed. The parameter values for this component is given in the absparams parameter.

Parameter=absparams (string not required)

The absorption model component parameter values.

See the paramvals section, in particular for information on how the "%GAL%", "%NRAO_NH%", and "%BELL_NH%" tokens are used to define a per-source column density.

Parameter=abund (string not required default=angr)

XSPEC solar abundances

See ahelp modelflux for more information and available options.

Parameter=pluginfile (file not required filetype=input stacks=no)

Python plugin script file name

The file name of the python scripts to run to perform additional analysis tasks with the srcflux outputs. The plugins must be named "srcflux_obsid_plugin" and/or "srcflux_merge_plugin" depending on whether it should be run for each individual observation or for the merged dataset (if multiple event files have been supplied).

For more details see the Plugin section (below).

Parameter=fovfile (file not required filetype=input stacks=no)

Field Of View (FOV) file

If not specified, a temporary fovfile will be created by the script by running the ahelp skyfov tool.

The FOV is used to filter the event file, psf, and images to correctly account for regions that overlap the edge of the detectors.

If the srcreg and bkgreg parameters are not specified, the FOV will also be included as part of the automatically generated regions (see pos description).

Parameter=asolfile (file not required filetype=input stacks=yes)

Stack of Aspect Solution Files

A stack with the file names of one or more aspect solution files. Most observations have a single aspect file but some will have more. If left blank, the tool will attempt to locate the correct file based on the event file header information.

Parameter=mskfile (file not required filetype=input stacks=no)

Mask file name

Name of the observation's mask file describing the active area of the detector. If left blank, the tool will attempt to locate the correct file based on the event file header information. It can be set to the string "none" to use no mask file.

Parameter=bpixfile (file not required filetype=input stacks=no)

Badpixel file name

Name of the observation specific bad pixel file. If left blank, the tool will attempt to locate the correct file based on the event file header information. It can be set to the string "none" to use no bad-pixel file.

Parameter=dtffile (file not required filetype=input stacks=no)

Dead time factors file (HRC only)

Name of the HRC dead time file for the observation. If left blank, the tool will attempt to locate the correct file based on the event file header information. It can be set to the string "none" to ignore the DTF corrections.

Parameter=ecffile (file not required filetype=input default=CALDB stacks=no)

PSF Calibration file

The filename of the PSF calibration file. Should be left as the default unless otherwise instructed.

Parameter=marx_root (file not required default=${MARX_ROOT})

Directory where MARX is installed

MARX must be installed for the any of the following srcflux options to work

• psfmethod=marx
• regions=optimized

The marx_root parameter values must be set to the root directory where marx is installed. That is the marx executable must be located in $marx_root/bin/marx.

If blank, then look for marx in the user's PATH and use that directory for marx_root.

Parameter=parallel (boolean not required default=yes)

Run code in parallel using multiple processors?

If multiple processors are available, then this parameter controls whether the tool should run various underlying tools in parallel.

If parallel=yes and verbose>0 users will see that sources will be run in a random order.

Parameter=nproc (integer not required default=INDEF min=1)

Number of processors to use

If parallel=yes, then this controls the number of processes to run at once. The default, INDEF, will use all available processors. The value cannot be larger than the number of processors.

If parallel=yes and verbose>0 users will see that sources will be run in a random order.

Parameter=tmpdir (file not required default=${ASCDS_WORK_PATH})

Directory for temporary files

Parameter=random_seed (integer not required default=-1)

Initial random seed for PSF simulations. It is passed to the simulate_psf tool when psfmethod=marx.

The random_seed is set to initialize the simulation. With random_seed equal to the default value of -1, the script will use a random value for the initial random_seed.

Parameter=clobber (boolean default=no)

Overwrite existing files?

Parameter=verbose (integer default=1 min=0 max=5)

Amount of tool chatter

Multiple Observations

Users can specify a stack of input event files. srcflux will produce results for each observation separately as well as computing properties based on the merged products.

If source and background regions are not supplied, then by default a circle enclosing 90% of the PSF region at 1keV is computed separately for each observation. If regions are supplied, the same regions are used for each input event file.

Absorbed and Unabsorbed model fluxes are computed by combining the ARF and RMF file using the combine_spectra script. Count rates and photon fluxes are computed by running the aprates tool with the sum of the source and background counts, and weighting by the exposure and PSF fractions.

PSF Correction

For extended sources, or when the PSF scattering is being ignored, the psfmethod=ideal setting should be used, which assumes that the source region contains all the source flux, so there is no source contribution to the background region.

Otherwise the PSF fraction can be approximated from a circular model (psfmethod=quick [source region only] and psfmethod=arfcorr [source and background regions]), or estimated from an input image (psfmethod=psffile).

Multiple Sources

Multiple source positions may be specified by supplying a file with RA and DEC values. If source and background regions are supplied, they need to match the positions in the file - the same number of regions and in the same order. Similarly, if psfmethod=psffile, then these must match the positions.

Multiple Bands

Multiple energy bands can be specified. There will be one output file per energy band. If using psfmethod=psffile, then the same psffile is used for all energy bands. Users who want to use a separate psffile for each energy band need to run the tool for each band separately.

Output files

This is a list of the column definitions in the output .flux file created for each observation. A '*' in the Orig column indicates that the value was computed directly by dmextract.

The following keywords are also added to each file:

If multiple event files are supplied, then the results are combined together into a merged .flux file. It contains the following columns:

Plugins

New in ciao-contrib 4.15.0

Introduction

While the purpose of the srcflux script is to provide users with robust flux estimates, along the way the script creates many data products which can be used for many other types of analysis: spectral fitting, creating radial profiles, determining source extent, refining source location, advanced timing analysis, etc. To facilitate these other analysis paths, srcflux can now run user supplied plugins and conjoin the results with the standard flux results it already produces. There are two hooks for plugins: one that is run after each energy band for each individual observation, and one that is run after each energy band for the merged datasets (if more than one event file has been supplied).

To use the plugins, users supply the file name to python scripts via the pluginfile parameter. If using both per-obsid and merged plugins then they both must be defined in the same file. The plugin is run sequentially for each source (not run in parallel).

Per ObsID/Per Energy Band

There are a few simple requirements for the user supplied plugin:

Requirements for user supplied plugins

• Set the srcflux parameter pluginfile to the file name of the Python script.
• The script must contain a function called 'srcflux_obsid_plugin'. It must take the following parameters: infile, outroot, energy-band name, min energy, max energy, and the ID number of the source (component number).
• The function must return a list of values to be added to the output .flux file. If there are no values, it must return an empty list, eg "[]". The order of the values in the list will be the same as in the output .flux file. The function must always return the same list of value, even if there is an exception raised.
• Each object in the list must have the following attributes: "name", "units", "value", and "description". This may be a NamedTuple, a dataclass object, or any other object type will work. The output column name must not already exist in the .flux file and must adhere to FITS standards (letters, numbers, hyphens and underscores only).
• The function is responsible for cleaning up any temporary files, and conversely may create arbitrary new data products.

An example Python script to perform a spectral fit using Sherpa and return various fit parameters and metrics can look like this:

import sys
import os
from collections import namedtuple
import numpy as np

from sherpa.astro.ui import *

ReturnValue = namedtuple('ReturnValue', 'name value units description')

def srcflux_obsid_plugin(infile, outroot, band, elo, ehi, src_num):
    """    
    Sample plugin: fitting spectrum.
    
    This sample plugin uses sherpa to fit a spectral model, and 
    return an estimate of the flux w/ errors calculated with
    the sample_flux routine.    
    """

    pi_file = outroot+".pi"

    try:
        load_data(pi_file)
        group_counts(1)
        set_source(xsphabs.abs1*xspowerlaw.pl1)
        set_method("simplex")
        notice(0.5,8.0)
        fit()        
        fit_info = get_fit_results()            
        fflux, cflux, vals = sample_flux(lo=2.0, hi=10.0)
        f0, fhi, flo = cflux
                
        retval = [ReturnValue("fitted_Nh", abs1.nH.val, "cm**-22", "Fitted Absorption value"),
                  ReturnValue("photon_index", pl1.PhoIndex.val, "", "Fitted Photon Index"),
                  ReturnValue("normalization", pl1.norm.val, "", "Spectrum Normalization"),
                  ReturnValue("reduced_statistic", fit_info.rstat, "", "Reduced Fit Statistic"),
                  ReturnValue("fit_statistic", fit_info.statval, "", "Fit Statistic"),
                  ReturnValue("dof", fit_info.dof, "", "Degrees of Freedom"),
                  ReturnValue("sample_flux", f0, "", "2-10 keV Sample Flux"),
                  ReturnValue("sample_flux_lo", flo, "", "2-10 keV Sample Flux Uncertainty Low"),
                  ReturnValue("sample_flux_hi", fhi, "", "2-10 Sample Flux Uncertainty Low"),
                  ]
    except Exception as wrong:
        sys.stderr.write(str(wrong)+"\n")
        sys.stderr.write(f"Problem fitting {outroot} spectrum. Skipping it.")

        retval = [ReturnValue("fitted_Nh", np.nan, "cm**22", "Fitted Absorption value"),
                  ReturnValue("photon_index", np.nan, "", "Fitted Photon Index"),
                  ReturnValue("normalization", np.nan, "", "Spectrum Normalization"),
                  ReturnValue("reduced_statistic", np.nan, "", "Reduced Fit Statistic"),
                  ReturnValue("fit_statistic", np.nan, "", "Fit Statistic"),
                  ReturnValue("dof", np.nan, "", "Degrees of Freedom"),
                  ReturnValue("sample_flux", np.nan, "", "2-10 keV Sample Flux"),
                  ReturnValue("sample_flux_lo", np.nan, "", "2-10 Sample Flux Uncertainty Low"),
                  ReturnValue("sample_flux_hi", np.nan, "", "2-10 Sample Flux Uncertainty Low"),                  
                  ]

    return retval

In this sample code we are using a NamedTuple to store information about the fit including the fitted nH, Photon Index, normalization, fit statistic, and flux estimate obtained using the sample_flux routine. In the event of an exception being thrown, the script still returns but sets all the values to NaN.

Post Merge/Per Energy Band

The post merge plugin works in the same way as the per ObsID plugin except

• The post merge plugin function must be called "srcflux_merge_plugin" with the same input parameters as the per-obsid plugin.
• The infile input parameter will now be a list of all the input event files.

Examples

Users can find example plugins in

$ASCDS_CONTRIB/data/sample_srcflux_plugins.py

These include

• Perform a spectral file (per obsid, and on merged data)
• Combined images and exposure maps on merged data
• Compute hardness ratios (per obsid)
• Extract radial profiles (per obsid)
• Perform blind deconvolution using arestore (per obsid)
• Estimate source extent (per obsid)
• Run the `aplimits` tool to get upper limits for missed detections and count rates for false detections.

See the Using srcflux plugins thread for a detailed example.

Processing steps

Given a position and no source and background regions, the script will by default create a source region that is a circle which encloses 90% of the PSF at 1.0keV and will create a co-located background annulus with inner radius equal to the source and outer radius 5 time the source radius.

The aprates tool is used to compute the net counts and 90% credible interval using the events in the specified energy band(s). The user may select a different credible interval by changing the conf parameter. The energy bands can be explicitly provided or can be specified to match those in the Chandra Source Catalog.

The fraction of the PSF in the source and background regions is computed in one of 5 ways. Ideal: assumes 100% of the PSF in the source region and 0% in the background. Quick: looks up the PSF fraction given size of the source region (circle only). Arfcorr: creates a 2D radially symmetric model of the PSF and estimates both the source and background PSF fractions. PSFFile: user supplies an image of the PSF from which the source and background PSF fractions are extracted. Marx: simulates the PSF at the user supplied location with the characteristic energy for the energy band.

The tool then computes a model independent flux using the flux values computed using the eff2evt tool which uses the events' energy and the local responses to estimate a flux value per event. These are the "Flux" values printed to the screen and are the "NET_FLUX_APER" values stored in the .flux output file.

The fluximage tool is run to create an exposure corrected image for just a small region around the source and background. The photon flux is extracted from this image. These values are not displayed to the terminal. They are stored in the "NET_PHOTFLUX_APER" columns in the .flux output file.

specextract is then run to generated the ARF and RMF needed to compute the model dependent fluxes using the modelflux tool. Both absorbed and unabsorbed fluxes can be computed. The screen output "Mod.Flux" values are the absorbed model flux values which are also stored in the "NET_MFLUX_APER" column in the .flux output file. If a separate absorption model was supplied, then the "Unabs Mod.Flux" screen output will be displayed with those flux values; those values are also stored in the "NET_UMFLUX_APER" column in the .flux output file.

To check for variability in the source region, the dither_region tool is used to determine the fraction of the geometric area of the region is exposed vs time (ie not being affected by bad pixels or chip edges). This information is then used with the glvary tool to look for variability. The glvary output provides the SRC_VAR_ODDS, SRC_VAR_PROB, and SRC_VAR_INDEX values. As an additional convenience the traditional standard lightcurve is created by running dmextract with a fixed 100s bin width. Both the glvary probability weighted lightcurve and the dmextract lightcurve are saved for each source.

The results are stored in an output file, one row per source, and one file for each energy band. With verbose>0, the results are also printed to the screen.

After the results are computed, and user supplied plugins are run and the results added to the output file.

Caveats

Model Independent Flux

The Flux values reported by srcflux are computed by summing a flux value associated with event based on its location in the field and detected energy. This is a useful model independent approximation of the flux. However, since the detected energy may significantly differ from the true energy (ie the effects encoded in the RMF) and the detected location may differ from the true location (ie the effects encoded in the PSF) users should be careful if the flux computed this way differs significantly from what they get from doing a proper spectral fit.

Using with Merged Datasets

Users should not use this script with merged datasets; rather they should supply the individual observations separately. Users should review the material on Extracting spectra from Merged Datasets regarding the issues of trying to extract and fit a spectra from a merged observation as they apply directly to this script.

Gratings

This script may only be used to estimate the count rate and flux from the 0th order grating datasets.

Crowded Fields

This script does not take source flux from neighboring sources into account when computing NET_RATE and errors. The aperture/region and PSF fraction will exclude them however, when the sources have significant overlap, the contributions from the overlap need to be handled differently.

Pileup

This script does not consider pileup effects when estimating the NET_FLUX or the credible intervals. Due to the non-linear relationship between observed counts and incident photons, users need to take extra care when analyzing data that affected by pileup.

Low Counts

eff2evt fluxes are very sensitive when there are a low number of counts, especially when the response changes significantly across the energy band. When there are few or no counts in the source region, the eff2evt fluxes are omitted (returned as NaN) since there is no way to estimate a model independent spectral shape in the absence of counts.

Continuous Clocking

This script will not work with continuous clocking (CC) mode data. CC mode data processing requires special handling beyond the scope of this script.

Changes in the scripts 4.16.2 (August 2024) release

If marx_root is blank, then look for marx in the user's PATH and derive marx_root from that path.

Combined Grating 0th Order Bug Fix

srcflux would fail when computing the model fluxes for gratings 0th order fluxes when combining multiple observations. This has been fixed.

Fix for very complex regions

Especially with the new region=optimized option, the automatically generated regions can become very complex with long polygons and multiple excluded, overlapping regions. These long regions when written as a string could cause errors when trying to save to FITS region files. This has been fixed. A side effect is that unused array values eg ROTANG (the rotation angle) values for circles are now stored as NaN's instead of 0's.

Changes in the scripts 4.16.1 (April 2024) release

Fixed a bug when using the new optimized region option when the source position is outside the field-of-view of the observation(s).

Changes in the scripts 4.16.0 (December 2023) release

New 'regions' parameter

The regions parameter has been added. It allows the user to select between two options when creating default source and background regions: "simple" and "optimized". See the parameter description for more details on these two options. Either choice is overridden if users specify the srcreg and bkgreg parameters (both must be provided if either is specified).

Bugfix for merged observations

A bug has been fixed that could cause an error when running srcflux with merged datasets where the combined PSF fraction (alpha) would be very, very slightly greater than 1.0 (eg 1.00000001). This can happen due to numerical precision/rounding of certain values. These values are now clipped at 1.0.

Changes in the scripts 4.15.2 (April 2023) release

Fixed a problem where the script could crash when computing the merged count rates if given particularly bad set of inputs.

Added a check that if using multiple event files with user supplied source and background regions that the event files must all be reprojected to the same tangent plane.

Added a check for missing parameters/incompatible parameter file.

Changes in the scripts 4.15.1 (January 2023) release

Fix the script so it works when run with bkgresp=no.

Changes in the scripts 4.15.0 (December 2022) release

Plugins

Users can now write srcflux plugins that can add additional source properties to the output .flux file. There is a separate plugin that is run for each energy band+obsid combination, and for each energy band with the merged data products. For details see the Plugins section above.

Default Region Changes

The default has been that any source region which falls inside the background annulus of another source is excluded from that annulus. The source region contains roughly 90% of the PSF from the source so there is some contamination in the background. This is can affect the flux estimates especially in the case of a bright source influencing the background estimate of a nearby faint source. To ameliorate this we have increased the size of the excluded sources. This applies both to sources overlapping the background annulus and to sources overlapping source regions (circles). For isolated sources this has no effect on the results.

Parallelization of PSF simulations

When psfmethod=marx, the simulations of the PSF are now done in parallel.

Changes in the scripts 4.14.2 (April 2022) release

Intra-obsid variability added

srcflux now runs the glvary tool to check for source variability during an observation. Given the generally low counts in the individual background regions, we do not check for per-source background variability. The G-L probability weighted "optimally" binned lightcurve file and the standard dmextract lightcurve file using 100s bins are created; both are corrected for exposure variations due to dither.

Handling of region files

Updated to use the new CXCRegion module. While there is functionally no difference, the new region module provides increased numeric precision to the shape parameters (coordinates, radii, angles). This can result in small numeric difference in the output (expected to be <<1%).

Changes in the scripts 4.14.0 (December 2021) release

Fix a rare error when merging results

If a source was at the edge of the field of view of a CCD it could appear as if it belonged to an inactive CCD, thanks to dither, which caused the script to crash.

Changes in the script 4.13.0 (December 2020) release

Merged Outputs

When multiple event files are specified, users will now also get a flux estimate from all the observations combined. Currently model independent fluxes are not combined; but rates, photon fluxes, and model fluxes (absorbed and unabsorbed) are computed. Uncertainties are computed using the aprates tool. Variable sources will likely yield incorrect flux estimates.

Other

In addition the energy band parameter has been changed to band=default. This allows both ACIS (default is broad band) and HRC (default is wide band) to work without explicitly changing this parameter.

A new random_seed parameter has been added which is passed to the simulate_psf script when psfmethod=marx. The default random_seed=-1 will use the current time to seed the random stream.

Updates to minimum number of events to simulate with MARX. Also updates to deal with floating point precision of MARX PSF images.

Changes in the scripts 4.12.2 (April 2020) release

Now uses the new skyfov method=convexhull algorithm when new aspect solution files with CONTENT=ASPSOLOBI are provided. This gives a tighter bounding polygon around each chip and a better estimate of the geometric area for regions that extend over the edges.

Changes in the scripts 4.11.3 (May 2019) release

Bugfix for net_photflux and net_flux values

Correction to the background PSF fraction in the net_photflux and net_flux values. For psfmethod=file|marx|arfcorr, these values would be overestimated by a factor proportional to the ratio of area of the background to source regions and the background PSF fraction; typically 5-15%.

Changes in the scripts 4.10.3 (October 2018) release

Internal fix to computation of near chip edge flag related to how floating-point values are treated in the pypixlib module. This does not affect any of the flux nor any of the rates, just the NEAR_CHIP_EDGE flag.

Recognizes when outroot is a directory and adjusts file names so they no longer begin with an underscore or period.

Changes in the script 4.9.4 (July 2017) release

Added an optimization for input stacks with large number of positions; especially when supplying externally created PSF images which may have exhausted system memory. There is no change in the output.

Changes in the script 4.9.2 (April 2017) release

There is a change to the script to correct an error for HRC-I photon fluxes (net_photflux_aper values) which was incorrectly including the background contribution twice.

Changes in the scripts 4.8.4 (September 2016) release

The following changes are included:

• Users who have installed MARX can now use psfmethod=marx which will run a monochromatic MARX simulation at the source location(s) to create a model.
• Users can now supply a stack of event files. If users also supply regions, the same regions are used with each event file in the stack -- therefore the regions should either be in celestial coordinates or the datasets need to be reprojected to the same tangent plane. The results for each input event file are reported separately; they are NOT combined.
• A new ${root}_summary.txt file is created with the final flux summary information.
• The summary information now includes the region (ie component) number.
• The default for the model and absmodel parameters have been changed, the later uses the %GAL% token to specify the galactic nH.

Changes in the scripts 4.7.2 (April 2015) release

The following changes are included:

• Users can now set the mskfile, bpixfile, and dtffile to the value "none". This can be useful in special cases, but note that it can lead to inaccurate or invalid results.
• The output .flux file now has CHIP_ID, CHIPX, and CHIPY columns for the nominal aspect location. This location may be off the detector.
• When given ACIS data, the per-chip LIVETIME (LIVTIMEx, where x goes from 0 to 9) is now used if available. The nominal chip ID for the source position is used.
• Additional data products are now retained including: the counts image, exposure map, flux image, net-rate probability density function, and - when method=arfcorr - the model PSF.
• The special tokens %GAL%, %NRAO_NH% and %BELL_NH% can be used in the paramvals and absparams parameters. These indicate that the nH column density value calculated by prop_colden should be used.

Changes in the scripts 4.6.6 (September 2014) release

A new, hidden, parameter called 'binsize' has been added to support using sub-pixel analysis (for small regions).

A hard-coded path to /tmp has been removed in part of the code; it now uses the tmpdir parameter.

Changes in the scripts 4.6.5 (June 2014) release

This patch fixes a problem where the background photon flux values, BG_PHOTFLUX, were incorrectly computed to be 0. The NET_PHOTFLUX_APER value and errors were therefore not background subtracted. The bug only affected the photon flux, *PHOTFLUX values; the count rates and other fluxes are not affected.

About Contributed Software

This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions - such as how to ensure that the parameter file is available.

Bugs

See Also

calibration

ardlib

psf

psf

tools::aspect

asphist, dither_region

tools::background

acis_bkgrnd_lookup, hrc_bkgrnd_lookup, readout_bkg

tools::composite

combine_grating_spectra, combine_spectra, specextract, srcextent

tools::coordinates

sky2tdet

tools::core

dmextract

tools::response

acis_fef_lookup, acis_set_ardlib, addresp, dmarfadd, eff2evt, find_mono_energy, fullgarf, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkosip, mkpsfmap, mkrmf, mkrprm, mkwarf, psf_project_ray, rmfimg

tools::statistics

aplimits, aprates, dmstat, lim_sens