Last modified: 8 December 2020


Gallery: Binning

Return to thumbnail page.


  1. Bin Event File to Image; Specify Bin Size
  2. Bin Event File to Image; Specify Number of Bins
  3. Bin Event File to Image With Filtering
  4. Bin Event File to Image With FOV Filtering
  5. Weighted Binning
  6. Adaptive Binning
  7. Contour Map Based Binning
  8. Map Based Binning: Hardness Ratio Map
  9. Binning Arbitrary Axes

1) Bin Event File to Image; Specify Bin Size

One of the first things Chandra users want to do is to bin their event file into an image. The ds9 application does this automatically when you load the event file; but when you need to run tools such as wavdetect or csmooth you will need to bin the event file into an image yourself using dmcopy.
dmcopy "acisf06934N002_evt2.fits[bin x=3500:4500:2,y=3500:4500:2]" 6934_sky_binsize.fits clob+

The following commands can be used to visualize the output

ds9 6934_sky_binsize.fits -scale log -zoom 1 -cmap load $ASCDS_CONTRIB/data/heart.lut

2) Bin Event File to Image; Specify Number of Bins

Rather than specify bin size you can specify number of bins.
dmcopy "acisf06934N002_evt2.fits[bin x=3500:4500:#512,y=3500:4500:#512]" 6934_sky_nbins.fits clob+

The following commands can be used to visualize the output

ds9 6934_sky_nbins.fits -scale log -zoom 1 -cmap load $ASCDS_CONTRIB/data/heart.lut

This example produces the same output as the example above, but rather than specifying the bin size we specify the number of bins.

3) Bin Event File to Image With Filtering

Typically, users will also need to apply various filters to their datasets when they are binning. In this example we apply a circular spatial filter to the event file as the data are being binned.
dmcopy "acisf06934N002_evt2.fits[sky=circle(4096.5,4096.5,500)][bin sky=2]" 6934_sky_circle.fits clob+

The following commands can be used to visualize the output

ds9 6934_sky_circle.fits -scale log -zoom 1 -cmap load $ASCDS_CONTRIB/data/heart.lut

In this example, the individual columns X and Y ranges have been replaced with the simplified syntax [bin sky=2]. sky is the name of the vector column, composed of the X and Y columns.

By default the image shrinks to a bounding-box around the filter. Values outside the region are set to 0. This behavior can be changed using DM options.

4) Bin Event File to Image With FOV Filtering

Another common spatial filter is to apply the Field of View file (FOV) to establish the edges of data within the image. The FOV file is a FITS REGION format file that contains at least 1 row per CCD.
dmcopy "acisf06934_000N002_fov1.fits[ccd_id=7]" s3.fov clob+
dmcopy "acisf06934N002_evt2.fits[sky=region(s3.fov),ccd_id=7][bin sky=2]" 6934_s3.fits clob+

The following commands can be used to visualize the output

ds9 6934_s3.fits -scale log -zoom 1 -cmap load $ASCDS_CONTRIB/data/heart.lut

5) Weighted Binning

We do not always bin to accumulate counts. We can use weighted binning to accumulate other things like flux.
eff2evt "acisf06934N002_evt2.fits[ccd_id=7,energy=500:3000]" fluxed.evt clob+
dmcopy "fluxed.evt[sky=region(s3.fov)][bin sky=2;flux]" 6934_flux.fits clob+

The following commands can be used to visualize the output

ds9 6934_flux.fits -scale log -zoom 1 -cmap load $ASCDS_CONTRIB/data/heart.lut

6) Adaptive Binning

Usually we work with images that are binned such that all the pixels are the same size (and most often, are square). There are applications where having the data binned on an irregular or adaptive grid can be useful. There are many approaches to compute such a grid, in this example we introduce the CIAO tool dmnautilus.

dmnautilus uses a quad-tree algorithm. It works by taking the image and dividing it into 4 approximately equal sub-images. It computes the signal-to-noise (SNR) for each of the sub-images. If the SNR is above the desired threshold, then it further subdivides that sub-image in four. If the SNR is below the threshold, then the process stops for that sub-image tree. The result is a grid where each cell ("pixel") will have at most a SNR equal to the input threshold.

dmnautilus 6934_s3.fits 6934_abin.fits snr=20 outmask=6934_mask.fits clob+

The following commands can be used to visualize the output

ds9 6934_mask.fits 6934_abin.fits  -frame 1 -zoom 1 -cmap load $ASCDS_CONTRIB/data/16_ramps.lut -frame 2 -scale log -cmap load $ASCDS_CONTRIB/data/heart.lut

The image on the Left shows the grid that dmnautilus computed, the 6934_mask.fits output file. Each of the cells in the grid has an upper limit SNR=20 (400 counts) -- single pixel cells that could not be subdivided further can exceed this limit.

The image on the Right shows the data with that binning applied. The boundary of the cluster emission is more easily identified.

7) Contour Map Based Binning

The dmnautilus example above shows one example of an irregular, adaptive binning algorithm. There are several other commonly used adaptive binning algorithms in the community: Weighted Voronoi Tessellation and Contour Binning are probably the most common two.

In this example we introduce the dmmaskbin tool that takes as input a traditional counts (or flux) image along with a pixel-map image (which pixels belong to which group) and uses those to create the binned image.

dmmaskbin 6934_s3.fits 6934_cbin.fits clob+

The following commands can be used to visualize the output

ds9 6934_cbin.fits -frame 1 -scale linear -cmap load $ASCDS_CONTRIB/data/16_ramps.lut -frame 2 -scale log -cmap load $ASCDS_CONTRIB/data/heart.lut

In this example we have a input map (Left), . The pixel value indicates to which group the pixel location belongs.

Right: The output image, 6934_cbin.fits with a contour mapping binning applied. The sum of the pixel values in each group from the input counts image have been normalized by the size of the group and that average value replicated in each pixel in the group in the output image.

8) Map Based Binning: Hardness Ratio Map

Based on the above two examples we can now create a more useful example: Creating a map of the hardness ratio. For simplicity we define the hardness ratio, R, as

\[ \mathcal{R} = \frac{H-S}{H+S} \]

Where H is the number of counts in the hard (high) energy band and S is the number of counts in the soft (low) energy band. So a hardness ratio approaching 1.0 is a region dominated by hard X-ray emission, and values approaching -1.0 are dominated by soft emission.

dmcopy "acisf00214N003_evt2.fits[sky=region(acisf00214_000N003_fov1.fits[ccd_id=7]),energy=500:7000]" cas_a.fits clob+
dmnautilus "cas_a.fits[bin sky=2]" cas_a_bin.fits snr=20 clob+
dmmaskbin "cas_a.fits[energy=500:1500][bin sky=2]" soft.fits  clob+
dmmaskbin "cas_a.fits[energy=1500:7000][bin sky=2]" hard.fits  clob+
dmimgcalc soft.fits,hard.fits none op="imgout=((img2-img1)/(img2+img1))" clob+

The following commands can be used to visualize the output

ds9 -zoom 1 -cmap load $ASCDS_CONTRIB/data/004-phase.lut -cmap invert yes -scale limits -1 1 -view colorbar yes

In this example we take the event file for CasA and apply the spatial binning and energy filtering we saw in the earlier examples.

We then run dmnautilus on the broad band, ie combine hard+soft bands, to create a grid where we have a combined SNR limit of 20 (ie a limit of 400 counts).

We then use this map to create an image of the soft band and hard band counts.

And the finally we combine those two images using the equation above to compute the hardness ratio map.

Since we have selected the bins to include roughly 400 counts each, the statistical error in this map is low.

We can clearly see from this map the hard emission in the Western part of the remnant. (North is towards the top of the image).

9) Binning Arbitrary Axes

So far all the binning example have been of data in sky coordinates. However, we can bin data on any column in the input table.

In this example we will show a quick way to generate thousands of spectra using the data from the hardness ratio example.

dmimgpick cas_a.fits cas_a.mapped.evt method=closest clob+
dmcopy "cas_a.mapped.evt[bin cas_a_broad_map=1:4957:1,pi=1:1024:1]" cas_a.spectra.img clob+

The following commands can be used to visualize the output

ds9 cas_a.spectra.img -pan to 2200 230 physical -scale log -cmap b

This thread starts by using dmimgpick to add a new column to the event file. The new column is called cas_a_broad_map. The tool looks up the sky position for each event and then uses the closest value in the map file to populate the new column.

Next we use dmcopy to create an image but not in sky coordinates. In this example the X-axis is the value of the cas_a_broad_map column; ie the group ID. The Y-axis is binned on pi, which is the observed energy channel.

The results: We now have an image where each column is the spectrum for different parts of the sky. The image above shows just a small segment of the total image zoomed into a region where we can clearly see the change in the spectral signature.

Note: This type of spectrum is not immediately useful with CIAO, as we do not have the appropriate response files (ARF and RMF), nor do we have the information we need to account for background (including area scaling information).