Introduction to ChaRT Data Files

Overview

Last Update: 18 Aug 2008 - updated for CIAO 4.0: minor changes to screen output

Synopsis:

After running ChaRT, you will be sent an email pointing to the directory on the FTP server where you can download a compressed tarfile containing the results of the run. This thread illustrates how to retrieve, unpack, and view the output data.

The data used here were created by running ChaRT with the following parameters:

  theta   = 5.949 arcmin  
  phi     = 197.74 degrees 
  density = 2
  energy  = 1.7 keV
  seed    = 96969267

Proceed to the HTML or hardcopy (PDF: A4 | letter) version of the thread.

Email from ChaRT

Once your job has finished, ChaRT will send you an email which looks similar to this:

	Your job has completed.  You may retrieve your files from our
anonymous ftp data server, where they will be stored for no more then
2 days.  Pertinent information is listed below.  Thank you.
	Host: cda.cfa.harvard.edu
	Username: anonymous
	Password: chartusr@cfa.harvard.edu
	Directory: /pub/traceftp
	Filename: chartusr-20060216-151627.tar.gz
	File size (approx, untarred, [MiB]): 32
	URL: ftp://cda.harvard.edu/pub/traceftp/chartusr-20060216-151627.tar.gz
	Job Parameters:

Name		 = ChaRT User
Email		 = chartusr@cfa.harvard.edu
Random Seed	 = 96969267

	Source 1

Coord Sys	 = Theta/Phi
Theta [arcmin]	 = 5.949
Phi [degree]	 = 197.74
Energies [keV]	 = 1.7
Density		 = 2

As well as giving the location of the tarfile, the email lists the parameters used to create the PSF.

Download and Unpack the Tarfile

The name of the tarfile (chartusr-20060216-151627.tar.gz) is created by taking the first eight characters of the email address (chartusr@cfa.harvard.edu) and adding the date (20060216) and the time the data was created (151627). There are two simple ways to retrieve the tarfile from the server:

Paste the URL from the email (ftp://cda.harvard.edu/pub/traceftp/chartusr-20060216-151627.tar.gz) into your web browser and a "Save As..." box should be launched.

From the command line, it is possible to use wget (most users have this tool installed on the system):

unix% wget ftp://cda.harvard.edu/pub/traceftp/chartusr-20060216-151627.tar.gz

or to FTP to cda.harvard.edu:

unix% ftp cda.harvard.edu
Connected to cda.
220 cda FTP server (Version wu-2.6.1(1) Mon Aug 7 15:20:43 EDT 2000) ready.
Name (cda.harvard.edu:egalle): anonymous
331 Guest login ok, send your complete e-mail address as password.
Password:
230-
230-    Welcome to the FTP server at the CXC Science Center 
230-
(output omitted)
230 Guest login ok, access restrictions apply.
ftp> cd /pub/traceftp
250 CWD command successful.
ftp> get chartusr-20060216-151627.tar.gz
200 PORT command successful.
150 Opening ASCII mode data connection for chartusr-20060216-151627.tar.gz (17837826 bytes).
226 Transfer complete.
local: chartusr-20060216-151627.tar.gz remote: chartusr-20060216-151627.tar.gz
17894667 bytes received in 17 seconds (1054.67 Kbytes/s)
ftp> quit

To unpack the compressed tarfile:

unix% gunzip -c chartusr-20060216-151627.tar.gz | tar xf -
unix% ls -F
source1/

unix% ls source1/
HRMA_theta5.949_phi197.7_en1.7_d2.fits

The tarfile contains one directory per source, called source<n>. This sample dataset has only one source.

Columns and Header Keywords

There are many columns in the output rayfile:

unix% cd source1

unix% dmlist HRMA_theta5.949_phi197.7_en1.7_d2.fits cols
--------------------------------------------------------------------------------
Columns for Table Block PSFRAYS
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   rt_cosx              none         Real8          -Inf:+Inf            Label for field
   2   rt_cosy              none         Real8          -Inf:+Inf            Label for field
   3   rt_cosz              none         Real8          -Inf:+Inf            Label for field
   4   rt_kev               KeV          Real8          -Inf:+Inf            Label for field
   5   rt_graze             radians      Real8          -Inf:+Inf            Label for field
   6   rt_id                none         UInt4          -                    Label for field
...
  16   rt_x                 mm           Real8          -Inf:+Inf            Label for field
  17   rt_y                 mm           Real8          -Inf:+Inf            Label for field
  18   rt_z                 mm           Real8          -Inf:+Inf            Label for field
  19   rt_srfms             none         UInt4          -                    Label for field
  20   rt_norm_x            none         Real8          -Inf:+Inf            Label for field
  21   rt_norm_y            none         Real8          -Inf:+Inf            Label for field
  22   rt_norm_z            none         Real8          -Inf:+Inf            Label for field
  23   rt_time              sec          Real8          -Inf:+Inf            Label for field
  24   rt_wght              none         Real8          -Inf:+Inf            Label for field

rt_x, rt_y, rt_z: ray position in telescope coordinates [mm]
rt_cosx, rt_cosy, rt_cosz: cosine of the ray direction
rt_kev: energy of the ray [keV]
rt_wght: fractional probability that this ray will reach the focal plane
rt_id: ray id
rt_graze: grazing angle at point of last reflection from an optic [radians]
rt_srfms: code indicating which surfaces had been missed
rt_normx, rt_normy, rt_normz: surface normal at point of last reflection from an optic
rt_time: arrival time of ray at entrance of telescope [s]. The first ray arrives at time zero.

There are also some header keywords that should be highlighted; to view the complete header, use:

unix% dmlist HRMA_theta5.949_phi197.7_en1.7_d2.fits header

The ChaRT input parameters used to create the PSF are written as keywords:

unix% dmlist HRMA_theta5.949_phi197.7_en1.7_d2.fits header | egrep 'CREATOR|SRC_|CONFFILE|PSFSEED1'
0021 CREATOR              ChaRT v12:44:00-2003/12/09     String       
0027 SRC_THET                     5.9490 [arcmin]        Real8        input THETA
0028 SRC_PHI                    197.740 [degrees]        Real8        input PHI
0029 SRC_E                        1.70 [keV]             Real8        Energy used for generation
0030 SRC_DENS             2                              Int4         input DENSITY
0042 CONFFILE             orbit_XRCF+tilts+ol_01         String       HRMA config. file
0044 PSFSEED1             96969267                       Int4         Primary random seed for saosac

The CONFFILE keyword lists the name of the raytrace configuration file used in the simulation. If a spectral model is used to create the PSF, different "SRC_" keywords are added to the header to record the filename and exposure time:

unix% dmlist HRMA_theta5.949_phi197.7_ensource_flux_chart.dat_exp15.fits \
      header | egrep 'SRC_'
0027 SRC_THET                     5.9490 [arcmin]        input THETA
0028 SRC_PHI                    197.740 [degrees]        input PHI
0029 SRC_SPEC             source_flux_chart.dat          User supplied spectrum file
0030 SRC_EXPT             15 [ksec]                      input EXPOSURE TIME

Examining the PSF data

HRMA_theta5.949_phi197.7_en1.7_d2.fits is a FITS file with the data stored in the PSFRAYS block of the file. Using dmlist shows that this file contains approximately 192,000 rays:

unix% dmlist HRMA_theta5.949_phi197.7_en1.7_d2.fits blocks
 
--------------------------------------------------------------------------------
Dataset: HRMA_theta5.949_phi197.7_en1.7_d2.fits
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: PSFRAYS                        Table        15 cols x 191683   rows

The total counts in the PSF image is also recorded in the TOTCTS header keyword:

unix% dmkeypar HRMA_theta5.949_phi197.7_en1.7_d2.fits totcts echo+
191683.0

Summary

The output from ChaRT (i.e. HRMA_theta5.949_phi197.7_en1.7_d2.fits) cannot be used directly in your analysis. It first needs to be projected onto the detector and have the detector response applied to it to create a simulated event file. The Using MARX to Create an Event File thread describes how to do this.

History

27 Jun 2003	original version, updated for CIAO 3.0: layout
13 Jul 2004	created Columns and Header Keywords section
16 Feb 2005	reviewed for CIAO 3.3: no changes
18 Aug 2008	updated for CIAO 4.0: minor changes to screen output