Last modified: 05 Dec 2022

URL: https://cxc.cfa.harvard.edu/ciao/threads/ssofreeze/

Reprojecting Coordinates of a Solar System Object

CIAO 4.16 Science Threads


Overview

Synopsis:

When an object is observed moving with respect to the observer, e.g. a planet or comet, the resulting event file looks "blurred" when viewed in (x,y) coordinates. The sso_freeze tool reprojects the coordinates to the frame of the object, eliminating this blurring.

This thread contains general information on running sso_freeze. The Object-centered Aspect Solution and Exposure Map thread explains how to use the object-centered aspect solution file.

[IMPORTANT]
chandra_repro now runs sso_freeze

chandra_repro will 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 reproject coordinates from the frame fixed to the celestial sphere to a reference frame which is fixed to the moving solar system object (SSO).

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: 1463 (ACIS-S, Jupiter)

unix% download_chandra_obsid 1463 evt2,asol,eph1

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 included in the primary directory.

unix% ls *eph1.fits
jupiterf059875200N001_eph1.fits
jupiterf059875200N002_eph1.fits
orbitf059443264N002_eph1.fits

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

unix% dmkeypar acisf01463N006_evt2.fits TSTART echo+
59968797.485273

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. The two ephemeris files for this observation are orbitf059443264N002_eph1.fits and jupiterf059875200N002_eph1.fits.

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 sso_freeze.

In many 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
pcadf059968984N004_asol1.fits

unix% punlearn sso_freeze
unix% pset sso_freeze infile=acisf01463N006_evt2.fits
unix% pset sso_freeze scephemfile=orbitf059443264N002_eph1.fits
unix% pset sso_freeze ssoephemfile=jupiterf059875200N002_eph1.fits
unix% pset sso_freeze asolfile=@pcad_asol1.lis
unix% pset sso_freeze ocsolfile=1463_oc_asol1.fits
unix% pset sso_freeze outfile=frozenjupiter.fits
unix% sso_freeze
Input event file or stack (acisf01463N004_evt2.fits): 
Input spacecraft ephemeris file (orbitf059443264N002_eph1.fits): 
Input solar system object file (jupiterf059875200N002_eph1.fits): 
Output event file name (frozenjupiter.fits): 

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


Display the Results

The new object-centered coordinates are stored in the ocx and ocy columns of the file. When displaying the "frozen" image, we must specify to bin on those columns (note that the binning syntax for ds9 is not the same as for the DM):

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

Alternatively, the image can be loaded in the usual way into ds9:

unix% ds9 frozenjupiter.fits &

Then the binning may be changed with the "Bin → Binning Parameters..." dialog box. Choose "ocx" and "ocy" with the buttons in the "Bin Columns" section.

Figure 1 shows the original and "frozen" images side-by-side.

Figure 1: Comparison of original and "frozen" images

[Thumbnail image: The original event file and the object-centered file are displayed side-by-side in ds9.]

[Version: full-size]

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

Figure 1: Comparison of original and "frozen" images

The Object-centered Aspect Solution and Exposure Map thread explains how to use the object-centered aspect solution file.



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


#----------------------------------------------------------------------
#
#  sso_freeze.par- Parameter file for planetary transformations routine
#
#----------------------------------------------------------------------
        infile = acisf01463N006_evt2.fits Input event file or stack
   scephemfile = orbitf059443264N002_eph1.fits Input spacecraft ephemeris file
  ssoephemfile = jupiterf059875200N002_eph1.fits Input solar system object file
       outfile = frozenjupiter.fits Output event file name
     (asolfile = @pcad_asol1.lis) Input aspect solution file
    (ocsolfile = 1463_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)              


History

03 Jan 2005 reviewed for CIAO 3.2: no changes
16 Dec 2005 updated for CIAO 3.3: bug in ChaSeR means that orbit ephemeris files must be retrieved from the CDA FTP site
01 Dec 2006 reviewed for CIAO 3.4: no changes
18 Jan 2008 updated for CIAO 4.0: sso_freeze can create object-centered aspect solution (Object-centered Aspect Solution thread); include aspect solution files in sso_freeze run; parameter file updated with new asolfile and ocsolfile
04 Feb 2009 updated for CIAO 4.1: image is inline
15 Jan 2010 reviewed for CIAO 4.2: no changes
13 Jan 2011 reviewed for CIAO 4.3: no changes
10 Jan 2012 reviewed for CIAO 4.4: no changes
03 Dec 2012 Review for CIAO 4.5; no changes
23 Dec 2014 Reviewed for CIAO4.7. Updated image; minor edits.
14 Feb 2022 Reviewed for CIAO 4.14. No changes.
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.