Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/dax.html
AHELP for CIAO 4.16

dax

Context: Tools::Composite

Synopsis

Run CIAO tasks from the ds9 Analysis menu

Description

A number of common CIAO tasks are available from the ds9 Analysis menu. This menu addition allows users to get source counts, smooth an image, and create a histogram - among many other things - from the ds9 program in CIAO. The analysis menu tasks are known as "dax" (ds9 analysis extensions).

Getting Started

The commands are stored in the file $ASCDS_CONTRIB/config/ciao.ds9 and are automatically loaded when ds9 is launched within CIAO.

The user can also explicitly point to the file in the ds9 -analysis switch:

unix% ds9 -analysis $ASCDS_CONTRIB/config/ciao.ds9 ...
      

Using the Tools

Under ds9's Analysis menu, at the bottom will be a "CIAO tools (DAX)" option. Selecting "CIAO tools (DAX)" will display the category of CIAO tasks :

Calculating the Statistics

The options under the Statistics item use the combination of all defined regions to calculate the quantities. To exclude certain areas, define a region and use the "Region -> Properties" menu to set it to "exclude". If no regions are defined, the calculations are run on the entire image created at the current binning value.

Plotting

Plotting is done using the built in ds9 "BLT" plotting package. User can use the menu bar on the plot window to change the axes to log scale, change fonts and colors, etc.

Fitting

When fitting spectra, images, or radial profiles, users will be presented with a model parameter editor before the fit is performed. Users can specify the initial value, change the limits, and thaw|freeze the parameters.

Busy Indicator

Tasks which may take a while to run will launch a small window with the task name and a busy indicator (technically an indeterminate progress bar). To abort a running task, users need to select the task again from the DAX menu.


Changes in the 4.15.0 (December 2022) release

Blocked Images

dax now properly updates the WCS when ds9 has blocked the image being analyzed. Note: block is different than both zoom and bin, neither of which have this problem.

Interactive Gratings Coordinates

There is a new dax task: Coordinates -> Interactive Grating Coordinates Vector. It will draw a vector with the non-arrow end point located at the grating 0 order location (obtained from the REGION extension in the event file). Then as the user moves the end-point with the arrow around, an information box will pop-up that displays the grating coordinates. For HETG observations, the task will determine which grating arm the end-point is closest to and will compute the coordinates for that grating arm. Users can change the grating order by typing the value into the information box and pressing Enter.

PSF Contour

The new Regions -> PSF Contour task will use the center of all selected regions (or all regions if none are selected) and run the psf_contour tool. This tools simulates the Chandra PSF at each location and generates a region that encloses a fraction of the PSF. For overlapping regions: the PSF fraction is reduced until they no longer overlap or until a minimum PSF fraction of 60% is reached; after hitting that limit the regions are simply excluded from each other.

This task uses simulate_psf to run MARX, so the MARX_ROOT environment variable must be set to where MARX is installed. The download pages show how to install and setup MARX for both conda and ciao-install environments.

Fixed Counts Backgrounds

The new Regions -> Fixed Counts Backgrounds task will use the center of all selected regions (or all regions if non are selected) and run the bkg_fixed_counts tool. The tool creates background annulus regions located at the source location which include a minimum number of counts while excluding a fraction of the PSF (and additional source regions, if specified).

Fitting updates

The Sherpa fitting tasks have two changes: pressing the Cancel button when the Dax Model Editor will now produce a nicer message (rather than the raw Python traceback), and internal changes to suppress info about noticed/ignored channels/regions.

New non-linear filters

The following new dmimgfilt filters have been added to the Image Processing -> Non-Linear Filter task: ridge, plain, q10, q90, and jitter.

Changes in the 4.14.2 (April 2022) release

The "Cross Correlate" option has been added, which uses the acrosscorr tool to compare two frames. This can be used to look for positional shifts between the two images.

When working with a large region (such as many individual shapes or a polygon with many sides), dax will now save the region to a temporary FITS region file. This is to avoid problems with excessively long virtual file name filters.

Changes in the 4.14.0 (December 2021) release

Button Bar

DAX makes use of the new ds9 "buttonbar" analysis menu option (new in ds9 v8.4). Several of the most frequently used dax tasks are now available as buttons.

Automatically Launch Prism

For dax tasks that output tables or regions, users can now automatically open those output files using ds9's prism interface. To enable this options, users need to run this pset command before starting ds9:

$ pset dax prism=yes

Output image block names

Previously, many of the output images would have the block name set to the temporary file name. Now, the image's block name is set to the tool which created the image.

Sherpa

The sherpa spectral fitting tasks no allows the user to specify a second absorption model which is folded into the source expression. In addition, the default absoprtion model has been changed to "xsphabs" (previously it was "xswabs").

Adaptive Binning

The new dmradar tool is available as the Image Processing -> "Adaptive Bin (radial)" task. The classic "Adaptive Bin" task (aka dmnautilus) also now has the new "method" parameter to specify how many of the quadrants must exceed the SNR limit to be divided.

Changes in the 4.13.2 (June 2021) release

The Sherpa -> 2D Fitting task now allows users to specify a file name for the PSF and a file name for the exposure map to be used when fitting the image. Also renamed the model components to "Model 1" and "Model 2" instead of "Source" and "Background" since what was called the "background" was not fit separately.

If an exception occurs during a sherpa fit() operation, the text of the exception is now displayed in a dialog window.

Added a random_seed parameter to dax.par. This is currently used by the simulate_psf command; but available for future tasks which may need a random seed.

Changes in the 4.13.1 (March 2021) release

Added additional redshifted absorption spectral models.

Added energy limits to the photon and energy flux calculations. Previously, the fluxes were computed for the entire energy range rather than for just the noticed energy range.

Added button to run `conf` to the Model Editor GUI.

Changes in the 4.13.0 (December 2020) release

Updates to plotting spectral fit results to match changes in sherpa.

Changes in the 4.12.4 (September 2020) release

This is a major upgrade to DAX. It includes several new analysis tasks, a new sherpa model parameter editor, visual busy indicators for long running tasks, and a few bug fixes.

New Tasks and Features

New Detect -> wavdetect task is now available. Users select the wavelet scales which are used. Note: This task can be very slow for large images. wavdetect is run without an exposure map and without a PSF map; therefore there will tend to be spurious source detected at the edge of the field of view and sources will be reconstructed using the smallest wavelet they were detected at (possibly smaller than PSF).

New Coordinates -> Chandra Grating Energy Lookup. Users draw a region around the 0th order location; when this task is run, it will prompt the user for a list of Energies and Orders. The location of these energies and orders will be identified on the image. Only for Chandra observation which used the gratings (HETG or LETG).

New Image Processing -> Regrid task which allows the user to shift, scale, and rotate image pixel values. This task intentionally does not adjust the WCS.

New Image Processing -> Reproject tasks will do a full, flux preserving, reprojection of the image in the current frame to match the WCS in the previous frame.

New Image Processing -> Crop task. While ds9 does support cropping, the WCS in the saved image does not correctly update the WCS for the cropped out region.

New Chandra PSF -> Simulate PSF with MARX task allows users to simulate a monochromatic PSF using MARX.

New Create Custom Color Map task allows user to generate a new color map based on standard X11 color names, eg from black to cadetblue, to white.

New Histogram -> Dither Region computes the fraction of the region area exposed vs. time due to dither for Chandra datasets.

New Histogram -> Enclosed Counts Fraction computes the ECF in the selected region.

New Calculator tasks allow users to perform simple arithmetic calculations (add, multiply, divide, subtract) using the images displayed in 2 frames. Additional scaling functions are provided for the current frame.

Updates to Existing Tasks

The Sherpa fitting tasks: spectra, images, or radial profiles, now launch a new model parameter editor. Users can modify the initial model parameters, change the model limits, and thaw or freeze model parameters. Users can also plot the model and data easily before the fit to help refine the values.

The spectral fit and radial fit tasks now use a common set of plotting routines. The plots have been rearranged so that the model is now drawn on top of the data.

The list of spectral models has been expanded. Users can also now specify a 2nd model component to be added to the first.

The Detect -> celldetect task now allows users to change the fixed cellsize that is used. Users can also now supply the file name for an exposure map and a PSF map.

Most of the dax tasks are now run via a single wrapper script. This means more uniform handling of regions and output files.

Long running dax tasks will now launch a small "Busy Indicator" window with the tool name and an indeterminate progress bar. Note: closing the busy indicator does not terminate the task. To kill a running task users must reselect the same task.

Bug Fixes

Fix problem with Net Counts task where background counts and area are incorrectly reported as '0'. Net rate errors are now included in the Net Counts task. Also now verifies a single unique instance of ds9 is running.

Changes in the 4.12.2 (April 2020) release

Updated the CIAO -> Regions -> PSF Fraction task to force regions in ds9 format. This update prevents dax from hanging when users have modified their preferences to save regions in ciao format.

Changes in the 4.11.3 (May 2019) release

This release includes major changes to dax affecting most of the individual analysis tasks.

Output Files

Users can now select the directory where they want the DAX output file to be written. There is a new dax.par parameter file where users can specify the default output directory, outdir. Alternatively, user can set the DAX_OUTDIR environment variable, or they can change the output directory via the new 'Change DAX output directory' analysis task.

Statistics

Histograms

All of the histogram plots are now created using ds9 built-in "BLT" plotting package. Users can use the options in the menu bar to save (print) the figure and adjust the plot style (linear|log, fonts, colors). All of the tasks also now save the output file in the DAX_OUTDIR (as discussed above).

Coordinates

Detect

Region

Sherpa

Image Processing

Change DAX output directory

New task to allow users to change DAX output directory during the current analysis session. The directory selected is not saved. Use

pset dax outdir=directory

to permanently change the output directory.

Changes in the 4.11.1 (December 2018) release

Clarified error messages to indicate that users must have regions selected to perform spectral or spatial fits. Additional internal changes to use python scripts to perform sherpa fits rather than using sherpa IPython wrapper.

Changes in the 4.10.3 (October 2018) release

Updated to ensure that on systems where ds9 autoloads funtools or zhtools analysis tools, that it is still able to start the chipsServer in the background.

Internal updates to support ds9 v8.

Change in the 4.8.4 (September 2016) release

Several tasks have been updated to ensure that the desired region format is retrieved from ds9 instead of relying on the assumed defaults.

Changes in the 4.6.7 (November 2014) release

A new "Net Counts" option has been added that emulates the FUNTOOLs 'Counts in a region' functionality. This provides net counts and rates individually for each region.

The Aperture Photometry task has been renamed and moved. It is now available as the "Statistics -> Photometry (srcflux)" task.

The "All" statistics have been renamed "dmstat" to make it more clear which task is being run.

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.

Known Limitations


Bugs

See the CIAO website for an up-to-date listing of known bugs.

Refer to the CIAO bug pages for an up-to-date listing of known issues.