UNDER DEVELOPMENT

The software package is currently being dramatically improved and updated.
This is a (very) old version, potentially with bugs.

  Shapelets web page     Shapelets IDL code     Installation     Help pages     Simulated images  
List of routines
Instrutions for general code
Instructions for image simulation code

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:

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.


     -  shapelets_demo.pro - ×     
       
There is also a copyright notice inserted here. pro shapelets_demo, image, sexcat, decomp, psf, shapecat <-- -- Declares the name of the routine.
If the variables "image", "sexcat", "decomp", "psf" and "shapecat" are defined, they act as inputs. They are then returned to the main level when the routine exits - ready for the next time it is run, or for you to play with!
---> 
; +
; NAME:
;       SHAPELETS_DEMO
;
; PURPOSE:
;       Runs through the main shapelet routines to provide an example of
;       their use and to check that they are installed correctly.
;
; CATEGORY:
Anything following a semicolon and on the same line is a comment. ;       For demonstration purposes only.
;
; CALLING PROCEDURE:
;       shapelets_demo, image, sexcat, decomp, psf, shapecat
;
; INPUTS:
;       Accepts previously defined values of parameters, to save calculating
;       them anew each time this routine is executed. None are necessary.
;
; KEYWORD PARAMETERS:
;       None. Various bits of information are noted in the header.
;
; OUTPUTS:
;       Various plots to screen, a SExtractor catalogue and a shapelet
;       catalogue to disc.
;
; DATA REQUIRED:
Tests to see if the example data exists where IDL thinks it should. If IDL baulks at this, either it wasn't installed correctly, or shapelets_paths.pro needs updating.
"+" is the IDL string concatenation operator.
"$" anywhere lets the command continue to the next line.
;       Requires example data available for download from the shapelets
;       website http://www.ast.cam.ac.uk/~rjm/shapelets/.
;       This includes a small section of the HDF-N and an oversampled image
;       of the TinyTim model of the HST PSF. These should all be placed in
;       the subdirectories described by shapelets_paths.pro
;
; PROCEDURES USED:
;       Virtually all of the shapelet routines!
;
; MODIFICATION HISTORY: Reads in a FITS image.
The extension is added automatically. Subdirectories or relative paths can be included inside the quotes, to look for the image file in other locations. Also looks for an inverse variance map of the pixel noise (called *_noise.fits). This will be useful both to SExtractor and to shex.pro. If it is not found, the noise level is guessed from the image background. The image and noise map are then are stored together for convenience in one IDL structure called "image".
;       Sep 03 - Finalised for version 1 of shapelet code release by RM.
;       Mar 02 - Written by Richard Massey
; -
 
COMPILE_OPT idl2
 
; Check that IDL can correctly locate the example image
---> if not file_test(shapelets_paths(3)+'example.fits') then $
  message,'Please download the example data, and correct shapelets_paths.pro'
 
 
Plots an image.
This is simpler to use than IDL's built-in TV command. However, Aaron Barth's ATV is recommended for even easier image viewing.
; Read in example image and pixel noise map (image structure)
if not keyword_set(image) then shapelets_read_image,image,'example' <-- --
 
window,0,title='Example image (part of HDF-N)',$ ; Open graphics window
       xsize=512,ysize=512 $                     ; Spawns SExtractor as a child process.
This program is widely used in astronomy to locate individual objects within an image, using a friends-of-friends algorithm. It also calculates basic shape properties for each object, including size, flux and ellipticity. The .fits and .sexcat extensions are again added automatically.
If you are having difficulty installing SExtractor, and the script crashes at this line, read the compatibility note.
---> shapelets_plot_image,alog10(image.image>1e-5),                 ; Show image (on log scale)
read,'Type a number to continue...',junk         ; Pause for user input
wdelete                                          ; Close graphics window
 
 
; Read in SExtractor catalogue for example image (sexcat structure)
Reads in a SExtractor catalogue.
This loads the object positions and shape parameters from the file example.sex. They are stored in an IDL structure called "sexcat".
if not keyword_set(sexcat) then begin
  if not file_test(shapelets_paths(3)+'example.sex') then $
    sex,'example',telescope='HDF',filter='gauss_2.0_5x5' <-- --
--->   shapelets_read_sexcat,sexcat,'example'
endif
 
window,0,title='Size-magnitude diagram for example image'
22.1 is the zeropoint magnitude of the example image (a small section of the HDF-N), and 0.04 is its pixel scale, in arcseconds per pixel. ---> plot,sexcat.mag+22.1,sexcat.fwhm*0.04,psym=2,$   ; Plot size-magnitude diagram
     xtitle='Magnitude',ytitle='FWHM (arcsec)'   ;
help,sexcat,/structure                           ; Lists elements of structure <-Lists the SExtractor parameters stored for each object. There are 178 objects in this image.
read,'Type a number to continue...',junk         ; Pause for user input
wdelete                                          ; Close graphics window
 
  Cuts out a region from the image, around SExtractor object number 0. The size of the region is determined from the object's SExtractor parameters. The smaller image array, and the shape parameters, are stored in an IDL structure called "pstamp".
Plots the small region of the image containing our selected object. In this case, it's a spiral galaxy. ; Extract small, "postage-stamp" image around one object (pstamp structure)
b_id=(sort(sexcat.mag))[0]                       ; Select brightest in field
pstamp=shapelets_sexcat2pstamp(image,sexcat,0)   ; Extract postage stamp <-- --
window,0,title='Spiral galaxy',xsize=500,ysize=555
---> shapelets_plot_image,pstamp.image,title='ORIGINAL - Pretty spiral!!',/colbar,/frame
 
Reconstructs an image from the shapelet model by integrating the basis functions within pixels, then plots it to the screen.  
; Decompose it into shapelets (decomp structure)
if not keyword_set(decomp) then $ <-- -- Decomposes an image into shapelets.
Here the beta (5.3 pixels), n_max (15) and centroid (39.7,39.8) parameters are specified in advance. The resulting Cartesian shapelet coefficients are stored in an IDL structure called "decomp".
The "shapelet transform".
 shapelets_decomp,pstamp.image,5.3,15,decomp,noise=pstamp.noise, $
 x0=[357.7-pstamp.im_ran[0],178.8-pstamp.im_ran[2]],name='HDF spiral';,psf=psf
window,1,title='Spiral galaxy',xsize=500,ysize=555
---> shapelets_plot_decomp,decomp,title='SHAPELET MODEL - Pretty good match!!',/frame
read,'Type a number to continue...',junk
 
 
With /coef or /polar switches, this routine instead simply plots the shapelet coefficient arrays. The colour scale shows the strength of each component. The conversion to polar shapelets is performed on-the-fly. ; Display shapelet coefficient matrix
---> shapelets_plot_decomp,decomp,/coef,title='Cartesian shapelet coefficients'
read,'Type a number to continue...',junk
---> shapelets_plot_decomp,decomp,/polar,title='Polar shapelet coefficients' Perform a series of image manipulations merely by applying operators to the shapelet coefficients.
As described in Polar Shapelets, available options include rotations, dilations, shears, translations, changes of flux, circularisation and flipping.
read,'Type a number to continue...',junk
 
 
; Perform some image manipulations in shapelet space <-- --
decomp_manip=decomp                              ; Don't alter our good model!
shapelets_rotate,decomp_manip,45                 ; Rotate 45 degrees a/c/w
shapelets_shear,decomp_manip,[0.04,0.03],extend=5; Shear (and increase n_max)
shapelets_dilate,decomp_manip,0.05               ; Enlarge by factor 1.1
;shapelets_plot_decomp,decomp_manip                         ; Equivalent to next 2 lines
Recontructs an image from the shapelet model, but does not plot it. Creates recomp_manip, a 2D array of pixels.
The "reverse shapelet transform".
---> shapelets_recomp,decomp_manip,recomp_manip
shapelets_plot_image,recomp_manip,/frame,/colbar,$ Plots the reconstructed image, after all.
          title='SHAPELET MODEL - After some manipulation' <-- --
read,'Type a number to continue...',junk
wdelete,0
wdelete,1 Determines the optimum n_max, beta and centroid parameters, starting from guesses based upon SExtractor outputs, and using the iterative procedure described in Polar Shapelets. It takes a couple of minutes to run.
Since this demonstration is so well-planned(!) that we knew the optimum parameters in advance, the returned "decomp_optimal" structure should be identical to "decomp". The structure "history" contains a record of the route taken through the n_max vs beta plane, and the chi-squared values at each step.
 
 
; More clever shapelet decomposition (optimising n_max and beta automatically)
shapelets_focus,pstamp,focus,decomp_optimal,recomp_optimal, $ <-- --
Reads in a (pre-rendered) fits image of the TinyTim HST WFPC2 PSF model, as applicable to the example image and included in the example data zip file. This routine then decomposes it into shapelets and returns the HST PSF as a decomp structure.       nmax_ran=[2,15],th_min_geom=0.2,nmax_g=2,/print;,psf=psf
 
 
; Read in PSF model for the example image (decomp structure)
---> if not keyword_set(psf) then shapelets_read_psf,psf,/HST,pixsize=0.04,n_max=12
window,0,title='TinyTim PSF',xsize=500,ysize=555
shapelets_plot_decomp,psf
read,'Type a number to continue...',junk
wdelete,0
 
 
; Create and read in shapelet coefficient catalogue (shapecat structure)
if not keyword_set(shapecat) then begin
  if not file_test(shapelets_paths(3)+'example.shape') then $
    shex,'example',sexcat=sexcat,image=image,n_max=15,/plot <-- -- Runs the shapelet equivalent of SExtractor. The optimal n_max, beta and centroid parameters for each of the objects in the example image are determined, using the iterative procedure described in Polar Shapelets. The results are written to disc. The whole process takes about a minute, but is skipped on future occasions. For your convenience (or in case of problems), the output file "example.shape" is included in the pre-done/ subdirectory of the sample data zip file.
Reads a previously-calculated shapelet catalogue from disc. The "shapecat" structure contains the information needed to recreate the optimal decomp strucutre for every object within the image. Use shapelets_ shapecat2decomp.pro to extract the decomp structure for individual objects. --->   shapelets_read_shapecat,shapecat,'example',/moments
  decomp=shapelets_shapecat2decomp(shapecat,(sort(shapecat.mag))[0])
endif
 
 
; Match up objects in the SExtractor and shapelet catalogues
match=intarr(shapecat.n)
for i=0L,n_elements(match)-1 do match[i]=where(sexcat.id eq shapecat.sexid[i])
 
 
; Display some plots comparing SExtractor and shapelets output
window,0,title='SExtractor vs shapelets',xsize=500,ysize=555
zpoint=22.08
plot,sexcat.mag[match]+zpoint,shapecat.mag+zpoint,psym=1,/isotropic,$
     xrange=[20,32],/xstyle,yrange=[20,32],/ystyle,$
     title='SExtractor vs shapelets',$
     xtitle='SExtractor magnitude',ytitle='Shapelet magnitude'
read,'Type a number to continue...',junk
plot,[0,0],[0,0],xrange=[-0.1,0.1],yrange=[-0.1,0.1],/nodata,/isotropic,$
     title='Difference between SExtractor and shapelet centroids',$
Plots several comparisons between basic astronomical parameters determined via SExtractor or shapelets.      xtitle='x offset [arcsec]',ytitle='y offset [arcsec]'
plots,transpose(shapecat.centroid-sexcat.x[match,*])*0.04,psym=1
read,'Type a number to continue...',junk
---> plot,sexcat.fwhm[match],shapecat.beta,psym=1,$
     xrange=[0,40],/xstyle,yrange=[0,8],/ystyle,$
     title='SExtractor vs shapelets',$
     xtitle='SExtractor FWHM',ytitle='!6Optimal shapelet !7b!6'
read,'Type a number to continue...',junk
wdelete,0
 
 
; Print a friendly "good bye" message
print & print
print,'Thank you for running the shapelets demonstration routine!' Thank you, and good night.
print
print,'We hope that this has provided some useful template code.'
print,'For further information, please see the shapelets web page'
That's all, folks! print,'at http://www.astro.caltech.edu/~rjm/shapelets/'
print
print,'Richard Massey and Alexandre Refregier.'
print
 
---> end
 
 

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.


Last modified on 02nd May 2008 by Richard Massey.

Valid HTML 4.01!