Binning and Filtering FITS Event Files

Return to the DS9 Users Manual


When an x-ray event file is loaded, ds9 makes a virtual image for display by binning on one or more axes. This threads describes how to adjust the binning and buffer sizes. Interactive data filtering is described, as well as binning in three dimensions.

Note that the terms "binning" and "blocking" are used interchangeably in this thread. They both refer to combining pixels in an image.

If you encounter any problems, please email saord @


Getting Started

This thread begins with Chandra data from an observation of the Antennae Galaxies (NGC 4038/NGC 4039, ObsID 315). Open the file in ds9:

unix% ds9 acisf00315N002_evt2.fits &

A small section of the data is visible when the file is loaded, as shown in Figure 1. The target of the observation is partially visible in the display frame.

By default, the buffer size is set to 1024x1024 and the binning factor is set to 1. These values will be adjusted in the following sections to illustrate how to make more of the data visible.

The "Bin" menu, shown in Figure 2, will be used to change the setting in the following examples. From top to bottom, this menu contains the bin function setting, blocking factor, buffer size options, and access to the binning parameters dialog box.

Buffer Size

The buffer size determines the size of the image generated by ds9. By default, a full-resolution 1024x1024 image of the data is created. If your input data file has larger dimensions, it is clipped to 1024x1024 in ds9. The buffer settings range from 128x128 to 8192x1892.

Setting the buffer to the smallest size, 128x128, illustrates how it works. The data was centered on the sources in ds9 before the buffer size was changed, creating Figure 3.

Setting the buffer to a large size, e.g. 4096x4096, produces Figure 4. The display frame is filled by the data, and the panner in the upper right indicates that more of the image is available. Clicking and dragging the viewing bounding box in the panner will display a different portion of the image.

Binning Basics

Changing the binning factor

While increasing the buffer size loads more of the file into ds9, binning the data makes more of it visible in the frame. Binning combines the specified number of pixels into one new pixel; the new pixel has a value equal to the sum of the original pixels. (Note that if the bin method is changed to "average", the pixel values are averaged instead of summed.)

The binning can changed from the "Bin" menu or from the "Bin" item in the button bar. It's also possible to step through different binning values with the -/+ buttons or the "Block In"/"Block Out" menu items.

In Figure 5, the buffer size is set to 1024x1024, but the block factor has been set to 4. A larger section of the data is visible in the frame.

Binning different columns

ds9 has the ability to display any of the other columns stored in the event file, although it is generally only meaningful to use the spatial vector columns. Begin by opening the "Bin → Binning Parameters" dialog box, shown in Figure 6.

The "Bin Columns" menus are used to select the columns to be binned. To create an image in detector coordinates, set the first to "detx" and the second to "dety"; the block is set to "2" for both. The "or center of data" box is checked so that the center of the data is recalculated for the new columns.

Click "Apply" and the ds9 frame is updated, as shown in Figure 7.

Alternatively, one can display an event file in specific coordinates when starting ds9 from the command line:

unix% ds9 "acisf00315N002_evt2.fits[bin=detx,dety]" &

Data Cubes: Binning in three dimensions

It is possible to add a third column to the binning, creating a 3-dimensional image also known as a "data cube". In this example, an (x,y,time) data cube is created of a Chandra observation of Jupiter (ObsID 1463). A cube may be created from any three columns that make sense in the analysis. For instance, you may want to create a PHA or energy axis to see how the spectral characteristics of a source change over time.

The data file is loaded into a new frame in ds9 and the "Bin → Binning Parameters" dialog box is opened again. The "time" column of the file is selected from the "Bin 3rd Column" menu. The limits of the data in that column are filled in automatically. The "depth" field determines how many intervals the column is divided into; a depth of 25 is used. The completed parameter box is shown in Figure 8.

After clicking "Apply", two things happen: the "Data Cube" dialog box (Figure 9) is launched and the frame is updated to show only the (x,y) image of the first time slice (Figure 10). (If the data cube dialog box doesn't launch, open it from the "Frame" menu.)

When "Play" is chosen, ds9 cycles through the bins of the time axis, essentially creating a movie of the (x,y) position of the object over time. The speed of the frame changes is controlled from the "Interval" menu of the dialog box. Any of the 25 intervals may be selected with the slider bar.

The data cube can be saved as an MPEG movie from the "File → Save Image..." menu. Select "MPEG-1 (Movie)" and click "OK"; after setting the filename, choose an MPEG Quality Factor. The Jupiter data was saved at a quality factor of 15: jupiter.mpg.

Filtering Data

The "Bin Filter" field in the "Binning Parameters" dialog box is used to apply filters to the data. A filter can be applied to any of the columns present in the input file. A colon is used to indicate a range of values. Filters can also use < (less than) or > (greater than).

For instance, to include only the hard-band photons (2500-8000 eV):


Clicking "Apply" updates the ds9 display and keeps the dialog open for adjusting the filters.

Multiple filters may be specified, separated by commas:

energy=2500:8000, ccd_id=7

The resulting image is shown in Figure 11.

The filtered dataset can be saved as a FITS file for use in data analysis from the "File → Save Frame as Fits..." menu.


26 Jun 2009 Original version

Return to the DS9 Users Manual