Last modified: 19 Jan 2022

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

Create a Color Spectrum

CIAO 4.15 Science Threads


Overview

Synopsis:

The tool dmimg2jpg may be used to create color images of grating spectra. Two different ways of displaying the spectrum are available; the result depends on whether the event file is filtered on sky or grating angular coordinates.

Purpose:

To create color spectra of grating data.

Related Links:

Last Update: 19 Jan 2022 - Reviewed for CIAO 4.14. No changes.


Contents


Get Started

Download the sample data: 1451 (ACIS-S/HETG, II PEG)

unix% download_chandra_obsid 1451 evt2

Filter the Event File

In both of the following examples, we want to create a spectrum that contains events from all orders of the observation (+/-1, 2, 3 for HEG and MEG) for the brightest source. To do so, we need to filter on the tg_srcid, tg_part, and tg_m columns:

unix% dmcopy \
      "acisf01451N006_evt2.fits[tg_srcid=1,tg_part=0,1,2,tg_m=-3,-2,-1,0,1,2,3]" \
      1451_spec_evt2.fits

Since this is an HETG observation, there is no need to add the LEG component to the tg_part filter. For an LETG observation, that portion of the command would be tg_part=0,3.

The following explanation of the columns is from the Chandra Grating Analysis Page:

  • tg_srcid: the source identifier index. Up to ten sources can be resolved simultaneously, but the pipeline only detects the brightest source.

  • tg_part: the spatial part of the spectrum. 0 - zero-order; 1 - HEG; 2 - MEG; 3 - LEG; 99 - unresolved.

  • tg_m: the signed diffraction order that is resolved if the detector has sufficient energy resolution (i.e. is the ACIS detector). Unresolved photons are assigned to order 99.


Create a Color Spectrum

A. In Sky Coordinates

This example creates a color spectrum in the familiar cross-dispersion pattern of Chandra grating observations.

First we need to create the input image files for dmimg2jpg. Here dmcopy is used to create 3 image files corresponding to different energy bands. We choose energy bands that overlap to produce a visually appealing image:

unix% punlearn dmcopy
unix% pset dmcopy infile="1451_spec_evt2.fits[energy=000:999][bin sky=2000:7000:8]"
unix% pset dmcopy outfile=sky_red.fits
unix% dmcopy 
Input dataset/block specification (1451_spec_evt2.fits[energy=000:999][bin sky=2000:7000:8]): 
Output dataset name (sky_red.fits): 

This command takes the events in the given energy range and bins them on the sky coordinates. A blocking factor of 8 was used; see ahelp dmcopy for information on blocking.

[NOTE]
Copy all blocks?

The above dmcopy commands will only copy the data from the requested blocks. Users who need the [REGION] extension copied from the evt2.fits file should use dmappend as prescribed in the dmcopy opt=all bug page.

The dmcopy command may be condensed to a single line; for the second band:

unix% dmcopy "1451_spec_evt2.fits[energy=800:2399][bin sky=2000:7000:8]" \
      sky_green.fits

And finally:

unix% dmcopy "1451_spec_evt2.fits[energy=1700:9999][bin sky=2000:7000:8]" \
      sky_blue.fits

Now we can use dmimg2jpg to combine the files into a single RGB image:

unix% punlearn dmimg2jpg
unix% pset dmimg2jpg infile=sky_red.fits
unix% pset dmimg2jpg greenfile=sky_green.fits
unix% pset dmimg2jpg bluefile=sky_blue.fits
unix% pset dmimg2jpg outfile=sky_1451.jpg
unix% dmimg2jpg
Input file name (red image if true color) (sky_red.fits): 
Green color channel file name (sky_green.fits): 
Blue color channel file name (sky_blue.fits): 
Output jpg file name (sky_1451.jpg):

The resulting spectrum is shown in Figure 1.

Figure 1: Color spectrum in sky coordinates

[Thumbnail image: The spectrum shows the familiar cross-dispersion pattern of Chandra grating observations.]

[Version: full-size]

[Print media version: The spectrum shows the familiar cross-dispersion pattern of Chandra grating observations.]

Figure 1: Color spectrum in sky coordinates

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


B. In Grating Angular Coordinates

This example creates a color spectrum in the grating angular coordinates; the image will look like a traditional line spectrum.

Again, we need to create input image files for dmimg2jpg. In this case, however, we both filter and bin on tg_d and tg_lam. From the Chandra Grating Analysis Page:

  • tg_d: the cross-dispersion angle in degrees, using the Rowland spacing as the focal-length.

  • tg_lam: if the photon is resolved, then this is the wavelength in Angstroms. tg_lam is non-negative; unresolved photons are assigned wavelengths of 0.0.

In this example, we choose the angles between +/- 0.000663889 degrees and wavelengths up to 25.005 Å. Due to a Data Model bug, the filtering and binning must be done in separate dmcopy commands.

For the first band:

unix% dmcopy \
      "1451_spec_evt2.fits[tg_d=-0.000663889:0.000663889,tg_lam=1:25.005,energy=000:999]" \
      red_filter.fits

unix% dmcopy \
      "red_filter.fits[bin tg_lam=1:25.00:0.04,tg_d=-1.0e-3:1.0e-3:2.0e-5]" \
      ga_red.fits

Note that the binning command here is not as simple as in the previous example - the two variables are blocked by different factors.

For the second band:

unix% dmcopy \
      "1451_spec_evt2.fits[tg_d=-0.000663889:0.000663889,tg_lam=1:25.005,energy=800:2399]" \
      green_filter.fits

unix% dmcopy \
      "green_filter.fits[bin tg_lam=1:25.00:0.04,tg_d=-1.0e-3:1.0e-3:2.0e-5]" \
      ga_green.fits

And finally:

unix% dmcopy \
      "1451_spec_evt2.fits[tg_d=-0.000663889:0.000663889,tg_lam=1:25.005,energy=1700:9999]" \
      blue_filter.fits

unix% dmcopy \
      "blue_filter.fits[bin tg_lam=1:25.00:0.04,tg_d=-1.0e-3:1.0e-3:2.0e-5]" \
      ga_blue.fits

Use dmimg2jpg to combine the files into a single RGB image; here we supply all the parameters on the command line:

unix% dmimg2jpg infile=ga_red.fits greenfile=ga_green.fits \
      bluefile=ga_blue.fits outfile=ga_1451.jpg 

The resulting spectrum is shown in Figure 2.

Figure 2: Color spectrum in grating angular coordinates

[Thumbnail image: The images looks like a traditional line spectrum.]

[Version: full-size]

[Print media version: The images looks like a traditional line spectrum.]

Figure 2: Color spectrum in grating angular coordinates


Real vs. Virtual Image Files

It is also possible to use virtual files as input to dmimg2jpg, bypassing the dmcopy steps. To repeat the sky example with virtual file syntax:

unix% punlearn dmimg2jpg
unix% pset dmimg2jpg infile="1451_spec_evt2.fits[energy=000:999][bin sky=2000:7000:8]"
unix% pset dmimg2jpg greenfile="1451_spec_evt2.fits[energy=800:2399][bin sky=2000:7000:8]"
unix% pset dmimg2jpg bluefile="1451_spec_evt2.fits[energy=1700:9999][bin sky=2000:7000:8]"
unix% pset dmimg2jpg outfile=virtual_1451.jpg
unix% dmimg2jpg
Input file name (red image if true color) (1451_spec_evt2.fits[energy=000:999][bin sky=2000:7000:8]): 
Green color channel file name (1451_spec_evt2.fits[energy=800:2399][bin sky=2000:7000:8]): 
Blue color channel file name (1451_spec_evt2.fits[energy=1700:9999][bin sky=2000:7000:8]): 
Output jpg file name (virtual_1451.jpg): 

This method is useful if disk space is an issue, since the intermediate files aren't written out.



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


#--------------------------------------------------------------------
# dmimg2jpg.par                 Parameter file for dmimg2jpg tool
#--------------------------------------------------------------------
# Input files.  infile = redfile for true color output
#--------------------------------------------------------------------
        infile = sky_red.fits     Input file name (red image if true color)
     greenfile = sky_green.fits   Green color channel file name
      bluefile = sky_blue.fits    Blue color channel file name
#--------------------------------------------------------------------
# Output files.  Currently to get a postscript file you need
# to make the jpeg file.
#--------------------------------------------------------------------
       outfile = sky_1451.jpg     Output jpg file name
#--------------------------------------------------------------------
# In greenfile == 'none'  use a lookup table
#--------------------------------------------------------------------
      (lutfile = )lut.grey -> /soft/ciao/data/grey.lut) Colormap file
 (colorstretch = 1)               Color lookup strech factor
   (colorshift = 0)               Color lookup table shift
       (invert = no)              Invert colors
#--------------------------------------------------------------------
# Scaling functions.  Use INDEF to get min and max of data
#--------------------------------------------------------------------
(scalefunction = log)             Scaling function(log|linear|power)
   (scaleparam = 3)               Scaling parameter (for non-linear scalefunction)
       (minred = INDEF)           Minimum value for the red color channel
     (mingreen = INDEF)           Minimum value for the green color channel
      (minblue = INDEF)           Minimum value for the blue color channel
       (maxred = INDEF)           Maximum value for the red color channel
     (maxgreen = INDEF)           Maximum value for the green color channel
      (maxblue = INDEF)           Maximum value for the blue color channel
#--------------------------------------------------------------------
# Regions, aimpoint and grid overlay
#--------------------------------------------------------------------
   (regionfile = )                Region overlay file
  (regioncolor = )colors.green -> 0 1 0) Region color triple
    (regionopt = individual)      Option of region shape drawing method (individal|combine)
 (showaimpoint = no)              Put crosshair at aimpoint
    (showlabel = no)              Label the contours?
     (showgrid = no)              Show grid on image
    (gridcolor = )colors.white -> 1 1 1) Grid color triple
     (gridsize = 120)             Gridsize [arcsec]
     (fontsize = 2)               Font label size
       (psfile = )                Optional post script file name
      (verbose = 0)               Level of verbose output
      (clobber = no)              Clobber existing outputs?
         (mode = ql) 
    

History

03 Jan 2005 reviewed for CIAO 3.2: no changes
05 Dec 2005 updated for CIAO 3.3: workaround for a Data Model bug was added to the Grating Angular Coordinates section
01 Dec 2006 reviewed for CIAO 3.4: no changes
24 Jan 2008 reviewed for CIAO 4.0: no changes
06 Jun 2008 added "opt=all" to dmcopy commands so all blocks are kept in the grating files
11 Feb 2009 updated for CIAO 4.1: images are inline
20 Apr 2009 updated for CIAO 4.1.2: the showaimpoint and showgrid parameters in dmimg2jpg are set to "no" by default
14 Jan 2009 reviewed for CIAO 4.2: no changes
12 Jan 2011 reviewed for CIAO 4.3: no changes
11 Jan 2012 reviewed for CIAO 4.4: no changes
03 Dec 2012 Review for CIAO 4.5; added note that energy overlap is intentional to get mix of colors.
02 Dec 2013 Review for CIAO 4.6; no changes.
18 Dec 2014 Review for CIAO 4.7; no changes.
02 Dec 2020 Remove dmcopy opt=all due to bug. Link to work dmappend workaround if users need REGION extension.
19 Jan 2022 Reviewed for CIAO 4.14. No changes.