Last modified: September 2020

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

dax

Context: tools

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