Please read CXC Director Dr. Pat Slane's A Letter to the Community regarding NASA's plans to decommission Chandra.

Synopsis

Creates a Color-Color diagram

color_color  infile outfile model param1 grid1 param2 grid2 soft medium
hard [rmffile] [plot_oversample] [outplot] [showplot] [random_seed]
[clobber] [verbose]

Description

In X-ray astronomy, we often use the term "color" to mean the "hardness ratio", H

H = (h-s)/(h+s)

where 'h' and 's' are the counts in two independent energy bands (hard and soft). This ratio is restricted to the range [-1,1]. Values less than 0 indicate a "soft" source, values greater than 0 indicate a "hard" source.

One common use of hardness ratios is when there are too few counts to obtain a statistically meaningful spectral fit. Users can construct a "Color-Color" diagram to estimate the model parameters.

A color-color diagrams starts with an assumed spectral model, for example an absorbed power-law. The color-color diagram is constructed by varying two of the independent model parameters, for example the slope of the power-law model component and the neutral Hydrogen density in the absorption model component. The parameter values are varied over a few discrete values. By including the instrument response, we can then simulate the observed spectra. We compute the total number of simulated counts in 3 independent energy bands: soft, medium, hard; and then use those counts to construct a pair hardness ratios: hard-to-medium and medium-to-soft.

HM = (h-m)/(h+m)

MS = (m-s)/(m+s)

The color-color diagram then is constructed by plotting the HM and MS values and connecting the points that represent fixed values for each of the two model parameters. Users can then compute the hardness ratios for the sources in their observations and use the color-color plot to look-up what spectral model parameters yield the colors they computed.

The color_color script computes these hardness ratios by simulating the spectrum and folding it through the instrument response file (ARF). It does this using the sherpa fake() command to generate the simulated spectrum and the calc_data_sum() command to compute the counts in each of the 3 user specified energy bands.

Examples

Example 1

pset color_color model="xswabs.abs1*xspowerlaw.pwrlaw"
pset color_color param1=pwrlaw.PhoIndex
pset color_color grid1=1,2,3,4
pset color_color param2=abs1.nH
pset color_color grid2=0.01,0.1,0.2,0.5,1,10
pset color_color soft=csc medium=csc hard=csc
color_color acis.arf clr.fits mode=h showplot=yes outplot=clr.png clob+

In this example we create a color-color diagram assuming the spectrum is an absorbed power-law. The power-law photon index is varied over 4 values (1,2,3,4), and the absorption's nH is varied over 6 values (0.01,0.1,0.2,0.5,1,10). The 3 energy bands: soft, medium, and hard, are set to "csc" which means to use the same energy band definitions as the Chandra Source Catalog, ie soft=0.5:1.2keV, medium=1.2:2.0keV, and hard=2.0:7.0keV. An ACIS ARF, acis.arf, is used to model the detector response. Since no RMF was supplied, a diagonal RMF was used (which is OK as long as the energy bands are considerably wider than the spectral resolution).

With showplot=yes, the color-color diagram will be displayed on the screen and the plot will be saved to output=clr.png file.

The individual hardness ratio values are stored in a table in the outfile.

Using the tool, all the other model parameters are left at their default values. If users need to adjust other model parameters then they can use the Python module directly.

Example 2

Below is an example Python script which uses the color_color module to do the same thing as the tool does in the previous example. With the Python module, users can adjust the plot properties and alter the model expression: in this example the solar abundances are modified to use the Anders & Grevesse values.

from color_color import *
import sherpa.astro.ui as ui
soft = EnergyBand( 0.5, 1.2, 'S')
medium = EnergyBand(1.2, 2.0, 'M')
hard = EnergyBand(2.0, 7.0, 'H')
mymodel = ui.xswabs.abs1 * ui.xspowerlaw.pwrlaw
arffile = "acis.arf"

ui.set_xsabund("angr")

clr_model = ColorColor( mymodel, arffile )

pho_grid = [ 1., 2., 3., 4. ]
photon_index = ModelParameter( pwrlaw.PhoIndex, pho_grid, fine_grid_resolution=20)

sg = [ 1.e20, 1.e21, 2.e21, 5.e21, 1.e22, 1e23] 
nh_grid = [x/1e22 for x in sg ]
absorption = ModelParameter( abs1.nH, nh_grid, fine_grid_resolution=20)

clr_out = clr_model( photon_index, absorption, soft, medium, hard)

photon_index.set_curve_style(marker="", linestyle="-", linewidth=2, color="black")
photon_index.set_label_style(color="black")
absorption.set_curve_style(marker="", linestyle="-", linewidth=2, color="forestgreen")
absorption.set_label_style(color="forestgreen")

clr_out.plot()

The fine_grid_resolution parameter is used to over-sample the model parameters when drawing the curves. So for nH=0.01, the photon index is evaluated on 20 linearly spaced values between 0 and 1, 20 values between 2 and 3, and so on. This provides a smoother curve.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input ARF file name.

The instrument is modeled by the ARF file which gives the effective area vs. energy.

Parameter=outfile (file required filetype=output)

Output file name.

The output file is a table with 4 columns: The two model parameters and the two hardness ratios.

Note: the same pair of model parameter values may show up in the output file multiple times, and with slightly different values for the hardness ratios. This is because the HRs are computed from simulated spectra (using sherpa's fake() command) and as such are subject to randomization.

The output file will contain the following columns:

List of columns in the output file.

Note: The counts are based on the default model normalization values set by sherpa. This provides a large number of counts needed to reduce the statistical noise in the hardness ratio calculations; and as such the individual counts values are not expected to match any observed quantities.

Parameter=model (string required)

The sherpa model expression.

The sherpa model expression to use to compute the simulated spectra. For example xswabs.abs1*xspowerlaw.pwrlaw; which defines a simple powerlaw model and gives it the name "pwrlaw" multiplied by an absorption model given the name "abs1".

Parameter=param1 (string required)

The first parameter that will be varied to compute the color color plot.

This is the name of the model parameter, eg. pwrlaw.PhoIndex, that will be used to compute the color-color plot.

Parameter=grid1 (string required)

The grid of values for the 1st model parameter

The hardness ratios are compute with the param1 model parameter set to each of the values listed in the grid1 parameter.

Parameter=param2 (string required)

The second parameter that will be varied to compute the color-color plot.

Same as the param1 parameter, eg abs1.nH.

Parameter=grid2 (string required)

The grid of values for the 2nd model parameter

The hardness ratios are compute with the param2 model parameter set to each of the values listed in the grid2 parameter.

Parameter=soft (string required default=csc)

The energy range, in keV, to use for the soft-band in the form low:high

Users can specify "csc" to use the default CSC soft band of 0.5:1.2 keV.

Parameter=medium (string required default=csc)

The energy range, in keV, to use for the medium-band in the form low:high

Users can specify "csc" to use the default CSC medium band of 1.2:2.0 keV.

Parameter=hard (string required default=csc)

The energy range, in keV, to use for the hard-band in the form low:high

Users can specify "csc" to use the default CSC hard band of 2.0:7.0 keV.

Parameter=rmffile (file filetype=input)

An optional response matrix file (RMF).

If specified then the RMF will be used when simulating the spectrum. If no RMF file is provided then an ideal, diagonal RMF is used.

The effects of the RMF will be small as long as the energy bands are wide compared to the spectral resolution.

Parameter=plot_oversample (integer default=20)

How fine to sub-sample the user supplied grids.

To improve the quality of the plots, the grids are over-sampled by the plot_oversample amount. So for example with the default of 20, there will be 20 linearly space data points compute between each parameter value in each of the grids. A value of '1' means no over-sampling and only the exact grid values are used; this generally results in a poor plot.

Parameter=outplot (file filetype=output)

The output filename for the plot (should end in .png, .jpg, .eps, etc).

The plot can be saved by matplotlib in any of the formats it supports. The file type is taken from file name extension.

Parameter=showplot (boolean default=yes)

Should the plot be displayed?

If the plot is displayed, then the user must close the plot for the tool to complete.

Parameter=random_seed (integer default=-1 min=-1)

The seed value used to initialize the random number generator.

Setting the value to -1 will use a randomly selected random seed.

Parameter=clobber (boolean default=no)

Overwrite output files if they already exist?

Parameter=verbose (integer default=1 min=0 max=5)

Amount of tool chatter level.

Changes in the scripts 4.15.2 (April 2023) release

Updates to work when no DISPLAY is set.

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.

See Also

tools::response

modelflux

tools::statistics

aprates

utilities

calc_chisqr, calc_energy_flux, calc_model_sum, calc_photon_flux, calc_source_sum, calc_stat, gamma, igam, igamc, incbet, lgam