# Help for "shapelets_decomp" routine:

## Transform an image into shapelets using overlap integrals or a least-squares fit.

This is essentially the core of the shapelets routines. It takes an image array and decomposes it into shapelets. It returns a decomp structure, which contains a list of the shapelet coefficients.

The input variable f should be a simple, 2D floating point array representing the flux in a grid of pixels (rather than a full image structure). The shapelet scale size, beta, and truncation order n_max are also required by this routine. If they are not known, shapelets_focus.pro, can be used to iteratively find the optimum values for these parameters, as described in the Shapelets: III. Polar shapelets paper. Setting an input variable x0=[10.5,11.2], for example, can also be used to specify the position where the shapelet basis functions are centred.

There are many other optional input parameters. These are all described in the header below. Perhaps the most useful are ls, which governs whether the decomposition is performed via least-squares fitting or overlap integrals; integrate, which governs whether the basis functions are evaluated at the centre of each pixel or by integration within them (assuming that they are regularly spaced in squares, and extend to the point half-way between their centre and the centre of the adjacent pixel in all directions); over, which controls the oversampling of pixels in the former case; and sky, which can be set to 1 to simultaneously fit the sky background or 2 to fit the sky background and local gradient.

A "reverse shapelet transform" i.e. the generation of a pixellated image from a list of shapelet coefficients can be performed using shapelets_recomp.pro.

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

```; NAME:
;      SHAPELETS_DECOMP
;
; CATEGORY:
;      Shapelets.
;
; PURPOSE:
;      Decompose an image into a weighted sum of shapelet basis functions.
;
; INPUTS:
;      IMAGE     - Shapelets image/pstamp structure, or 2D image array.
;      BETA      - Shapelet basis function scale size.
;      N_MAX     - Maximum order of the basis coefficients used in model.
;
; OPTIONAL INPUTS:
;      PSF       - A decomp structure representing the local PSF, to be
;                  decomvolved.
;      CENTRE    - Coordinates of the centre of the basis functions.
;                  DEFAULT: from structure, or centre of the image.
;      NAME      - Name of object (string).
;                  DEFAULT: from structure, or empty.
;      NOISE     - Inverse variance map of pixels, or constant noise value.
;                  Assumes zero covariance between adjacent pixels.
;                  DEFAULT: from structure, or constant unity.
;      MASK      - Array the same size as images, with zero for good pixels
;                  and one for pixels to ignore (could also be achieved with
;                  the weight map.
;      BASIS_ELLI- Ellipticity of basis functions, in weak lensing notation:
;                  either [e1,e2] or complex(e1,e2), where e1=e*cos(2theta) and
;                  e2=e*sin(2theta), with e=(a-b)/(a+b) for major and minor axes
;                  and theta is the angle of the major axis, a/c/w from x axis.
;                  This only works for basis functions not integrated in pixels.
;                  DEFAULT: circular basis functions.
;      THETA_ZERO- Basis functions are rotated by this anlge, a/c/w from x axis.
;                  DEFAULT: zero for circular basis functions, and the major
;                           axis of the ellipse for elliptical ones.
;      OVERSAMPLE- Force an oversampling factor to evaluate the basis fns.
;                  the basis functions (set over=1 to get round(1/theta_min))
;                  DEFAULT: no oversampling
;      SKY       - 1: fit sky background with a constant value
;                  2: fit sky gradient with a plane
;                  DEFAULT: no sky subtraction.
;      REBIN_RESI- Bin up the residual image by this integer factor before
;                  calculating chi squared.
;                  DEFAULT: residual image used in same pixel scale as input.
;      SMOOTH_RES- Smooth the residual image (using a boxcar average of this
;                  number of pixels) before calculating chi squared.
;                  DEFAULT: residual image returned in same form as the input.
;
; KEYWORD PARAMETERS:
;      POLAR     - Perform decomposition using polar shapelet basis fns.
;                  DEFAULT: Cartesian shapelet basis functions.
;      EXPONENTIA- Perform decomposition using exponential shapelet basis fns.
;                  DEFAULT: Gaussian shapelet basis functions.
;      OVERLAP   - Obtain coefficients via Fourier-style overlap integrals.
;                  DEFAULT: least-squares fitting.
;      FULL_ERROR- Return full covariance matrix of coefficients.
;                  DEFAULT: return error on coefficients in error variable.
;      INTEGRATE - Use basis functions integrated within pixels.
;                  DEFAULT: integration (for central pixel value, set int=0)
;      NON1      - n=1 coefficients are forced to be zero, Kuijken-like.
;                  DEFAULT: all the coefficients are fit.
;      INVERSION - Use a simple matrix inversion rather than SVD.
;                  DEFAULT: singular valued decomposition, as of March 07.
;      DIAMOND   - Alternate truncation scheme for shapelet basis functions.
;                  DEFAULT: usual tringular scheme, with n<=n_max
;
;
; OUTPUTS:
;      DECOMP    - A shapelet decomp structure is returned, containing the
;                  evaluated shapelet coefficeints, meta-parameters and other
;                  information.
;
; OPTIONAL OUTPUTS
;      RECOMP    - Repixellated image of the shapelet model (still containing
;                  the sky background and convolved with the original PSF. To
;                  remove this, use shapelets_recomp,decomp,recomp).
;      RESIDUAL  - Residual image (after any treatments used to adjust chi^2).
;      WAVELET_RE- Wavelet decomposition of the residual (before adjustments).
;
; CALLING SEQUENCE:
;      decomp=shapelets_decomp(image, beta, n_max)
;
; KNOWN BUGS:
;      Overlap integrals give slightly different results for polar and
;      Cartesian shapelet basis functions. Results are identical when fitting,
;      and I'd've thought that they would also be for overlap. Should they?
;
; TO DO:
;      In the SVD, should singular values be set to zero or infinity?
;      Do something (anything!) with the full covariance matrix of errros.
;
; MODIFICATION HISTORY:
;      Aug 10 - RM disabled simultaneous truncation schemes to simplify code.
;      Jul 10 - RM added EXPONENTIAL option.
;      Jun 10 - RM added ability to supply PSF as a bitmap image.
;      Feb 10 - RM improved handling of NaNs and memory for large images.
;      Sep 07 - RM made sure noise variable is created despite any input format.
;      Apr 07 - RM added THETA_ZERO option.
;      Mar 07 - RM implemented fitting with elliptical basis functions.
;      Mar 07 - RM replaced matrix inversion with singular value decomposition.
;      Mar 07 - RM added wavelet analysis of residual (needs JLS's software).
;      Mar 07 - Joel Berge recorrected propagation of errors on polar coeffs.
;      Feb 07 - RM added RESIDUAL keyword, plus options to rebin or smooth the
;               residual before calculating chi squared.
;      Feb 07 - RM used no. of independent, non-oversampled pixels in chi2.
;      Sep 05 - RM changed the routine from a procedure to a function.
;      Sep 05 - RM added POLAR and DIAMOND options.
;      Aug 05 - RM accepted images in a wider variety of input formats.
;      Aug 05 - RM internalised LS fitting matrix and reorganised whole routine
;               in an attempt to speed things up.
;      Jul 05 - RM incorporated external create_decomp routine.
;      Jan 05 - RM optimised gamma and n_max_gamma during PSF deconvolution.
;      Apr 04 - RM added ability to mask pixels (by setting weight map to zero)
;               but still calculate the correct number of DOFs in the fit
;      Sep 03 - RM changed name of routine to shapelet_decomp.pro
;      Jul 03 - RM added "name" element to decomp structure
;      Apr 02 - RM added PSF deconvolution
;      Mar 02 - AR computed Chi^2 and fixed normalisation. Also added
;               option to return the recomposed (still convolved) image
;      Dec 01 - RM implemented least squares fitting of basis fns to data
;      Nov 01 - RM added background subtraction and sky fitting
;      Nov 01 - Richard Massey added numerical integration of basis fns
;      Feb 01 - AR incorporated oversampling of the basis functions
;      Jul 00 - AR changed to order by n=n1+n2
;      Jul 99 - mk_decomp.pro written by Alexandre Refregier
```

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

 Last modified on 2nd Mar 2009 by Richard Massey.