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 (list elements)
  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.
• 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 (hide list)
  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'.

  NAME	STRING	Name of the catalogue
  TYPE	STRING	"shapecat"
  N	INTEGER	Number of objects contained in the catalogue
  MAXN_MAX	INTEGER ARRAY	Maximum shapelet order used by any object in the catalogue
  POLAR	BYTE	Flag to remember whether these coefficients are in Cartesian (0) or polar (1) shapelet form
  SEEING	FLOAT	FWHM seeing of oringinal image, in pixels
  X	FLOAT ARRAY	Centroid (x,y) of each object
  BETA	FLOAT ARRAY	Shapelet scale size for each object
  N_MAX	INTEGER ARRAY	Truncation parameter for each object
  N_COEFFS	INTEGER	Maximum number of shapelet coefficients used by an object
  COEFFS	FLOAT ARRAY	Shapelet coefficients, f_00 but f_ij/f_00 for the rest (to keep their range of values within floating point accuracy)
  COEFFS_ERROR	FLOAT ARRAY	Rms errors on shapelet coefficients for each object
  FLAG	INTEGER ARRAY	Two flags for each object, describing the success (or otherwise) of their decomposition. For their meanings, see the header of shex.pro.
  CHISQ	FLOAT ARRAY	Chi-squared values given by the fit to each object in the original image
  And, if SExtractor shape estimates are available
  SEXTRACTOR	BYTE	1/0 flag to show whether SExtractor shape estimates are available
  SEXID	INTEGER ARRAY	SExtractor ID number of each object
  SEXFWHM	FLOAT ARRAY	SExtractor FWHM size of each object
  SEXFLUX	FLOAT ARRAY	SExtractor total flux of each object
  SEXMAG	FLOAT ARRAY	SExtractor magnitude of each object (without zero-point calibration)
  SEXCLASS	FLOAT ARRAY	SExtractor star/galaxy classification of each object
  SEXA	FLOAT ARRAY	SExtractor major axis length of each object
  SEXTHETA	FLOAT ARRAY	SExtractor angle to major axis for each object
  SEXE1	FLOAT ARRAY	SExtractor horizontal ellipticity component of each object
  SEXE2	FLOAT ARRAY	SExtractor diagonal ellipticity component of each object
  SEXX	FLOAT ARRAY	SExtractor x coordinate of each object
  SEXY	FLOAT ARRAY	SExtractor y coordinate of each object
  SEXAREA	INTEGER ARRAY	Number of pixels used in SExtractor segmentation map for each object
  OBJX_MIN	INTEGER ARRAY	Left-most pixel included in postage stamp for each object's inital decomposition
  OBJX_MAX	INTEGER ARRAY	Right-most pixel included in postage stamp for each object's inital decomposition
  OBJY_MIN	INTEGER ARRAY	Lowest pixel included in postage stamp for each object's inital decomposition
  OBJY_MAX	INTEGER ARRAY	Highest pixel included in postage stamp for each object's inital decomposition
  And, if the catalogue is read using the additional flag /MOMENTS, the following are also calculated from the shapelet coefficients of each object:
  MOMENTS	BYTE	1/0 flag to show whether objects' shape moments have been calculated from the shapelet coefficients
  FLUX	FLOAT ARRAY	Total flux
  FLUX_ERROR	FLOAT ARRAY	Error on the flux
  SNR	FLOAT ARRAY	Estimated signal-to-noise ratio
  MAG	FLOAT ARRAY	Magnitude (without zero-point calibration)
  CENTROID	FLOAT ARRAY	Centroid (same as x above)
  CENTROID_ERROR	FLOAT ARRAY	Error on the centroid
  RSQUARED	FLOAT ARRAY	Rms size estimator
  RSQUARED_ERROR	FLOAT ARRAY	Error on the rms size estimator
  ELLIPTICITY	FLOAT ARRAY	Unweighted ellipticity
  ELLIPTICITY_ERROR	FLOAT ARRAY	Error on the ellipticity
  QUADRUPOLE	FLOAT ARRAY	Unweighted quadrupole moments
  QUADRUPOLE_ERROR	FLOAT ARRAY	Error on the quadrupole moments

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.