AdaptiveBin documentation (for version 0.1.1)

AdaptiveBin is the main Adbin program. It takes one or more images and adaptively bins them. If one image is supplied, then the pixels are binned by fractional error on the intensity. If two or more images are supplied, then the pixels are fractional binned by error on the combined colour.

Usage

# AdaptiveBin --help
Usage: AdaptiveBin [OPTIONS] file bg=count...
Adaptively bins a set of images
Written by Jeremy Sanders, 2000, 2001.

  -o, --out=FILE           set out file (def adbin_out.fits)
  -e, --error=FILE         set error out file (def adbin_err.fits)
  -n, --binmap=FILE        set binmap out file (def adbin_binmap.fits)
  -p, --pixel=FILE         set pixel out file (DISCOURAGED)
  -t, --threshold=VAL      set threshold fraction (def 10%)
  -v, --value=STR          set output value (eg count(0), ratio(1,2))
  -s, --subpix=INT         set subpixel positioning divisior (def. 1)
  -c, --contig             only allow contiguous regions
      --verbose            display more information
      --help               display this help message
  -V, --version            display the program version

Report bugs to <jss@ast.cam.ac.uk>

AdaptiveBin takes a list of input FITS files and (optional) background counts. If one image is given, the image is binned based on the fractional error of the intensity of that image. If more than one images are supplied, then the adaptive binning is based on the fractional error of the combined colour of that image.

The switches --out, --error and --binmap set the output FITS images for the output binned image, error map and bin map, respectively. By default the file names are adbin_out.fits, adbin_err.fits and adbin_binmap.fits.

Version < 0.1.2: The --pixel option was used instead of --binmap. The old option is still available, but discouraged. Also the default output file names were different (adbin-out.fits, adbin-err.fits and pixel.fits).

The maximum fractional error is set using the --threshold=0.xx option. By default it is 0.1.

The type of binned image produced is set using the --value switch. This option is only useful when colour binning is being done. If this option is set to count(x), then the pixels in the output-image will contain the average count in band x for their bins (x is numbered from 0). The error map will show the fractional error on that count (note the bins are always produced using the error on the combined-colour). If --value is set to ratio(x,y), then the output-image will show the average colour x/y in the bin, and the error map will show the error on that colour.

The --subpix=x switch enables sub-pixel positioning (it should be called sub-bin positioning). The results of this option usually aren't great, but feel free to experiment. This option takes an integer value greater than 1. The value specifies where the top corner of a bin can be placed. Normally bins can only be placed on a regular grid, with a grid spacing of the size of the bin. This switch allows bins to be placed at intervals x times that frequency. Bins are drawn in ascending fractional error.

Version >= 0.1.1: The --contig option has been added. This makes sure that bins form contiguous regions. Using this option prevents 'stranded bins' which are binned together with a lower intensity region, due to them not having enough counts to have an error less than or equal to the threshold. If a bin consists of two isolated regions, then it is split into two different bins. A region is isolated if it does not have any neighbouring pixels (including sharing corners) with a different region. This option slows down the program, but there is probably some room for optimisation of the code.
Contiguous regions

Notes

  1. Version >= 0.1.2: AdaptiveBin can expand its options and arguments from a file, instead of the command line. Using an argument of @filename will substitute the text in the file in as options. The file can contain comments (preceeded by the # character); quote signs must be escaped using a backslash character.
  2. Brackets are changed by shells. The --value option needs to be surrounded by quotes. For example, --value="ratio(0,1)"
  3. WCS information is copied (in a simple form) from the first input image to the output images (including error and pixel maps).
  4. All input images must be of the same size.

Examples

# AdaptiveBin --threshold=0.05 --out=adbin_intensity_005.fits \
    --err=adbin_intensity_error_005.fits --binmap=binmap_005.fits \
    infile.fits bg=0.874

Bin infile.fits using intensity-adaptive binning with a fractional error threshold of 0.05 (5%). The output filename is adbin_intensity_005.fits, with error and binmap filenames adbin_intensity_error_0.05.fits and binmap_005.fits. A background of 0.874 counts per pixel is used to analyse the input file.

# AdaptiveBin --threshold=0.2 --value="ratio(1,2)" \
    image0.fits image1.fits bg=2.3 image2.fits bg=4.12

Do combined colour adaptive binning with a fractional error threshold of 0.2. The input images are image0.fits (no background), image1.fits (background 2.3 counts per pixel) and image2.fits (background 4.12 counts per pixel). The output, error and pixel filenames are the defaults. A colour image is outputted in the output and error images showing the ratio of the second and third input images (image1.fits and image2.fits).


Back to the documentation page


This page is maintained by Jeremy Sanders. It was last modified on 2001/1/18. This page is not an official page of the Institute of Astronomy.