API Reference¶

class statmorph.SourceMorphology(image, segmap, label, mask=None, weightmap=None, gain=None, psf=None, cutout_extent=2.5, min_cutout_size=48, n_sigma_outlier=10, annulus_width=1.0, eta=0.2, petro_fraction_gini=0.2, skybox_size=32, petro_extent_cas=1.5, petro_fraction_cas=0.25, boxcar_size_mid=3.0, niter_bh_mid=5, sigma_mid=1.0, petro_extent_flux=2.0, boxcar_size_shape_asym=3.0, sersic_fitting_args=None, sersic_model_args=None, sersic_maxiter=None, include_doublesersic=False, doublesersic_rsep_over_rhalf=2.0, doublesersic_tied_ellip=False, doublesersic_fitting_args=None, doublesersic_model_args=None, segmap_overlap_ratio=0.25, verbose=False)[source]¶

Class to measure the morphological parameters of a single labeled source. The parameters can be accessed as attributes or keys.

Parameters:

image (array-like) – A 2D image containing the sources of interest. The image must already be background-subtracted.
segmap (array-like (int) or photutils.segmentation.SegmentationImage) – A 2D segmentation map where different sources are labeled with different positive integer values. A value of zero is reserved for the background. It is assumed that the sum of pixel values within each labeled segment is positive.
label (int) – A label indicating the source of interest.
mask (array-like (bool), optional) – A 2D array with the same size as image, where pixels set to True are ignored from all calculations.
weightmap (array-like, optional) – Also known as the “sigma” image, this is a 2D array with the same size and units as image that contains one standard deviation of the value at each pixel (which is related to the Poisson noise). Note that SExtractor and other software sometimes produce a weight map in units of the variance (RMS^2) or the inverse variance (1/RMS^2).
gain (scalar, optional) – A multiplication factor that converts the image units into electrons/pixel, which is used internally to calculate the weight map (i.e., the sigma-image) using Poisson statistics. This parameter is only used when weightmap is not provided.
psf (array-like, optional) – A 2D array representing the PSF, where the central pixel corresponds to the center of the PSF. Typically, including this keyword argument will make the code run slower by a factor of a few, depending on the size of the PSF, but the resulting Sersic fits will be more correct.
cutout_extent (float, optional) – The target fractional size of the data cutout relative to the minimal bounding box containing the source. The value must be >= 1.
min_cutout_size (int, optional) – The minimum size of the cutout, in case cutout_extent times the size of the minimal bounding box is smaller than this. Any given value will be truncated to an even number.
n_sigma_outlier (scalar, optional) – The number of standard deviations that define a pixel as an outlier, relative to its 8 neighbors. Outlying pixels are removed as described in Lotz et al. (2004). If the value is zero or negative, outliers are not removed. The default value is 10.
annulus_width (float, optional) – The width (in pixels) of the annuli used to calculate the Petrosian radius and other quantities. The default value is 1.0.
eta (float, optional) – The Petrosian eta parameter used to define the Petrosian radius. For a circular or elliptical aperture at the Petrosian radius, the mean flux at the edge of the aperture divided by the mean flux within the aperture is equal to eta. The default value is typically set to 0.2 (Petrosian 1976).
petro_fraction_gini (float, optional) – In the Gini calculation, this is the fraction of the Petrosian “radius” used as a smoothing scale in order to define the pixels that belong to the galaxy. The default value is 0.2.
skybox_size (int, optional) – The target size (in pixels) of the “skybox” used to characterize the sky background.
petro_extent_cas (float, optional) – The radius of the circular aperture used for the asymmetry calculation, in units of the circular Petrosian radius. The default value is 1.5.
petro_fraction_cas (float, optional) – In the CAS calculations, this is the fraction of the Petrosian radius used as a smoothing scale. The default value is 0.25.
boxcar_size_mid (float, optional) – In the MID calculations, this is the size (in pixels) of the constant kernel used to regularize the MID segmap. The default value is 3.0.
niter_bh_mid (int, optional) – When calculating the multimode statistic, this is the number of iterations in the basin-hopping stage of the maximization. A value of at least 100 is recommended for “production” runs, but it can be time-consuming. The default value is 5.
sigma_mid (float, optional) – In the MID calculations, this is the smoothing scale (in pixels) used to compute the intensity (I) statistic. The default is 1.0.
petro_extent_flux (float, optional) – The number of Petrosian radii used to define the aperture over which the flux is measured. This is also used to define the inner “radius” of the elliptical aperture used to estimate the sky background in the shape asymmetry calculation. Following SDSS, the default value is 2.0.
boxcar_size_shape_asym (float, optional) – When calculating the shape asymmetry segmap, this is the size (in pixels) of the constant kernel used to regularize the segmap. The default value is 3.0.
sersic_fitting_args (dict, optional) – A dictionary of keyword arguments passed to Astropy’s LevMarLSQFitter, which cannot include z or weights (these are handled internally by statmorph).
sersic_model_args (dict, optional) – A dictionary of keyword arguments passed to Astropy’s Sersic2D. Note that, by default, statmorph will make reasonable initial guesses for all the model parameters (recommended), although this functionality can be overridden for more customized fits. Also note that, by default, statmorph imposes a lower bound of n = 0.01 for the fitted Sersic index.
sersic_maxiter (int, optional) – Deprecated. Please use sersic_fitting_args instead.
include_doublesersic (bool, optional) – If True, also fit a double 2D Sersic model. The default is False.
doublesersic_rsep_over_rhalf (float, optional) – This specifies the “boundary” used to separate the inner and outer regions of the image, which are used to perform single Sersic fits and thus construct an initial guess for the double Sersic fit. This argument is provided as a multiple of the (non-parametric) half-light semimajor axis rhalf_ellip. The default value is 2.0.
doublesersic_tied_ellip (bool, optional) – If True, both components of the double Sersic model share the same ellipticity and position angle. The same effect could be achieved using doublesersic_model_args in combination with the ‘tied’ argument, although the syntax would be slightly more involved. The default value is False.
doublesersic_fitting_args (dict, optional) – Same as sersic_fitting_args, but for the double 2D Sersic fit.
doublesersic_model_args (dict, optional) – Same as sersic_model_args, but for the double 2D Sersic fit.
segmap_overlap_ratio (float, optional) – The minimum ratio (in order to have a “good” measurement) between the area of the intersection of the Gini and MID segmaps and the area of the largest of these two segmaps.
verbose (bool, optional) – If True, this prints various minor warnings (which do not result in “bad” measurements) during the calculations. The default value is False.

References

See README.rst for a list of references.

property asymmetry¶: Calculate asymmetry as described in Lotz et al. (2004).

property concentration¶: Calculate concentration as described in Lotz et al. (2004).

property deviation¶: Calculate the deviation (D) statistic as described in Peth et al. (2016).

property doublesersic_aic¶: Akaike Information Criterion (AIC) of the fitted model.

property doublesersic_amplitude1¶: The amplitude of the first component of the double 2D Sersic fit at its effective radius (rhalf1).

property doublesersic_amplitude2¶: The amplitude of the second component of the double 2D Sersic fit at its effective radius (rhalf2).

property doublesersic_bic¶: Bayesian Information Criterion (BIC) of the fitted model.

property doublesersic_chi2_dof¶: Reduced chi^2 statistic of the fitted double 2D Sersic model.

property doublesersic_ellip1¶: The ellipticity of the first component of the double 2D Sersic fit.

property doublesersic_ellip2¶: The ellipticity of the second component of the double 2D Sersic fit.

property doublesersic_n1¶: The Sersic index n of the first component of the double 2D Sersic fit.

property doublesersic_n2¶: The Sersic index n of the second component of the double 2D Sersic fit.

property doublesersic_rhalf1¶: The effective (half-light) radius of the first component of the double 2D Sersic fit.

property doublesersic_rhalf2¶: The effective (half-light) radius of the second component of the double 2D Sersic fit.

property doublesersic_theta1¶: The orientation (counterclockwise, in radians) of the first component of the double 2D Sersic fit.

property doublesersic_theta2¶: The orientation (counterclockwise, in radians) of the second component of the double 2D Sersic fit.

property doublesersic_xc¶: The x-coordinate of the center of the double 2D Sersic fit, relative to the original image.

property doublesersic_yc¶: The y-coordinate of the center of the double 2D Sersic fit, relative to the original image.

property ellipticity_asymmetry¶: The ellipticity of (the Gaussian function that has the same second-order moments as) the source, relative to the point that minimizes the asymmetry.

property ellipticity_centroid¶: The ellipticity of (the Gaussian function that has the same second-order moments as) the source, relative to the centroid.

property elongation_asymmetry¶: The elongation of (the Gaussian function that has the same second-order moments as) the source, relative to the point that minimizes the asymmetry.

property elongation_centroid¶: The elongation of (the Gaussian function that has the same second-order moments as) the source, relative to the centroid.

property flux_circ¶: Return the sum of the pixel values over a circular aperture with radius equal to petro_extent_flux (usually 2) times the circular Petrosian radius.

property flux_ellip¶: Return the sum of the pixel values over an elliptical aperture with “radius” equal to petro_extent_flux (usually 2) times the elliptical Petrosian “radius”.

property gini¶: Calculate the Gini coefficient as described in Lotz et al. (2004).

property gini_m20_bulge¶: Return the Gini-M20 bulge statistic, F(G, M20), as defined in Rodriguez-Gomez et al. (2019).

property gini_m20_merger¶: Return the Gini-M20 merger statistic, S(G, M20), as defined in Rodriguez-Gomez et al. (2019).

property intensity¶: Calculate the intensity (I) statistic as described in Peth et al. (2016).

property m20¶: Calculate the M_20 coefficient as described in Lotz et al. (2004).

property multimode¶

Calculate the multimode (M) statistic as described in Freeman et al. (2013) and Peth et al. (2016).

Notes

In the original publication, Freeman et al. (2013) recommends using the more robust quantity (A2/A1)*A2, while Peth et al. (2016) recommends using the size-independent quantity A2/A1. Here we take a mixed approach (which, incidentally, is also what Mike Peth’s IDL implementation actually does): we maximize the quantity (A2/A1)*A2 (as a function of the brightness threshold) but ultimately define the M statistic as the corresponding A2/A1 value.

The original IDL implementation only explores quantiles in the range [0.5, 1.0], at least with the default settings. While this might be useful in practice, in theory the maximum (A2/A1)*A2 value could also happen in the quantile range [0.0, 0.5], so here we take a safer, more general approach and search over [0.0, 1.0].

In practice, the quantity (A2/A1)*A2 is tricky to optimize. We improve over previous implementations by doing so in two stages: starting with a brute-force search over a relatively coarse array of quantiles, as in the original implementation, followed by a finer search using the basin-hopping method. This should do a better job of finding the global maximum.

property nx_stamp¶: Number of pixels in the ‘postage stamp’ along the x direction.

property ny_stamp¶: Number of pixels in the ‘postage stamp’ along the y direction.

property orientation_asymmetry¶: The orientation (in radians) of the source, relative to the point that minimizes the asymmetry.

property orientation_centroid¶: The orientation (in radians) of the source, relative to the centroid.

property outer_asymmetry¶: Calculate outer asymmetry as described in Wen et al. (2014). Note that the center is the one used for the standard asymmetry.

property r20¶: The radius that contains 20% of the light within ‘petro_extent_cas’ (usually 1.5) times ‘rpetro_circ’.

property r50¶: The radius that contains 50% of the light within ‘petro_extent_cas’ (usually 1.5) times ‘rpetro_circ’.

property r80¶: The radius that contains 80% of the light within ‘petro_extent_cas’ (usually 1.5) times ‘rpetro_circ’.

property rhalf_circ¶: The radius of a circular aperture containing 50% of the light, assuming that the center is the point that minimizes the asymmetry and that the total is at rmax_circ.

property rhalf_ellip¶: The semimajor axis of an elliptical aperture containing 50% of the light, assuming that the center is the point that minimizes the asymmetry and that the total is at rmax_ellip.

property rmax_circ¶: Return the distance (in pixels) from the pixel that minimizes the asymmetry to the edge of the main source segment, similar to Pawlik et al. (2016).

property rmax_ellip¶: Return the semimajor axis of the minimal ellipse (with fixed center, elongation and orientation) that contains the entire main segment of the shape asymmetry segmap. In most cases this is almost identical to rmax_circ.

property rms_asymmetry2¶: Calculate the RMS asymmetry as in eq. 27 of Sazonova et al. (2024). Note that this actually corresponds to the square of A_rms.

property rpetro_circ¶: Calculate the Petrosian radius with respect to the point that minimizes the asymmetry.

property rpetro_ellip¶: Return the elliptical Petrosian “radius”, calculated with respect to the point that minimizes the asymmetry.

property sersic_aic¶: Akaike Information Criterion (AIC) of the fitted model.

property sersic_amplitude¶: The amplitude of the 2D Sersic fit at the effective (half-light) radius (astropy.modeling.models.Sersic2D).

property sersic_bic¶: Bayesian Information Criterion (BIC) of the fitted model.

property sersic_chi2_dof¶: Reduced chi^2 statistic of the fitted model.

property sersic_ellip¶: The ellipticity of the 2D Sersic fit (astropy.modeling.models.Sersic2D).

property sersic_n¶: The Sersic index n (astropy.modeling.models.Sersic2D).

property sersic_rhalf¶: The effective (half-light) radius of the 2D Sersic fit (astropy.modeling.models.Sersic2D).

property sersic_theta¶: The orientation (counterclockwise, in radians) of the 2D Sersic fit (astropy.modeling.models.Sersic2D).

property sersic_xc¶: The x-coordinate of the center of the 2D Sersic fit (astropy.modeling.models.Sersic2D), relative to the original image.

property sersic_yc¶: The y-coordinate of the center of the 2D Sersic fit (astropy.modeling.models.Sersic2D), relative to the original image.

property shape_asymmetry¶: Calculate shape asymmetry as described in Pawlik et al. (2016). Note that the center is the one used for the standard asymmetry.

property sky_mean¶: Mean background value. Equal to -99.0 when there is no skybox.

property sky_median¶: Median background value. Equal to -99.0 when there is no skybox.

property sky_sigma¶: Standard deviation of the background. Equal to -99.0 when there is no skybox.

property smoothness¶: Calculate smoothness (a.k.a. clumpiness) as defined in eq. (11) from Lotz et al. (2004). Note that the original definition by Conselice (2003) includes an additional factor of 10.

property sn_per_pixel¶: Calculate the signal-to-noise per pixel using the Petrosian segmap.

property xc_asymmetry¶: The x-coordinate of the point that minimizes the asymmetry, relative to the original image.

property xc_centroid¶: The x-coordinate of the centroid, relative to the original image.

property xmax_stamp¶: The maximum x position of the ‘postage stamp’.

property xmin_stamp¶: The minimum x position of the ‘postage stamp’.

property yc_asymmetry¶: The y-coordinate of the point that minimizes the asymmetry, relative to the original image.

property yc_centroid¶: The y-coordinate of the centroid, relative to the original image.

property ymax_stamp¶: The maximum y position of the ‘postage stamp’.

property ymin_stamp¶: The minimum y position of the ‘postage stamp’.

statmorph.source_morphology(image, segmap, **kwargs)[source]¶

Calculate the morphological parameters of all sources in image as labeled by segmap.

Parameters:

image (array-like) – A 2D image containing the sources of interest. The image must already be background-subtracted.
segmap (array-like (int) or photutils.segmentation.SegmentationImage) – A 2D segmentation map where different sources are labeled with different positive integer values. A value of zero is reserved for the background.
kwargs (~statmorph.SourceMorphology properties.) –

Returns:

sources_morph – A list of SourceMorphology objects, one for each source. The morphological parameters can be accessed as attributes or keys.

Return type:

list

API Reference¶

Navigation

Related Topics