HSM Implementation

Primary Interface

template<typename T, typename U>
void galsim::hsm::EstimateShearView(ShapeData &results, const BaseImage<T> &gal_image, const BaseImage<U> &PSF_image, const BaseImage<int> &gal_mask_image, float sky_var = 0.0, const char *shear_est = "REGAUSS", const char *recompute_flux = "FIT", double guess_sig_gal = 5.0, double guess_sig_PSF = 3.0, double precision = 1.0e-6, galsim::Position<double> guess_centroid = galsim::Position<double>(-1000., -1000.), const HSMParams &hsmparams = HSMParams())

Carry out PSF correction directly using Images.

A template function to carry out one of the multiple possible methods of PSF correction using the HSM package, directly accessing the input Images. The input arguments get repackaged before calling general_shear_estimator, and results for the shape measurement are returned as ShapeData. There are two arguments that have default values, namely shear_est (the type of shear estimator) and recompute_flux (for the REGAUSS method only).

Parameters:

  • [in/out] – results A ShapeData object to hold the results

  • gal_image – [in] The BaseImage for the galaxy being measured

  • PSF_image – [in] The BaseImage for the PSF

  • gal_mask_image – [in] The BaseImage for the mask image to be applied to the galaxy being measured (integer array, 1=use pixel and 0=do not use pixel).

  • sky_var – [in] The variance of the sky level, used for estimating uncertainty on the measured shape; default 0.

  • *shear_est – [in] A string indicating the desired method of PSF correction: REGAUSS, LINEAR, BJ, or KSB; default REGAUSS.

  • *recompute_flux – [in] A string indicating whether to recompute the object flux, which should be NONE (for no recomputation), SUM (for recomputation via an unweighted sum over unmasked pixels), or FIT (for recomputation using the Gaussian + quartic fit).

  • guess_sig_gal – [in] Optional argument with an initial guess for the Gaussian sigma of the galaxy, default 5.0 (pixels).

  • guess_sig_PSF – [in] Optional argument with an initial guess for the Gaussian sigma of the PSF, default 3.0 (pixels).

  • precision – [in] The convergence criterion for the moments; default 1e-6.

  • guess_centroid – [in] Optional argument with an initial guess for the centroid of the galaxy; if not set, then the code will try the center of the image.

  • hsmparams – [in] Optional argument to specify parameters to be used for shape measurement routines, as an HSMParams object.

template<typename T>
void galsim::hsm::FindAdaptiveMomView(ShapeData &results, const BaseImage<T> &object_image, const BaseImage<int> &object_mask_image, double guess_sig = 5.0, double precision = 1.0e-6, galsim::Position<double> guess_centroid = galsim::Position<double>(-1000., -1000.), bool round_moments = false, const HSMParams &hsmparams = HSMParams())

Measure the adaptive moments of an object directly using Images.

This function repackages the input BaseImage in a format that find_ellipmom_2 accepts, in order to iteratively compute the adaptive moments of an object. The key result is the best-fit elliptical Gaussian to the object, which is computed by initially guessing a circular Gaussian that is used as a weight function, computing the weighted moments, recomputing the moments using the result of the previous step as the weight function, and so on until the moments that are measured are the same as those used for the weight function.

Parameters:

  • [in/out] – A ShapeData object to hold the results

  • object_image – [in] The BaseImage for the object being measured.

  • object_mask_image – [in] The BaseImage for the mask image to be applied to the object being measured (integer array, 1=use pixel and 0=do not use pixel).

  • guess_sig – [in] Optional argument with an initial guess for the Gaussian sigma of the object, default 5.0 (pixels).

  • precision – [in] The convergence criterion for the moments; default 1e-6.

  • guess_centroid – [in] Optional argument with an initial guess for the centroid of the galaxy; if not set, then the code will try the center of the image.

  • hsmparams – [in] Optional argument to specify parameters to be used for shape measurement routines, as an HSMParams object.

struct HSMParams

Public Functions

inline HSMParams(double _nsig_rg, double _nsig_rg2, double _max_moment_nsig2, int _regauss_too_small, int _adapt_order, double _convergence_threshold, long _max_mom2_iter, long _num_iter_default, double _bound_correct_wt, double _max_amoment, double _max_ashift, int _ksb_moments_max, double _ksb_sig_weight, double _ksb_sig_factor, double _failed_moments)
inline HSMParams()

A reasonable set of default values

Public Members

double nsig_rg
double nsig_rg2
double max_moment_nsig2
int regauss_too_small
int adapt_order
double convergence_threshold
long max_mom2_iter
long num_iter_default
double bound_correct_wt
double max_amoment
double max_ashift
int ksb_moments_max
double ksb_sig_weight
double ksb_sig_factor
double failed_moments
class HSMError : public std::runtime_error

Exception class thrown by the adaptive moment and shape measurement routines in the hsm namespace.

Public Functions

inline HSMError(const std::string &m)

Helper Functions

unsigned int galsim::hsm::general_shear_estimator(ConstImageView<double> gal_image, ConstImageView<double> PSF_image, ObjectData &gal_data, ObjectData &PSF_data, const char *shear_est, unsigned long flags, const HSMParams &hsmparams)

Carry out PSF correction.

Carry out one of the multiple possible methods of PSF correction using the HSM package. Results for the shape measurement are returned by modifying the galaxy data directly. The flags parameter is only used for the REGAUSS shape measurement method, and is defined as follows: 0x1=recompute galaxy flux by summing unmasked pixels, 0x2=recompute galaxy flux from Gaussian-quartic fit, 0x4=cut off Gaussian approximator at NSIG_RG sigma to save time, 0x8=cut off PSF residual at NSIG_RG2 to save time.

Parameters:

  • gal_image – [in] The galaxy Image.

  • PSF_image – [in] The PSF Image.

  • gal_data – [in] The ObjectData object for the galaxy

  • PSF_data – [in] The ObjectData object for the PSF

  • shear_est – [in] A string indicating the desired method of PSF correction: REGAUSS, LINEAR, BJ, or KSB.

  • flags – [in] A parameter for REGAUSS (typical usage is 0xe).

  • hsmparams – [in] Optional argument to specify parameters to be used for shape measurement routines, as an HSMParams object.

Returns:

A status flag that should be zero if the measurement was successful.

void galsim::hsm::find_ellipmom_2(ConstImageView<double> data, double &A, double &x0, double &y0, double &Mxx, double &Mxy, double &Myy, double &rho4, double convergence_threshold, int &num_iter, const HSMParams &hsmparams)

Measure the adaptive moments of an object.

This function iteratively computes the adaptive moments of an image, and tells the user the results plus other diagnostic information. The key result is the best-fit elliptical Gaussian to the object, which is computed by initially guessing a circular Gaussian that is used as a weight function, computing the weighted moments, recomputing the moments using the result of the previous step as the weight function, and so on until the moments that are measured are the same as those used for the weight function.

Parameters:

  • data – [in] The Image for the object being measured.

  • A – [out] The amplitude of the best-fit elliptical Gaussian (total image intensity for the Gaussian is 2A).

  • x0 – [out] The x centroid of the best-fit elliptical Gaussian.

  • y0 – [out] The y centroid of the best-fit elliptical Gaussian.

  • Mxx – [out] The xx component of the moment matrix.

  • Mxy – [out] The xy component of the moment matrix.

  • Myy – [out] The yy component of the moment matrix.

  • rho4 – [out] The weighted radial fourth moment.

  • convergence_threshold – [in] The required level of accuracy.

  • num_iter – [out] The number of iterations needed to converge.

  • hsmparams – [in] Optional argument to specify parameters to be used for shape measurement routines, as an HSMParams object.

struct ShapeData

Struct containing information about the shape of an object.

This representation of an object shape contains information about observed shapes and shape estimators after PSF correction. It also contains information about what PSF correction was used; if no PSF correction was carried out and only the observed moments were measured, the PSF correction method will be ‘None’. Note that observed shapes are bounded to lie in the range |e| < 1 or |g| < 1, so they can be represented using a Shear object. In contrast, the PSF-corrected distortions and shears are not bounded at a maximum of 1 since they are shear estimators, and placing such a bound would bias the mean. Thus, the corrected results are not represented using Shear objects, since it may not be possible to make a meaningful per-object conversion from distortion to shear (e.g., if |e|>1).

Public Functions

inline ShapeData()

Constructor, setting defaults.

Public Members

Bounds<int> image_bounds

galsim::Bounds object describing the image of the object

int moments_status

Status after measuring adaptive moments; -1 indicates no attempt to measure them.

float observed_e1

The observed shape e1,e2.

float observed_e2
float moments_sigma

Size sigma = (det M)^(1/4) from the adaptive moments, in units of pixels; -1 if not measured.

float moments_amp

Total image intensity for best-fit elliptical Gaussian from adaptive moments; note that this is not flux, since flux = (total image intensity)*(pixel scale)^2.

Position<double> moments_centroid

Centroid of best-fit elliptical Gaussian.

double moments_rho4

The weighted radial fourth moment of the image.

int moments_n_iter

Number of iterations needed to get adaptive moments; 0 if not measured.

int correction_status

Status after carrying out PSF correction; -1 indicates no attempt to do so.

float corrected_e1

Estimated e1 after correcting for effects of the PSF, for methods that return a distortion. Default value -10 if no correction carried out.

float corrected_e2

Estimated e2 after correcting for effects of the PSF, for methods that return a distortion. Default value -10 if no correction carried out.

float corrected_g1

Estimated g1 after correcting for effects of the PSF, for methods that return a shear. Default value -10 if no correction carried out.

float corrected_g2

Estimated g2 after correcting for effects of the PSF, for methods that return a shear. Default value -10 if no correction carried out.

std::string meas_type

‘e’ for PSF correction methods that return a distortion, ‘g’ for methods that return a shear. “None” if PSF correction was not done.

float corrected_shape_err

Shape measurement uncertainty sigma_gamma (not sigma_e) per component.

std::string correction_method

String indicating PSF-correction method; “None” if PSF correction was not done.

float resolution_factor

Resolution factor R_2; 0 indicates object is consistent with a PSF, 1 indicates perfect resolution; default -1.

float psf_sigma

PSF size sigma = (det M)^(1/4) from the adaptive moments, in units of pixels; default -1.

float psf_e1

PSF shape from the adaptive moments.

float psf_e2
std::string error_message

A string containing any error messages from the attempted measurements, to facilitate proper error handling in both C++ and python.

struct ObjectData

Characterizes the shape and other parameters of objects.

Describe the hsm shape-related parameters of some object (usually galaxy) before and after PSF correction. All ellipticities are defined as (1-q^2)/(1+q^2), with the 1st component aligned with the pixel grid and the 2nd aligned at 45 degrees with respect to it. There are two choices for measurement type: ‘e’ = Bernstein & Jarvis (2002) ellipticity (or distortion), ‘g’ = shear estimator = shear*responsivity. The sigma is defined based on the observed moments M_xx, M_xy, and M_yy as sigma = (Mxx Myy - M_xy^2)^(1/4) = [ det(M) ]^(1/4).

Public Functions

inline ObjectData()

Public Members

double x0

x centroid position within the postage stamp, in units of pixels

double y0

y centroid position within the postage stamp, in units of pixels

double sigma

size parameter

double flux

total flux

double e1

first ellipticity component

double e2

second ellipticity component

double responsivity

responsivity of ellipticity estimator

char meas_type

type of measurement (see function description)

double resolution

resolution factor (0=unresolved, 1=resolved)