AHELP for CIAO 4.11

# srcflux

Context: tools

## Synopsis

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

## Syntax

srcflux  infile pos outroot [bands] [srcreg] [bkgreg] [bkgresp]
[psfmethod] [psffile] [conf] [binsize] [rmffile] [arffile] [model]
[paramvals] [absmodel] [absparams] [abund] [fovfile] [asolfile]
[mskfile] [bpixfile] [dtffile] [ecffile] [parallel] [nproc] [tmpdir]
[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 be used to estimate upper limits as well as detections, as well as to 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. 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 four 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.

## 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
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.
Making response files for rhooph_0001
Running modeflux for region 1
Appending flux results onto output
Appending photflux results onto output
Computing Net fluxes
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 creates a 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% confidence 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)

#  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)

#  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 confidence limits.

### 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)

#  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% 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 confidence limits.

### Example 6

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
Appending flux results onto output
Appending photflux results onto output
Computing Net fluxes
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 or 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 7

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 confidence limits 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 of an upper limits computed for the soft band rate and fluxes.

### Example 8

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 9

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.

## Parameters

name type ftype def min max units reqd stacks
infile file input         yes yes
pos string           yes no
outroot file output         yes no
bands string   broad     keV no yes
srcreg string input         no yes
bkgreg string input         no yes
bkgresp boolean   yes       no
psfmethod string   ideal       no
psffile file input         no yes
conf real   0.9 0 1   no
binsize real   1 0     no
rmffile file input         no yes
arffile file input         no yes
model string           no
paramvals string           no
absmodel string           no
absparams string           no
abund string   angr       no
fovfile file input         no no
asolfile file input         no yes
mskfile file input         no no
bpixfile file input         no no
dtffile file input         no no
ecffile file input CALDB       no no
parallel boolean   yes       no
nproc integer   INDEF 1     no
tmpdir file   ${ASCDS_WORK_PATH} no clobber boolean no verbose integer 1 0 5 ## 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. The results are not merged. #### 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 Suffix File contents .arf ARF for source region, with PSF corrections _nopsf.arf ARF for source region, without PSF corrections .rmf RMF for source region .pi Spectrum of source region _grp.pi Grouped spectrum of source region with min 15 counts per group _bkg.arf ARF for background region (only if bkgresp=yes) _bkg.rmf RMF for background region (only if bkgresp=yes) .pi Spectrum of background region _srcreg.fits Source region file _bkgreg.fits Background region file _thresh.img counts image around the source (new in 4.7.2) _thresh.expmap exposure map around the source (new in 4.7.2) _flux.img Fluxed (exposure corrected) image (new in 4.7.2) .prob Probability Density Function for the source count rate (new in 4.7.2) _model.psf The model psf used if method=arfcorr (new in 4.7.2) #### Parameter=bands (string not required default=broad 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: Band name Minimum Energy Maximum Energy Effective Energy broad 0.5 7.0 2.3 soft 0.5 1.2 0.92 medium 1.2 2.0 1.56 hard 2.0 7.0 3.8 ultrasoft 0.2 0.5 0.4 wide n/a n/a 1.5 ##### CSC The value "csc" can be used as a short form for the combination of "soft,medium,hard". ##### wide The "wide" energy band can only be used with HRC. ##### 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=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. If srcreg is not specified, the tool will use a circle that encloses 90% of the PSF at 1.0keV. If the fovfile is provided, then it will be included if the region overlaps the edge of the detector. #### 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. If srcreg is not specified the background is an annulus created by multiplying the source region by 1 (inner radius) and 5 (outer radius). Overlapping sources are excluded from both the source and the background region. #### 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 4 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. #### 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 confidence interval for the errors. If the net counts are 0, then the upper limit 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=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 head 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=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=clobber (boolean default=no)

Overwrite existing files?

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

Amount of tool chatter

### 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. A '*' in the Orig column indicates that the value was computed directly by dmextract.

Name Orig Description
sky(x,y) * Physical pixel location of center of extraction region. If no region, then will be the same as XPOS,YPOS (below)
EQPOS(Ra,Dec) * RA and Dec of center of extraction region. If no region, then will be the same as RAPOS,DECPOS (below)
SHAPE * shape of extraction region
R * radii of extraction region (physical pixels).
COMPONENT * integer number identifying region number
COUNTS * total counts in source region
ERR_COUNTS * approx error on total counts
AREA * area of source region in physical pixels
EXPOSURE * exposure time
COUNT_RATE * total count rate in source region
COUNT_RATE_ERR * approx error on total count rate in source regions
BG_COUNTS * total number of counts in background region
BG_ERR * approx error on total number of counts in background region
BG_AREA * area of background region (physical pixels)
BG_EXPOSURE * exposure time in background (same as source)
BG_RATE * total rate in background region
BG_SUR_BRI * total surface brightness in background region
BG_SUR_BRI_ERR * approx error on background surface brightness
NET_COUNTS * Net counts in source region from scaled background counts
NET_ERR * error on net counts
NET_RATE * Net count rate in source region from scaled background counts
ERR_RATE * Gaussian error on net_rate
SUR_BRI * Surface brightness. Net counts per pixel.
SUR_BRI_ERR * Gaussian error on surface brightness.
XPOS Input position converted to physical coordinates
YPOS Input position converted to physical coordinates
THETA Location of position relative to the optical axis
PHI Location of position azimuthally around the optical axis
RAPOS RA of position (decimal degrees)
DECPOS Dec of position (decimal degrees)
CHIP_ID CHIP number at mean aspect and sim location
CHIPX CHIP X location at mean aspect and sim location
CHIPY CHIP Y location at mean aspect and sim location
INSIDE_FOV A value of TRUE means that the source - using the position (RAPOS, DECPOS) - is within the field-of-view of the observation.
NEAR_CHIP_EDGE A value of TRUE means that the POS location of the source is within 32 pixels of the edge an ACIS CCD meaning the source position and/or region may be partially off-chip.
PSFFRAC Fraction of the PSF in source region
BG_PSFFRAC Fraction of the PSF in the background region
NET_RATE_APER Net COUNT rate in source is computed using the aprates tool. It computes the Bayesian background-marginalized posterior probability distribution function (PDF) for the NET_RATE, assuming non-informative priors for the intensities in the source and background apertures. The mode of the PDF is the NET_RATE_APER. A value of 0 indicates that only an upper limit is available.
NET_RATE_APER_LO Lower equal tail confidence limit on NET_RATE. A value of NaN indicates that only an upper limit is available as the NET_RATE_APER_HI value.
NET_RATE_APER_HI Upper equal tail confidence limit on NET_RATE. If the _LO value is NaN and the RATE is 0 then this value represent the upper limit on the count rate.
SRC_SIGNIFICANCE The source significance given the source and background count rates and their errors.
FLUX_APER Model independent flux computed by summing the FLUX values produced by running eff2evt on the event file in the source region.
BG_FLUX_APER Same FLUX_APER for the background region.
NET_FLUX_APER A model independent net flux for the counts in the source region.
NET_FLUX_APER_LO Lower confidence limit the model independent net flux computed by scaling the NET_RATE limits. If only an upper limit was compute then it is used to scale the values.
NET_FLUX_APER_HI Same as NET_FLUX_APER_LO for the upper confidence limit.
UPPER_LIMIT A flag identifying whether the NET_FLUX_APER limits are computed from an upper limit estimate (yes) or an observed NET_RATE (no).
MEAN_SRC_EXP The mean value of the exposure map pixel values (cm^2) in the source region.
MEAN_BKG_EXP The mean value of the exposure map pixel values (cm^2) in the background region.
SRC_PHOTFLUX The sum of the pixel values fluximage output integrated over the source region (photon/cm^2/sec)
BG_PHOTFLUX The sum of the pixel values fluximage output integrated over the background region (photon/cm^2/sec)
NET_PHOTFLUX_APER The net photon flux computed using the source and background photflux, area, and PSF fractions.
NET_PHOTFLUX_APER_LO The lower limit on the NET_PHOTFLUX_APER value obtained by scaling the NET_RATE_APER_LO value.
NET_PHOTFLUX_APER_HI The upper confidence limit on the NET_PHOTFLUX_APER value obtained by scaling the NET_RATE_APER_HI value.
MFLUX_CNV The conversion factor used for the (absorbed) model flux.
UMFLUX_CNV The conversion factor used for the unabsorbed model flux (if absmodel specified)
NET_MFLUX_APER The net flux assuming the specified model computed by scaling the NET_RATE by the MFLUX_CNV value
NET_MFLUX_APER_LO The lower confidence in NET_MFLUX_APER
NET_MFLUX_APER_HI The upper confidence in the NET_MFLUX_APER
NET_UMFLUX_APER The net unabsorbed flux assuming the specified model, computed when the absmodel parameter is specified. Value is NET_RATE scaled by the UMFLUX_CNV value.
NET_UMFLUX_APER_LO Lower confidence limit on unabsorbed model flux
NET_UMFLUX_APER_HI Upper confidence limit on the unabsorbed model flux

The following keywords are also added to each file:

Keyword Description
ENERGY Characteristic monochromatic energy for band [keV]
EMIN Minimum energy in band [keV]
EMAX Maximum energy in band [keV]
CONF Confidence interval
MODEL Sherpa model expression
PARAMVAL Sherpa model parameters
ABSMODEL Sherpa model expression for absorption component
ABSPARAM Sherpa absorption parameters

### Processing steps

Given a position and no source and background regions, the script will 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% confidence interval using the events in the specified energy band(s). The user may select a different confidence 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 4 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.

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.

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.

### 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. 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. To summarize, while it is trivial to simply combine the counts, even something as simple as NET_COUNTS is problematic if the source was observed on different CCD's.

### 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 confidence 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.

### 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. ## Bugs Error in the model independent NET_FLUX_APER and the NET_PHOTFLUX_APER values (and uncertainties). (3 May 2019) There is an error in the computation of the model independent NET_FLUX_APER and the NET_PHOTFLUX_APER values reported in${root}.flux output file when using psfmethod=file or arfcorr or marx. The fraction of the source flux in the background region is getting incorrectly scaled by the ratio of the area of source-to-background.

Consider the default case where the background area to source area is approximately r=24 (background annulus outer radius is 5 times the source radius) and has typical PSF fractions of a=90% in the source region, and b=9% in the background region. The error in the fluxes will be the ratio of $$\frac{(r*a-b)}{(r*(a-b))} = 1.106$$, so a a 10.6% over-estimate of the photon flux. The same error is propagated to the LO and HI confidence interval limits for both NET_FLUX_APER and NET_PHOTFLUX_APER values. The actual values for r,a,b can be obtained from the columns in the \${root}.flux file: r = BG_AREA/AREA, a = PSFFRAC, and b = BG_PSFFRAC.

The offchip flag may be incorrectly set for some observations.

The offchip flag may be incorrectly set for observations with large DY or DZ offsets. This does not affect any of the flux values nor any of the rates.