Preparing to Run ChaRT
![[CXC Logo]](../../imgs/cxc-logo.gif){kind=logo}
CIAO 4.16 Science Threads
Overview
Synopsis:
![[WARNING]](../../imgs/warning.png)
Users of the previous version of ChaRT will notice changes to the the interface and necessary inputs.
- Providing information about an aspect solution is the major new feature of ChaRT v2.
- In lieu of azimuthal and off-axis angles, ChaRT now allows users to input celestial coordinates.
- Exposure time is no longer tied to the source spectrum.
- The spectrum file has been changed to a 3-column (energy_lo, energy_hi, photon flux) format.
- For a monochromatic source spectrum, the ray density parameter has been replaced with a photon flux value.
Additional details of these changes, and how to handle them, are described in this thread.
This thread shows how to determine the parameter values needed to run ChaRT: the coordinates, spectrum, and telescope aspect solution.
It is important to read the caveats before running ChaRT and using the resulting PSF simulations in analysis.
Last Update: 22 Feb 2022 - Review for CIAO 4.14. Updated for Repro-5/CALDB 4.9.6
Contents
- Get Started
- Determine the Source Coordinates
- Specify Spectral Shape
- Aspect Information
- Additional Inputs
- Summary
- History
- Images
Get Started
Download the sample data: 942 (ACIS-S, NGC 4244)
unix% download_chandra_obsid 942
This thread assumes that the data have been reprocessed using the chandra_repro script.
Determine the Source Coordinates
The Chandra PSF varies significantly across the field of view. It goes from sub-arcsec FWHM near the optical axis to over 100 arcsec at the extreme edges of the detectors.
As such, the location of the source in the field is required to run ChaRT. The location can be entered in either celestial coordinates, Right Ascension and Declination (decimal degrees or sexagesimal format) or in Chandra off-axis angle, θ and ϕ, mirror spherical coordinates.
ChaRT now allows users to input celestial coordinates which is now the preferred coordinate system.
Celestial Coordinates
The coordinates of the source can be obtained in various ways such as from the output of the CIAO source detection tools (wavdetect, celldetect, or vtpdetect), by computing the centroid with dmstat, via an external catalog such as the Chandra Source Catalog, or by visual inspection. The later approach is used as illustration in this thread. The event file is displayed in ds9
unix% ds9 acisf00942_repro_evt2.fits
Figure 1 shows the data for OBS_ID 942. The coordinates for the source have been manually selected and are shown in the pop-up window.
Figure 1: Image of OBS_ID 942
![[Thumbnail image: image of obs_id 942]](ds9.png)
[Version: full-size]
Figure 1: Image of OBS_ID 942
An image of OBS_ID 942, NGC 4244 (no energy filter applied). The left frame shows data for the entire observation. The right frame is zoomed into the source that is going to be analyzed in this thread.
Moving the mouse pointer over the center of the source and pressing the "c" key displays the coordinates at that location in a new window. The coordinate for the source are
12:16:56.990 +37:43:35.69
Alternatively, users can simply read and manually record the values from the fk5 line in the information panel.
Detector Coordinates
User can input these celestial coordinate directly into ChaRT. ChaRT also accepts inputs in Chandra off-axis angles (mirror spherical coordinates). The RA and Dec can be converted to theta and phi using dmcoords:
unix% punlearn dmcoords unix% dmcoords acisf00942_repro_evt2.fits op=cel ra=12:16:56.990 dec=+37:43:35.69 celfmt=hms unix% pget dmcoords theta phi 5.962619244223243 197.0927445449041
This shows that this source is approximately 5.96 arcmin offset from the optical axis (theta) and 197.1 degrees rotation in azimuth (phi).
Specify Spectral Shape
The Chandra PSF varies with energy as well as position. ChaRT allows users to specify the spectral shape as either a single monochromatic energy or allows the user to upload the spectrum as a file.
Veteran ChaRT users will also notice that exposure time is no longer tied to spectral shape. Information about observation duration is discussed below in the aspect solution section.
Upload spectrum file
Users may upload a file describing the spectrum of their source.
The format of the file is any format support by the CXC Datamodel (FITS and various ASCII formats). The file must be a table with only 3 columns. The first two columns must be the lower and upper energy boundaries, in keV; the values must be between 0.2 and 10.0. The 3rd column is the photon flux in units of photon/cm2/sec; the values in the flux column must be > 0. The names of the columns and any other meta-data (ie keywords) are ignored.
One method for creating the input spectrum is to use the results of a sherpa spectral fit. This begins by extracting the pulse height spectrum from the observation
unix% specextract "acisf00942_repro_evt2.fits[sky=circle(12:16:56.990,+37:43:35.69,20)]" ngc4244 verbose=0
and then fitting it with sherpa. In the example below the spectrum is fit with an absorbed powerlaw.
unix% sherpa -n sherpa> load_data("ngc4244.pi") read ARF file ngc4244.arf read RMF file ngc4244.rmf sherpa> group_counts(10) sherpa> notice(0.4,6.0) sherpa> set_source( xsphabs.abs1 * powlaw1d.p1) sherpa> abs1.nh = 0.5 sherpa> guess(p1) sherpa> fit() Dataset = 1 Method = levmar Statistic = chi2gehrels Initial fit statistic = 35113.9 Final fit statistic = 83.7215 at function evaluation 72 Data points = 93 Degrees of freedom = 90 Probability [Q-value] = 0.666149 Reduced statistic = 0.930239 Change in statistic = 35030.2 abs1.nH 0.421028 +/- 0.0537392 p1.gamma 4.94907 +/- 0.304912 p1.ampl 0.000324726 +/- 5.30461e-05
Figure 2 shows a plot of the modeled source spectrum, that is the spectrum of the source at the entrance of the mirrors.
Figure 2: Fitted Spectrum
![[Thumbnail image: fitted spectrum]](source_spectrum.png)
[Version: full-size]
Figure 2: Fitted Spectrum
The source spectrum using the best-fit model parameters for an absorbed powerlaw model fit to the data.
The units of the spectrum are controlled with the set_analysis command. Setting the factor=1 is necessary to get units of photon/cm2/sec. (Leaving it at the default of 0 gives photon/cm2/sec/keV which produces the wrong normalization.)
sherpa> set_analysis(1, "energy", "rate", factor=1) sherpa> plot_source() sherpa> import matplotlib.pylab as plt sherpa> plt.xscale("log") sherpa> plt.yscale("log")
The save_chart_spectrum() command from the sherpa_contrib.chart module may be used to create the output spectrum file to be input to ChaRT. In this example, we use the optional elow and ehigh arguments to restrict the output to the 0.4-6 keV range. If the bounds are omitted, the full energy range as determined by Sherpa is used.
sherpa> from sherpa_contrib.chart import *
sherpa> save_chart_spectrum("source_flux_chart.dat", elow=0.4, ehigh=6.0)
Created: source_flux_chart.dat
The file source_flux_chart.dat is now ready to be uploaded to ChaRT.
The format of the spectrum file that users upload has changed from previous versions of ChaRT. The previous 2-column (mid-energy vs photon flux) format has been replaced with a 3-column (energy_lo, energy_hi, photon flux), format. Users can convert their existing two-column spectrum files—created by save_chart_spectrum in CIAO 4.7 and earlier— to the new format using dmtcalc as shown here
unix% dmtcalc old.dat new.dat expression="col1=col1-(0.01/2.0);col1a=col1+0.01;col2=col2" clob+
The value 0.01 is the step size in energy from the original file. The file new.dat will be written in FITS format. Users who wish to keep the file in ASCII format can specify the kernel option.
unix% dmtcalc old.dat "new.dat[opt kernel=text/simple]" expression="col1=col1-(0.01/2.0);col1a=col1+0.01;col2=col2" clob+
ChaRT can use either ASCII or FITS format spectrum files.
Specifying a monochromatic energy and photon flux
Users can simulate a PSF with a monochromatic energy between 0.2 and 10.0 keV.
The Selecting a Monochromatic Energy Why topic provides some guidance on how to select the energy for a given assumed spectral model and energy band. As the energy dependence is not strong, an energy near the middle of the energy band is often sufficient.
Users must also specify a value for the photon flux of the source, in units of photon/cm2/sec. The value must be between 1.0E-2 and 1.0E-9 photon/cm2/sec.
Previous versions ChaRT required a ray density when users supplied a monochromatic energy. This has been replaced with a photon flux value.
![[CAUTION]](../../imgs/caution.png)
Users, especially veteran ChaRT users, may be tempted to input the maximum flux value to generate a simulation with the most number of rays. This may lead to unexpected results, particularly if using MARX to simulate pileup. As the flux increases so will the simulated pileup which can distort the PSF in ways that may not match what was observed.
Instead, users should run multiple simulations and average the results as is discussed in the Using MARX to Create an Event File from ChaRT Rays thread.
An easy way to get an estimate of the photon flux is with the srcflux tool as shown here:
unix% srcflux acisf00942_repro_evt2.fits "12:16:56.990 +37:43:35.69" flux psfmethod=quick verbose=0 clob+ unix% dmkeypar flux_broad.flux net_photflux_aper echo+ 0.000167113260534439
So for this source, using a monochromatic of 2.3 keV (the characteristic monochromatic energy for the broad, 0.5 to 7.0 keV, energy band) a flux of 1.7e-4 should give a PSF which provides a good match for the observation.
Aspect Information
The ability to provide information about the aspect solution is the major new feature in ChaRT v2.
The aspect solution describes the pointing of the telescope as a function of time. Most observations are performed where the pointing of the telescope follows a Lissajous pattern. This has the effect of sampling a small range of off-axis angles around the source position resulting in a blurring of the PSF. A simple symmetrical blurring may be insufficient to model this effect, especially in short observations where the aspect solution may not uniformly sample the true distribution of off-axis angles around the source location.
ChaRT also uses the duration of the aspect solution as the exposure time. Rays will be generated with TIME values between the aspect solution file's first and last time records. The exposure time of the observation cannot be artificially extended.
Specify the OBS_ID value
For unmodified, non-proprietary observations users can simply specify the OBS_ID of the observation being analyzed. If the observation is one of the multi-obi observations, then users must also supply the OBI_NUM value
% dmkeypar acisf00942_repro_evt2.fits OBS_ID echo+ 942 % dmkeypar acisf00942_repro_evt2.fits OBI_NUM echo+ 1
ChaRT will retrieve the latest version of the aspect solution file(s) from the Chandra archive. If there is more than one file, it will dmmerge them together before using them.
Users should not use this option if any of the following apply:
User has barycenter corrected the TIME values in the file with axbary
User has applied a correction to the astrometry using reproject_aspect or wcs_update
-
User is using an older processing version of the data products. The CXC encourages users to make use of the latest version of data products available from the Chandra archive and recalibrate them with the latest calibrations available; however sometimes that is not always practical.
The easiest way to check for the latest version is to re-retrieve the files from the archive with download_chandra_obsid![[TIP]](../../imgs/tip.png)
chandra_reprochandra_repro applies the latest calibrations to the event file, not the aspect solution.
unix% download_chandra_obsid 942 asol Downloading files for ObsId 942, total size is 13 Mb. Type Format Size 0........H.........1 Download Time Average Rate --------------------------------------------------------------------------- asol fits 13 Mb already downloaded
If any of these conditions apply, then users must choose from the next two options.
Upload aspect solution file
Under the conditions above users may need to upload their aspect solution file to ChaRT.
The aspect solution is necessary to correctly sample the distribution of off-axis angles the source is observed by. This is especially necessary when attempting to use data binned at subpixel resolutions.
Some observations have more than one aspect solution file. These files need to be merged together before uploading to ChaRT with dmmerge. The default header merging rules lookup table is inappropriate for aspect solution files so a custom file must be used.
unix% echo "DATE-OBS calcForce" > hdr_lookup.txt unix% echo "DATE-END calcForce" >> hdr_lookup.txt unix% echo "TSTART calcForce" >> hdr_lookup.txt unix% echo "TSTOP calcForce" >> hdr_lookup.txt unix% dmmerge @acisf00942_asol1.lis pcad_asol.fits lookupTab=hdr_lookup.txt
This same merged file must then be used with MARX or psf_project_ray when the rays are projected onto the detector.
Files that are gzip'ed are also acceptable.
No dither
The final option for users doing analysis that does not depend on a particular observation is to supply a nominal value for the RA, DEC, and ROLL. These values must be sensible when the source position is input in celestial coordinates.
The values for an existing observation can be retrieve with several tools, for example:
unix% dmlist acisf00942_repro_evt2.fits header,clean | grep _NOM RA_NOM 184.3418938417 [deg] Nominal RA DEC_NOM 37.7818775744 [deg] Nominal Dec ROLL_NOM 230.8704994876 [deg] Nominal Roll -or- unix% dmmakepar acisf00942_repro_evt2.fits hdr.par unix% grep _nom hdr.par ra_nom,r,h,184.3418938417,,,"Nominal RA [deg]" dec_nom,r,h,37.781877574364,,,"Nominal Dec [deg]" roll_nom,r,h,230.87049948755,,,"Nominal Roll [deg]"
Users working directly with off-axis values (theta and phi) can set these values to 0.0.
Users who specify a value the nominal pointing must also supply an exposure time. This must be between 1 and 200 ksec.
Additional Inputs
Email Address
ChaRT simulations may take a long time and are therefore run asynchronously. Users will receive an email when their job is complete with instructions for retrieval.
Emails will be sent from cxc_rays at head.cfa.harvard.edu. This address is an unattended account.
Random Seed
Users who require statistically different ray files should specify unique values for the random seed parameter. A value of -1 will use a value based on the time the job was submitted.
The value is stored in the header of the output file.
Number of Iterations
As the time of the simulation is fixed by the duration of of the aspect solution and the flux is limited due to pileup, users may need to run multiple simulations. These independent realizations of the PSF can then be combined (averaged) to reduce the statistical uncertainty in the PSF.
ChaRT will automatically pick a different random seed for each iteration after the first.
Summary
Since all the necessary information has been obtained, you are ready to run ChaRT.
History
| 14 Dec 2004 | updated for CIAO 3.2: location of chart_spectrum.sl |
| 16 Feb 2005 | reviewed for CIAO 3.3: no changes |
| 18 Aug 2008 | updated for CIAO 4.0: version N003 event file, minor changes to screen output; the chart_spectrum.sl script must be run in CIAO 3.4 (a new version for CIAO 4 will be released as soon as it is available); updated to have inline image |
| 08 Oct 2008 | when using the Spectrum & Exposure Time method, exposure time may be up to 200 ks |
| 02 Mar 2009 | the chart_spectrum script has been updated for CIAO 4.1 - Python and S-Lang versions are available (revision "CIAO 4.1 - 1.0"); information Spectrum & Exposure Time section expanded |
| 15 Apr 2009 | The chart_spectrum script has been renamed to the sherpa_contrib.chart module; the write_chart_spectrum() has been renamed save_chart_spectrum(); the old version of the script and routine have been retained but are now deprecated; ahelp files are now available for save_chart_spectrum, plot_chart_spectrum, and get_chart_spectrum. |
| 17 Feb 2010 | reviewed for CIAO 4.2: minor updates to screen output to match Sherpa 4.2; added Scripting It section |
| 12 Jul 2010 | the S-Lang version of this thread has been removed. Please contact CXC Helpdesk if you require the S-Lang commands for creating a spectrum file. |
| 15 Dec 2010 | reviewed for CIAO 4.3: no changes |
| 19 Apr 2011 | The run ChaRT link points to the new web interface. |
| 29 Mar 2013 | Update file version to N004. |
| 03 Apr 2014 | Include asol file download, and go to appropriate sub-directory. |
| 06 May 2015 | Rewritten for new ChaRT 2 update. Users can now specify either celestial or off-axis coordinates. Users can supply an aspect solution, and the format of the spectral information has changed. |
| 12 Apr 2016 | updated to make use of fixed sherpa_contrib.chart Python module. |
| 05 Apr 2019 | Updated to use matplotlib commands to plot. |
| 22 Feb 2022 | Review for CIAO 4.14. Updated for Repro-5/CALDB 4.9.6 |