Search https://cxc.harvard.edu/ciao/
Contact the CXC HelpDesk
Last modified: 05 December 2022

URL: https://cxc.cfa.harvard.edu/ciao/threads/ssoaspect/
/ ciao / threads / ssoaspect /
Return to Threads Page: Top | All | Imag

Object-centered Aspect Solution and Exposure Map

CIAO 4.15 Science Threads

Overview

Synopsis:

In addition to reprojecting the event data to the reference frame of the object, the sso_freeze tool can create an object-centered aspect solution file. The new aspect solution file may then be used to generate an exposure map or response file (ARF) for the data.

This thread focuses on how to use the aspect solution file. The Reprojecting Coordinates of a Solar System Object has more general information on running sso_freeze.

[IMPORTANT]
chandra_repro now runs sso_freeze

[New] chandra_repro will now automatically run sso_freeze if it locates a solar-system ephemeris file in the primary directory. To check if sso_freeze has been run, look for the Object Centered coordinate columns, ocx,ocy, in the output file 

unix% dmlist 1463/repro/acisf01463_repro_evt2.fits cols | grep ocx,ocy
  17   oc(ocx,ocy)          pixel        Real8          0.50:     8192.50    -          Object centered coordinates

Users must not (re-)run sso_freeze on an event file with existing Object Centered coordinate columns. This triggers a bug in sso_freeze which will create new columns with the same name; this causes problems with other tools.

Purpose:

To create an object-centered aspect solution file for a solar system object and build an exposure map with it.

Related Links:

Last Update: 05 Dec 2022 - Updated for CIAO 4.15. chandra_repro will now automatically run sso_freeze for solar system objects. Users must not re-run it again to avoid a bug that creates duplicate columns in the output.

Contents

Choosing the Ephemeris Files

Download the sample data: 3726 (ACIS-S, Jupiter)

unix% download_chandra_obsid 3726 evt2,asol,eph1,msk

There are two ephemeris input files needed for the tool to run: the spacecraft ephemeris file (scephemfile) and the SSO ephemeris file (ssoephemfile). Both of these files are part of the primary data products. In WebChaSeR, they are listed as the "MT (moving target) ephem" and "Orbit ephemeris" data products. 

unix% ls -1 *eph1.fits
anglesf03726_000N005_eph1.fits
jupiterf162475200N001_eph1.fits
lunarf162216300N001_eph1.fits
orbitf162216300N001_eph1.fits
solarf162216300N001_eph1.fits

The ephemeris files are selected based on the start time (TSTART) of the observation: 

unix% dmkeypar acisf03726N005_evt2.fits TSTART echo+
162488245.80274

Make sure that the timestamp in the filenames is less than the start time of the data. Also, if there is more than one version of a file - e.g. N001 and N002 - choose the newest (higher number) version available.

Spacecraft and SSO ephemeris files are also available from the CDA FTP site (cda.harvard.edu) if you have trouble retrieving them via WebChaSeR. Login as "anonymous", using your email address as the password; the files are in the /pub/arcftp/bary/ephem directory.

Run sso_freeze

Once you have the necessary input files, you are ready to run the tool.

In some rare cases, there will be more than one aspect solution file (pcad_asol1.fits) for an observation. All the files must be input to the asolfile parameter, either as a comma-separated list or as a stack. Here we use: 

unix% cat pcad_asol1.lis
pcadf03726_000N001_asol1.fits

unix% punlearn sso_freeze
unix% pset sso_freeze infile=acisf03726N005_evt2.fits
unix% pset sso_freeze scephemfile=orbitf162216300N001_eph1.fits
unix% pset sso_freeze ssoephemfile=jupiterf162475200N001_eph1.fits
unix% pset sso_freeze asolfile=@pcad_asol1.lis
unix% pset sso_freeze ocsolfile=3726_oc_asol1.fits
unix% pset sso_freeze outfile=3726_jupiter_oc.fits
unix% sso_freeze
Input event file or stack (acisf03726N005_evt2.fits): 
Input spacecraft ephemeris file (orbitf162216300N001_eph1.fits): 
Input solar system object file (jupiterf162475200N001_eph1.fits): 
Output event file name (3726_jupiter_oc.fits):

The contents of the parameter file may be checked using plist sso_freeze. 

unix% ds9 "3726_jupiter_oc.fits[bin=ocx,ocy]" &

Jupiter is displayed in object-centered (OC) coordinates (ocx,ocy) in Figure 1. Notice that in the reference frame of Jupiter, the point source at (4099,4092) becomes a long streak. The source may be removed from the field with the dmcopy or dmfilth tools, if desired.

Figure 1: Jupiter in OC coordinates (ocx,ocy)

[Thumbnail image: Most of the source has a value of zero due to a bias problem in the observation.]

[Version: full-size]

[Print media version: Most of the source has a value of zero due to a bias problem in the observation.]

Figure 1: Jupiter in OC coordinates (ocx,ocy)

In the reference frame of Jupiter, the point source at (4099,4092) becomes a long streak.

In the new event file, the origin of the OC coordinate system is (0,0). The RA and Dec header keyword values are updated to reflect this, so that the correct reference point is used in the rest of the analysis.

An edit list file is used as input to dmhedit: 

unix% cat edits.lis 
#add
RA_NOM = 0.0
DEC_NOM = 0.0
RA_PNT = 0.0
DEC_PNT = 0.0

unix% dmhedit 3726_jupiter_oc.fits filelist=edits.lis

You can check the parameter file that was used with plist dmhedit.

Create an Exposure Map

1. Make the aspect histogram

With the OC aspect solution file we can create a binned histogram detailing the aspect history of the observation.

Data Model syntax is used in the infile parameter to rename the "OCSOL" block to "ASPSOL". The "ocra" and "ocdec" columns are also renamed on-the-fly to "ra" and "dec", respectively. The changes are required because asphist expects the block and columns to have those names.

If you created more than one OC aspect solution file, all the files must be input to the infile parameter, either as a list or as a stack. 

unix% punlearn asphist
unix% pset asphist infile="3726_oc_asol1.fits[OCSOL][cols time,ra=ocra,dec=ocdec,roll,dy,dz,dtheta][ASPSOL]"
unix% pset asphist outfile=3726_oc_asphist.fits 
unix% pset asphist evtfile=3726_jupiter_oc.fits
unix% asphist
Aspect Solution List Files (3726_oc_asol1.fits[OCSOL][cols time,ra=ocra,dec=ocdec,roll,dy,dz,dtheta][ASPSOL]): 
Aspect Histogram Output File (3726_oc_asphist.fits): 
Event List Files (3726_jupiter_oc.fits):

You can check the parameter file that was used with plist asphist.

2. Calculate the Instrument Map

In this example we choose to create a monoenergetic distribution of source photons of 1.0 keV. The ACIS dead area correction is not applied.

This observation of Jupiter falls on chip ACIS-S3 (ccd_id=7). You may need to change the detsubsys parameter value for your observation.

Note that it is not necessary for the instrument map to be congruent with the exposure map; the instrument map should describe the chip with full resolution. We will use the default values for the detector region (pixelgrid parameter), creating a 1024 x 1024 pixel image that covers the whole chip. 

unix% punlearn mkinstmap
unix% pset mkinstmap obsfile="3726_jupiter_oc.fits[EVENTS]"
unix% pset mkinstmap outfile=3726_oc_instmap.fits
unix% pset mkinstmap maskfile=acisf03726_000N005_msk1.fits
unix% pset mkinstmap detsubsys=ACIS-S3
unix% pset mkinstmap pixelgrid="1:1024:#1024,1:1024:#1024"
unix% pset mkinstmap pbkfile=NONE dafile=NONE
unix% pset mkinstmap spectrumfile=NONE
unix% pset mkinstmap monoenergy=1.0

unix% mkinstmap
Output File Name (3726_oc_instmap.fits): 
Energy Spectrum File (see docs) (NONE): 
Energy for mono-chromatic map [keV] (0.1:10) (1): 
Pixel grid specification x0:x1:#nx,y0:y1:#ny (1:1024:#1024,1:1024:#1024): 
Name of fits file + extension with obs info (3726_jupiter_oc.fits[EVENTS]): 
Detector Name (ACIS-S3): 
Grating for zeroth order ARF (NONE|LETG|HETG) (NONE): 
NONE, or name of ACIS window mask file (acisf03726_000N005_msk1.fits): 
NONE, or the name of the parameter block file (NONE):

Including the maskfile parameter is particularly important if you are interested in having an accurate exposure map at the very edge of a CCD, subarray or window. For more information, see the dictionary entry on mask files.

You can check the parameter file that was used with plist mkinstmap.

3. Calculate the Exposure Map

Now we use mkexpmap and the aspect information stored in the histogram to project the instrument map onto the sky.

The xygrid parameter is set to produce a 512 x 512 pixel exposure map, centered at (4096,4096). 

unix% punlearn mkexpmap
unix% pset mkexpmap instmapfile=3726_oc_instmap.fits 
unix% pset mkexpmap outfile=3726_oc_expmap.fits
unix% pset mkexpmap xygrid="2048:6144:#512,2048:6144:#512"
unix% pset mkexpmap asphistfile=3726_oc_asphist.fits
unix% pset mkexpmap useavgaspect=no
unix% pset mkexpmap normalize=no
unix% mkexpmap
Aspect Histogram File (3726_oc_asphist.fits): 
Output File Name (3726_oc_expmap.fits): 
Name of Instrument Map (3726_oc_instmap.fits): 
grid specification syntax x0:x1:#nx,x0:x1:ny (2048:6144:#512,2048:6144:#512): 
Use Average Aspect Pointing (no):

The exposure map may be displayed in ds9 (Figure 2).

You can check the mkexpmap parameter file that was used with plist mkexpmap.

Since we set the normalize parameter = no, the exposure map has units of [cm2*s*counts/photon]. This allows us to simply divide the image by the exposure map to derive an image in units of flux [photons/cm2/s/pixel]. If the setting had been left as yes (the default), the units of the exposure map would be [cm2*counts/photon]. The units can be added to the exposure map using dmhedit 

unix% dmhedit expmap.fits file= op=add key=BUNIT value="cm**2 sec"

Please see the help file for mkexpmap for more details on this.

Figure 2: Exposure map image

[Thumbnail image: The exposure map of the ACIS-S3 chip is displayed in ds9.]

[Version: full-size]

[Print media version: The exposure map of the ACIS-S3 chip is displayed in ds9.]

Figure 2: Exposure map image

Create the Fluxed Image

The exposure map is in units of [cm2*s*counts/photon] since it was created by projecting the instrument map (in [cm2*counts/photon]) onto the tangent plane of the observation. To create an image in units of [photon/cm2/s/pixel], we simply need to divide by the exposure map. This is done by the tool dmimgcalc.

Data Model syntax is used to create a virtual image for the infile parameter which has the same binning used in making the exposure map. 

unix% punlearn dmimgcalc
unix% pset dmimgcalc infile="3726_jupiter_oc.fits[bin ocx=2048:6144:#512,ocy=2048:6144:#512]"
unix% pset dmimgcalc infile2=3726_oc_expmap.fits
unix% pset dmimgcalc outfile=3726_oc_norm.fits
unix% pset dmimgcalc operation=div
unix% dmimgcalc
Input file #1 (3726_jupiter_oc.fits[bin ocx=2048:6144:#512,ocy=2048:6144:#512]): 
Input file #2 (3726_oc_expmap.fits): 
output file  (3726_oc_norm.fits): 
arithmetic operation (div): 
warning: CONTENT has 1 different values.
warning: DETNAM has different value...Merged...

The messages are related to how the tool merges the header information in the input files. The merging_rules ahelp file explains the rules and how they affect the output file header.

The units of 3726_oc_norm.fits (Figure 3) are [photon/cm2/s/pixel].

You can check the parameter file that was used with plist dmimgcalc.

Figure 3: Fluxed image of Jupiter

[Thumbnail image: The fluxed image of the chip is displayed in ds9.]

[Version: full-size]

[Print media version: The fluxed image of the chip is displayed in ds9.]

Figure 3: Fluxed image of Jupiter

Optional: Confirm the Accuracy of the Aspect Solution

This section is an optional exercise which demonstrates that the OC event file and aspect solutions are consistent.

1. OC (RA,DEC) vs target (RA,Dec)

To visualize the motion of the aspect solution in OC coordinates, we modify the ocra column of the OC aspect solution so that -180 < ocra < 180, instead of 0 < ocra < 360: 

unix% dmtcalc 3726_oc_asol1.fits 3726_oc180_asol1.fits \
      expression="if(ocra>180)then(ocra=ocra-360.0)"

Next, create images of the aspect solution in (ra,dec) and (ocra,ocdec). The dmstat tool is used to determine the limits for the binning. 

unix% dmstat 3726_oc180_asol1.fits"[cols ocra]" verb=0
unix% pget dmstat out_min out_max
-0.031108391089
0.012724649401

unix% dmstat 3726_oc180_asol1.fits"[cols ocdec]" verb=0
unix% pget dmstat out_min out_max
-0.012529705774
-0.00031648365187

unix% dmcopy "3726_oc180_asol1.fits[bin ocra=-.03:.02:.0001,ocdec=-.02:0.0:.0001]" \
      3726_oc_radec.img


unix% dmstat 3726_oc180_asol1.fits"[cols ra]" verb=0
unix% pget dmstat out_min out_max
132.93131506
132.93721088

unix% dmstat 3726_oc180_asol1.fits"[cols dec]" verb=0
unix% pget dmstat out_min out_max
18.513642921
18.519299402

unix% dmcopy "3726_oc180_asol1.fits[bin ra=132.931:132.938:.00001,dec=18.512:18.520:.00001]" \
      3726_targ_radec.img

Figure 4 compares the images in ds9: 

unix% ds9 3726_targ_radec.img 3726_oc_radec.img &

Figure 4: Object-centered dither pattern vs target dither

[Thumbnail image: The object-centered and original aspect solutions are displayed side-by-side in ds9.]

[Version: full-size]

[Print media version: The object-centered and original aspect solutions are displayed side-by-side in ds9.]

Figure 4: Object-centered dither pattern vs target dither

The object-centered aspect solution is in the left frame and the original aspect solution (target RA,Dec) is in the right frame.

The OC (RA,Dec) coordinates drift over time (left ds9 frame), representing the increase in distance between the OC origin (Jupiter's position) and Chandra pointing as Jupiter moves across the sky. In the right ds9 frame there is no drift, as the pointing does not change with respect to the telescope.

2. Event data vs OC aspect solution

The sso_track script is used to create a set of 10 regions representing the current position of Jupiter: 

unix% sso_track 3726_oc_asol1.fits 10 sso.reg
ocsol, nreg are: 3726_oc_asol1.fits 10
nrows is 120865  
dt is 13429.4444
ssora,dec are: 132.9658671282 18.5195749695
ssora,dec are: 132.9609329984 18.5202451938
ssora,dec are: 132.9560468016 18.5209561862
ssora,dec are: 132.9512045626 18.5217051671
ssora,dec are: 132.9464037802 18.5224893790
ssora,dec are: 132.9416409073 18.5233065438
ssora,dec are: 132.9369141861 18.5241544081
ssora,dec are: 132.9322207554 18.5250312062
ssora,dec are: 132.9275594288 18.5259351345
ssora,dec are: 132.9229282045 18.5268647788

A comparison between Jupiter's motion and the OC aspect solution is shown in Figure 5: 

unix% ds9 3726_jupiter_oc.fits -region sso.reg 3726_oc_radec.img -orient x &

The event data is in sky coordinates (left ds9 frame). The circular regions (loaded from sso.reg) represent the current position of Jupiter, with the most recent position in green. These data show Jupiter moving higher in Dec (up) and lower in RA (right) over time.

Figure 5: Fluxed image of Jupiter

[Thumbnail image: The event data and the object-centered aspect solution are displayed side-by-side in ds9.]

[Version: full-size]

[Print media version: The event data and the object-centered aspect solution are displayed side-by-side in ds9.]

Figure 5: Fluxed image of Jupiter

Left frame: event data is in sky coordinates; RA decreases to the right along the x-axis. The circular regions (loaded from sso.reg) represent the current position of Jupiter, with the most recent position in green.

Right frame: OC aspect solution in (RA,Dec) coordinates; The right most edge of this data have the earliest timetags, so the dither pattern is moving from right to left over time.

Note: The size of the circle is not the size of the solar system object. It is the step size (so a function of the number of regions).

The OC aspect solution is in (RA,Dec) coordinates (right ds9 frame). The right most edge of this data have the earliest timetags, so the dither pattern is moving from right to left over time. The distance to the Chandra pointing vector (RA_NOM, DEC_NOM) as seen from the position of Jupiter moves lower in Dec (down) and higher in RA (right) over time.

Therefore, the event image and OC aspect image are consistent: from the fixed EQPOS frame, Jupiter moves higher in Dec and lower in RA. Looking back from Jupiter, the fixed dither pattern appears to be moving in the opposite direction: lower in Dec and higher in RA. 


Parameters for /home/username/cxcds_param/sso_freeze.par


        infile = acisf03726N005_evt2.fits Input event file or stack
   scephemfile = orbitf162216300N001_eph1.fits Input spacecraft ephemeris file
  ssoephemfile = jupiterf162475200N001_eph1.fits Input solar system object file
       outfile = 3726_jupiter_oc.fits Output event file name
     (asolfile = @pcad_asol1.lis  Input aspect solution file
    (ocsolfile = 3726_oc_asol1.fits) Output asol in OC coordinates
      (logfile = STDOUT)          debug log file ( STDOUT | stdout | <filename>)
        (scale = 0)               Image pixel scale (km/pixel, 0=angular coords)
    (lookuptab = ${ASCDS_CALIB}/dmmerge_header_lookup.txt -> /soft/ciao/data/dmmerge_header_lookup.txt) lookup table
      (clobber = no)              Overwrite existing output dataset with same name?
      (verbose = 0)               debug level (0-5)
         (mode = ql)              
    

Parameters for /home/username/cxcds_param/dmhedit.par


        infile = 3726_jupiter_oc.fits Input dataset/block specification
      filelist = edits.lis        Edit list file name
     operation =                  Operation
           key =                  Keyword
         value =                  Value for keyword
     (datatype = indef)           Keyword data type
         (unit = )                Unit for keyword
      (comment = )                Comment for keyword
      (verbose = 0)               Verbosity Level(0-5)
         (mode = ql)              
    

Parameters for /home/username/cxcds_param/asphist.par


        infile = 3726_oc_asol1.fits[OCSOL][cols time,ra=ocra,dec=ocdec,roll,dy,dz,dtheta][ASPSOL] Aspect Solution List Files
       outfile = 3726_oc_asphist.fits Aspect Histogram Output File
       evtfile = 3726_jupiter_oc.fits Event List Files
       dtffile =                  Live Time Correction List Files for HRC
      (geompar = geom)            Parameter file for Pixlib Geometry files
       (res_xy = 0.5)             Aspect Resolution x and y in arcsec
     (res_roll = 600.)            Aspect Resolution roll in arcsec
      (max_bin = 10000.)          Maximal number of bins
      (clobber = no)              Clobber output
      (verbose = 0)               Verbose
         (mode = ql)              
    

Parameters for /home/username/cxcds_param/mkinstmap.par


       outfile = 3726_oc_instmap.fits Output File Name
  spectrumfile = NONE             Energy Spectrum File (see docs)
    monoenergy = 1                Energy for mono-chromatic map [keV]
     pixelgrid = 1:1024:#1024,1:1024:#1024 Pixel grid specification x0:x1:#nx,y0:y1:#ny
       obsfile = 3726_jupiter_oc.fits[EVENTS] Name of fits file + extension with obs info
     detsubsys = ACIS-S3          Detector Name
       grating = NONE             Grating for zeroth order ARF
      maskfile = acisf03726_000N005_msk1.fits NONE, or name of ACIS window mask file
       pbkfile = NONE             NONE, or the name of the parameter block file
       (mirror = HRMA)            Mirror Name
       (dafile = NONE)            NONE, CALDB, or name of ACIS dead-area calibration file
(ardlibparfile = ardlib.par)      name of ardlib parameter file
      (geompar = geom)            Parameter file for Pixlib Geometry files
      (verbose = 0)               Verbosity
      (clobber = no)              Overwrite existing files?
         (mode = ql)              Enter mode for parameter file.
    

Parameters for /home/username/cxcds_param/mkexpmap.par


   asphistfile = 3726_oc_asphist.fits Aspect Histogram File
       outfile = 3726_oc_expmap.fits Output File Name
   instmapfile = 3726_oc_instmap.fits Name of Instrument Map
#
        xygrid = 2048:6144:#512,2048:6144:#512 grid specification syntax x0:x1:#nx,x0:x1:ny
  useavgaspect = no               Use Average Aspect Pointing
#---------------------------------------------------------------------------
#  Aspect Histogram Parameters
#  If UseAvgAspect is set to yes, then only the average pointing derived from
#  the many pointings in the aspect histogram will be used.
#---------------------------------------------------------------------------
#asphistfile,f,a,"../data/aciss_asphist.fits",,,"Aspect Histogram File"
    (normalize = no)              Normalize exposure map by exposure time
#
      (geompar = geom)            Parameter file for Pixlib Geometry files
      (verbose = 0)               Verbosity
      (clobber = no)              Overwrite existing files?
         (mode = ql)              Enter mode for parameter file.
    

Parameters for /home/username/cxcds_param/dmimgcalc.par


# parameter file for dmimgcalc
        infile = 3726_jupiter_oc.fits[bin ocx=2048:6144:#512,ocy=2048:6144:#512] Input file #1
       infile2 = 3726_oc_expmap.fits Input file #2
       outfile = 3726_oc_norm.fits output file 
     operation = div              arithmetic operation
       (weight = 1)               weight for first image
      (weight2 = 1)               weight for second image
    (lookupTab = ${ASCDS_CALIB}/dmmerge_header_lookup.txt -> /soft/ciao/data/dmmerge_header_lookup.txt) lookup table
      (clobber = no)              delete old output
      (verbose = 0)               output verbosity
         (mode = ql)

History

18 Jan 2008 new for CIAO 4.0
04 Feb 2009 updated for CIAO 4.1: images are inline; user pget instead of grep to get dmstat output values in OC (RA,DEC) vs target (RA,Dec) section; input data must have a CTI_APP keyword
12 Jan 2010 updated for CIAO 4.2: calibration update - the ACIS QE contamination model has been upgraded to vN0005.
15 Dec 2010 updated for CIAO 4.3: new ACIS contamination calibration file
01 Mar 2011 CALDB 4.4.2 release: fix to the header of the ACIS QE contamination file. Prior to this release, CIAO would fail when trying to look up the contamination model correction for chips ACIS-8 (S4) and ACIS-9 (S5).
10 Jan 2012 reviewed for CIAO 4.4: no changes
03 Dec 2012 Review for CIAO 4.5; mkexpmap chatter removed.
02 Apr 2013 Changed reference from Chaser to WebChaser.
23 Dec 2014 Reviewed for CIAO 4.7; minor edits only
30 Jan 2017 Reviewed for CIAO 4.9. Updated final image to match direction of RA.
14 Feb 2022 Review for CIAO 4.14. Updated for Repro-5 and CALDB 4.9.6.
05 Dec 2022 Updated for CIAO 4.15. chandra_repro will now automatically run sso_freeze for solar system objects. Users must not re-run it again to avoid a bug that creates duplicate columns in the output.
Return to Threads Page: Top | All | Imag
/ ciao / threads / ssoaspect /