Help for "shapelets_focus" routine:

Optimise nmax, beta and centroid parameters.

Several "meta-parameters" must be specified before a shapelet decomposition is possible. This routine explores possible values of these beta (size of the Gaussian around which shapelet basis functions are based), n_max (truncation parameter) and x_c (centre of the shapelet basis functions) parameters. It iteratively explores the parameter space, recording the chi^2 of the reconstruction residual at each step. It heads towards parameters that produce a model whose residual is consistent with noise (chi^2=1), using the fewest possible coefficents (lowest n_max) to achieve this goal. It is described in great detail in the paper Polar shapelets by Massey & Refregier (2004).

The two main components of this search are the routines shapelets_focus_beta.pro and shapelets_focus_nmax.pro. These perform the search in the beta and n_max directions respectively. The optimisation of the x_c turns out to be very quick and stable. A simultaneous centroid iteration is therefore included during each step taken in the beta direction.

See also the header below, which has been extracted from the source code for this routine.

; NAME:
;       SHAPELETS_FOCUS
;
; PURPOSE:
;       Find the optimal beta, n_max and centroid for a shapelet
;       decomposition via an iterative search throughout the space spanned
;       by these (meta-)variables. See the paper Polar shapelets, by
;       Massey & Refregier (2004) for more details.
;
; CATEGORY:
;       Shapelets.
;
; INPUTS:
;       PSTAMP - Postage stamp structure containing the image (and other
;                parameters) around a single object. This can be created with
;                shapelets_sexcat2pstamp.pro
;
; OPTIONAL INPUTS:
;       BETA_GUESS      - Starting point for shapelet scale size beta.
;       N_MAX_GUESS     - Starting point for truncation order n_max.
;       CENTRE_GUESS    - Starting point for centre of shapelet basis functions.
;       CHISQ_TARGET    - Ideal value of reduced chi^2 for the residual image.
;       CHISQ_TOLERANCE - Acceptable accuracy for chi^2, in units of the rms.
;       CHISQ_FLATNESS  - Minimum difference in chi^2 between two decompositions
;                         with n_max differing by two to trigger the flatness
;                         constraint in shapelets_focus_nmax
;       BETA_TOLERANCE  - Fractional tolerance for finding beta.
;       FIXED_BETA      - Force this value of beta for all objects. Still iterates
;                         to find the best centroid and n_max.
;       AMOEBA_SCALE    - Controls the size of the amoeba's steps.
;       THETA_MIN_GEOM  - Minimum scale on which it is possible for the image to
;                         contain data.
;       N_MAX_RANGE     - Range of n_max values to consider.
;       PSF             - A shapelet decomp structure representing the local PSF.
;                         The shapelet model of the galaxy will be deconvolved
;                         from this.
;
; KEYWORD PARAMETERS:
;       SILENT          - Operate silently.
;       VERBOSE         - Operate noisily.
;       SKY             - 1: fit sky background with a constant value around object.
;                         2: fit sky gradient with a plane around object.
;                         DEFAULT: no sky subtraction.
;       NON1            - a_01 and a_10 are forced to be zero, Kuijken-like.
;       FULL_FOCUS      - Record every single attempt made at decomposition during
;                         iteration. Makes things a little slower, but plots nicer. 
;
; OUTPUTS:
;       DECOMP     	- Decomposition structure containing the shapelet
;                  	  coefficients with the optimal beta, n_max and centroid
;                  	  parameters.
;
; OPTIONAL OUTPUTS:
;       FOCUS      	- IDL structure tracing the search on the beta-n_max plane.
;       RECOMP     	- Recomposed image using optimal shapelet parameters.
;
; CALLING SEQUENCE:
;       decomp=shapelets_focus(pstamp,focus=focus)
;
; NOTES:
;       MEANINGS OF FLAG: (out of date!)
;       0: OK
;       1: Iteration bounced into theta_min or max wall at some point
;       2: n_max_max reached - shapelets incompletely represent object
;       3: Converged (in n_max search) by flatness limit.
;       4: Could not converge to target chi^2 (either not monotonic in n_max or dithering amoeba) 
;       5: Centroid wandered, pushing the basis functions off the edge of the postage stamp
;       6: Fatal error
;       NB it can only be one of these. If duplicated, highest number takes
;          priority.
;
; MODIFICATION HISTORY:
;       Jul 07 - Fixed to work with older versions of IDL by RM.
;       Feb 07 - *_RESIDUAL keywords propagated by RM
;       Apr 06 - Possibility of a maximum allowed iteration time added by RM.
;       Sep 05 - POLAR and DIAMOND options added by RM.
;       Jul 05 - Significant load of bug fixes and clean up by RM.
;       Apr 05 - NON1 keyword added by RM.
;       Apr 05 - Guess used as starting n_max by Stephane Paulin-Henriksson.
;       Nov 04 - PSF passed to guess_nmax_beta routine by RM.
;       Aug 04 - Fixed_beta and max_loops keywords added by RM.
;       Jul 04 - Header updated to reflect new additional options by RM.
;       May 04 - Tidied up by RM.
;       Apr 02 - PSF deconvolution implemented by Richard Massey.
;       Apr 02 - Written by Richard Massey and Alexandre Refregier.

View the full source code for this routine, return to the shapelets web page, or return to the code help menu.