Demonstration code:

An example script to demonstrate the most important shapelet routines and structure types.

A demonstration IDL script is included in the zip file when you download the example data. It demonstrates some basic operations for those not familiar with IDL. It also introduces the new shapelet routines... and checks that they are installed correctly! It will perform various shapelet decompositions and image manipulations, outputting the results to the screen.

General information about the shapelet routines:

The shapelet routines are written to be fairly transparent and do not use IDL's complicated and somehwhat restrictive object-oriented notation. However, they use a series of IDL "anonymous structures" to similar effect. An IDL structure is simply a grouping together of several variables under one name. They are accessed by typing structurename.variablename. Most of the routines take one of these structures as an input, change it, and possibly output some new structures. There are five main types of structure used by the shapelet routines, which would typically become available in the following order. All of these will be explored in the demonstration script:

• image structure (hide list)
  An image array, plus a pixel noise map and SExtractor segmentation/background maps if available.
  Obtained via shapelets_read_image, image, 'example'.

  NAME	STRING	Filename of the image
  TYPE	STRING	"image"
  NPIX	INTEGER ARRAY	Number of pixels (x,y) in the image
  IMAGE	FLOAT ARRAY	Image data
  BACKGROUND	FLOAT ARRAY	SExtractor's model of the background level
  NOISE	FLOAT ARRAY	Inverse variance pixel noise map
  SEG	INT ARRAY	SExtractor segmentation map
  PIXEL_SCALE	FLOAT	Arcseconds per pixel
  HEADER	STRUCTURE	FITS image header

• sexcat structure (hide list)
  SExtractor catalogue. This contains the positions of objects within an image, determined by SExtractor. Some of the objects' basic shape parameters, including flux, size and ellipticity, are also stored.
  Obtained via sex, 'example' & shapelets_read_sexcat, sexcat, 'example'.

  NAME	STRING	Filename of the image
  TYPE	STRING	"sexcat"
  N	INTEGER	Number of objects in the catalogue
  SEEING	FLOAT	FWHM seeing in pixels
  X	FLOAT ARRAY	Object centroids (x,y)
  XPEAK	INTEGER ARRAY	Coordinated of brightest pixel in each object (x,y)
  XMIN	INTEGER ARRAY	Coordinates of bottom-left pixel belonging to each object (x,y)
  XMAX	INTEGER ARRAY	Coordinates of top-right pixel belonging to each object (x,y)
  ID	FLOAT ARRAY	SExtractor ID number of each object
  CLASS	FLOAT ARRAY	Star/galaxy separation estimator for each object
  A	FLOAT ARRAY	Major axis length of each object
  B	FLOAT ARRAY	Minor axis length of each object
  THETA	FLOAT ARRAY	Angle of major axis from x axis, for each object
  E	FLOAT ARRAY	Ellipticity = (A^2-B^2)/(A^2+B^2) of each object
  E1	FLOAT ARRAY	Horizontal ellipticity component of each object
  E2	FLOAT ARRAY	Diagonal ellipticiy component of each object
  FLUX	FLOAT ARRAY	Total flux in each object of each object
  MAG	FLOAT ARRAY	Magnitude of each object (without zero-point offset)
  FWHM	FLOAT ARRAY	FWHM of each object
  AREA	INTEGER ARRAY	Number of pixels belonging to each object

• pstamp structure (hide list)
  Small postage stamp image, extracted around one object within a much larger image using SExtractor parameters as a guide to its size and extent.
  Obtained via shapelets_sexcat2pstamp, image, sexcat, id_number, pstamp.

  NAME	STRING	Name of the image and SExtractor ID number of the object
  TYPE	STRING	"pstamp"
  FLAG	INTEGER VECTOR	A linear combination of: 0=Failed, 1=OK, 2=Beware of nearby object, 4=Noise has been renormalised
  IMAGE	FLOAT ARRAY	Image data
  NOISE	FLOAT ARRAY	Inverse variance noise map
  SEG	INTEGER ARRAY	SExtractor segmentation map
  IM_RAN	INTEGER ARRAY	Coordinates of bottom-left and top-right of postage stam, in image coordinates
  XO	FLOAT VECTOR	SExtractor centroid (x) in postage stamp coordinates
  YO	FLOAT VECTOR	SExtractor centroid (y) in postage stamp coordinates
  SEXID	INTEGER VECTOR	SExtractor ID number
  BACK_MEAN_LOCAL	FLOAT VECTOR	Local estimation of background level
  BACK_RMS_LOCAL	FLOAT VECTOR	Local estimation of background noise
  BACK_RMS	FLOAT VECTOR	Global extimation of background noise
  X	FLOAT VECTOR	SExtractor centroid (x) in oringinal image coordinates
  Y	FLOAT VECTOR	SExtractor centroid (y) in oringinal image coordinates
  XPEAK	INTEGER VECTOR	Other SExtractor parameters, all in original image coordinates
  YPEAK	INTEGER VECTOR	"  "
  XMIN	INTEGER VECTOR	"  "
  XMAX	INTEGER VECTOR	"  "
  YMIN	INTEGER VECTOR	"  "
  YMAX	INTEGER VECTOR	"  "
  AREA	INTEGER VECTOR	"  "
  A	FLOAT VECTOR	"  "
  B	FLOAT VECTOR	"  "
  THETA	FLOAT VECTOR	"  "
  CLASS	FLOAT VECTOR	"  "
  FWHM	FLOAT VECTOR	"  "
  MAG	FLOAT VECTOR	"  "

• decomp structure (hide list)
  Shapelet decomposition of one object. Parameters stored include the Cartesian shapelet coefficients, scale size beta, and the location of the centroid within the central pixel. Note that polar shapelet coefficients are never stored, and are calculated on-the-fly whenever they are needed.
  Obtained via shapelets_decomp, decomp, image.image, beta, n_max, decomp or decomp=shapelets_shapecat2decomp(shapecat, id_number).

  NAME	STRING	Name of the object
  TYPE	STRING	"decomp_cartesian" ("decomp_polar" reserved for future use)
  HISTORY	STRING ARRAY	Where the object is from and has happened to it recently
  X	FLOAT ARRAY	Centre of the object in the original image (x,y)
  BETA	FLOAT	Scale size of shapelet basis functions
  N_MAX	INTEGER	Truncation of the shapelet series at this order of basis functions
  N_COEFFS	INTEGER	Number of shapelet coefficients (worked out from above)
  COEFFS	FLOAT ARRAY	Shapelet coefficients
  ERROR	INTEGER ARRAY	Rms error on shapelet coefficients
  N1	INTEGER ARRAY	n_1 value of each coefficient in array
  N2	INTEGER ARRAY	n_2 value of each coefficient in array
  N_PIXELS	INTEGER ARRAY	Number of pixels (x,y) in original image
  OVER	FLOAT	Oversampling factor used for original decomposition
  INTEGRATE	BYTE	Flag to show whether basis functions were integrated within pixels during original decomposition
  CHISQ	FLOAT ARRAY	Chi-squared and reduced chi-squared of shapelet fit to the original image
  SKYFIT	FLOAT ARRAY	Sky background level that was fitted and removed, optionally followed by sky gradient parameters
  SEX	BYTE or STRUCTURE	Zero, or a structure containing SExtractor parameters of original object
  MOMENTS	BYTE or STRUCTURE	Zero, or a structure containing object's moments (and errors) calculated from shapelet model

• shapecat structure (list elements)
  Shapelet catalogue, containing the shapelet decomposition of many objects. The information from more than one decomp structure, stored in a more efficient form.
  Obtained via shex, 'example', decomp & shapelets_read_shapecat, shapecat, 'example'.

SExtractor compatability note:

Note that objects are first located within the image using SExtractor, a widely used friends-of-friends algorithm by Emmanuel Bertin. This requires SExtractor to be installed on your computer, and the location of the executable file stored in shapelets_paths.pro. Installation instructions can be found in Benne Holwerda's "Source Extractor for Dummies". In case you just can't get this to work (and the script keeps crashing at line 86), a pre-run SExtractor catalogue for the example image is included in the sample data zip file. Simply copy this from shapelets/data/pre-done/example.sexcat to shapelets/data/example.sexcat. Of course, this is something of a last resort because you will need to get SExtractor working properly if you require shapelet catalogues of any other images...

Running the script:

If you open the file shapelets_demo.pro in the IDL development environment, it should look something like the diagram below. (If this extends too far off the edge of your browser, try reducing the font size). Clicking on any of the black shapelet routine names will take you to its help page. The green comments and the annotation at the sides should also help to explain each step.

To run the demonstration script, type:
shapelets_demo, sexcat, cat, image, decomp
at an IDL prompt. Occasionally, it will pause so that you can see the results for yourself. You are then asked to type a number. Any number will do, but there has to be one! Remember to press return afterwards. The typical output of this script is shown at the bottom of this page.

Return to the top of this page, the shapelets web page or the download page for shapelets code.

Typical output:

IDL Version 6.0 (linux x86 m32). (c) 2003, Research Systems, Inc.
Installation number: 19540.
Licenced for use by: California Institute of Technology
 
IDL> shapelets_demo, image, sexcat, decomp, psf, shapecat
% Compiled module: SHAPELETS_DEMO.
% Compiled module: SHAPELETS_PATHS.
% SHAPELETS_PATHS: Shapelet export version of path names!
% Compiled module: PATH_SEP.
% Compiled module: SHAPELETS_READ_IMAGE.
% SHAPELETS_PATHS: Shapelet export version of path names!
% SHAPELETS_READ_IMAGE: Reading in image data from /home/idris/rjm/idl/shapelets/data/example.fits
% Compiled module: FITS_READ.
% Compiled module: FITS_OPEN.
% Compiled module: SXPAR.
% Compiled module: GETTOK.
% Compiled module: SXDELPAR.
% Compiled module: SXADDPAR.
% Compiled module: IEEE_TO_HOST.
% Compiled module: FITS_CLOSE.
% SHAPELETS_READ_IMAGE: Reading in inverse variance map
% SHAPELETS_READ_IMAGE: Reading in segmented pixel map
% SHAPELETS_READ_IMAGE: Image /home/idris/rjm/idl/shapelets/data/example.fits now in memory
% Compiled module: PLT_IMAGE.
% Compiled module: CONGRID.
Type a number to continue...1
% SHAPELETS_PATHS: Shapelet export version of path names!
% Compiled module: SHAPELETS_READ_SEXCAT.
% SHAPELETS_PATHS: Shapelet export version of path names!
% SHAPELETS_READ_SEXCAT: Reading in SExtractor catalogue from example.sex
% Compiled module: READCOL.
% Compiled module: NUMLINES.
% Compiled module: ZPARCHECK.
% Compiled module: REMCHAR.
% Compiled module: REPCHR.
% Compiled module: STRNUMBER.
% SHAPELETS_READ_SEXCAT: Found 178 objects.
** Structure <8210e64>, 20 tags, length=11780, data length=11780, refs=1:
   NAME            STRING    'example'
   TYPE            STRING    'sexcat'
   N               LONG               178
   SEEING          FLOAT           4.45000
   X               FLOAT     Array[178, 2]
   XPEAK           INT       Array[178, 2]
   XMIN            INT       Array[178, 2]
   XMAX            INT       Array[178, 2]
   ID              LONG      Array[178]
   CLASS           FLOAT     Array[178]
   A               FLOAT     Array[178]
   B               FLOAT     Array[178]
   THETA           FLOAT     Array[178]
   E               FLOAT     Array[178]
   E1              FLOAT     Array[178]
   E2              FLOAT     Array[178]
   FLUX            FLOAT     Array[178]
   MAG             FLOAT     Array[178]
   FWHM            FLOAT     Array[178]
   AREA            INT       Array[178]
Type a number to continue...1
% Compiled module: SHAPELETS_SEXCAT2PSTAMP.
% SHAPELETS_SEXCAT2PSTAMP: Local construction of segmentation map
% Compiled module: SHAPELETS_MAKE_XARR.
% Compiled module: UNIQ.
% Compiled module: MEAN.
% Compiled module: MOMENT.
% Compiled module: STDDEV.
% SHAPELETS_SEXCAT2PSTAMP: Local background: mean, rms:  5.27947e-05  3.59792e-05
% Compiled module: PLT_COLBAR.
% Compiled module: SHAPELETS_DECOMP.
% Compiled module: SHAPELETS_MAKE_LS_MATRIX.
% Compiled module: SHAPELETS_PHI.
% Compiled module: SHAPELETS_HERMITE.
% Compiled module: PLT_DECOMP.
% Compiled module: SHAPELETS_RECOMP.
Type a number to continue...1
Type a number to continue...1
% Compiled module: SHAPELETS_C2P.
Type a number to continue...1
% Compiled module: SHAPELETS_ROTATE.
% Compiled module: SHAPELETS_SHEAR.
% Compiled module: SHAPELETS_EXTEND_NMAX.
% Compiled module: SHAPELETS_DILATE.
% Compiled module: SHAPELETS_READ_PSF.
% Compiled module: SHAPELETS_CONVOLVE.
% Compiled module: SHAPELETS_CONVOLUTION_MATRIX.
% SHAPELETS_EXTEND_NMAX: not changing n_max!
% Compiled module: TAG_EXIST.
Type a number to continue...1
% Compiled module: SHAPELETS_FOCUS.
% Compiled module: SHAPELETS_GUESS_NMAXBETA.
% SHAPELETS_FOCUS: Guessing n_max, beta, x_c:                2      9.55594                   40.8260      40.6830
% Compiled module: SHAPELETS_FOCUS_BETAX0.
% Compiled module: SIGN.
% Compiled module: SHAPELETS_AMOEBA.
% Compiled module: SHAPELETS_CENTROID.
% SHAPELETS_AMOEBA_CHI2:  n_max, beta, chi^2, x_c:           2      9.55594      38.8590      40.8260      40.6830
% SHAPELETS_AMOEBA_CHI2:  n_max, beta, chi^2, x_c:           2      11.7783      38.7892      40.7337      40.1408
% SHAPELETS_FOCUS_BETAX0: n_max, beta, chi^2, x_c:           2      11.7783      38.7945      40.6701      40.1595
% Compiled module: SHAPELETS_FOCUS_NMAX.
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:           2      11.7783      38.7945      40.6701      40.1595
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:           4      11.7783      32.8493      40.6701      40.1595
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:           6      11.7783      29.5038      40.6701      40.1595
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:           8      11.7783      25.8277      40.6701      40.1595
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:          10      11.7783      21.7415      40.6701      40.1595
% SHAPELETS_FOCUS_NMAX: n_max reached maximum
% SHAPELETS_AMOEBA_CHI2:  n_max, beta, chi^2, x_c:          10      11.7783      21.7415      40.6701      40.1595
% SHAPELETS_AMOEBA_CHI2:  n_max, beta, chi^2, x_c:          10      9.03913      12.9450      41.4748      40.4688
% SHAPELETS_FOCUS_BETAX0: n_max, beta, chi^2, x_c:          10      6.64239      6.62757      40.9295      40.4792
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:           2      6.64239      88.9436      40.9295      40.4792
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:           4      6.64239      27.8898      40.9295      40.4792
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:           6      6.64239      18.7179      40.9295      40.4792
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:           8      6.64239      9.20680      40.9295      40.4792
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:          10      6.64239      6.62757      40.9295      40.4792
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:          12      6.64239      3.80872      40.9295      40.4792
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:          14      6.64239      3.08563      40.9295      40.4792
% SHAPELETS_FOCUS_NMAX: n_max reached maximum
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:          15      6.64239      2.74338      40.9295      40.4792
% SHAPELETS_AMOEBA_CHI2:  n_max, beta, chi^2, x_c:          15      6.64239      2.74338      40.9295      40.4792
% SHAPELETS_AMOEBA_CHI2:  n_max, beta, chi^2, x_c:          15      5.09765      5.52217      40.6967      40.8232
% SHAPELETS_FOCUS_BETAX0: n_max, beta, chi^2, x_c:          15      6.54584      2.65841      40.6970      40.8459
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:           2      6.54584      92.1788      40.6970      40.8459
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:           4      6.54584      30.3180      40.6970      40.8459
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:           6      6.54584      18.2577      40.6970      40.8459
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:           8      6.54584      9.40836      40.6970      40.8459
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:          10      6.54584      6.45929      40.6970      40.8459
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:          12      6.54584      3.98094      40.6970      40.8459
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:          14      6.54584      2.98862      40.6970      40.8459
% SHAPELETS_FOCUS_NMAX: n_max reached maximum
% SHAPELETS_FOCUS_NMAX:   n_max, beta, chi^2, x_c:          15      6.54584      2.65841      40.6970      40.8459
% SHAPELETS_FOCUS: Flags: (0,2), n_max=15, chi^2=2.65841
% SHAPELETS_READ_PSF: Reading in TinyTim model of HST PSF
% SHAPELETS_PATHS: Shapelet export version of path names!
% SHAPELETS_EXTEND_NMAX: not changing n_max!
Type a number to continue...1
% SHAPELETS_PATHS: Shapelet export version of path names!
% Compiled module: SHAPELETS_READ_SHAPECAT.
% SHAPELETS_SHAPECAT_MOMENTS: Calculating object moments
% Compiled module: SHAPELETS_QUADRUPOLE.
% Compiled module: SHAPELETS_SHAPECAT2DECOMP.
Type a number to continue...1
Type a number to continue...1
Type a number to continue...1
 
 
Thank you for running the shapelets demonstration routine!
 
We hope that this has provided some useful template code.
For further information, please see the shapelets web page
at http://www.astro.caltech.edu/~rjm/shapelets/
 
Richard Massey and Alexandre Refregier.
 
% Program caused arithmetic error: Floating underflow
IDL>_

Return to the top of this page, the shapelets web page or the download page for shapelets code.