flux_obs

Synopsis

Combine reprojected observations to create an exposure-corrected image.

flux_obs  infiles outroot [bands] [xygrid] [maxsize] [binsize]
[asolfiles] [badpixfiles] [maskfiles] [dtffiles] [units] [expmapthresh]
[background] [bkgparams] [psfecf] [psfmerge] [random] [parallel]
[nproc] [tmpdir] [cleanup] [clobber] [verbose]

Description

The flux_obs script takes a stack of event files, creates exposure maps for each observation, and divides the resulting images to produce a coadded, exposure-corrected image. This process can be done for one or more energy bands.

It is assumed that the event files are already re-projected (e.g. they are the output of reproject_obs), or have the same tangent point. The script will warn you if observations have different tangent points but it does not remove them from the list.

For recently-processed data the script can be run along with reproject_obs: for example

unix% reproject_obs "*/repro/*evt2.fits" reproj/
unix% flux_obs reproj/ reproj/

will store the merged data products in the directory reproj/, creating this directory if necessary. The output files include:

• reproj/broad_flux.img, the exposure-corrected broad-band image;
• reproj/merged.fov, the merged FOV file from all the observations.

We took advantage of the stack support to process all the files that match "*/repro/*evt2.fits" (reproject_obs). Note that the quotes around the pattern are needed so that the shell does not do the matching, which would result in a parameter file error. When given a directory, flux_obs searches for all files matching "*evt*", skipping any merged event files it finds; as shown in the examples below the files can also be explicitly listed.

Examples

Example 1

unix% punlearn reproject_obs flux_obs
unix% reproject_obs
5826/repro/acisf05826_repro_evt2.fits,5827/repro/acisf05827_repro_evt2.f
its reproj/
unix% flux_obs reproj/ m87
unix% ds9 m87_broad_flux.img -region m87_merged.fov

The two ACIS observations, reprojected to a common tangent point by reproject_obs are combined to create m87_broad_flux.img, which is the broad-band (0.5 to 7 keV) image divided by an exposure map created at 2.3 keV. As these are ACIS observations the pixel size is set to 8 (i.e. 3.936 arc seconds).

Since a directory name was given to flux_obs, searches for relevant event files (see the parameter description for the infile parameter fore a full description of the search). Note that, as of the scripts 4.5.2 release, the merged event file created by reproject_obs will be skipped over by flux_obs since it has an ObsId value of "Merged"; this simplifies using the two tools together.

The location of the necessary support files - e.g. aspect solution, bad-pixel file, mask file, and DTF file - are taken from the headers of the event files.

The processing steps are run in parallel when possible to reduce the run time of the script; this can be turned off by setting the parallel flag to "no", or the number of processors used changed with the nproc parameter.

Example 2

unix% flux_obs 10551/repro/ comb/

In this case, ObsId 10551 is an interleaved-mode observation, so has two event files in the repro directory - with labels e1 and e2 for the primary and secondary exposures. These can be treated as separate files and combined using flux_obs as shown; we do not need to use reproject_obs since both files have the same aim point. If you wish to combine multiple interleaved-mode observations then you should use reproject_obs first, or merge_obs.

Example 3

unix% flux_obs reproj/5826_reproj_evt.fits,reproj/5827_reproj_evt.fits
m87

In this example we explicitly list the observations to be combined.

Example 4

unix% flux_obs "merged/*reproj_evt.fits" merged/
unix% ds9 merged/broad_flux.img -region merged/merged.fov

Here we use the stack support which lets CIAO tools expand out patterns to list the input event files; in this case all files that end in reproj_evt.fits in the merged/ directory (this is the pattern used by reproject_obs to name its output).

Since the outroot is set to a directory, the exposure-corrected image will be called "merged/broad_flux.img". The directory will be created if it does not already exist.

Example 5

unix% find . -name \*reproj_evt.fits > evt2.lis
unix% flux_obs @evt2.lis merged/ clobber+

This is similar to the previous example, this time using an external file as a stack (see ahelp stack) to combine all the files ending in "reproj_evt.fits" that are in the current directory or any of its children.

Example 6

unix% flux_obs "@evt2.lis[ccd_id=0:3]" merged/acisi

A DataModel filter is used to restrict the combination to only those chips with a ccd_id of 0 to 3 (i.e. the ACIS-I array). This filter is applied to each line of the stack file (evt2.lis). Those event file which contain no data after the filter will be ignored by the script.

The outroot has been changed so that the files do not clash with those from the previous run. If you wish to overwrite them then you would set outroot to merged/ and add clobber=yes to the command line call.

Example 7

unix% flux_obs @evt2.lis merged/ bands=csc

The csc band is a short form for the soft, medium, and hard bands defined by the Chandra Source Catalog. This means that three exposure-corrected images will be created: merged/soft_flux.img, merged/medium_flux.img, and merged/hard_flux.img.

Example 8

unix% flux_obs @evt2.lis merged/ psfecf=0.9

Create per-observation PSF maps using an encircled-energy fraction of 0.9 (that is, the pixels in the PSF map give the radius, in arcsec, of the PSF size that contains 90 per cent of the PSF at that location). These maps are combined to create a single version for the field, using the default psfmerge setting, which uses the minimum ECF value at each pixel.

The combined PSF map is called merged/broad_thresh.psfmap.

Example 9

unix% flux_obs @evt2.lis merged/ psfecf=0.9 psfmerge=exptime

The combined PSF map is created by weighting the ECF values by the observation exposure times rather than taking the minimum value (which is the default psfmerge setting).

Example 10

unix% flux_obs @evt2.lis hires bin=2

The binsize parameter has been changed from its default value of 8 to 2. This may lead to large images if there is not significant overlap of all the observations.

Example 11

unix% flux_obs @evt2.lis hires maxsize=2048

In this example we force the longest dimension of the output images to have 2048 pixels.

Example 12

unix% flux_obs @hrc.lis merged/

In this example a set of HRC-I observations are being merged, which means that the wide band is used by default. The exposure-corrected image will be called merged/wide_flux.img.

The default setting for the background parameter is "default", which means that an estimate of the HRC-I particle background will be subtracted from each observation if the HRC CALDB package is installed and a match is found (as determined by the hrc_bkgrnd_lookup script). Observations for which no matching background file can be found will be skipped; to include these observations set background=none.

Example 13

unix% flux_obs @hrc.lis merged/ background=none

In this case the HRC-I data is processed without any background subtraction (which will be significantly quicker). Please see the caveat about "rings" seen in exposure-corrected HRC-I data for more information on why the particle background is removed by default.

Example 14

unix% flux_obs @hrc.lis merged/ bands=30:200:1.1 binsize=16

In this case the images will be filtered to only include events with PI=30:200, the exposure map is evaluated at 1.1 keV, and a bin size of 16 (rather than the default 32) is used. The final output file will be called merged/30-200_flux.img.

Example 15

unix% punlearn flux_obs
unix% pset flux_obs xygrid=2000.5:6000.5:8,2048.5:6128.5:8
unix% flux_obs @evt2.lis hires

Here we give the explicit grid for the output image (a 500 by 510 pixel image with a bin size of 8). All observations are reprojected, but only those that cover the grid will be used to create the combined image.

Example 16

unix% flux_obs @evt2.lis hires xygrid=merged.img

Thegrid for the images is taken to match that used to create the image merged.img (i.e. it is the output of get_sky_limits when run on merged.img).

Example 17

unix% flux_obs @evt2.lis combined/ bands=plwgt.dat,bbwgt.dat nproc=-1

There will be two exposure-corrected images created in combined/, both using spectral weights files: band1_flux.img for plwgt.dat and band2_flux.img for bbwgt.dat.

The default parameter settings for parallel (yes) and nproc (INDEF) mean that all processors on your machine are used. In this example we change nproc to -1, which means that it uses all-but-one of your processors; so on a four-core machine the script will use three cores.

Example 18

unix% punlearn flux_obs
unix% pset flux_obs asolfiles=obs1.asol,obs2a.asol,obs2b.asol
unix% pset flux_obs badpixfiles=obs1.bpix,obs2.bpix
unix% pset flux_obs maskfiles=NONE
unix% flux_obs obs1.evt2,obs2.evt2 out/ bands=0.5:4:2

Here the two event files to be combined are called obs1.evt2 and obs2.evt2 and the ancillary files - aspect solution and badpixel files - are explicitly given. No mask files will be used since maskfiles is set to NONE. In this example the second observation has two asol files - here called obs2a.asol and obs2b.asol.

Rather than use one of the pre-canned energy bands we use the 0.5 to 4 keV band with the exposure map evaluated as 2 keV.

Stack files

We could have also used stack files - e.g.

unix% ls -1 *asol > asol.lis
unix% ls -1 *bpix > bpix.lis
unix% ls -1 *evt2 > evt2.lis
unix% flux_obs @evt2.lis out/ bands=0.5:4:2 asol=@asol.lis
badpix=@bpix.lis mask=NONE

Example 19

unix% flux_obs @evt2.lis merged/ units=time

Here the exposure maps have units of seconds, rather than cm^2 s count / photon, and so the exposure-corrected images have units of count / s. The energy value of the band parameter - in this case 2.3 keV - is ignored and only the low and high energy limits are used.

Parameters

Detailed Parameter Descriptions

Parameter=infiles (file required stacks=yes)

Input event files

Multiple event files are provided as a comma-separated list or as a stack; see "ahelp stack" for more information. The observations do not need to be given in time order.

Listing just a directory name

Rather than list the full path to an event file, you can just give a directory name; in such a case the script searches for any files that match the pattern

• dirname/repro/*evt*
• dirname/primary/*evt*
• dirname/*evt*

where the search is done in the order given above, and stops as soon as a match (or matches) is found.

Skipping files

Any observations that do not match the instrument of the first observation are skipped, as are CC mode observations or those with no data (e.g. because of a ccd_id filter). For HRC data, the first observation determines whether HRC-I or HRC-S are being combined, with observations from the other instrument being skipped. Any file with an OBS_ID keyword of "Merged" is skipped.

If multiple files with the same OBS_ID keyword are found, then all but the first are skipped, unless they are part of an ACIS interleaved-mode observation (i.e. they have CYCLE=P or CYCLE=S).

The observations should all have the same tangent point, but this is not enforced: warning messages will be displayed for those observations which do not match.

File headers

The header of the event file(s) is used to determine the names of the supporting data files - aspect solution, bad pixel, parameter block, mask, and dead-time factor files - if they are not explicitly set in the parameter file.

Parameter=outroot (string required)

Root of output files

If the parameter ends in "/" then the output files are placed in this directory (which will be created if necessary), otherwise it is prepended to the file names, with a "_" added. So, with bands=broad and outroot=fi/ the exposure-corrected image is called fi/broad_flux.img whereas with outroot=fi the file is fi_broad_flux.img.

An empty outroot value, or one set to ".", will cause the output files to be written to the current working directory with no prefix.

Parameter=bands (string default=default)

What energy or PI band, or bands, should be used?

The script will create an exposure-corrected image for each band. A band can be given using a name (which will use the appropriate definitions from the Chandra Source Catalog), by explicit limits, or by giving the name of a file containing the spectral weights (see ahelp make_instmap_weights).

For the first two options, the names for the output files are created using the minimum and maximum limits for each band. When using a weights file, the output files are labelled using "band1" to "bandn", where n is the number of weights file given to the parameter.

The default setting

The value of 'default' is converted to 'broad' for ACIS data and 'wide' for HRC data.

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 exposure map for the band:

CSC

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

Explicit ranges

If you want to use different values to those of the CSC then you can use the format lo:hi:eff where

Spectral weights

If a filename is given then it is assumed to be an ASCII file containing spectral weights; two colums giving the energy in keV and the weight value for that energy. This file can be created using the make_instmap_weights script, the save_instmap_weights() routine from the sherpa_contrib.utils module, or manually; see the description of the spectrumfile parameter of mkinstmap for more information on the format of this file.

The energy limits to use for the images are calculated from this file. If the file contains two lines (before the data) with the format

# ENERG_LO = elo
# ENERG_HI = ehi

then the elo and ehi values are taken for the limits (they are assumed to be in keV). This format is created by the make_instmap_weights script and the save_instmap_weights() routine. If these lines do not exist, or the elo/ehi values are not valid numbers, then the limits will be calculated from the first column using the formulae (x1 is the first value, xn is the last, and xm the last-but-one value):

elo = (3 * x1 - x2) / 2

ehi = (3 * xn - xm) / 2

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 (where wgt1.dat and wgt2.dat are weights files):

bands="csc,broad"
bands="0.5:7:2.5,ultrasoft"
bands="0.5:7:2.5,csc,wgt1.dat,wgt2.dat"

At present multiple bands can not be used with HRC data.

Parameter=xygrid (string default=)

xygrid for output or filename

When set, this parameter overrides both the maxsize and bin parameters, and defines the SKY coordinate range and binning used to create the output count images, exposure maps, and exposure-corrected images.

xygrid is set

When set, it can either be:

• a filename,
• a grid specification of the form "xlo:xhi:#nx or dx,ylo:yhi:#ny or dy".

If a filename is given then its sky range is used to determine the output; this is useful if you want to create an exposure-corrected image that matches an existing image. Otherwise the grid range is given explicitly; examples include "3824.5:5112.5:#161,4008.5:5296.5:#161" and "3824.5:5112.5:8,4008.5:5296.5:8".

xygrid is not set

When left at the default (empty) value, the script calculates the xygrid for the output image based on the observational data; the skyfov tool is used to determine the maximum area of the sky that is covered by the observations. In this mode the bin size is determined by either the maxsize or binsize parameters.

Parameter=maxsize (real default=INDEF min=1)

Maximum image width or height in pixels

This parameter is only used if the xygrid is empty (set to "").

If set (i.e. changed from INDEF) then the maximum dimension of the output image is set to this value. This can be useful if you quickly want to look at data and want to make sure the output image is not too large. Note that due to the way the ranges are calculated the actual image dimension is only guaranteed to be within a few pixels of the requested value.

The SKY ranges for the images are determined automatically, based on the ranges of the FOV files for each observation (see "ahelp skyfov").

Parameter=binsize (real default=INDEF min=0)

Image binning factor

This parameter is only used if the xygrid is empty (set to "") and maxsize is set to INDEF.

When set to INDEF a default value is used: 8 for ACIS data and 32 for HRC data. The binning factor has units of the SKY pixel (0.492" for ACIS and 0.1318" for HRC), so binsize=4 for an ACIS observation will create images with 1.968 arcsecond pixels. The value need not be an integer, and can be less than 1 if you want to look at small-scale structure near the aim point of the observation; in this case it is strongly suggested that a spatial filter is applied to ensure manageable file sizes.

The SKY ranges for the images are determined automatically, based on the ranges of the FOV files for each observation (see "ahelp skyfov").

Parameter=asolfiles (file stacks=yes)

Input aspect solutions

If the value is empty then the ASOLFILE keyword from the events files will be used to find the files to use. Unlike the other ancillary products, an aspect solution is required for the script to run.

The aspect solution files have names like pcadf*_asol1.fits (chandra_repro) or <obsid>.asol (reproject_obs). To explicitly specify the asol files use the stack syntax (e.g. a comma, or space, separated string or an external file as described in "ahelp stack" for more information). So to use asol1.fits, asol2.fits, and asol3.fits you could say

asolfile="asol1.fits,asol2.fits,asol3.fits"

or

asolfile="asol1.fits asol2.fits asol3.fits"

or

asolfile=@asol.lis

where asol.lis contains the names of each file, one per line. The files do not have to be given in time order.

Since there may be multiple asol files for an observation there may be more entries in this parameter than there are in the infiles parameter.

Aspect histograms - the output of the asphist tool - can not be used here.

Parameter=badpixfiles (file stacks=yes)

Input bad pixel files

If the value is empty then the BPIXFILE keyword from the events files will be used to find the files to use.

A value of "CALDB" will use the CalDB bad-pixel file and "NONE" will use no bad-pixel file (the value is case insensitive). The bad-pixel file is not required to run the script, but care should be taken when analyzing the output if it is not used.

The bad-pixel file has a name like acisf*bpix1.fits (chandra_repro) or <obsid>.bpix (reproject_obs). If you have used or created a custom bad-pixel file for the observations then these should be used.

Use the stack syntax - see 'ahelp stack' - to specify multiple files either as a comma (or space) separated list of file names or read from a file using the '@' syntax.

The order of the bad-pixel files do not need to match that of the infiles parameter.

Parameter=maskfiles (file stacks=yes)

Input mask files

If the parameter is empty then the MASKFILE keyword in the events files will be used. A value of "NONE" will use no mask file in the analysis; in this case care should be taken when analyzing the results since the exposure map will not be correct if the data was taken using a sub array (i.e. not all the chips or ccds were read out).

The mask file has a name like acisf*msk1.fits (chandra_repro) or <obsid>.mask (reproject_obs).

Use the stack syntax - see 'ahelp stack' - to specify multiple files either as a comma (or space) separated list of file names or read from a file using the '@' syntax.

The order of the mask files do not need to match that of the infiles parameter.

Parameter=dtffiles (file stacks=yes)

Input dtf files for HRC observations

This parameter is only used with HRC observations.

If the parameter is empty then the DTFFILE keyword in the events files will be used. A value of "NONE" will mean that only a mean DTF value will be used.

The file has a name like hrcf*dtf1.fits (chandra_repro) or <obsid>.dtf (reproject_obs).

Use the stack syntax - see 'ahelp stack' - to specify multiple files either as a comma (or space) separated list of file names or read from a file using the '@' syntax.

The order of the dtf files does not need to match that of the infiles parameter.

Parameter=units (string default=default)

Units for the exposure map

This parameter determines the units of the instrument and exposure maps.

This parameter combines the normalize parameter of mkexpmap and the modifiers for the detsubsys and mirror parameters of mkinstmap (see 'ahelp ardlib').

What is units=time equivalent to?

When units=time is used, instrument maps are created with the additional settings:

• ";IDEAL" is appended to the detsubsys parameter to remove any correction for the detector quantum efficiency (QE), quantum efficiency uniformities (QEU), or the ACIS contamination model;
• the mirror parameter is set to "HRMA;area=1" rather than "HRMA" to ignore the effective area of the Chandra mirrors;
• and the dafile parameter is set to "NONE" to remove the ACIS "dead area" correction, which accounts for the (small) decrease in detector efficiency due to the background cosmic ray flux.

The result is that the instrument map pixels have values of 0 or 1.

Parameter=expmapthresh (string default=1.5%)

Remove low-exposure regions?

If set to "" then no clipping of the counts images or exposure maps is performed before creating the exposure-corrected image.

When set, the parameter determines how the per-observation counts image and exposure maps are clipped before being combined together to create the exposure-corrected image. This can be used to exclude those pixels at the edge of a chip which, due to the strong gradient in the exposure map, end up dominating the final image.

For a full list of supported options, see the description of the cut parameter of dmimgthresh. Here we discuss the two most common options:

• expmapthresh="2%", which excludes those pixels where the exposure map falls below 2% of its peak value,
• and expmapthresh="100", which excludes those pixels where the exposure map value is less than 100 (in this case the value of the units parameter is important).

Note that both the counts image and the exposure map for each observation are thresholded before being combined together rather than the thresholding being applied to the final, coadded, image and exposure map.

Parameter=background (string default=default)

Method for background removal (HRC-I)

This parameter is only used for HRC-I data. The reason for subtracting the particle background component is to help remove the "rings" seen in exposure-corrected HRC-I data, but does significantly increase the time taken to run the script.

If set to "none", or no HRC-I background CALDB files can not be found, then the data is processed with no background subtraction. Observations for which a HRC-I background file can not be found - when background is not set to "none" - will be removed from the analysis.

method=default

This is the same as method=time.

method=time

This setting scales the background file by the ratio of the observation to background exposure times. It is the method used in the thread discussed above.

method=particle

This option scales the background by the ratio of the counts in the range determined by the bkgparams parameter, rather than by exposure time.

Header keywords

The full path to the selected background event file is added to the header file of the background-subtracted image and fluxed image using the BEVTFILE keyword. The scaling method and factor are added to the relevant files using the BKGMETH and BKGSCALE keywords, respectively.

Parameter=bkgparams (string default=[pi=300:500])

Optional argument for background subtraction

This is only used when background subtraction occurs and the method being used is set to "particle". The parameter is taken to be a Data Model filter to apply to both the observation and the particle background file, and is expected to be of the form "[pi=lo:hi]". It is used to select a subset of the observation that represents the particle background - i.e. it is not strongly "contaminated" by cosmic emission - but is close enough (in PI) to the source emission to minimise differences in the spectral shape of the particle emission between the observation and that seen in the background observations.

Parameter=psfecf (real default=INDEF min=0 max=1)

If set, create PSF map with this ECF

If set, create a "PSF map" image, which contains the radius of the PSF which contains this ECF for each pixel, in arcseconds. The calculation is done by the mkpsfmap tool, and the energy is taken to be the same value used to create the exposure maps (the effective energy described in the the bands parameter or the weight file).

The output files are identified by the label "psfmap". The combined version is controlled by the psfmerge parameter.

Note

The PSF sizes are calculated using a number of approximations and so should not be used for detailed analysis of sources, where the PSF should be modelled as discussed in the CIAO PSF Central documentation.

Parameter=psfmerge (string default=min)

How are the PSF maps combined?

There is no one "correct" way to combine the per-observation PSF maps, so this script provides several options, which are controlled by the psfmerge parameter. The output file is identified by the label "psfmap".

The available options for psfmerge are: exptime, expmap, min, max, mean, median, and mid.

psfmerge=exptime

Weight each pixel by the exposure time of the observation, dividing by the total exposure time observed by the pixel.

psfmerge=expmap

Weight each pixel by the exposure map of the observation, dividing by the sum of the exposure map values for the pixel. This result should be similar to using the "exptime" method, but will include features seen in the exposure maps, such as bad pixels and columns.

psfmerge=min

Use the minimum PSF size for each pixel.

psfmerge=max

Use the maximum PSF size for each pixel.

psfmerge=mean

Use the average PSF size for each pixel.

psfmerge=median

Use the median of the PSF sizes for each pixel. If there are an even number (n) values to chose from, then the median is taken to be the n/2-th value, rather than averaging the (n/2) and (n/2)+1 values.

psfmerge=mid

Use the mid-point of the PSF sizes for each pixel. This finds the minimum (min) and maximum (max) PSF size for a pixel and uses (min + max) / 2.

Parameter=random (integer default=0 min=0)

Random seed for randomization.

The random parameter is sent to reproject_events when processing the HRC-I background files to match the observation. A value of 0 uses the system time to seed the random number generator.

Parameter=parallel (boolean default=yes)

Run processes in parallel?

When run on a multi-processor system, many of the tasks can be run in parallel to reduce the execution time of the script. Since the tasks are likely to be memory or I/O-bound, the reduction in run time will be less than the number of cores on a machine. When parallel=yes, the default behaviour is to use all the CPU processors, but this can be changed with the nproc parameter.

This option can be ignored when run on a single-processor system.

Parameter=nproc (integer default=INDEF)

Number of processors to use

This parameter is only used when parallel=yes. It determines the number of processors to use. If maxproc is the actual number of processors on your machine, then a value of INDEF - the default value - means that all maxproc processors will be used. A positive value means to use that number of processors (any value larger than maxproc will be set to maxproc). A negative value is added to maxproc (and any value less than one is set to one).

Parameter=tmpdir (string default=${ASCDS_WORK_PATH})

Directory for temporary files.

Directory for storing temporary files that require further processing before becoming useful. If the directory does not exist then it will be created for use by the script, and then deleted.

Parameter=cleanup (boolean default=yes)

Cleanup intermediary files on exit.

If set to "yes", the intermediate data products are deleted when the script ends, leaving only: the reprojected event files; merged event file; per-observation images, exposure maps, and exposure-corrected images; and the combined images, exposure maps, and exposure-corrected images.

Parameter=clobber (boolean default=no)

Overwrite existing files?

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

Output verbosity.

The default verbosity value of 1 prints status messages as the script runs. Higher verbosity settings print the commands that are being run. Setting verbose=0 turns off most of the screen output (some output is currently unavoidable).

Energy bands

The energy bands - when given by name - are taken from the Chandra Source Catalog definitions. The default bands setting (i.e. "default") means to use the "broad" band setting for ACIS data and the "wide" band setting for HRC data. Another common choice (for ACIS data) is "csc", which creates the "soft", "medium", and "hard" bands.

The examples and description of the band parameter describe how explicit energy ranges and effective energies can be specified if required. A spectral weights file can also be used if required.

Examples of specifying the bands are:

unix% flux_obs \*evt2.fits out/
unix% flux_obs \*evt2.fits out/ bands=csc
unix% flux_obs @evt2.lis out/ bands=0.5:2:1.7
unix% flux_obs @evt2.lis out/ bands=csc,broad
unix% flux_obs @evt2.lis out/ bands=wgt.dat

which use

• the default band (so broad for ACIS, wide for HRC),
• the CSC setting (soft, medium, and hard bands),
• an explicit range of 0.5 to 2 keV with an exposure map evaluated at 1.7 keV,
• four bands (soft, medium, hard, and broad),
• and a spectral-weights file (wgt.dat), created either manually or with the make_instmap_weights script.

The examples and description of the bands parameter describe how either

• explicit energy or PI ranges and effective energies,
• or a spectral weights file

can be specified.

ACIS low-energy bands and the ACIS contamination

Please review the Monochromatic Energy for Low Energy Bands document for the latest information on how the ACIS contamination layer can affect the analysis when using a mono-chromatic energy for calculating exposure maps, such as setting the bands parameter to one of the CSC bands (in particular the soft band).

Parallel processing

The execution time can be reduced by running some steps in parallel. This is controlled by the parallel flag, which defaults to yes. The nproc parameter controls the number of processors that will be used; the default is to use all of then. If run on a single-processor machine then both parameters are ignored.

Output files

The primary output files are named using the following schemes:

Combined data

Per-observation data

where blabel is either the band name (e.g. soft, broad, ...), "lo-hi" where lo and hi are the limits of the range (keV for ACIS, PI for HRC), or band1 to bandn (when using spectral weight files). The above is when outroot does not end in a "/"; if it does then remove "outroot_" and the files will be created in the directory named by outroot. Examples of the exposure-corrected image name for a combination of bands and outroot settings are given in the following table:

Names of the exposure-corrected coadded images

For HRC data, using bands=::eval results in a label of "all" being used.

Interleaved mode

For interleaved-mode data, "e1" or "e2" is appended to the ObsId value when creating file names.

Multi-OBI datasets

There are 30 ObsIds which contain multiple OBI segments. If the data has been split using splitobs then they can be combined using merge_obs, but the ObsId labels will contain the suffix _00n (where n is the OBI_NUM value from the header).

Output image area and size

The default behavior - when xygrid="" - is to calculate the output image size so that it covers all the data: a FOV file is created for the observation and the limits of this file are used to determine the X and Y range of the image. In this mode the binning is set by either the maxsize or binzise parameters. The maxsize parameter - if set - determines the maximum number of pixels used along the longest edge of the output, otherwise the binsize parameter is used. This parameter is in units of the native pixel size (i.e. 0.492" for ACIS and 0.1318" for HRC), and can be set to sub-pixel values (e.g. 0.5).

The tool can also be given an explicit grid for the output image size using the xygrid parameter (in this mode the binsize parameter is ignored). The grid can either be:

• a filename,
• or a grid specification, of the form "xlo:xhi:#nx or dx,ylo:yhi:#ny or dy".

When given a file, the sky range of the file is used for the output (e.g. the get_sky_limits tool is run on the file and its xygrid parameter value is used). Otherwise, the grid is given using the same format as the xygrid parameter of mkexpmap; examples include:

3824.5:5112.5:8,4008.5:5296.5:8

and

3824.5:5112.5:#161,4008.5:5296.5:#161

If the requested grid results in the last row or column being partially filled - in other words the width or height divided by the bin size is not a whole number - then the exposure map values in the column or row will be over estimated (since they are calculated assuming that the pixel is "full").

Handling filter or grids that do not overlap the observation

The tool will error out when there is no overlap between the observation and the xygrid (if given) or any spatial filter applied to the input file.

Required data files

For observations that has been reprocessed by chandra_repro - and optionally reprojected by reproject_obs - then all that is needed is to give the events file since the required ancillary files can be found using the header of the events file. These ancillary files can be located in one of the following directories, relative to the events file:

• .
• repro/
• primary/
• secondary/
• ../repro/
• ../primary/
• ../secondary/

If the files are not in one of these directories, they have been renamed, or new versions have been created during your analysis (e.g. a new bad-pixel file or a reprojected aspect solution created by reproject_aspect) then they can be explicitly set using the following parameters:

Ancillary data products

The only required information is that provided by the aspect solution file(s); any other file can be ignored, (either explicitly, by setting the parameter to NONE, or implicitly because it can not be found), in which case the appropriate correction or information is ignored.

Processing steps

An overview of how flux_obs works:

• The event files are checked to ensure they are all for the same instrument (ACIS-I and ACIS-S, HRC-I, or HRC-S). Event files with no data - perhaps because of a ccd_id filter - or that are for CC-mode observations are ignored.
• The ancillary files for these observations are found, if not given explicitly given, and matched up with the observations.
• For each new event file, images, exposure maps, exposure-corrected images, and an optional PSF map are created for the requested list of bands. An optional thresholding step is applied to both the image and exposure map when the expmapthresh parameter is set. This step is similar to running fluximage on each observation.
• A FOV file for each observation is created using the reprojected event files. These regions are combined to create the merged FOV file.
• For each band, the counts images and exposure maps are summed, and used to create exposure-corrected images, one per band. Any observation PSF maps are combined together, using the psfmerge-defined scheme, to create the output PSF map per band.

Changes in the scripts 4.14.0 (December 2021) release

When using the maxsize parameter, the calculated pixel size is now adjusted so that it does not have excessive precision: for instance a pixel size of 4.2 is now used rather than 4.19140625. This should allow the use of both the maxsize and the psfecf parameters (prior to this the combination could cause the script to fail).

The script now generates the FOV file for each reprojected event file and a combined region file (merged.fov) that includes all the individual observation FOV files.

There have been improvements to how the script handles a large number of observations.

Changes in the scripts 4.13.1 (March 2021) release

Ignore the frame-store shadow region

The frame-store shadow is now included when calculating the instrument map for ACIS observations. This means that a small number of rows of the instrument and exposure maps are now excluded, to match the data processing. Please see the ACIS frame-store caveat for more information.

Changes in the scripts 4.12.2 (April 2020) release

The script has been updated to support aspect solutions produced in the DS 10.8.3 release (or later). These files have a CONTENT keyword of ASPSOLOBI (earlier releases use ASPSOL), and can be used with skyfov when method=convexhull.

Changes in the scripts 4.11.1 (December 2018) release

The script will now create PSF maps for the observations if the psfecf parameter is set. The combined PSF map can be created using a variety of merging rules, such as weighting by the exposure time or using the minimum value.

Changes in the scripts 4.8.2 (January 2016) release

The random parameter has been added. It is used to control the random parameter of reproject_events when background subtracting HRC-I data.

Changes in the scripts 4.8.1 (December 2015) release

The code has been updated to avoid warning messages from NumPy version 1.9. There is no difference to how the script behaves.

Changes in the scripts 4.7.3 (June 2015) release

Order of DTF files

It is no longer necessary, when giving the DTF files explicitly (rather than the suggested approach of using the DTFFILE keyword in the event file), to give the files in the same order as the event files are given to the infiles parameter.

Improved support for multi-obi datasets

The script is now able to work with multi-obi datasets that have been processed by splitobs and then chandra_repro.

Changes in the scripts 4.6.6 (September 2014) release

Warning about different tangent points

The script will now only warn if the tangent points of two files differ by more than 0.05 arcsec.

Changes in the scripts 4.6.5 (June 2014) release

Filtering the aspect solution by the event file GTI

The skyfov is run in order to calculate the sky range covered by each observation; e.g. see ahelp get_fov_limits. The aspect solutions are now filtered by the good-time intervals (GTI) of the event file - that is, the script sets

aspect=asol1.fits[@evt.fits]

(assuming the aspect solution is called asol1.fits and the event file evt.fits) when calling skyfov. This should not change most results but may produce slightly-smaller output images in cases where the GTI of the observation covers only a small fraction of the aspect solution.

HRC-I analysis

It is now possible to apply a PI filter range for the images by specifying PI limits in the bands parameter, that is bands=30:200:1.2 will use a PI range of 30 to 200 when creating all the imaging products. The monochromatic energy used for the instrument map is still given in keV, so 1.2 keV in this example.

A new subtraction method, which scales the background to match the data using the ratio of the counts in the band PI=300:500 (this can be changed with the new bkgparams parameter), can be selected by setting method=particle. The default method uses the exposure times of the observation and particle background files for the scaling. The scaling method and factor are added to the relevant files using the BKGMETH and BKGSCALE keywords, respectively.

The status filter used to filter the HRC-I particle background file is now included in the screen output at the default verbosity level and added to the particle background files (retained when cleanup=no) using the STATFILT keyword. The background-unsubtracted files retained when cleanup=no now match the documentation (rather than include the typo 'undsubtracted').

Changes in the scripts 4.5.4 (August 2013) release

The description of the bands parameter has been updated to point out that when using the explicit format - e.g. a:b:c - for an energy band then the a and b values are required for ACIS data but should not be set for HRC data.

The handling of files with a DataModel filter has been improved.

Changes in the scripts 4.5.2 (April 2013) release

Event file selection

The script now skips event files which have an OBS_ID keyword of "Merged".

Interleaved mode data

The script will now include both the primary and secondary cycles (i.e. the "e1" and "e2" forms) of ACIS interleaved mode data. Previously it would just select one of the files (generally the "e1", which is the shorter of the two). If you only want to include one of the cycles then use an explicit list of observations. When processing interleaved-mode data, file names are labelled as "<obsid>e1" or "<obsid>e2".

Aspect solutions

The program now checks that the aspect-solution files are not aspect histograms.

Improved warnings and errors

The handling of missing ancillary files has been improved; if none of a particular type - such as the mask file - can be found then the program runs as if you has set that parameter to 'NONE', otherwise the error message now tells you what observation was missing a file.

Changes in the scripts 4.6.1 (December 2013) release

Removal of the pbkfiles parameter

The pbkfiles parameter has been removed as these files are no longer needed to run mkinstmap on ACIS observations. This means that it is no longer possible to turn off the ACIS dead-area correction for the exposure map; users who need this flexibility will have to generate the exposure maps manually (e.g. the ACIS single-chip thread).

For old data sets the removal of the pbkfile parameter can lead to error messages about missing keywords; in this case please download the latest archive version of your observation with download_chandra_obsid and then reprocess with chandra_repro.

Changes in the scripts 4.5.1 (December 2012) release

The script has been updated to work in CIAO 4.5.

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

There are no known bugs for this tool.

See Also

calibration

ardlib

psf

psf

tools

acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, addresp, aprates, asphist, combine_grating_spectra, combine_spectra, dither_region, dmarfadd, dmextract, eff2evt, flux_obs, fluximage, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, mean_energy_map, merge_obs, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, readout_bkg, reproject_obs, rmfimg, sky2tdet, specextract