fluximage

Synopsis

Create exposure-corrected images and exposure maps for an observation.

fluximage  infile outroot [bands] [xygrid] [binsize] [asolfile]
[badpixfile] [maskfile] [pbkfile] [dtffile] [units] [expmapthresh]
[background] [parallel] [nproc] [tmpdir] [cleanup] [clobber] [verbose]

Description

The fluximage script creates exposure-corrected images of an ACIS or HRC observation given an events file and one or more energy bands. It automates the creation of the aspect histogram, instrument, and exposure maps. The output image size can be automatically chosen to cover all the data in the observation, or it can be set to match an existing image. For HRC-I observations, the HRC background files from the Chandra CALDB are used - if installed - to subtract off the particle background and so reduce the ring artifacts that can be seen in HRC-I data (this can be turned off by setting the hidden background parameter to "none").

For recently-processed data the script can be run with only two parameters: for example

unix% fluximage evt2.fits out/

creates a number of files in the directory out/, including the exposure-corrected image, out/broad_flux.img (ACIS) or out/wide_flux.img (HRC).

Example 1

unix% download_chandra_obsid 1843
unix% cd 1843
unix% chandra_repro indir=. outdir=repro
unix% fluximage . fluxed/
unix% ds9 fluxed/broad_flux.img

Here we download ObsId 1843 from the Chandra archive (an ACIS observation), reprocess it using chandra_repro, and then create an exposure-corrected image of the data using the CSC broad band (0.5 to 7 keV with an effective energy of 2.3 keV) in the directory fluxed/ (this directory will be created if it does not exist). As the infile parameter is set to a directory, the script searches for any files that match the pattern "./repro/*evt*", "./primary/*evt*", then "./*evt". In this case the script picks repro/acisf01843_repro_evt2.fits.

The output image contains all ACIS ccds that were on in the observation and has been binned to 8 ACIS pixels (so an output pixel scale of 3.936 arcseconds on a side). The events file is used to locate all the necessary files (which, due to chandra_repro, have all been copied to the repro/ directory). Finally ds9 is used to view the exposure-corrected image, the name of which includes the energy range, effective energy used and the binning factor.

Note that reprocessing your data - whether via chandra_repro or manually - is not required to use fluximage. It does however ensure that the necessary keywords are included in the events file (old data may be missing one or more of the keywords used to identify the ancillary data files) and that the latest calibrations have been applied.

Example 2

unix% fluximage repro/acisf01843_repro_evt2.fits fluxed/

This is a repeat of the previous example except that the event file to use is listed explicitly as the infile parameter value.

Example 3

unix% fluximage repro/ fluxed/ binsize=4 clobber+
unix% ds9 fluxed/broad_flux.img

Here we repeat the analysis but use half the bin size (4 instead of 8, giving a pixel size of 1.968 arcseconds on a side). The clobber mode has been set to yes to ensure the output from the previous example does not call the script to fail.

Example 4

unix% fluximage "evt2.fits[ccd_id<4]" acisi/ binsize=2

Here a Data Model filter is used to restrict the output to the ACIS I array (ie ccd_id values of 0 to 3). The output image axis range is calculated so that it just covers the data in the input events file (after applying any Data Model filters).

The script will reflect any previous filtering applied to the file, so the following will create the same output (the use of clobber ensures that the existing data will be over-written):

unix% dmcopy "evt2.fits[ccd_id<4]" acisi.evt
unix% fluximage acisi.evt acisi/ binsize=2 clobber=yes

Example 5

unix% fluximage evt2.fits fimg bands=csc,broad

In this example four separate exposure-corrected images are created: one each for the CSC soft, medium, hard and broad energy bands. As with the previous example the names of the ancillary files - such as bad-pixel file and aspect solution - are read from the header of the events file.

Since the outroot does not end with a / character then the the output files will be created in the same directory as the events file, with names like fimg_soft_flux.img.

It is also possible to run the script once for each band; so the following is equivalent to the single run above:

unix% fluximage evt2.fits fimg bands=soft
unix% fluximage evt2.fits fimg bands=medium
unix% fluximage evt2.fits fimg bands=hard
unix% fluximage evt2.fits fimg bands=broad

Example 6

unix% make_instmap_weights wgts.txt "xsphabs.gal*powlaw1d.pl" \
paramvals="gal.nh=0.45;pl.gamma=1.7" emin=0.5 emax=7 ewidth=0.25
unix% fluximage evt2.fits fimg/ bands=wgts.txt
unix% ds9 fimg/band1_flux.img

In this example we use a weights file (wgts.txt), created by make_instmap_weights, so that the exposure map is the weighted sum of a range of energies rather than evaluated at a single energy. The output files will be labelled "band1", so the exposure-corrected image will be called "fimg/band1_flux.fits". The energy range used to create the images is calculated from the contents of the weights file, so in this case 0.5 to 7 keV.

Example 7

unix% fluximage evt2.fits fimg bands=csc,0.5:7:3,wgt1.dat,wgt2.dat

Here we combine the three different forms for specifying an energy band - using a label ("csc"), an explicit range ("0.5:7:3"), and weights files ("wgt1.dat" and "wgt2.dat") to create 6 exposure-corrected images. The files using the weights file "wgt1.dat" are labelled "band1" and those using "wgt2.dat" are labelled "band2".

Example 8

unix% download_chandra_obsid 144
unix% cd 144
unix% chandra_repro indir=. outdir=repro
unix% fluximage repro/hrcf00144_repro_evt2.fits fluxed/
unix% ds9 fluxed/wide_flux.img

Here we use a HRC-I observation, for which the default "bands=default" setting is the same as setting "bands=wide". The "wide" band uses all events (since the spectral response of HRC-I is so broad), and evaluates the exposure map at an energy of 1.5 keV. The default binning value for HRC data is 32. If the Chandra CALDB package "HRC background event files" is installed then the appropriate background file will be subtracted from your data in order to ring artifacts that can be seen in HRC-I data. To turn off this step, set the background parameter to "none"; e.g.

unix% pset fluximage background=none
unix% fluximage repro/hrcf00144_repro_evt2.fits fluxed2/

Example 9

unix% fluximage evt2.fits fi_ bands=csc xygrid=acisi/broad.img

Here we use multiple bands (csc is a short form for "soft,medium,hard"), write files to the current directory with a prefix of "fi_" (rather than to a separate directory), and use the xygrid parameter to make the data match the sky area covered by the acisi/broad.img (in this case the result of a previous run of the script but it can be any file which can be processed by the get_sky_limits script). The binsize parameter is not used in this case.

Example 10

unix% pset fluximage xygrid="3428.5:5476.5:2,6874.5:7898.5:2"
unix% fluximage evt2.fits zoom

Here we explicitly give the grid for the output images.

Example 11

unix% fluximage repro/ fluxed/ parallel=no

In this case, by setting parallel to no, only a single processor will be used.

Example 12

unix% fluximage repro/ fluxed/ nproc=-1

The nproc parameter allows you to control the number of processors that are used; in this case (nproc=-1), all-but-one of them (if your machine has 4 processors then nproc=3 could be used instead).

Example 13

unix% fluximage evt2.fits fimg badpixfile=caldb

Here we use the bad-pixel file in the CALDB, rather than the observation-specific bad-pixel file (the value of the BPIXFILE keyword in evt2.fits).

Example 14

unix% fluximage evt2.fits fimg bands=0.5:6:2 parallel=no
unix% ds9 fimg_0.5-6_flux.img

Here a manually-specified band is used - 0.5 to 6 keV with an effective energy (that is, the energy used to calculate the exposure map), of 2 keV.

The computation only uses a single processor since the parallel parameter is set to no.

Example 15

unix% fluximage evt2.fits out badpixfile=bpix1.fits asolfile=@asol.lis
pbkfile=NONE

In this example most of the ancillary data files are specified explicitly rather than read in from the header of the events file. The aspect solution is read in from the stack of files listed in the file asol.lis (see 'ahelp stack' for more information on this syntax); the bad-pixel file is taken from bpix1.fits and the parameter-block file is ignored (which will result in warning messages from the script and an exposure map which does not include the ACIS dead-area correction).

Since the maskfile parameter has not been given, and so defaults to "", it's value will be read from the events file evt2.fits.

Example 16

unix% fluximage "evt2.fits[sky=box(4096,4096,600,600)]" acisi/
binsize=0.25

Here the exposure-corrected image is created using pixels that are a quarter the width of the default ACIS pixel. A spatial filter has been applied to restrict the calculation to a small area around the aim point of the observation, since this is where the Chandra spatial resolution is high enough to make this analysis worthwhile.

Example 17

unix% fluximage evt2.fits qlook_ units=time

Here we use the units parameter to create an exposure map which has units of seconds, so the exposure-corrected image will have units of count/s. In this case the monochromatic setting used as part of the bands setting is ignored; that is bands=broad and bands=0.5:7:1 will produce the same output (since they both use an energy filter of 0.5 to 7.0 keV).

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required)

The events file to use.

The events file can include Data Model filters to restrict the area used, or the chips processed; for example

infile="evt2.fits[sky=region(clus.reg)]"

This file is used to determine the location of the ancillary files - such as aspect solution, bad-pixel, pbk file - if they are not explicitly given. If you have used chandra_repro to reprocess your data then all the necessary files will be in the same directory as the reprocessed events file.

Using a directory name

If the infile parameter is set to a directory name - e.g. "repro" or "." - then the following search is made, where dirname represents the directory name used:

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

The script will display which file it finds. If there are no matches, or multiple matches in the same directory then the script will fail. DataModel filters - such as "[ccd_id=0:3]" - can not be used when only a directory name is given.

Parameter=outroot (string required)

Root name for the 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 band, or bands, should be used?

The script will create an exposure-corrected image - along with supporting data products - for each energy 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, maximum and effective-energy values 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 lo, hi and eff give the minimum, maximum and effective energies to use for the band (values are in keV). The low and or high values can be left blank, in which case all data is used, but it is suggested that this is only used for HRC data.

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"

HRC data

Since the HRC has no real energy resolution when in imaging mode, the low and high energy values should not be used; that is you should use either the wide band or use a value like "::1.5". Multiple bands are not supported with HRC data.

Parameter=xygrid (string default=)

xygrid for output or filename

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 input data. In this mode the bin size is determined by the binsize parameter.

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".

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

Image binning factor

This parameter is only used when xygrid is set to "" (which is the default setting).

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.

Parameter=asolfile (file stacks=yes)

Aspect solution for the observation.

If the value is empty then the ASOLFILE keyword from the events file will be used to find the file(s) 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 and are included in the output directory of the chandra_repro script. If multiple asol files exist for the observation and you want to explicitly select them - rather than use the file names given in the ASOLFILE keyword - then use the stack syntax (e.g. a comma, or space, separated string as described in "ahelp stack" for more information). So to use asol1.fits and asol2.fits you could say

asolfile="asol1.fits,asol2.fits"

or

asolfile="asol1.fits asol2.fits"

The files do not have to be given in time order.

Parameter=badpixfile (file)

Input bad pixel file

If the parameter is empty then the BPIXFILE keyword in the events file will be used.

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 and is included in the output directory of the chandra_repro script. If you have used or created a custom bad-pixel file for the observation then this should be used.

Parameter=maskfile (file)

Mask file for the observation.

If the parameter is empty then the MASKFILE keyword in the events file 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 and is included in the output directory of the chandra_repro script.

Parameter=pbkfile (file)

Input pbk file for ACIS observations

This parameter is only used with ACIS observations.

If the parameter is empty then the PBKFILE keyword in the events file will be used. A value of "NONE" will use no parameter block in the analysis, which means that the cosmic-ray induced dead-area correction will not be included in the exposure map.

The parameter block has a name like acisf*pbk0.fits and is included in the output directory of the chandra_repro script.

Parameter=dtffile (file)

Input dtf file for HRC observations

This parameter is only used with HRC observations.

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

The parameter block has a name like hrcf*dtf1.fits and is included in the output directory of the chandra_repro script.

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').

Converting from the normalize parameter

To replicate the old normalize=no setting, use units=default and for normalize=yes use units=area.

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 image or exposure map is performed before creating the exposure-corrected image.

When set, the parameter determines how the counts image and exposure map 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 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 are thresholded before being combined (this is new to the October 2012 release; in earlier versions only the counts image was clipped).

Parameter=background (string default=default)

Method for background removal (HRC-I)

This parameter is only used for HRC-I data. If set to "none" then the data is processed with no background subtraction. When set to "default" - and the HRC-I background CALDB package has been installed - then the particle background is subtracted using the HRC-I background event files. The background-subtraction step should help to remove the "rings" seen in exposure-corrected HRC-I data.

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 counts image, clipped counts image, combined exposure map, and exposure-corrected image.

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.

Examples of specifying the bands are:

unix% fluximage evt2.fits out/
unix% fluximage evt2.fits out/ bands=soft
unix% fluximage evt2.fits out/ bands=csc
unix% fluximage evt2.fits out/ bands=csc,broad
unix% fluximage evt2.fits out/ bands=wgt.dat

which use

• the default band (so broad for ACIS, wide for HRC),
• the soft band,
• the CSC bands (i.e. soft, medium, and hard),
• and 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 band parameter below describe how explicit energy ranges and effective energies can be specified if required. A spectral weights file can also be used if required (this feature is new in the October 2012 release).

Parallel processing

When analyzing an observation with multiple chips (ACIS) or HRC-S plates, or if using multiple energy bands, 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 (new in the October 2012 release) 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 scheme (which has been changed in the October 2012 release):

where elabel is either the band name (e.g. soft, broad, ...), "elo-ehi" where elo and ehi are the limits of the energy range used in keV, or band1 to bandn (when using spectral weight files). The Flag column indicates when the file is created (when cleanup=yes): A indicates always, T is for when the expmapthresh parameter is set, and E is for when the the expmapthresh parameter is empty.

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 images

For HRC data the label is either "wide" or - if bands=::eval is used - then the label "all" is used.

The intermediary files follow the same rule for outroot and have the form given below, where ccd refers to the plate number for HRC data:

By default, the intermediary per-chip data products are removed after the script has completed running. To save these (potentially numerous) files, set the cleanup parameter to 'no'.

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 the binzise 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").

Prior to the October 2012 release the binsize parameter was a required parameter; it is now a hidden parameter set to 8 (ACIS) or 32 (HRC) by default. The xygrid parameter is new in this release.

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, 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 (the chandra_repro script ensures that all the files needed for this script are copied to the same directory as 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

The script primarily makes use of the asphist, mkinstmap, and mkexpmap tools; generally following the outline of the "Step-by-Step Guide" sections of the "Exposure Maps" threads of the "Imaging" science analysis threads. The following steps are taken to create the data products:

• skyfov and get_fov_limits: to determine the output image area
• dmcopy: to create an events image with the specified binning factor
• hrc_bkgrnd_lookup, reproject_events, and dmimgcalc: to subtract the particle background (HRC-I only)
• asphist: to build the aspect histogram(s)
• mkinstmap: to calculate the instrument map(s) for the effective energy given for each energy band
• mkexpmap: to calculate the exposure map(s) in each energy band
• dmimgcalc: to combine the exposure maps if there are multiple ACIS CCDs or HRC-S plates
• dmimgthresh: to make a "threshold cut" before dividing the image by the exposure map, to reduce the noise at the edge of the chip (optional)
• dmimgcalc: to normalize the image by the exposure map

Changes in the October 2012 Release

Parameter changes

The bands and binsize parameters are now hidden parameter, three new hidden parameters have been added (xygrid, background, and nproc), and the normalize parameter has been replaced by the units parameter.

The changes mean that it is possible to run fluximage with just two parameters, for example:

unix% fluximage 50/ pillar/
unix% fluximage 50/repro/acisf00050_repro_evt2.fits pillar/

In the first call, as a directory is given, the script will search for files that match the patterns "50/repro/*evt*", then "50/primary/*evt*", then "50/*evt*", stopping at the first match (multiple matches within a directory will cause the script to error out). To avoid confusion you can specify the event file directly, as shown in the second call.

Spectrally-weighted exposure maps

Spectrally-weighted exposure maps can now be created, rather than using a single energy value to evaluate the effective area. The bands parameter will now accept a mkinstmap weights file - e.g. as produced by make_instmap_weights - and the files will be named "band1" to "bandn" (where n is the number of weights files given).

The default value of the bands parameter is now 'default', which means 'broad' for ACIS data and 'wide' for HRC data. The previous default was 'broad'.

Default binsize value

Now that binsize is a hidden parameter, it has a default setting of INDEF, which means 8 for ACIS data and 32 for HRC data.

File names

The output file names have been simplified by removing the binning value and monochromatic energy values and using the supplied band name where possible. As an example, the exposure-corrected image when bands=broad and outroot=out/ used to be called out/0.5_7.0-2.3_bin8_flux.img and is now out/broad_flux.img. The ENERGYLO and ENERGYHI keywords added to the files can be used to find out the energy limits used to create the files.

Units for the exposure map

In earlier versions, the exposure map was created with units of either cm^2 s count / photon or cm^2 count / photon. It is now possible to create an exposure map with units of s (ie. it contains no effective area information) by setting units=time. To accomodate this change, the normalize parameter has been removed; use units=default to get the same behavior as normalize=no and units=area for normalize=yes.

The units are now also propogated to the exposure-corrected image, so with units=default the final image will have units of '/cm**2 /sec', and if units=time then the result would have units of '/s'.

Aspect histogram creation

The binning used to create aspect histograms (i.e. the res_xy parameter of asphist) is now set to be the maximum of 0.5 arcsec and half the output grid size (converted to arcsec). This is done to avoid unnescessary work - and so reduce the time needed to run the script - when the bin size is large (greater than 2 for ACIS data and greater than 8 for HRC data).

HRC-I background subtraction

By setting the background parameter to "none", background subtraction will not be performed for HRC-I data. See the "rings" in HRC-I exposure-corrected images caveat for more information on this background subtraction.

Bug fix: grating data

In previous versions the instrument map - and hence exposure map - was over-estimated for grating data since the zeroth-order grating efficiency was not included in the calculation (mkinstmap was called with grating=NONE rather than grating=HETG or LETG).

Note that the effective area maps are not corrected for the diffracted counts that are excluded from the data, which results in an apparent drop in the surface brightness at the location of the grating arms. Also note that only the dispersed events from the primary target are removed when creating the exposure-corrected images.

Improved search for ancillary data products

In earlier versions, the ancillary data products were only searched for in the same directory as the event file, but they are now looked for in the following directories, relative to the event file:

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

This search is only done when the relevant parameter - asolfile, badpixfile, maskfile, pbkfile, or dtffile - is set to "", as it is by default.

Removed checks on PBK and DTF files

The script used to check that the PBK or DTF file - if given - covered the same time range as the events file. This check has been removed since it is not valid in all cases.

Improved support for using gzipped files

The script will now correctly handle the case when the bad-pixel file is gzipped. This fixes a bug introduced in the February 2012 release.

Defining the size and location of the output images

The default behavior - when xygrid="" - is to automatically calculate the area and location of the output images based on the input data; this is the same as in earlier releases, and uses the binsize parameter (which is now hidden).

Setting xygrid allows users to specify what area of the sky is used in the output images; the value can either be a filename or a grid specification (e.g. "3824.5:5112.5:#161,4008.5:5296.5:#161"). In this mode the binsize parameter is ignored.

Metadata

The ENERGYLO and ENERGYHI keywords are now added to the images; these give the minimum and maximum energies used to construct the image. The SPECTRUM, WGFILE, ENERG_LO, and ENERG_HI keywords from the instrument map (they define the spectrum file and energy range used to create the instrument map) are now copied over to the exposure maps and exposure-corrected image. This has been added since the file name no longer contains the energy used to evaluate the instrument map.

Changes in the February 2012 Release

Badpixfile parameter

Setting badpixfile=CALDB will use the CalDB bad-pixel file and badpixfile=NONE will use no bad-pixel file.

HRC-I background files

The HRC-I background events file, from the HRC background CALDB package, are now optional; if not found the background-subtraction stage will be skipped.

If the background files do exist then they are now correctly filtered before subtraction (the application of the STATUS filter was lost in the update of the script for CIAO 4.4). HRC-I products processed in CIAO 4.4 with a version of the script package earlier than 06 February 2012 should be re-run through fluximage to correct this problem.

HRC-I instrument maps

In earlier versions of the script, the HRC-I instrument map was generated at the native HRC resolution; the instrument map is now binned using the binsize parameter value to save time and memory.

Script version

The script version is now written as a COMMENT in the header of the output files; for instance

unix% dmlist 0.5-7.0_2.3_bin8_flux.img header,clean,raw | grep COMMENT | grep version
COMMENT      =  fluximage version 14 February 2012 /                     

Full support for the tmpdir parameter

The code has been updated so that all temporary files are created in the tmpdir; in previous versions several files were created in the current working directory which would cause the script to fail if you did not have write permission.

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

Caveats

WARNING about creating a large image  (11 Jul 2011)

If the chosen binning factor is small enough (e.g. binsize=1 for an ACIS-I observation) then the following warning will be seen:

# DMCOPY (CIAO): WARNING: Creating large image: 84 MB. Current max set at 50 MB.
Increase maximum using [opt mem=n] or increase blocking to reduce size.

The output files are completely valid; the warning is just there to let you know that the files that are being created are large. At present there is no way to hide this message.

See Also

calibration

ardlib

psf

psf

tools

acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, add_grating_orders, add_grating_spectra, addresp, asphist, combine_spectra, dither_region, dmarfadd, dmextract, eff2evt, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, mean_energy_map, merge_all, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsf, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, rmfimg, sky2tdet, specextract