Find the matching ACIS "blank-sky" dataset for an observation
With a parameter file:
acis_bkgrnd_lookup infile [outfile] [verbose]
Without a parameter file:
acis_bkgrnd_lookup chipids aimpoint infile [verbose]
The acis_bkgrnd_lookup script is used to find the ACIS background
(i.e. "blank sky") dataset from the CALDB that matches your observation.
It is suggested that - before using this tool - you read over the
ACIS Background Memos page, Maxim Markevitch's
ACIS background discussion, and the
ACIS Background Subtraction thread since
there are a number of these datasets available - some with unique
characteristics that may not be available from the CALDB.
When supplied with an event file, the script will determine
the aimpoint and set of ACIS CCDs covered by the file or
selected region. For this to happen, the parameter file
(acis_bkgrnd_lookup.par) should be made available as discussed
on the
Script Installation page.
An advantage to using the parameter file is that the results of
the CALDB search are written to the outfile parameter - and
so accessible by calling
pget acis_bkgrnd_lookup outfile
- as well as being written to the screen.
It is still possible to use the old syntax where you
manually specify the range of CCD numbers, the aimpoint,
and supply an event file.
For this to work you must give the three parameters
values on the command line (or 4, since you can also include the
verbose level) without specifying the parameter name:
so
unix% acis_bkgrnd_lookup 0123 i evt2.fits
will work, but
unix% acis_bkgrnd_lookup 0123 i infile=evt2.fits
will not.
In this mode the parameter file is ignored - so the
outfile parameter will not be set to the matched files; the
only output of this information is to the screen (i.e. stdout).
This mode has been marked as deprecated and will be removed
at a future date.
Due to the way the ACIS background files are created and
indexed in the CALDB there may not be one file per CCD:
for example recent ACIS-I observations tend to be covered
by one events file.
If more than one file is found then they are listed on the
screen one to a line and written to the parameter file - if
the new scheme is used - as a comma-separated list (i.e.
a stack).
Due to the large number of background files there may be more
than one that matches your data. In the case of such a match
this script returns the first file in the CALDB that matches the
search query used.
Prior to CIAO 3.0 this fact was hidden to users since such output
would have interferred with the screen output of the selected files.
With the
CIAO 3.0 release you will see a warning message from the CALDB
printed to the screen with such a match. This will look something
like:
# caldb (CIAO3.0): WARNING: 2 CALDB files found. Using the first
In such a case it is worth checking the ACIS Background documents
discussed above and in the
thread
to ensure you are using the most appropriate dataset for your
observation.
acis_bkgrnd_lookup evt2.fits
Here we use the new (to CIAO 3.0) syntax of just specifying the
event file. The script finds out the aimpoint from information in
the header of the file and scans the ccd_id column of
the event file to select what chips to look for.
For this to happen the parameter file (acis_bkgrnd_lookup.par)
should be made available as discussed on the
Script Installation page.
The matching file(s) are printed to the screen and stored in
the outfile parameter of the script. This can be retrieved
by saying:
pget acis_bkgrnd_lookup outfile
acis_bkgrnd_lookup "evt2.fits[sky=region(source.reg)]"
The input file can include any Data Model expression
(see "ahelp dmsyntax") as long as the resulting file is still
a table with a ccd_id column.
Here we use a spatial filter to filter the events file: the
resulting background file(s) will be chosen to match only the
CCDs that cover the region source.reg (due to the way the
background files are stored then it may be the case that the
selected file(s) still contain CCDs that aren't covered
by the spatial filter).
acis_bkgrnd_lookup 0123 i evt2.fits
Here we show an example of the old syntax - which is now
deprecated, and so will be removed at a future
date - that does not use a parameter file.
The set of CCD values to search for and the ACIS aimpoint
are explicitly given; the event file is only used to
find out the date of the observation in this mode.
Since this mode does not use a parameter file the
names of the ACIS background files are only printed
to the screen. They are not stored in the outfile parameter.
Event file for which you want background files
ACIS background file(s) to use
This parameter will be set to the name(s) of the
ACIS background files selected from the
CALDB to match your observation.
The file names include the full path.
If more than one file is selected then they will
be stored as a comma-separated stack.
Debug level (0=no debug information)
In most cases the default vrebose level (of 0)
is the correct value to use. Higher values may prove
useful when trig to track down problems with the
script.
Fixed a bug that caused the script to exit with an error rather than
write the the file name, or names, to the parameter file.
In CIAO 3.0 the suggested way to run the script is to give
it only parameter - the event file (which can include a
Data model virtual-file filter to restrict the data (see
"ahelp dmsyntax").
The old format is still supported but has been marked as deprecated
and will be removed in a future version.
The event-file only mode requires that the parameter file
for the script be installed.
Sere the
Script Installation page
for more details of this.
When the parameter-file mode is used the set of background
files is stored in the outfile parameter as well as printed
to the screen, making it easier to script.
Since the background files are now stored in the outfile
parameter, the script no longer hides the mesages from the
CALDB that one file from several was chosen. This message
is now displayed to the screen to indicate when potential
conflicts may arise. In such situations the ACIS background
documentation should be reviewed to find out what is the
most appropriate dataset to use for your observation.
The script has been re-written in S-Lang to take advantage of
CIAO 3.0 features - such as the availability of the
S-Lang parameter, pixlib, and caldb libraries.
The fact that the script is now written in S-Lang
rather than sh should not be obvious to you as a user.
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 the
installation instructions page
for help on installing the package.
As of the CALDB 3.0.0 release on December 14 2004, the ACIS background
files have been moved out of the main CALDB download file. They are now
packaged separately, and are available from the
CALDB download page.
- calibration
-
ardlib
- tools
-
acis_fef_lookup,
acis_set_ardlib,
acisspec,
add_grating_orders,
add_grating_spectra,
asphist,
dither_region,
dmarfadd,
dmfilth,
dmregrid,
fullgarf,
mkacisrmf,
mkarf,
mkexpmap,
mkgarf,
mkgrmf,
mkinstmap,
mkpsf,
mkrmf,
mkwarf,
psextract,
psf_project_ray,
rmfimg,
specextract
|
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}