Using MARX to Create an Event File
![[CXC Logo]](/ciao/imgs/cxc-logo.gif){kind=logo}
Overview
Synopsis:
The output of ChaRT is a set of rays (a PSFRAYS table) which cannot be used directly in your analysis; it must be converted into a suitable format, i.e. a pseudo event file. The MARX software is used to project the rays onto the detector plane.
Using MARX allows us to take into account all changes to the photon distribution emerging from the HRMA due to the detector response. In particular, the detector QE & QEU and the roll are accounted for. In addition to simulating the detector response, MARX uses the ray weights to account for the mirror effects, i.e. different efficiency of different shells at different angles/energies.
This thread is not a definitive guide to using MARX. There are many more options and parameters discussed in the MARX manual.
Related Links:
- Caveats page: details on what is not included when using MARX.
- The MARX Frequently Asked Questions webpage
Last Update: 1 May 2013 - Added a note about pileup and normalization.
Contents
- Get Started
- Setting up MARX
- Get Source Coordinates
- Projecting the Rays
- Include ACIS Pileup Effects?
- Create an Event File
- Correcting for an Offset
- Summary
- History
- Images
Get Started
This example uses HRMA_theta5.949_phi197.7_en1.7_d2.fits, which was created in the Introduction to ChaRT Data Files thread. Also:
Download the sample data: 942 (ACIS-S, NGC 4244)
unix% download_chandra_obsid 942 evt2
Setting up MARX
This thread requires the MARX software. If you do not have at least MARX v4.0.8 installed, download and install MARX before continuing. MARX v4.5.0 is used in this thread.
If you are using MARX v5.0, there is an incompatibility with ChaRT/SAOTrace v1 and particular attention should be paid when running marx2fits.
Set up your environment to access all the files and directories which MARX needs:
unix% setenv MARX_DIR <local_marx_directory> unix% set path = ($path $MARX_DIR/bin) unix% setenv MARX_DATA_DIR $MARX_DIR/share/marx/data
Alternatively, the MARX DataDirectory parameter can be defined to point to the data files. By default, this parameter is set to the contents of the MARX DATA DIR environment variable. At this point, your system is ready to run simulations
Get Source Coordinates
Before running the simulation, it is necessary to determine the nominal position of the detector during the observation. These values are stored in the header of the level=2 event file:
unix% dmlist acisf00942N004_evt2.fits header | grep _NOM 0055 RA_NOM 184.3430399825 Real8 Nominal RA 0056 DEC_NOM 37.7808853898 Real8 Nominal Dec 0057 ROLL_NOM 230.8753656982 Real8 Nominal Roll
Additionally, the source coordinates for the PSF are required. These were determined in the Determine the Off-axis Angle section of the Preparing to Run ChaRT thread:
unix% punlearn dmcoords unix% dmcoords acisf00942N004_evt2.fits asol=pcadf075214790N004_asol1.fits dmcoords>: sky 4704 3700 (RA,Dec): 12:16:57.136 +37:43:35.94 (RA,Dec): 184.23807 37.72665 deg THETA,PHI 5.949' 197.74 deg (Logical): 4704.00 3700.00 SKY(X,Y): 4704.00 3700.00 DETX,DETY 3405.57 3875.41 CHIP ACIS-S2 573.49 753.83 TDET 3448.49 2455.83 dmcoords>: q
This step could also be done with dmcoords in non-interactive mode:
unix% dmcoords acisf00942N004_evt2.fits asol=pcadf075214790N004_asol1.fits opt=sky x=4704 y=3700 celfmt=deg unix% pget dmcoords ra dec 184.2380699128197 37.72665053564964
Projecting the Rays
In order to analyze the spatial distribution of the PSF, we need to project the PSF rays in HRMA_theta5.949_phi197.7_en1.7_d2.fits onto the detector plane. MARX enables us to do so.
Copy over the parameter file locally:
unix% cp $MARX_DIR/share/marx/pfiles/marx.par ./marx.par
and set the necessary parameters:
unix% pset ./marx SAOSACFile=HRMA_theta5.949_phi197.7_en1.7_d2.fits unix% pset ./marx OutputDir=HRMA_theta5.949_phi197.7_en1.7_d2.dir unix% pset ./marx DitherModel=INTERNAL unix% pset ./marx SourceType=SAOSAC unix% pset ./marx RA_Nom=184.34304 unix% pset ./marx Dec_Nom=37.78089 unix% pset ./marx Roll_Nom=230.87537 unix% pset ./marx SourceRA=184.34304 unix% pset ./marx SourceDEC=37.78089 unix% pset ./marx DetectorType=ACIS-S unix% pset ./marx GratingType=NONE unix% pset ./marx ExposureTime=0.0
There are a few things to note in the pset commands:
-
Make sure to use the correct detector for the DetectorType parameter; valid options are HRC-S, ACIS-S, HRC-I, or ACIS-I.
-
The Exposuretime is set to 0.0 to ensure that the simulated output has the desired exposure length. The "Simulation Control: Exposure Time" section of the MARX manual (PDF) has more information on setting this parameter.
-
In this example, we are simulating an on-axis source, so SourceRA = RA_NOM and SourceDEC = DEC_NOM. If you are doing an off-axis simulation, they shouldn't be the same.
Now run the tool. Note the syntax (@@) required to use the local parameter file; see Example 9 of ahelp parameter for details.
unix% marx @@./marx.par
MARX version 4.5.0, Copyright (C) 2002-2010 Massachusetts Institute of Technology
... screen output omitted...
Initializing source type SAOSAC...
Opening SAOSAC fits file HRMA_theta5.949_phi197.7_en1.7_d2.fits
System initialized.
Starting simulation. NumRays to collect = 1000000, dNumRays = 100000
Collecting 100000 photons...
100000 collected.
Reflecting from HRMA
Detecting with ACIS-S
Writing output to directory 'HRMA_theta5.949_phi197.7_en1.7_d2.dir' ...
Total photons: 100000, Total Photons detected: 60805, (efficiency: 0.608050)
(efficiency this iteration 0.608050) Total time: 104.231735
Collecting 100000 photons...
91683 collected.
Reflecting from HRMA
Detecting with ACIS-S
Writing output to directory 'HRMA_theta5.949_phi197.7_en1.7_d2.dir' ...
Total photons: 191683, Total Photons detected: 116315, (efficiency: 0.606809)
(efficiency this iteration 0.605456) Total time: 200.602434
Include ACIS Pileup Effects?
If the objective of running ChaRT and MARX is to simulate an observation as opposed to generate a model PSF, then you may want to include pileup effects. First you need to be sure that your simulation parameters exactly matched the observation (for example the spectrum flux was not artifically increased to increase sampling of the PSF). If these are not correct, you can not match the observed pileup to the simulation.
To include pileup, you must run the marxpileup tool:
unxi% marxpileup MarxOutputDir=HRMA_theta5.949_phi197.7_en1.7_d2.dir
Note: With pileup enabled, it is unclear how to apply an ad-hoc normalization to get the simulation to match the data. One can try to use a region away from the core of the PSF; however, if the observed data does have any extended emission (dust halo, PWN, etc) then the result will be incorrect.
Create an Event File
MARX creates a number of ASCII files in the specified directory (HRMA_theta5.949_phi197.7_en1.7_d2.dir):
unix% ls HRMA_theta5.949_phi197.7_en1.7_d2.dir b_energy.dat pha.dat xpos.dat detector.dat sky_dec.dat ycos.dat energy.dat sky_ra.dat ypixel.dat marx.par time.dat ypos.dat mirror.dat xcos.dat zcos.dat obs.par xpixel.dat zpos.dat
These .dat files need to be converted to a FITS event file before they can be used in CIAO. The MARX tool marx2fits does this, given the directory name and the output filename:
unix% marx2fits HRMA_theta5.949_phi197.7_en1.7_d2.dir marx_HRMA_theta5.949_phi197.7_en1.7_d2.fits Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/time.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/detector.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/energy.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/b_energy.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/xpos.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/ypos.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/zpos.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/xcos.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/ycos.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/zcos.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/xpixel.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/ypixel.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/pha.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/mirror.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/sky_ra.dat Examining HRMA_theta5.949_phi197.7_en1.7_d2.dir/sky_dec.dat unix%
If you are running MARX v5.0, the correct marx2fits command is as follows:
unix% marx2fits --pixadj=RANDOMIZE HRMA_theta5.949_phi197.7_en1.7_d2.dir marx_HRMA_theta5.949_phi197.7_en1.7_d2.fits
note the extra --pixadj=RANDOMIZE switch.
The file may be viewed in ds9:
unix% ds9 marx_HRMA_theta5.949_phi197.7_en1.7_d2.fits &
![[Thumbnail image: The event file created by MARX includes the ACIS readput streak.]](marx.png)
[Version: full-size]
Figure 1: The event file created by MARX
MARX includes a simulation of the ACIS readout streak in the event file.
Correcting for an Offset
In some Chandra observations, the science instrument module (SIM) is offset from the nominal location. If this offset is not included in the MARX run, the simulated PSF will be offset from the event file.
The MARX run was done with no offset:
unix% plist marx.par | grep DetOffset
DetOffsetX = 0 Enter Detector X offset from nominal (mm)
DetOffsetY = 0 Enter Detector Y offset from nominal (mm)
DetOffsetZ = 0 Enter Detector Z offset from nominal (mm)
It is easiest to correct for the observation offset after doing a MARX run with the offsets set to zero. First, compare the SIM values in the original Chandra event file and in the MARX-produced event file:
unix% dmlist acisf00942N004_evt2.fits header | grep SIM_ 0039 SIM_X -0.68282252473119 Real8 SIM focus pos (mm) 0040 SIM_Y 0 Real8 SIM orthogonal axis pos (mm) 0041 SIM_Z -190.1400660499 Real8 SIM translation stage pos (mm) unix% dmlist marx_HRMA_theta5.949_phi197.7_en1.7_d2.fits header |grep SIM_ 0046 SIM_X -0.68426746699586 Real8 SIM offset, mm 0047 SIM_Y 0 Real8 SIM offset, mm 0048 SIM_Z -190.1325231040 Real8 SIM offset, mm
Some observations are done with an offset of several mm. The difference, calculated as event_file_value - marx_file_value, is small in this case:
SIM_X: -0.68282252473119 - (-0.68426746699586) = 0.00144494 SIM_Z: -190.1400660499 - (-190.1325231040) = -0.00754295
Set these values in marx.par and run the simulation again:
unix% pset ./marx DetOffsetX = 0.00144494 unix% pset ./marx DetOffsetZ = -0.00754295 unix% pset ./marx OutputDir=offset_HRMA_theta5.949_phi197.7_en1.7_d2.dir unix% marx @@./marx.par unix% marx2fits offset_HRMA_theta5.949_phi197.7_en1.7_d2.dir offset_marx_HRMA_theta5.949_phi197.7_en1.7_d2.fits
The resulting MARX file has the new SIM values:
unix% dmlist offset_marx_HRMA_theta5.949_phi197.7_en1.7_d2.fits header |grep SIM_ 0046 SIM_X -0.68282252699586 Real8 SIM offset, mm 0047 SIM_Y 0 Real8 SIM offset, mm 0048 SIM_Z -190.1400660540 Real8 SIM offset, mm
Summary
The output file (marx_HRMA_theta5.949_phi197.7_en1.7_d2.fits or offset_marx_HRMA_theta5.949_phi197.7_en1.7_d2.fits) is a pseudo event file that can be used, for example, to create an image of the PSF.
History
| 27 Jun 2003 | original version, updated for CIAO 3.0: layout |
| 02 Dec 2004 | added note about setting ExposureTime parameter |
| 16 Feb 2005 | reviewed for CIAO 3.3: no changes |
| 31 Jul 2007 | updates for ciao3.4 |
| 18 Aug 2008 | updated for CIAO 4.0: MARX v4.2.0; minor changes to screen output; image converted to inline |
| 09 Oct 2008 | updated to MARX v4.3.0 |
| 18 Feb 2009 | updated to MARX v4.4.0 |
| 19 Mar 2009 | updated MARX v4.4.0 syntax to find modified parameter file first |
| 18 Feb 2010 | updated to MARX v4.5.0; added Correcting for an Offset section; added mention of the MARX DataDirectory parameter |
| 15 Dec 2010 | reviewed for CIAO 4.3: no changes |
| 22 Feb 2012 | reviewed for CIAO 4.4: point to MARX 4.5 page |
| 01 Oct 2012 | reviewed for PSF site overhaul. Updates for some MARX 5.0 syntax needed for ChaRT v1 compatibility |
| 29 Mar 2013 | Updated file version from N003 to N004. |
| 01 May 2013 | Added a note about pileup and normalization. |
