Last modified: December 2021

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/find_mono_energy.html
AHELP for CIAO 4.14

find_mono_energy

Context: tools

Synopsis

Compute monochromatic for energy band given input spectrum and responses.

Syntax

find_mono_energy  arffile rmffile model paramvals band [metric]
[energy] [verbose]

Description

`find_mono_energy' can be used to compute a monochromatic energy appropriate for a specified energy band, spectral model, and instrument response. The script provides two options to compute the appropriate energy: either a spectrum weighted average value, or the energy where the spectrum is maximum.


Examples

Example 1

unix% find_mono_energy acis.arf acis.rmf \
model="xsphabs.abs1*xspowerlaw.pwrlaw" \
paramvals="pwrlaw.PhoIndex=2.0;abs1.nH=0.1" \
band=2.0:10.0 metric=mean

In this example, we find the monochromatic energy for an energy band that goes from 2.0 to 10.0 keV, using an ACIS ARF and RMF as inputs. We use an absorbed powerlaw as the spectral model and the output energy is computed as the spectrum weighted mean energy.

Example 2

unix% find_mono_energy acis.arf acis.rmf \
model="const1d.flat" paramvals= \
band=soft metric=max

In this example we use a flat/constant spectral model so the only weights are the effective area coming from ARF. We also use the CSC soft energy with energy limits going from 0.5 to 1.2 keV, and compute the monochromatic energy as the energy with the maximum spectrum, or in this case the maximum effective area in the band.

Not that in this case the result does not depend on the normalization of the model (flat.c0), so we use the default value by clearing out the paramvals parameter.


Parameters

name type def min max reqd
arffile file       yes
rmffile file       yes
model string       yes
paramvals string       yes
band string       yes
metric string mean      
energy real        
verbose integer 1 0 5  

Detailed Parameter Descriptions

Parameter=arffile (file required)

Input ARF file

The input ARF file is used to setup the energy grid the spectral model is evaluated over. The spectrum is weighted by the effective area in the ARF.

Parameter=rmffile (file required)

Input RMF file

The response matrix contains the mapping from spectral energy to observed pulse height channel. The spectrum is convolved with the RMF. Typically the RMF will have a minimal effect on the spectral weights unless the energy band is very narrow.

Parameter=model (string required)

Sherpa model expression

The spectral model is used to compute the weights used to compute the monochromatic energy.

A constant model can be used to produce weights which only include the effective area from the ARF.

model="const1d.flat" paramvals="flat.c0=100"

Parameter=paramvals (string required)

The parameter values for the spectral model.

This parameter contains the list of model parameter values, following the same scheme as modelflux, namely "id.parameter=value" settings separated by semi-colons. The id values are the names given in the model expression and ahelp on these names will list the available parameters.

Parameter=band (string required)

Desired energy band

The monochromatic energy is computed for a specific energy band.

Users can specify the band as a colon separate pair of values, eg

band=2.0:10.0

or can specify the band using the CSC nomenclature

Band name Minimum Energy Maximum Energy
broad 0.5 7.0
soft 0.5 1.2
medium 1.2 2.0
hard 2.0 7.0
ultrasoft 0.2 0.5
wide 0.1 10.0

Parameter=metric (string default=mean)

Metric used to compute the monochromatic energy

There are two options to compute the monochromatic energy

Parameter=energy (real)

The output monochromatic energy

The tool stores the value of the monochromatic energy in its own parameter file in the "energy" parameter. If there is a problem with the script, the energy parameter will be left blank.

The tool will also report the monochromatic energy to the terminal (if verbose>0).

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

Amount of tool chatter


Changes in the scripts 4.14.0 (December 2021) release

This script is new.

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.


Bugs

See the bugs page for this tool on 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.

See Also

calibration
ardlib
psf
psf
tools
acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, addresp, aprates, asphist, combine_grating_spectra, combine_spectra, dither_region, dmarfadd, dmextract, eff2evt, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psf_project_ray, readout_bkg, rmfimg, sky2tdet, specextract