3. Examples

This section presents examples using the hist1d and hist2d functions. The examples are particularly relevant to X-ray astronomy. The evt2img demo program distributed with the histogram module may be regarded as a more complex combination of the examples below.

3.1 Example 1: Light Curves and Color-Color Diagrams

Each event measured by the Chandra X-Ray Observatory is characterized by many attributes including exposure-number and energy. Many objects observed by the observatory undergo flares causing a change in the observed count-rate. Suppose that the values of the variables expno and energy are 1-d arrays such that expno[i] and energy[i] represent the exposure number and energy of the ith event, respectively. Then an array representing the number of events per exposure number may be constructed using the hist1d function:

    expno_grid = [min(expno):max(expno)];
    count_rate = hist1d (expno, expno_grid);

For a weak source, there may be few events in each exposure causing the measured count-rate to look noisy. The signal to noise ratio can be increased by using larger bin sizes when constructing the histogram. For example,

   bin_size = 50;   % Use 50 exposures per bin
   expno_grid = [min(expno):max(expno):bin_size];
   count_rate = hist1d (expno, expno_grid)/bin_size;

By studying the measured count-rate, one can ascertain whether or not the source had a flare. Another important question is whether during the flare the spectrum of the source changed. For example, the X-ray spectrum of some sources will change from a soft state (low energies) to a hard state (high energies) during a flare. The mean energy per exposure may be used to get a handle upon any spectral changes. The computation of this quantity involves computing the mean energy of each event within an exposure. Although one can use brute-force methods to compute this, the simplest and most efficient is to use a histogram, but keeping track of what events went into each bin of the histogram. As before

   bin_size = 50;
   expno_grid = [min(expno):max(expno):bin_size];
   count_rate = hist1d (expno, expno_grid, &rev)/bin_size;

    mean (energy[rev[0]]) / bin_size

    num_bins = length (expno_grid);
    mean_energy = Double_Type [num_bins];
    for (i = 0; i < num_bins; i++)
      mean_energy[i] = mean (energy[rev[i]])/bin_size;

Finally, consider the construction of a so-called color-color diagram. This is simply a plot of the ratios of count-rates in various energy bands. Suppose that one is interested in three energy bands: 1-2 keV, 2-6 keV, and 6-12 keV. The event list may be filtered in these three bands as follows:

    i_low = where ((energy >= 1) and (energy < 2));
    i_med = where ((energy >= 2) and (energy < 6));
    i_hi  = where ((energy >= 6) and (energy < 12));

    rate_low = hist1d (energy[i_low], expno_grid)/bin_size;
    rate_med = hist1d (energy[i_med], expno_grid)/bin_size;
    rate_hi = hist1d (energy[i_hi], expno_grid)/bin_size;

3.2 Example 2: A true-color image

This example shows how to use the hist2d function to create a color-coded image. In addition to the energy and exposure number, an event is also associated with an (X,Y) coordinate representing the position on the sky where the photon causing the event originated. The three energy bands of the previous example will be used. Events with an energy in the lowest band will be represented by the color red, the events in the middle band by green, and those in the highest energy band by blue.

A full resolution image generated by the Chandra Observatory's ACIS detector consists of 8192x8192 pixels. For economy, a lower resolution 1024x1024 image will be produced. The hist2d function will be used to produce the individual planes of the final image:

     xgrid = [1:8192:8];
     ygrid = [1:8192:8];
     r_image = hist2d (X[i_low], Y[i_low], xgrid, ygrid);
     g_image = hist2d (X[i_med], Y[i_med], xgrid, ygrid);
     b_image = hist2d (X[i_hi], Y[i_hi], xgrid, ygrid);