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 :
- Statistics: calculates various statistics: min|max pixel value, centroid, net-counts, and fully calibrated aperture photometry (for Chandra event files).
- Histograms: create spectra, lightcurves, and radial profiles.
- Coordinates: Obtain coordinates for a region center or crosshair in various Chandra coordinate systems: chips, detector, sky, celestial. Also identify location of energies in Chandra dispered grating spectra.
- Regions: generate regions that enclose a fraction of flux, magic-wand style source selector (local contouring), and convex hulls.
- Detect: run source detection tools on images.
- Chandra PSF: look up the size of the Chandra PSF at a location, or determine the fraction of the PSF enclosed by a selected region. Users can also simulate the PSF using MARX.
- Sherpa: extract and fit spectra, 2D images, or radial profiles.
- Image Processing: adaptive smooth (including csmooth), adaptive bin, smooth (various kernels), non-linear filtering (median), fill in where sources have been removed (dmfilth), and more options.
- Calculator: add, subtract, multiply, divide, scale, offset, and more.
- Change DAX output directory: All outputs files are saved to a temporary directory; the default is $ASCDS_WORK_PATH/ds9_dax.$USER. Users can select a different directory.
- Custom Color Map: users can create a custom color map (color lookup table).
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
- Removed individual dmstat statistics
- Reformatted dmstat output
- Reformatted moments output
- Removed centroid snap task from menu
- Improved Help
- Net counts are now computed for the selected regions (if any) or all regions if none are selected. Also now uses the image as currently displayed rather (eg smoothed, filtered).
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).
- New `convert_ds9_region_to_ciao_stack` script replaces old awk script to expand ds9 regions: panda, epanda, bpanda, mutli-radii annulus, multi-radii ellipse, mutli-radii box. Also handles excluded regions.
- Radial profile task now uses image as displayed (eg smoothed/etc) instead of original file on disk.
- User can now select pixels are arcsec for radial profile task
- Extract along polygon now also plots data vs row-number, x, y, radius, or angle.
- Improved Help
Coordinates
- Removed individual coordinates; now always display all coordinates.
- Reformatted 'All' coordinates
- Coordinates are now computed at: The location of the crosshair, if in crosshair mode; Or, the center of the 1st selected circle|box|ellipse|annulus; Or, the center of the 1st non-selected circle|box|ellipse|annulus.
- Chandra Field-of-View task now run inside a wrapper script so that any error messages/etc are shown.
- Improved Help
Detect
- All detect tasks are now run with data as displayed rather than going back to file on disk.
- All detect tasks are now run inside a wrapper script so that any error messages/etc are shown.
- celldetect is now run with fixedcell=12
- Improved Help
Region
- All region tasks are now run with data as displayed rather than going back to file on disk.
- All region tasks are now run inside a wrapper script so that any error messages/etc are shown.
- New `contour` task runs `dmcontour` to create regions at specified levels. Interior holes are automatically excluded.
- Improved error checking in PSF Size task
- Improved Help
Sherpa
- Replaced chips plots with native ds9 blt plots.
- Spectral fit now gives user the choice of statistic (chi2gehrels|chi2xspecvar|cash|cstat|wstat), minimization method (levmar|neldermead|moncar), absorption model(xswabs|xsphabs)
- Removed clean cache task
- 2D Image fit now saves output model, residuals, and fitting commands. Model and Residuals are now displayed in separate, tiled, frames.
- New Radial Profile Fit task. Computes and fits radial profile with 1 or 2 additive model components from gauss1d|beta1d|const1d|lorentz1d|polynom1d|powlaw1d
- Improved Help
Image Processing
- All tasks are now run inside a wrapper script so that any error messages/etc are shown.
- Updated Source Fill task to no longer rely on user Grouping source and background regions. The script now requires 1-to-1 src-to-background region matches.
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
- The stacked shapes (panda, annulus, elliptical annulus, box annulus, etc.) only work with the radial profile task.
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.